cursedbelt 5.40.0 → 5.45.0

package/src/react/nav/PlaceBar.tsx

@@ -11,7 +11,7 @@ import { Drawer } from '../components/Drawer.js';
 import { IconButton } from '../components/IconButton.js';
 import { cn } from '../lib/cn.js';
 import {
-  isPathWithin,
+  isDomainActive,
   NAV_BADGE_TONE,
   type NavBadgeTone,
   NavLink,
@@ -168,9 +168,10 @@ export function PlaceBar({
             onClick={() => setMoreOpen(true)}
             className={cn(
               'relative flex min-w-0 flex-1 flex-col items-center justify-center gap-0.5 rounded-md px-1 py-1.5 text-xs font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
-              overflowActive ? 'text-foreground' : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+              overflowActive ? 'bg-accent/10 text-foreground' : 'text-muted-foreground hover:bg-muted hover:text-foreground',
             )}
           >
+            {overflowActive && <ActiveBar />}
             {/* Accent tints the icon only — see the PlaceTab comment above (cbux-101). */}
             <span
               className='relative grid size-6 place-items-center [&_svg]:size-5'
@@ -244,11 +245,6 @@ export function PlaceBar({
   );
 }
 
-/** A place is active when the route is its landing or lives within it (rail-consistent). */
-function isDomainActive(domain: NavDomain, activeHref: string | undefined): boolean {
-  if (isPathWithin(domain.path, activeHref)) return true;
-  return domain.groups.some((g) => g.items.some((it) => isPathWithin(it.path, activeHref)));
-}
 
 interface PlaceTabProps extends NavNavigationProps {
   place: NavDomain;
@@ -292,9 +288,12 @@ function PlaceTab({
       ariaLabel={place.label}
       className={cn(
         'relative flex min-w-0 flex-1 flex-col items-center justify-center gap-0.5 rounded-md px-1 py-1.5 text-xs font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
-        active ? 'text-foreground' : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+        active ? 'bg-accent/10 text-foreground' : 'text-muted-foreground hover:bg-muted hover:text-foreground',
       )}
     >
+      {/* NAV-6 on a bottom bar: its leading edge is the top one, facing the page. With the
+          tint and the foreground caption that is three marks — never color alone. */}
+      {active && <ActiveBar />}
       {/* The accent only ever tints the icon (graphical, 3:1 floor — axe doesn't
           score it as text) — never the label. `navAccent`/`--accent-solid` stays
           saturated in both modes for white-on-solid-fill use; as real label text
@@ -333,3 +332,14 @@ function PlaceTab({
     </NavLink>
   );
 }
+
+/** The 3px accent bar across the top of the current tab (NAV-6). */
+function ActiveBar() {
+  return (
+    <span
+      aria-hidden='true'
+      data-cb-active-indicator=''
+      className='absolute inset-x-3 top-0 h-[var(--indicator-w)] rounded-full bg-accent-solid'
+    />
+  );
+}

package/src/react/nav/SideNav.tsx

@@ -2,10 +2,12 @@ import { Fragment, type ReactNode, Suspense, useState } from 'react';
 import {
   allowAllGate,
   CURRENT_NAV_PREFS_VERSION,
+  deriveDomainItems,
   deriveSideNavDomains,
   type GateFn,
   type NavDomain,
   type NavigationModel,
+  type NavItem,
   type NavPreferences,
 } from 'cursedbelt-core/navigation';
 import { DisclosureButton } from '../components/DisclosureButton.js';
@@ -15,6 +17,7 @@ import { Tooltip } from '../components/Tooltip.js';
 import type { DragItemApi } from '../hooks/dragShared.js';
 import { cn } from '../lib/cn.js';
 import {
+  isDomainActive,
   isPathWithin,
   NAV_BADGE_TONE,
   type NavBadgeTone,
@@ -76,8 +79,18 @@ export interface SideNavProps extends NavNavigationProps {
   badgeTone?: NavBadgeTone;
   /** App slot above the list (logo / brand). */
   header?: ReactNode;
-  /** App slot below the list (theme toggle / avatar). */
+  /**
+   * App slot below the list — the version, `BuildFreshness` and a Settings link (NAV-13). Set
+   * in 12px muted type, under a 1px rule; a tool has no marketing footer anywhere else. Not
+   * drawn in the `collapsed` icon rail, which is 64px wide.
+   */
   footer?: ReactNode;
+  /**
+   * Show the ACTIVE place's own items beneath it, each label aligned under the parent's label
+   * text (NAV-7) — so a reader sees where they are inside a place without a second nav.
+   * Default `true`. Never in the icon rail, which has no labels to align to.
+   */
+  expandActive?: boolean;
   className?: string;
 }
 
@@ -109,6 +122,7 @@ export function SideNav({
   badgeTone = 'alert',
   header,
   footer,
+  expandActive = true,
   className,
 }: SideNavProps) {
   const domains = deriveSideNavDomains(model, gate);
@@ -159,11 +173,18 @@ export function SideNav({
     sections.sort((a, b) => Number(b.section === undefined) - Number(a.section === undefined));
   }
 
-  const renderRow = (domain: NavDomain, drag?: DragItemApi): ReactNode => (
+  const renderRow = (domain: NavDomain, drag?: DragItemApi): ReactNode => {
+    const active = isDomainActive(domain, activeHref);
+    const children = active && expandActive && !collapsed ? deriveDomainItems(domain, gate) : [];
+    const activeChild = children.find((it) => isPathWithin(it.path, activeHref));
+    const row = (
     <DomainRow
       key={domain.id}
       domain={domain}
-      active={isDomainActive(domain, activeHref)}
+      active={active}
+      // When a child is the current page, IT carries the bar and the tint; the place keeps
+      // its foreground label so the reader still sees which place they are inside.
+      activeIsChild={Boolean(activeChild)}
       color={prefs?.colors?.[domain.id]}
       badge={badges?.[domain.id]}
       badgeTone={badgeTone}
@@ -179,11 +200,26 @@ export function SideNav({
       }}
       {...navProps}
     />
-  );
+    );
+    if (children.length === 0) return row;
+    return (
+      <Fragment key={domain.id}>
+        {row}
+        <ul data-cb-sidenav-children='' className='mt-0.5 space-y-0.5'>
+          {children.map((item) => (
+            <li key={item.id}>
+              <ChildRow item={item} active={item === activeChild} {...navProps} />
+            </li>
+          ))}
+        </ul>
+      </Fragment>
+    );
+  };
 
   return (
     <nav
       data-cb-sidenav=''
+      data-cb-nav-collapsed={collapsed ? '' : undefined}
       aria-label='Primary'
       className={cn('flex h-full flex-col', collapsed ? 'w-16' : 'w-full', className)}
     >
@@ -256,8 +292,10 @@ export function SideNav({
         )}
       </ScrollArea>
 
-      {(footer || (canCustomize && hiddenDomains.length > 0)) && (
-        <div className='shrink-0 space-y-2 border-t border-border px-3 py-3'>
+      {/* The footer is words in a 240px column (NAV-13); the 64px icon rail has no room for
+          them, so it leaves them to the expanded rail and Settings. */}
+      {((footer && !collapsed) || (canCustomize && hiddenDomains.length > 0)) && (
+        <div data-cb-sidenav-footer='' className='shrink-0 space-y-2 border-t border-border px-3 py-3 text-xs text-muted-foreground'>
           {canCustomize && hiddenDomains.length > 0 && (
             <Suspense fallback={null}>
               <RestoreHiddenMenu
@@ -267,22 +305,19 @@ export function SideNav({
               />
             </Suspense>
           )}
-          {footer}
+          {collapsed ? null : footer}
         </div>
       )}
     </nav>
   );
 }
 
-/** A domain is active when the route is its landing or lives within it. */
-function isDomainActive(domain: NavDomain, activeHref: string | undefined): boolean {
-  if (isPathWithin(domain.path, activeHref)) return true;
-  return domain.groups.some((g) => g.items.some((it) => isPathWithin(it.path, activeHref)));
-}
 
 interface DomainRowProps extends NavNavigationProps {
   domain: NavDomain;
   active: boolean;
+  /** The current page is one of this place's items, shown beneath it. */
+  activeIsChild?: boolean;
   color?: string;
   badge?: number | string;
   badgeTone: NavBadgeTone;
@@ -296,6 +331,7 @@ interface DomainRowProps extends NavNavigationProps {
 function DomainRow({
   domain,
   active,
+  activeIsChild = false,
   color,
   badge,
   badgeTone,
@@ -327,7 +363,7 @@ function DomainRow({
       linkComponent={linkComponent}
       onNavigate={onNavigate}
       onAfterNavigate={onAfterNavigate}
-      ariaCurrent={active ? 'page' : undefined}
+      ariaCurrent={active && !activeIsChild ? 'page' : undefined}
       disabled={limited}
       // When there IS a host limit the wrapper below carries the richer hint, so the
       // link must not open a second, nested one.
@@ -345,7 +381,13 @@ function DomainRow({
         collapsed
           ? `size-10 justify-center ${TAP_TARGET}`
           : `w-full gap-3 px-3 py-2 ${TAP_TARGET_HEIGHT}`,
-        active ? 'bg-muted text-foreground' : 'text-foreground hover:bg-muted',
+        // NAV-6: the current place is marked three ways — the bar below, this tint, and a
+        // foreground label against the muted ones around it. Color alone fails.
+        active && !activeIsChild
+          ? 'bg-accent/10 text-foreground'
+          : active
+            ? 'text-foreground hover:bg-muted'
+            : 'text-muted-foreground hover:bg-muted hover:text-foreground',
       )}
     >
       {/* Active accent bar — colored by the per-row override or theme accent. The
@@ -359,12 +401,13 @@ function DomainRow({
           caught a domain green at 2.67:1 on the dark-mode muted background);
           the label stays on the guaranteed-contrast `text-foreground` token
           regardless of which accent a domain picks. */}
-      {active && (
+      {active && !activeIsChild && (
         <span
           aria-hidden='true'
+          data-cb-active-indicator=''
           className={cn(
-            'absolute left-0 rounded-full',
-            collapsed ? 'inset-y-1 left-0 w-[3px]' : 'inset-y-1.5 w-0.5',
+            'absolute left-0 w-[var(--indicator-w)] rounded-full',
+            collapsed ? 'inset-y-1' : 'inset-y-1.5',
           )}
           style={{ backgroundColor: accent }}
         />
@@ -432,3 +475,42 @@ function DomainRow({
     </div>
   );
 }
+
+/**
+ * One of the active place's items (NAV-7). Its label starts exactly under the parent's label:
+ * the parent row's `px-3` + its 20px icon + its `gap-3` is 44px, so the child's padding is 44px
+ * (`pl-11`) and its text lands on the same x. Marked like the place when it is the current page.
+ */
+function ChildRow({
+  item,
+  active,
+  linkComponent,
+  onNavigate,
+  onAfterNavigate,
+}: NavNavigationProps & { item: NavItem; active: boolean }) {
+  return (
+    <NavLink
+      path={item.path}
+      linkComponent={linkComponent}
+      onNavigate={onNavigate}
+      onAfterNavigate={onAfterNavigate}
+      ariaCurrent={active ? 'page' : undefined}
+      className={cn(
+        'relative flex w-full items-center rounded-md py-1.5 pl-11 pr-3 text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        TAP_TARGET_HEIGHT,
+        active ? 'bg-accent/10 font-medium text-foreground' : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+      )}
+    >
+      {active && (
+        <span
+          aria-hidden='true'
+          data-cb-active-indicator=''
+          className='absolute inset-y-1.5 left-0 w-[var(--indicator-w)] rounded-full bg-accent-solid'
+        />
+      )}
+      <span data-cb-nav-child-label='' className='min-w-0 flex-1 truncate text-left'>
+        {item.label}
+      </span>
+    </NavLink>
+  );
+}

package/src/react/nav/TopBar.spec.tsx

@@ -13,34 +13,89 @@ const items: TopBarItem[] = [
 
 const brand = { icon: <Glyph name='brand' />, label: 'Music', href: '/' };
 
-describe('TopBar — icons, not words (owner, 2026-09-25)', () => {
-  test('🔴 an item paints its ICON and no words; the label is its accessible name', () => {
+describe('TopBar — destinations have words (NAV-2, owner review 2026-10-01)', () => {
+  test('🔴 an item paints its icon AND its label from md up; the label is its accessible name', () => {
     const { getByRole } = render(<TopBar brand={brand} items={items} />);
     const link = getByRole('link', { name: 'Downloads' });
     expect(link.querySelector('[data-glyph="downloads"]')).not.toBeNull();
-    // No text at all inside the link — the word lives only in aria-label.
-    expect(link.textContent).toBe('');
+    const word = Array.from(link.querySelectorAll('span')).find((s) => s.textContent === 'Downloads');
+    expect(word?.className).toContain('hidden');
+    expect(word?.className).toContain('md:inline');
     expect(link.getAttribute('href')).toBe('/downloads');
   });
 
-  test('the active place is lit and announced as the current page', () => {
+  test('a router nav is marked primary for the design audit; an iconOnly utility bar is not', () => {
+    const { container } = render(<TopBar brand={brand} items={items} />);
+    const nav = container.querySelector('[data-cb-topbar-nav]') as HTMLElement;
+    expect(nav.hasAttribute('data-cb-primary-nav')).toBe(true);
+    cleanup();
+    const utility = render(<TopBar brand={brand} items={items} iconOnly />);
+    const bar = utility.container.querySelector('[data-cb-topbar-nav]') as HTMLElement;
+    expect(bar.hasAttribute('data-cb-primary-nav')).toBe(false);
+    expect(bar.hasAttribute('data-cb-nav-utility')).toBe(true);
+    // A utility bar paints glyphs only, at every width.
+    expect(utility.getByRole('link', { name: 'Downloads' }).textContent).toBe('');
+  });
+
+  test('🔴 the active place is marked three ways (NAV-6): bar, tint, foreground — and aria-current', () => {
     const { getByRole } = render(<TopBar brand={brand} items={items} />);
-    expect(getByRole('link', { name: 'Library' }).getAttribute('aria-current')).toBe('page');
-    expect(getByRole('link', { name: 'Downloads' }).getAttribute('aria-current')).toBeNull();
+    const active = getByRole('link', { name: 'Library' });
+    expect(active.getAttribute('aria-current')).toBe('page');
+    expect(active.querySelector('[data-cb-active-indicator]')).not.toBeNull();
+    expect(active.className).toContain('bg-accent/10');
+    expect(active.className).toContain('text-foreground');
+    const idle = getByRole('link', { name: 'Downloads' });
+    expect(idle.getAttribute('aria-current')).toBeNull();
+    expect(idle.querySelector('[data-cb-active-indicator]')).toBeNull();
+    expect(idle.className).toContain('text-muted-foreground');
   });
 
-  test('words appear ONLY with a stated reason, and even then drop below sm', () => {
-    const withReason: TopBarItem[] = [{ ...items[1], wordsBecause: 'two identical glyphs side by side' }];
-    const { getByRole } = render(<TopBar brand={brand} items={withReason} />);
-    const words = Array.from(getByRole('link', { name: 'Downloads' }).querySelectorAll('span')).find(
-      (s) => s.textContent === 'Downloads',
-    );
-    expect(words?.className).toContain('hidden');
-    expect(words?.className).toContain('sm:inline');
-    const blank: TopBarItem[] = [{ ...items[1], wordsBecause: '   ' }];
+  test('🔴 a count is never hidden: beside the word from md up, on the glyph\'s corner below, and in the name', () => {
+    const counted: TopBarItem[] = [items[0] as TopBarItem, { ...(items[1] as TopBarItem), badge: 1234 }];
+    const { getByRole } = render(<TopBar brand={brand} items={counted} />);
+    // Read as part of the name, so a screen reader hears the figure the eye sees.
+    const link = getByRole('link', { name: 'Downloads · 99+' });
+    const badge = link.querySelector('[data-cb-nav-badge]') as HTMLElement;
+    expect(badge.textContent).toBe('99+');
+    expect(badge.className).not.toContain('hidden');
+    expect(badge.className).toContain('max-md:absolute');
     cleanup();
-    const again = render(<TopBar brand={brand} items={blank} />);
-    expect(again.getByRole('link', { name: 'Downloads' }).textContent).toBe('');
+    const utility = render(<TopBar brand={brand} items={counted} iconOnly />);
+    const corner = utility.getByRole('link', { name: 'Downloads · 99+' }).querySelector('[data-cb-nav-badge]') as HTMLElement;
+    expect(corner.className).toContain('absolute');
+  });
+
+  test('header geometry (NAV-1): the --header-h token, a 1px bottom border, three zones', () => {
+    const { container } = render(<TopBar brand={brand} items={items} trailing={<span>x</span>} />);
+    const bar = container.querySelector('[data-cb-topbar]') as HTMLElement;
+    expect(bar.className).toContain('h-[var(--header-h)]');
+    expect(bar.className).toContain('border-b');
+    expect(bar.className).not.toContain('shadow');
+    const zones = Array.from(bar.children).map((z) => z.getAttribute('data-cb-topbar-zone'));
+    expect(zones).toEqual(['left', 'center', 'right']);
+    cleanup();
+    const dense = render(<TopBar brand={brand} items={items} density='dense' />);
+    expect((dense.container.querySelector('[data-cb-topbar]') as HTMLElement).className).toContain(
+      'h-[var(--header-h-dense)]',
+    );
+  });
+
+  test("phonePlaces='none' hands the places to a PlaceBar below md", () => {
+    const { container } = render(<TopBar brand={brand} items={items} phonePlaces='none' />);
+    expect((container.querySelector('[data-cb-topbar-nav]') as HTMLElement).className).toContain('max-md:hidden');
+  });
+
+  test('six or more places warn in dev — NAV-3 puts them in a sectioned SideNav', () => {
+    const warn = console.warn;
+    const said: string[] = [];
+    console.warn = (m: string) => said.push(m);
+    try {
+      const six = Array.from({ length: 6 }, (_, i) => ({ ...items[1], id: `p${i}`, href: `/p${i}` }));
+      render(<TopBar brand={{ ...brand, label: 'Six-place app' }} items={six} />);
+    } finally {
+      console.warn = warn;
+    }
+    expect(said.some((m) => m.includes('NAV-3'))).toBe(true);
   });
 
   test('🔴 the row cannot widen the page: clamped, and the places scroll inside themselves', () => {
@@ -55,15 +110,17 @@ describe('TopBar — icons, not words (owner, 2026-09-25)', () => {
     // Brand and trailing controls never shrink — the account menu stays reachable.
     const brandLink = container.querySelector('[data-cb-topbar-brand]') as HTMLElement;
     expect(brandLink.className).toContain('shrink-0');
-    expect((nav.nextElementSibling as HTMLElement).className).toContain('shrink-0');
+    const right = container.querySelector('[data-cb-topbar-zone="right"]') as HTMLElement;
+    expect(right.querySelector('[data-trailing]')).not.toBeNull();
+    expect(right.className).toContain('shrink-0');
   });
 
   test('a leading control sits BEFORE the brand and never shrinks — the phone sidebar button', () => {
     const { container } = render(
       <TopBar brand={brand} items={items} leading={<span data-leading=''>☰</span>} />,
     );
-    const bar = container.querySelector('[data-cb-topbar]') as HTMLElement;
-    const first = bar.firstElementChild as HTMLElement;
+    const left = container.querySelector('[data-cb-topbar-zone="left"]') as HTMLElement;
+    const first = left.firstElementChild as HTMLElement;
     expect(first.querySelector('[data-leading]')).not.toBeNull();
     expect(first.className).toContain('shrink-0');
     expect(first.nextElementSibling?.hasAttribute('data-cb-topbar-brand')).toBe(true);