cursedbelt 5.82.0 → 5.85.0

package/src/react/nav/NavItemMenu.tsx

@@ -45,6 +45,7 @@ export function NavItemMenu({
   trigger,
   onOpenChange,
   className,
+  ...rest
 }: NavItemMenuProps) {
   const [open, setOpen] = useState(false);
   const change = (next: boolean) => {
@@ -54,6 +55,7 @@ export function NavItemMenu({
 
   return (
     <Popover
+      {...rest}
       open={open}
       onOpenChange={change}
       align={align}

package/src/react/nav/PlaceBar.tsx

@@ -14,7 +14,11 @@ import { PRESS } from '../lib/press.js';
 import {
   isDomainActive,
   NAV_BADGE_TONE,
+  type NavBadge,
   type NavBadgeTone,
+  navBadgeText,
+  navBadgeTone,
+  navBadgeValue,
   NavLink,
   type NavNavigationProps,
   navAccent,
@@ -28,8 +32,8 @@ export interface PlaceBarProps extends NavNavigationProps {
   gate?: GateFn;
   /** Current route — the active place lights up. */
   activeHref?: string;
-  /** Dynamic per-place badge (unread dot), keyed by domain id. */
-  badges?: Record<string, number | string>;
+  /** Dynamic per-place badge (unread dot), keyed by domain id. A badge may carry its own tone — see {@link NavBadge}. */
+  badges?: Record<string, NavBadge>;
   /** How those counts read — see {@link NavBadgeTone}. Default `alert` (red). */
   badgeTone?: NavBadgeTone;
   /**
@@ -83,6 +87,7 @@ export function PlaceBar({
   onAfterNavigate,
   resolveIcon,
   className,
+  ...rest
 }: PlaceBarProps) {
   const all = deriveSideNavDomains(model, gate);
   const limit = Math.max(1, max);
@@ -132,12 +137,17 @@ export function PlaceBar({
 
   const overflowActive = overflow.some((p) => isDomainActive(p, activeHref));
   const overflowBadge = overflow.reduce<number>((sum, p) => {
-    const b = badges?.[p.id];
+    const b = navBadgeValue(badges?.[p.id]);
     return sum + (typeof b === 'number' ? b : b ? 1 : 0);
   }, 0);
+  // The More tab reads red if ANY rolled-up badge is an alert; a sheet of plain facts stays quiet.
+  const overflowTone: NavBadgeTone = overflow.some((p) => navBadgeValue(badges?.[p.id]) !== null && navBadgeTone(badges?.[p.id], badgeTone) === 'alert')
+    ? 'alert'
+    : badgeTone;
 
   return (
     <nav
+      {...rest}
       data-cb-placebar=''
       aria-label='Places'
       // gap-3 is the 12px clear space between adjacent links (e2e/touch-targets.spec.ts), so the
@@ -192,9 +202,9 @@ export function PlaceBar({
                 // raising it bursts the circle, and §4's floor is about metadata a reader reads.
                 <span
                   // guardrails-ignore micro-typography-floor: a COUNT glyph inside a 16px dot — raising it bursts the circle, and §4's floor is about metadata a reader reads.
-                  className={cn('absolute -right-1.5 -top-1 min-w-3.5 rounded-full px-1 text-caption font-bold leading-4', NAV_BADGE_TONE[badgeTone])}
+                  className={cn('absolute -right-1.5 -top-1 min-w-3.5 rounded-full px-1 text-caption font-bold leading-4', NAV_BADGE_TONE[overflowTone])}
                 >
-                  {overflowBadge > 99 ? '99+' : overflowBadge}
+                  {navBadgeText(overflowBadge)}
                 </span>
               )}
             </span>
@@ -206,7 +216,7 @@ export function PlaceBar({
               {overflow.map((place) => {
                 const active = isDomainActive(place, activeHref);
                 const icon = renderIcon(resolveIcon, place.icon);
-                const badge = badges?.[place.id];
+                const badge = navBadgeValue(badges?.[place.id]);
                 return (
                   <li key={place.id}>
                     <NavLink
@@ -238,9 +248,9 @@ export function PlaceBar({
                         </span>
                       )}
                       <span className='min-w-0 flex-1 truncate'>{place.label}</span>
-                      {badge != null && badge !== 0 && (
-                        <span className={cn('rounded-full px-1.5 py-0.5 text-xs font-bold', NAV_BADGE_TONE[badgeTone])}>
-                          {typeof badge === 'number' && badge > 99 ? '99+' : badge}
+                      {badge !== null && (
+                        <span className={cn('rounded-full px-1.5 py-0.5 text-xs font-bold tabular-nums', NAV_BADGE_TONE[navBadgeTone(badges?.[place.id], badgeTone)])}>
+                          {navBadgeText(badge)}
                         </span>
                       )}
                     </NavLink>
@@ -259,7 +269,7 @@ export function PlaceBar({
 interface PlaceTabProps extends NavNavigationProps {
   place: NavDomain;
   active: boolean;
-  badge?: number | string;
+  badge?: NavBadge;
   /**
    * 🔴 Threaded 2026-08-22. `PlaceTab` hardcoded `bg-destructive-solid` and ignored
    * the model's tone entirely, while the More sheet's rows twenty lines up honoured
@@ -285,7 +295,8 @@ function PlaceTab({
 }: PlaceTabProps) {
   const accent = navAccent(undefined);
   const icon = renderIcon(resolveIcon, place.icon);
-  const showBadge = badge != null && badge !== 0;
+  const badgeShown = navBadgeValue(badge);
+  const showBadge = badgeShown !== null;
 
   return (
     <NavLink
@@ -324,9 +335,9 @@ function PlaceTab({
           // raising it bursts the circle, and §4's floor is about metadata a reader reads.
           <span
             // guardrails-ignore micro-typography-floor: a COUNT glyph inside a 16px dot — raising it bursts the circle, and §4's floor is about metadata a reader reads.
-            className={cn('absolute -right-1.5 -top-1 min-w-3.5 rounded-full px-1 text-caption font-bold leading-4', NAV_BADGE_TONE[badgeTone])}
+            className={cn('absolute -right-1.5 -top-1 min-w-3.5 rounded-full px-1 text-caption font-bold leading-4', NAV_BADGE_TONE[navBadgeTone(badge, badgeTone)])}
           >
-            {typeof badge === 'number' && badge > 99 ? '99+' : badge}
+            {badgeShown === null ? null : navBadgeText(badgeShown)}
           </span>
         )}
       </span>

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

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { cleanup, render } from '@testing-library/react';
+import { FilterRail } from '../filter-rail/FilterRail.js';
+import { RailPlaces } from './RailPlaces.js';
+import type { TopBarItem } from './TopBar.js';
+
+afterEach(cleanup);
+
+const Glyph = ({ name }: { name: string }) => <svg data-glyph={name} />;
+
+const items: TopBarItem[] = [
+  { id: 'library', label: 'Library', icon: <Glyph name='library' />, active: true, href: '#/' },
+  { id: 'stats', label: 'Stats', icon: <Glyph name='stats' />, href: '#/stats', badge: 3 },
+  { id: 'consoles', label: 'Consoles', icon: <Glyph name='consoles' />, href: '#/consoles', unavailable: 'Only on the Mac.' },
+];
+const brand = { icon: <Glyph name='brand' />, label: 'ROMs', href: '#/' };
+
+describe('RailPlaces — the top bar moved into the sidebar (owner, 2026-10-20)', () => {
+  test('🔴 every place is a labeled link with its real href, and the list is the primary nav', () => {
+    const { container, getByRole } = render(<RailPlaces brand={brand} items={items} />);
+    const nav = container.querySelector('nav[data-cb-primary-nav]') as HTMLElement;
+    expect(nav.getAttribute('aria-label')).toBe('Places');
+    const library = getByRole('link', { name: 'Library' });
+    expect(library.getAttribute('href')).toBe('#/');
+    expect(library.textContent).toContain('Library');
+    expect(getByRole('link', { name: 'Stats · 3' }).getAttribute('href')).toBe('#/stats');
+  });
+
+  test('the current place is marked three ways (NAV-6): aria-current, the raised fill, the 3px accent edge', () => {
+    const { getByRole } = render(<RailPlaces brand={brand} items={items} />);
+    const library = getByRole('link', { name: 'Library' });
+    expect(library.getAttribute('aria-current')).toBe('page');
+    expect(library.className).toContain('bg-card-overlay');
+    expect(library.className).toContain('inset_3px_0_0_0_var(--accent)');
+    expect(getByRole('link', { name: 'Stats · 3' }).getAttribute('aria-current')).toBeNull();
+  });
+
+  test('an unavailable place stays on screen as a disabled link, never a dead href (owner-uis-are-one-ui)', () => {
+    const { container } = render(<RailPlaces brand={brand} items={items} />);
+    const consoles = container.querySelector('[aria-label="Consoles"]') as HTMLElement;
+    expect(consoles.tagName).toBe('SPAN');
+    expect(consoles.getAttribute('aria-disabled')).toBe('true');
+    expect(consoles.hasAttribute('href')).toBe(false);
+  });
+
+  test('the brand links home and the utilities sit on its line, marked as utilities', () => {
+    const { container, getByRole } = render(
+      <RailPlaces brand={brand} items={items} trailing={<span data-utility=''>Account</span>} />,
+    );
+    expect(getByRole('link', { name: 'ROMs' }).getAttribute('href')).toBe('#/');
+    const utilities = container.querySelector('[data-cb-rail-utilities]') as HTMLElement;
+    expect(utilities.hasAttribute('data-cb-nav-utility')).toBe(true);
+    expect(utilities.textContent).toBe('Account');
+  });
+
+  test('🔴 collapsed: icons with an sr-only name, the utilities kept in a column, and the nav says it is the collapsed rail', () => {
+    const { container, getByRole } = render(
+      <RailPlaces brand={brand} items={items} collapsed trailing={<span data-utility=''>Account</span>} />,
+    );
+    // A folded rail keeps the account: it stacks under the mark rather than vanishing.
+    const utilities = container.querySelector('[data-cb-rail-utilities]') as HTMLElement;
+    expect(utilities.textContent).toBe('Account');
+    expect(utilities.className).toContain('flex-col');
+    expect(container.querySelector('nav')?.hasAttribute('data-cb-nav-collapsed')).toBe(true);
+    expect(getByRole('link', { name: 'Library' }).querySelector('.sr-only')?.textContent).toBe('Library');
+  });
+
+  test('🔴 in FilterRail\'s `places` slot it survives the rail collapsing, where `header` does not', () => {
+    const rail = (collapsed: boolean) => (
+      <FilterRail
+        label='Library'
+        sections={[{ id: 'views', items: [{ id: 'all', label: 'All' }] }]}
+        selected='all'
+        onSelect={() => {}}
+        collapsed={collapsed}
+        onCollapsedChange={() => {}}
+        places={<RailPlaces brand={brand} items={items} collapsed={collapsed} />}
+        header={<span data-rail-header=''>Filter</span>}
+      />
+    );
+    const open = render(rail(false));
+    expect(open.container.querySelector('[data-cb-rail-places]')).not.toBeNull();
+    expect(open.container.querySelector('[data-rail-header]')).not.toBeNull();
+    cleanup();
+    const folded = render(rail(true));
+    expect(folded.container.querySelector('[data-cb-rail-places]')).not.toBeNull();
+    expect(folded.getByRole('link', { name: 'Library' })).toBeTruthy();
+    expect(folded.container.querySelector('[data-rail-header]')).toBeNull();
+  });
+
+  test('🔴 a footer given as a function stays on the folded rail, told it is folded; a node footer does not', () => {
+    const rail = (collapsed: boolean, footer: Parameters<typeof FilterRail>[0]['footer']) => (
+      <FilterRail
+        label='Library'
+        sections={[{ id: 'views', items: [{ id: 'all', label: 'All' }] }]}
+        selected='all'
+        onSelect={() => {}}
+        collapsed={collapsed}
+        onCollapsedChange={() => {}}
+        footer={footer}
+      />
+    );
+    const folded = render(rail(true, (c) => <span data-foot=''>{c ? 'icons' : 'Settings'}</span>));
+    expect(folded.container.querySelector('[data-foot]')?.textContent).toBe('icons');
+    cleanup();
+    const open = render(rail(false, (c) => <span data-foot=''>{c ? 'icons' : 'Settings'}</span>));
+    expect(open.container.querySelector('[data-foot]')?.textContent).toBe('Settings');
+    cleanup();
+    expect(render(rail(true, <span data-foot=''>Settings</span>)).container.querySelector('[data-foot]')).toBeNull();
+  });
+});

package/src/react/nav/RailPlaces.tsx

@@ -0,0 +1,192 @@
+import type { ElementType, ReactNode } from 'react';
+import { Tooltip } from '../components/Tooltip.js';
+import { cn } from '../lib/cn.js';
+import { TAP_TARGET, TAP_TARGET_HEIGHT } from '../lib/tapTarget.js';
+import { NAV_BADGE_TONE } from './navShared.js';
+import type { TopBarItem, TopBarProps } from './TopBar.js';
+
+export interface RailPlacesProps {
+  /** The app's mark and name, linking to its root — the same shape `TopBar` takes. */
+  brand: TopBarProps['brand'];
+  /** The app's places, in IA order — the same items a `TopBar` would have drawn. */
+  items: readonly TopBarItem[];
+  /**
+   * The utility cluster on the brand's line: help, theme, account. Icons, each with its own
+   * tooltip (NAV-2 allows utilities to be icons). Collapsed, they stack under the mark instead: a
+   * rail folded to icons must not lose the account or the lock.
+   */
+  trailing?: ReactNode;
+  /** The rail's icon-only state: every place is its icon, its tooltip and an sr-only name. */
+  collapsed?: boolean;
+  /** SPA link component (receives `to` as well as `href`), as `TopBar` takes it. */
+  linkComponent?: ElementType;
+  /** Accessible name of the places list. Default "Places". */
+  navLabel?: string;
+  className?: string;
+}
+
+/**
+ * An app's brand, its places and its global utilities at the TOP OF ITS SIDEBAR — in place of a
+ * `TopBar` above the page.
+ *
+ * ── Why ────────────────────────────────────────────────────────────────────
+ * The owner, 2026-10-20, on roms, vault and music: *"All apps will use the sidebar instead of an
+ * extra top row, utilize space better"* and *"move all top row buttons into the far left sidebar
+ * and no longer have the top row so we save space and see more content with less scrolling
+ * needed."* An app that already gives its left edge to a sidebar was spending a second 64px strip
+ * across the whole width on three places and an avatar. Linear and Notion put exactly these in
+ * the sidebar's head — workspace mark and account on one line, the places under it — and the page
+ * keeps its full height. NAV-3's top bar stays the pattern for an app with NO sidebar.
+ *
+ * ── The pieces ─────────────────────────────────────────────────────────────
+ * - The brand line: the mark and name (a link to the root), then `trailing` locked to the right.
+ * - The places: labeled rows with the rail's own look, so a place and a filter row line up — and
+ *   the current one is marked three ways (NAV-6): a 3px accent edge, the raised fill, the medium
+ *   weight. Real hrefs, so they copy and middle-click; `TopBarItem`'s `badge` and `unavailable`
+ *   behave as they do in the bar (`owner-uis-are-one-ui`: an unavailable place is shown, with why).
+ * - A hairline under the block, so the app's own sections below read as the page's, not the app's.
+ *
+ * Put it in `FilterRail`'s `places` slot (it survives the rail's collapse there) or at the top of
+ * any other sidebar. The design audit's NAV-15 fails a `TopBar` shown beside a sidebar at ≥768px,
+ * so the two cannot drift back into both.
+ */
+export function RailPlaces({
+  brand,
+  items,
+  trailing,
+  collapsed = false,
+  linkComponent,
+  navLabel = 'Places',
+  className,
+  ...rest
+}: RailPlacesProps) {
+  const Brand: ElementType = linkComponent ?? 'a';
+  return (
+    <div
+      {...rest}
+      data-cb-rail-places=''
+      className={cn('flex flex-none flex-col gap-1 border-b border-rule px-2 pt-2 pb-2', className)}
+    >
+      <div className={cn('flex h-10 min-w-0 items-center gap-1', collapsed && 'justify-center')}>
+        <Brand
+          {...brand.linkProps}
+          {...(linkComponent ? { to: brand.href } : {})}
+          href={brand.href}
+          aria-label={brand.label}
+          data-cb-rail-brand=''
+          className={cn(
+            'flex min-w-0 items-center gap-2 rounded-md px-1.5 py-1 font-semibold text-foreground',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+            TAP_TARGET,
+            !collapsed && 'flex-1',
+          )}
+        >
+          <span aria-hidden='true' className='grid size-6 shrink-0 place-items-center [&_svg]:size-5'>
+            {brand.icon}
+          </span>
+          {collapsed ? null : (
+            <span aria-hidden='true' className='truncate text-sm'>
+              {brand.label}
+            </span>
+          )}
+        </Brand>
+        {trailing && !collapsed ? (
+          <div data-cb-rail-utilities='' data-cb-nav-utility='' className='flex shrink-0 items-center gap-0.5'>
+            {trailing}
+          </div>
+        ) : null}
+      </div>
+      {trailing && collapsed ? (
+        <div data-cb-rail-utilities='' data-cb-nav-utility='' className='flex flex-col items-center gap-0.5'>
+          {trailing}
+        </div>
+      ) : null}
+      {items.length > 0 ? (
+        <nav
+          aria-label={navLabel}
+          data-cb-primary-nav=''
+          data-cb-nav-collapsed={collapsed ? '' : undefined}
+          className='flex flex-col gap-px'
+        >
+          {items.map((item) => (
+            <RailPlaceLink key={item.id} item={item} collapsed={collapsed} linkComponent={linkComponent} />
+          ))}
+        </nav>
+      ) : null}
+    </div>
+  );
+}
+
+function RailPlaceLink({
+  item,
+  collapsed,
+  linkComponent,
+}: {
+  item: TopBarItem;
+  collapsed: boolean;
+  linkComponent: ElementType | undefined;
+}) {
+  const Link: ElementType = item.unavailable ? 'span' : (linkComponent ?? 'a');
+  const showBadge = item.badge != null && item.badge !== 0;
+  const badgeText = typeof item.badge === 'number' && item.badge > 99 ? '99+' : item.badge;
+  const target = item.unavailable
+    ? // HTML has no disabled anchor: a span that still announces as the link it is.
+      { role: 'link', 'aria-disabled': 'true', tabIndex: 0 }
+    : { ...item.linkProps, ...(linkComponent ? { to: item.href } : {}), href: item.href };
+  const link = (
+    <Link
+      {...target}
+      aria-label={showBadge ? `${item.label} · ${badgeText}` : item.label}
+      aria-current={item.active ? 'page' : undefined}
+      data-active={item.active ? '' : undefined}
+      data-cb-nav-item=''
+      className={cn(
+        'relative flex items-center gap-2 rounded-md text-sm transition-colors',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        collapsed ? `size-10 justify-center mx-auto ${TAP_TARGET}` : `px-2.5 py-1.5 ${TAP_TARGET_HEIGHT}`,
+        item.unavailable && 'opacity-55',
+        item.active
+          ? 'bg-card-overlay font-medium text-foreground shadow-[inset_3px_0_0_0_var(--accent)]'
+          : 'text-muted-foreground hover:bg-card-raised hover:text-foreground',
+      )}
+    >
+      <span aria-hidden='true' className='grid size-4 shrink-0 place-items-center [&_svg]:size-4'>
+        {item.icon}
+      </span>
+      {collapsed ? (
+        <span className='sr-only'>{item.label}</span>
+      ) : (
+        <span aria-hidden='true' className='min-w-0 flex-1 truncate'>
+          {item.label}
+        </span>
+      )}
+      {showBadge ? (
+        <span
+          aria-hidden='true'
+          data-cb-nav-badge=''
+          className={cn(
+            'rounded-full px-1.5 py-0.5 text-xs font-bold leading-none tabular-nums',
+            NAV_BADGE_TONE[item.badgeTone ?? 'alert'],
+            collapsed && 'absolute -top-0.5 -right-0.5',
+          )}
+        >
+          {badgeText}
+        </span>
+      ) : null}
+    </Link>
+  );
+  if (item.unavailable) {
+    return (
+      <Tooltip content={`${item.label} — not available here. ${item.unavailable}`} side='right' multiline>
+        {link}
+      </Tooltip>
+    );
+  }
+  return collapsed ? (
+    <Tooltip content={item.label} side='right'>
+      {link}
+    </Tooltip>
+  ) : (
+    link
+  );
+}

package/src/react/nav/SearchResults.tsx

@@ -55,16 +55,17 @@ export function SearchResults({
   onAfterNavigate,
   resolveIcon,
   className,
+  ...rest
 }: SearchResultsProps) {
   const hasResults = groups.some((g) => g.items.length > 0);
   if (!hasResults) {
     return emptyContent ? (
-      <div className={cn('p-6 text-center', className)}>{emptyContent}</div>
+      <div {...rest} className={cn('p-6 text-center', className)}>{emptyContent}</div>
     ) : null;
   }
 
   return (
-    <div className={cn('flex flex-col', className)} role='listbox' aria-label='Search results'>
+    <div {...rest} className={cn('flex flex-col', className)} role='listbox' aria-label='Search results'>
       {groups.map((group) =>
         group.items.length === 0 ? null : (
           <div key={group.key} className='py-1'>

package/src/react/nav/SideNav.tsx

@@ -26,6 +26,10 @@ import {
   navAccent,
   rankBySavedOrder,
   renderIcon,
+  type NavBadge,
+  navBadgeText,
+  navBadgeTone,
+  navBadgeValue,
 } from './navShared.js';
 import { TAP_TARGET, TAP_TARGET_HEIGHT } from '../lib/tapTarget.js';
 
@@ -73,8 +77,8 @@ export interface SideNavProps extends NavNavigationProps {
   /** Fired when a section header is toggled while `collapsedSections` is controlled;
    *  `collapsed` is the section's NEXT state. */
   onSectionToggle?: (section: string, collapsed: boolean) => void;
-  /** Dynamic per-domain badge (unread count, etc.), keyed by domain id. */
-  badges?: Record<string, number | string>;
+  /** Dynamic per-domain badge (unread count, etc.), keyed by domain id. A badge may carry its own tone — see {@link NavBadge}. */
+  badges?: Record<string, NavBadge>;
   /** How those counts read — see {@link NavBadgeTone}. Default `alert` (red). */
   badgeTone?: NavBadgeTone;
   /** App slot above the list (logo / brand). */
@@ -124,6 +128,7 @@ export function SideNav({
   footer,
   expandActive = true,
   className,
+  ...rest
 }: SideNavProps) {
   const domains = deriveSideNavDomains(model, gate);
   const hiddenIds = prefs?.hidden ?? [];
@@ -218,6 +223,7 @@ export function SideNav({
 
   return (
     <nav
+      {...rest}
       data-cb-sidenav=''
       data-cb-nav-collapsed={collapsed ? '' : undefined}
       aria-label='Primary'
@@ -319,7 +325,7 @@ interface DomainRowProps extends NavNavigationProps {
   /** The current page is one of this place's items, shown beneath it. */
   activeIsChild?: boolean;
   color?: string;
-  badge?: number | string;
+  badge?: NavBadge;
   badgeTone: NavBadgeTone;
   collapsed: boolean;
   canCustomize: boolean;
@@ -347,6 +353,7 @@ function DomainRow({
 }: DomainRowProps) {
   const accent = navAccent(color);
   const icon = renderIcon(resolveIcon, domain.icon);
+  const badgeShown = navBadgeValue(badge);
   /**
    * 🔴 `UX_STANDARDS.md` §8.6 / the owner's `owner-uis-are-one-ui` ruling: a nav item
    * that cannot do its job on this host must SAY SO BEFORE IT IS CLICKED. The prod
@@ -422,9 +429,9 @@ function DomainRow({
         </span>
       )}
       {!collapsed && <span className='flex-1 truncate text-left'>{domain.label}</span>}
-      {!collapsed && badge != null && badge !== 0 && (
-        <span className={cn('rounded-full px-1.5 py-0.5 text-xs font-bold', NAV_BADGE_TONE[badgeTone])}>
-          {typeof badge === 'number' && badge > 99 ? '99+' : badge}
+      {!collapsed && badgeShown !== null && (
+        <span data-cb-nav-badge='' className={cn('rounded-full px-1.5 py-0.5 text-xs font-bold tabular-nums', NAV_BADGE_TONE[navBadgeTone(badge, badgeTone)])}>
+          {navBadgeText(badgeShown)}
         </span>
       )}
     </NavLink>

package/src/react/nav/SideNavCustomize.tsx

@@ -40,7 +40,7 @@ export interface ReorderableRowsProps {
 }
 
 /** The rail's list, drag-reorderable (pointer, touch and keyboard via the shared hook). */
-export function ReorderableRows({ domains, onReorder, renderRow }: ReorderableRowsProps) {
+export function ReorderableRows({ domains, onReorder, renderRow, ...rest }: ReorderableRowsProps) {
   const reorder = useDragReorder({
     items: domains,
     getKey: (d) => d.id,
@@ -51,7 +51,7 @@ export function ReorderableRows({ domains, onReorder, renderRow }: ReorderableRo
 
   return (
     <reorder.DragContext>
-      <ul className='space-y-0.5'>
+      <ul {...rest} className='space-y-0.5'>
         {domains.map((domain) => (
           <reorder.Sortable key={domain.id} itemKey={domain.id}>
             {(api) => (
@@ -81,9 +81,10 @@ export function RowCustomizeControls({
   drag,
   onHide,
   onColor,
+  ...rest
 }: RowCustomizeControlsProps) {
   return (
-    <div className='absolute right-1 flex items-center gap-0.5 opacity-0 transition-opacity focus-within:opacity-100 group-hover/navitem:opacity-100'>
+    <div {...rest} className='absolute right-1 flex items-center gap-0.5 opacity-0 transition-opacity focus-within:opacity-100 group-hover/navitem:opacity-100'>
       {drag && (
         <Tooltip content={`Reorder ${label}`}>
           <button
@@ -117,6 +118,7 @@ export function RestoreHiddenMenu({
   domains,
   resolveIcon,
   onRestore,
+  ...rest
 }: {
   domains: NavDomain[];
   resolveIcon?: IconResolver;
@@ -125,6 +127,7 @@ export function RestoreHiddenMenu({
   const [open, setOpen] = useState(false);
   return (
     <Popover
+      {...rest}
       open={open}
       onOpenChange={setOpen}
       align='start'

package/src/react/nav/TopBar.tsx

@@ -104,6 +104,11 @@ export interface TopBarProps {
  *
  * `guardrails no-raw-nav` is the other half: a hand-rolled `<nav>` in app source fails the
  * app's gate, so the next header is this one.
+ *
+ * 🔴 **Only for an app with no sidebar** (NAV-15, owner 2026-10-20: *"All apps will use the
+ * sidebar instead of an extra top row"*). Where a sidebar is on screen, the same `brand` and
+ * `items` go to `RailPlaces` at its top and this bar is not drawn; it stays the phone's
+ * shell where that sidebar is a drawer. The design audit fails the two shown together at ≥768px.
  */
 export function TopBar({
   brand,
@@ -117,6 +122,7 @@ export function TopBar({
   linkComponent,
   navLabel = 'Places',
   className,
+  ...rest
 }: TopBarProps) {
   if (!iconOnly && items.length > 5) {
     devWarnOnce(
@@ -128,6 +134,7 @@ export function TopBar({
   const hasPlaces = items.length > 0;
   return (
     <header
+      {...rest}
       data-cb-topbar=''
       data-cb-density={density}
       className={cn(
@@ -208,6 +215,7 @@ export function TopBarPlaces({
   phonePlaces = 'icons',
   linkComponent,
   navLabel = 'Places',
+  ...rest
 }: TopBarPlacesProps) {
   const fade = useScrollEdgeFade();
   const wide = useMediaQuery(WIDE_QUERY);
@@ -234,6 +242,7 @@ export function TopBarPlaces({
       </span>
     ) : null}
     <nav
+      {...rest}
       aria-label={navLabel}
       data-cb-topbar-nav=''
       // The design audit's NAV-2 check reads `data-cb-primary-nav`: a router must show its

package/src/react/nav/index.ts

@@ -61,6 +61,10 @@ export {
   NavLink,
   type NavLinkProps,
   type NavNavigationProps,
+  type NavBadge,
+  navBadgeText,
+  navBadgeTone,
+  navBadgeValue,
 } from './navShared.js';
 export { PlaceBar, type PlaceBarProps } from './PlaceBar.js';
 export {
@@ -79,3 +83,4 @@ export {
   type TopBarPlacesProps,
   type TopBarProps,
 } from './TopBar.js';
+export { RailPlaces, type RailPlacesProps } from './RailPlaces.js';