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');
},
);
});