fix(web): show sidebar hints only on the icon rail, above the main area (UF-042)

With the full-width sidebar every item showed a hover hint that repeated its
visible label, and the part of the hint that reached past the sidebar was
hidden wherever the main area had content: the hint rendered inside the nav,
and the nav and <main> are sibling z-10 layers.

Sidebar hints now show only on the icon rail below lg, where they are the
only label, and render in document.body through a new opt-in `portal` flag
on HintTooltip. Other hints keep rendering in place, since several sit in
overlays above z-50 where a portaled hint would end up underneath.
This commit is contained in:
shumeiko.it
2026-10-25 23:37:20 +01:00
parent 07a529512c
commit efcb19e682
5 changed files with 107 additions and 18 deletions

View File

@@ -1,4 +1,4 @@
import type { ElementType } from "react";
import type { ElementType, ReactElement } from "react";
import { useLocation, useNavigate } from "react-router-dom";
import { ChevronDown, Plus, Search } from "lucide-react";
import { cmdKLabel } from "@/lib/platform";
@@ -50,6 +50,15 @@ function initialOf(name: string | null, fallback: string): string {
return (c ?? fallback).toUpperCase();
}
/** Every label is visible at ≥lg, so the hover hint shows only on the icon rail
* below lg, where it is the only way to read the label. Portaled: <main> is a
* sibling z-10 layer and paints over anything inside the nav (UF-042). */
const RailHint = ({ content, children }: { content: string; children: ReactElement }) => (
<HintTooltip content={content} side="right" portal className="lg:hidden">
{children}
</HintTooltip>
);
const Sidebar = ({
workspaceName,
spine,
@@ -71,9 +80,7 @@ const Sidebar = ({
const active = isActive(item);
const Icon = item.icon;
return (
// Below lg the sidebar collapses to an icon rail — the hover tooltip is the
// only way to read the label there. It's redundant (but harmless) at ≥lg.
<HintTooltip key={item.key} content={item.label} side="right">
<RailHint key={item.key} content={item.label}>
<button
data-testid={`nav-${item.key}`}
aria-label={item.label}
@@ -102,7 +109,7 @@ const Sidebar = ({
</span>
)}
</button>
</HintTooltip>
</RailHint>
);
};
@@ -124,7 +131,7 @@ const Sidebar = ({
className="waggle-sidebar relative z-10 flex w-16 lg:w-[248px] shrink-0 flex-col gap-1 overflow-y-auto border-r border-[var(--line-soft)] bg-[var(--bg-2)] px-2 lg:px-3 py-3.5"
>
{/* Workspace switcher pill */}
<HintTooltip content={workspaceName ?? "Workspace"} side="right">
<RailHint content={workspaceName ?? "Workspace"}>
<button
data-testid="sidebar-workspace"
aria-label="Switch workspace"
@@ -145,7 +152,7 @@ const Sidebar = ({
</span>
<ChevronDown className="hidden h-4 w-4 shrink-0 text-[var(--text-dim)] lg:block" />
</button>
</HintTooltip>
</RailHint>
{/* Five-place calm spine */}
{spine.map(renderNavItem)}
@@ -160,7 +167,7 @@ const Sidebar = ({
{/* General → ⌘K */}
<div className={zoneLabel}>General</div>
<HintTooltip content={`Search & commands (${cmdKLabel})`} side="right">
<RailHint content={`Search & commands (${cmdKLabel})`}>
<button
data-testid="sidebar-command"
aria-label="Search and commands"
@@ -173,10 +180,10 @@ const Sidebar = ({
{cmdKLabel}
</kbd>
</button>
</HintTooltip>
</RailHint>
{/* New agent — primary spawn affordance (also reachable from ⌘K) */}
<HintTooltip content="New Agent" side="right">
<RailHint content="New Agent">
<button
data-testid="nav-spawn-agent"
aria-label="New Agent"
@@ -186,12 +193,12 @@ const Sidebar = ({
<Plus className="h-[18px] w-[18px] shrink-0" strokeWidth={1.8} />
<span className="hidden flex-1 text-[13px] font-semibold lg:inline">New Agent</span>
</button>
</HintTooltip>
</RailHint>
<div className="flex-1" />
{/* User row → Settings */}
<HintTooltip content={userName ?? "Account"} side="right">
<RailHint content={userName ?? "Account"}>
<button
data-testid="sidebar-user"
aria-label="Account and settings"
@@ -207,7 +214,7 @@ const Sidebar = ({
</span>
</span>
</button>
</HintTooltip>
</RailHint>
</nav>
</TooltipProvider>
);

View File

@@ -17,7 +17,7 @@
* to bare child if both are empty, never crashes).
*/
import * as React from 'react';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
import { Tooltip, TooltipContent, TooltipPortal, TooltipTrigger } from '@/components/ui/tooltip';
export interface HintTooltipProps {
/** Tooltip text or node. Falsy values render children without a tooltip. */
@@ -30,6 +30,10 @@ export interface HintTooltipProps {
delay?: number;
/** Extra classes for the content pill. */
className?: string;
/** Render the pill in document.body, for triggers whose layer a sibling
* layer paints over. Off by default: hints inside high-z overlays must stay
* in the overlay's layer. */
portal?: boolean;
}
export function HintTooltip({
@@ -39,14 +43,18 @@ export function HintTooltip({
align = 'center',
delay = 200,
className,
portal = false,
}: HintTooltipProps) {
if (!content) return children;
const pill = (
<TooltipContent side={side} align={align} className={className}>
{content}
</TooltipContent>
);
return (
<Tooltip delayDuration={delay}>
<TooltipTrigger asChild>{children}</TooltipTrigger>
<TooltipContent side={side} align={align} className={className}>
{content}
</TooltipContent>
{portal ? <TooltipPortal>{pill}</TooltipPortal> : pill}
</Tooltip>
);
}

View File

@@ -9,6 +9,8 @@ const Tooltip = TooltipPrimitive.Root;
const TooltipTrigger = TooltipPrimitive.Trigger;
const TooltipPortal = TooltipPrimitive.Portal;
const TooltipContent = React.forwardRef<
React.ElementRef<typeof TooltipPrimitive.Content>,
React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
@@ -25,4 +27,4 @@ const TooltipContent = React.forwardRef<
));
TooltipContent.displayName = TooltipPrimitive.Content.displayName;
export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };
export { Tooltip, TooltipTrigger, TooltipContent, TooltipPortal, TooltipProvider };

View File

@@ -0,0 +1,62 @@
/**
* Sidebar hover hints (UF-042).
*
* At ≥lg every item shows its label, so a hint would only repeat it; below lg
* the sidebar is an icon rail and the hint is the only label. The hint must
* render outside the nav: the nav and <main> are sibling z-10 layers, and
* <main> paints over anything inside the nav that reaches into it.
*/
import { describe, it, expect, afterEach } from 'vitest';
import { render, screen, cleanup, act } from '@testing-library/react';
import { MemoryRouter } from 'react-router-dom';
import { Home } from 'lucide-react';
import Sidebar, { type SidebarNavItem } from '@/components/os/Sidebar';
class ResizeObserverStub {
observe() {}
unobserve() {}
disconnect() {}
}
(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver ??= ResizeObserverStub;
afterEach(cleanup);
const spine: SidebarNavItem[] = [
{ key: 'home', label: 'Home', icon: Home, to: '/home', match: ['/home'] },
];
function renderSidebar() {
return render(
<MemoryRouter initialEntries={['/home']}>
<Sidebar
workspaceName="Acme"
spine={spine}
onOpenWorkspaceSwitcher={() => {}}
onOpenCommand={() => {}}
onSpawnAgent={() => {}}
userName="Marko"
/>
</MemoryRouter>,
);
}
async function openHint(testId: string): Promise<HTMLElement> {
act(() => screen.getByTestId(testId).focus());
const tooltip = await screen.findByRole('tooltip');
const content = tooltip.closest<HTMLElement>('[data-side]');
if (!content) throw new Error('tooltip content not found');
return content;
}
describe('Sidebar hover hints (UF-042)', () => {
it.each(['nav-home', 'nav-spawn-agent', 'sidebar-command'])(
'%s: the hint renders outside the nav and only on the icon rail',
async (testId) => {
renderSidebar();
const hint = await openHint(testId);
expect(screen.getByRole('navigation', { name: 'Primary' }).contains(hint)).toBe(false);
expect(hint).toHaveClass('lg:hidden');
},
);
});

View File

@@ -70,6 +70,7 @@ Baseline: commit `b20b138` of `git.os-dev.tech/oleg.m/waggle-os`.
| UF-039 | A memory saved to an unknown workspace lands in personal memory | Fixed | Sidecar, memory, privacy |
| UF-040 | The support bundle never includes recent installs | Fixed | Sidecar, support |
| UF-041 | The CLI server does not exit on Ctrl+C or SIGTERM | Fixed | Sidecar, CLI |
| UF-042 | Sidebar hints repeat the visible labels and are partly hidden behind the main area | Fixed | Web UI |
## Entries
@@ -415,3 +416,12 @@ Entries UF-010 to UF-019 come from the UI audit `anti-slop/audit-001-2026-10-14.
- Cause: the OAuth routes start a cleanup interval when the module loads and never clear or unref it. The service installs SIGTERM and SIGINT handlers, which replace Node's default exit, closes the server, and relies on the event loop going empty; the interval keeps it alive.
- What we did: the interval is unref'd. A launcher test checks that the built CLI exits by itself after SIGTERM, and the launcher tests now stop `npx` and the `waggle` process it starts as one process group.
- Recommendation: unref housekeeping timers or clear them when the server closes, and consider ending the signal handler with an explicit exit.
### UF-042. Sidebar hints repeat the visible labels and are partly hidden behind the main area
- Status: Fixed
- Found: 2026-10-25
- Where: at commit `b20b138`, `apps/web/src/components/os/Sidebar.tsx:76-78`, 129, 165, 181, 196 (a `HintTooltip` on every item, unportaled per `apps/web/src/components/ui/tooltip.tsx`), with the sidebar at `Sidebar.tsx:126` and `<main>` at `AppShell.tsx:497`, both `relative z-10`
- Symptom: with the full-width sidebar every item shows a hover hint that only repeats its visible label, for example "New Agent" next to the "New Agent" button. The hint is cut off where the main area has content to the right of the sidebar.
- Cause: the sidebar shows the same hints at every width, although they are only needed on the icon rail below `lg`, as a code comment already noted. The hint renders inside the nav, and the nav and `<main>` are sibling `z-10` layers, so `<main>`, later in the DOM, paints over the part of the hint that reaches into it.
- What we did: sidebar hints show only on the icon rail (`lg:hidden`) and render in `document.body` through a new opt-in `portal` flag on `HintTooltip`, so `<main>` no longer covers them. Other hints are unchanged, because several of them sit inside overlays above `z-50`, where a portaled hint would end up under the overlay. A test checks both properties.
- Recommendation: apply the same change in the main project, and review other hints that repeat a visible label.