@startsimpli/ui 0.4.84 → 0.4.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.84",
+  "version": "0.4.85",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -43,8 +43,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "^0.5.52",
-    "@startsimpli/auth": "^0.4.31"
+    "@startsimpli/auth": "^0.4.31",
+    "@startsimpli/api": "^0.5.51"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/index.ts

@@ -50,10 +50,8 @@ export type {
 // UnifiedTable utils
 export * from './unified-table/utils'
 
-// Export Navigation
-export * from './navigation/sidebar'
-export * from './navigation/app-shell'
-export * from './navigation/grouped-nav'
+// Export Navigation (Sidebar, AppShell, GroupedNav, EntitySwitcher)
+export * from './navigation'
 
 // Workspace layout primitives (SplitPane, DualPaneWorkspace) — generic two-pane shell
 export * from './workspace'

package/src/components/navigation/__tests__/entity-switcher.test.tsx

@@ -0,0 +1,258 @@
+/**
+ * EntitySwitcher — generic searchable "which record am I looking at?" control
+ * (startsim-768w.21.1).
+ *
+ * It is deliberately entity-agnostic: items are `{ id, label, sublabel?, badge? }`,
+ * so the same control switches foundries, companies, projects or workspaces.
+ * These tests pin the contract the rail (and later OrgSwitcher, .21.4) relies on.
+ */
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { EntitySwitcher, type EntitySwitcherItem } from '../entity-switcher'
+
+const items: EntitySwitcherItem[] = [
+  { id: 'acme', label: 'Acme Robotics', sublabel: 'acme' },
+  { id: 'globex', label: 'Globex', sublabel: 'globex-industries' },
+  { id: 'initech', label: 'Initech', sublabel: 'initech', badge: <span data-testid="badge-initech">live</span> },
+]
+
+function setup(props: Partial<React.ComponentProps<typeof EntitySwitcher>> = {}) {
+  const onSelect = jest.fn()
+  const utils = render(
+    <EntitySwitcher items={items} currentId="acme" onSelect={onSelect} {...props} />
+  )
+  return { onSelect, ...utils }
+}
+
+describe('EntitySwitcher — trigger', () => {
+  it("renders the current item's label on the trigger", () => {
+    setup()
+    expect(screen.getByRole('combobox')).toHaveTextContent('Acme Robotics')
+  })
+
+  it('exposes combobox a11y wiring on the trigger', async () => {
+    const user = userEvent.setup()
+    setup()
+    const trigger = screen.getByRole('combobox')
+    expect(trigger).toHaveAttribute('aria-expanded', 'false')
+
+    await user.click(trigger)
+
+    const listbox = await screen.findByRole('listbox')
+    expect(trigger).toHaveAttribute('aria-expanded', 'true')
+    expect(trigger).toHaveAttribute('aria-controls', listbox.id)
+  })
+
+  it('takes a triggerClassName override so it can sit on a dark rail', () => {
+    setup({ triggerClassName: 'my-dark-trigger' })
+    expect(screen.getByRole('combobox')).toHaveClass('my-dark-trigger')
+  })
+})
+
+describe('EntitySwitcher — opening and filtering', () => {
+  it('opening the trigger reveals a labelled filter input and every item', async () => {
+    const user = userEvent.setup()
+    setup()
+
+    await user.click(screen.getByRole('combobox'))
+
+    // Labelled (accessible name), not a bare unlabelled textbox.
+    const filter = await screen.findByRole('textbox', { name: /search|filter/i })
+    expect(filter).toBeInTheDocument()
+
+    const options = screen.getAllByRole('option')
+    expect(options).toHaveLength(3)
+    expect(options.map((o) => o.textContent)).toEqual(
+      expect.arrayContaining([expect.stringContaining('Acme Robotics')])
+    )
+  })
+
+  it('filters on the label, case-insensitively', async () => {
+    const user = userEvent.setup()
+    setup()
+    await user.click(screen.getByRole('combobox'))
+    await user.type(await screen.findByRole('textbox', { name: /search|filter/i }), 'GLOB')
+
+    await waitFor(() => expect(screen.getAllByRole('option')).toHaveLength(1))
+    expect(screen.getByRole('option')).toHaveTextContent('Globex')
+  })
+
+  it('filters on the sublabel too, case-insensitively', async () => {
+    const user = userEvent.setup()
+    setup()
+    await user.click(screen.getByRole('combobox'))
+    // "industries" only appears in Globex's sublabel, never in a label.
+    await user.type(await screen.findByRole('textbox', { name: /search|filter/i }), 'INDUSTRIES')
+
+    await waitFor(() => expect(screen.getAllByRole('option')).toHaveLength(1))
+    expect(screen.getByRole('option')).toHaveTextContent('Globex')
+  })
+
+  it('renders an explicit empty state when nothing matches, not a blank popover', async () => {
+    const user = userEvent.setup()
+    setup({ emptyLabel: 'No foundries match' })
+    await user.click(screen.getByRole('combobox'))
+    await user.type(await screen.findByRole('textbox', { name: /search|filter/i }), 'zzzz')
+
+    await waitFor(() => expect(screen.queryAllByRole('option')).toHaveLength(0))
+    expect(screen.getByText('No foundries match')).toBeInTheDocument()
+  })
+
+  it('hides the filter input when searchable={false}', async () => {
+    const user = userEvent.setup()
+    setup({ searchable: false })
+    await user.click(screen.getByRole('combobox'))
+
+    await screen.findByRole('listbox')
+    expect(screen.queryByRole('textbox')).not.toBeInTheDocument()
+    expect(screen.getAllByRole('option')).toHaveLength(3)
+  })
+
+  it('renders a per-item badge when supplied', async () => {
+    const user = userEvent.setup()
+    setup()
+    await user.click(screen.getByRole('combobox'))
+    expect(await screen.findByTestId('badge-initech')).toBeInTheDocument()
+  })
+
+  // Regression (startsim-768w.21.1.3): the sublabel used to be hard-wired to
+  // `text-muted-foreground`, a colour chosen for `bg-popover`. On the
+  // highlighted row — which paints `bg-accent` — that grey-on-accent measured
+  // 1.1:1 in the browser, i.e. effectively invisible. The sublabel must track
+  // the row's own foreground.
+  it('switches the sublabel to the accent foreground on the highlighted row', async () => {
+    const user = userEvent.setup()
+    setup()
+    await user.click(screen.getByRole('combobox'))
+    await screen.findByRole('listbox')
+
+    const sublabelOf = (name: RegExp) =>
+      screen.getByRole('option', { name }).querySelector('span > span.text-xs')!
+
+    // Opens highlighted on the current item (Acme Robotics).
+    await waitFor(() =>
+      expect(screen.getByRole('option', { name: /Acme Robotics/ })).toHaveAttribute(
+        'data-highlighted',
+        'true'
+      )
+    )
+    expect(sublabelOf(/Acme Robotics/)).toHaveClass('text-accent-foreground/80')
+    expect(sublabelOf(/Acme Robotics/)).not.toHaveClass('text-muted-foreground')
+
+    // ...and the un-highlighted rows keep the muted treatment.
+    expect(sublabelOf(/Globex/)).toHaveClass('text-muted-foreground')
+    expect(sublabelOf(/Globex/)).not.toHaveClass('text-accent-foreground/80')
+
+    // The treatment follows the highlight rather than the selection.
+    await user.keyboard('{ArrowDown}')
+    await waitFor(() =>
+      expect(sublabelOf(/Globex/)).toHaveClass('text-accent-foreground/80')
+    )
+    expect(sublabelOf(/Acme Robotics/)).toHaveClass('text-muted-foreground')
+  })
+})
+
+describe('EntitySwitcher — a11y of the list', () => {
+  it('renders role=listbox with role=option children and marks the current one aria-selected', async () => {
+    const user = userEvent.setup()
+    setup()
+    await user.click(screen.getByRole('combobox'))
+
+    const listbox = await screen.findByRole('listbox')
+    expect(listbox).toBeInTheDocument()
+
+    const options = screen.getAllByRole('option')
+    expect(options).toHaveLength(3)
+    const current = options.find((o) => o.textContent?.includes('Acme Robotics'))!
+    expect(current).toHaveAttribute('aria-selected', 'true')
+    const other = options.find((o) => o.textContent?.includes('Globex'))!
+    expect(other).toHaveAttribute('aria-selected', 'false')
+  })
+})
+
+describe('EntitySwitcher — keyboard', () => {
+  it('ArrowDown/ArrowUp move the highlighted option', async () => {
+    const user = userEvent.setup()
+    setup()
+    await user.click(screen.getByRole('combobox'))
+    const filter = await screen.findByRole('textbox', { name: /search|filter/i })
+
+    // Opens highlighted on the current item (index 0).
+    await waitFor(() =>
+      expect(screen.getByRole('option', { name: /Acme Robotics/ })).toHaveAttribute(
+        'data-highlighted',
+        'true'
+      )
+    )
+    expect(filter).toHaveAttribute(
+      'aria-activedescendant',
+      screen.getByRole('option', { name: /Acme Robotics/ }).id
+    )
+
+    await user.keyboard('{ArrowDown}')
+    await waitFor(() =>
+      expect(screen.getByRole('option', { name: /Globex/ })).toHaveAttribute('data-highlighted', 'true')
+    )
+    expect(screen.getByRole('option', { name: /Acme Robotics/ })).toHaveAttribute(
+      'data-highlighted',
+      'false'
+    )
+
+    await user.keyboard('{ArrowUp}')
+    await waitFor(() =>
+      expect(screen.getByRole('option', { name: /Acme Robotics/ })).toHaveAttribute(
+        'data-highlighted',
+        'true'
+      )
+    )
+  })
+
+  it('Enter selects the highlighted option', async () => {
+    const user = userEvent.setup()
+    const { onSelect } = setup()
+    await user.click(screen.getByRole('combobox'))
+    await screen.findByRole('listbox')
+
+    await user.keyboard('{ArrowDown}')
+    await user.keyboard('{Enter}')
+
+    expect(onSelect).toHaveBeenCalledTimes(1)
+    expect(onSelect).toHaveBeenCalledWith('globex')
+  })
+
+  it('Escape closes the popover and restores focus to the trigger', async () => {
+    const user = userEvent.setup()
+    const { onSelect } = setup()
+    const trigger = screen.getByRole('combobox')
+    await user.click(trigger)
+    await screen.findByRole('listbox')
+
+    await user.keyboard('{Escape}')
+
+    await waitFor(() => expect(screen.queryByRole('listbox')).not.toBeInTheDocument())
+    expect(trigger).toHaveAttribute('aria-expanded', 'false')
+    await waitFor(() => expect(trigger).toHaveFocus())
+    expect(onSelect).not.toHaveBeenCalled()
+  })
+})
+
+describe('EntitySwitcher — selection', () => {
+  it("clicking an item calls onSelect with that item's id and closes", async () => {
+    const user = userEvent.setup()
+    const { onSelect } = setup()
+    await user.click(screen.getByRole('combobox'))
+
+    await user.click(await screen.findByRole('option', { name: /Initech/ }))
+
+    expect(onSelect).toHaveBeenCalledWith('initech')
+    await waitFor(() => expect(screen.queryByRole('listbox')).not.toBeInTheDocument())
+  })
+
+  it('selecting the already-current item still reports it (caller decides to no-op)', async () => {
+    const user = userEvent.setup()
+    const { onSelect } = setup()
+    await user.click(screen.getByRole('combobox'))
+    await user.click(await screen.findByRole('option', { name: /Acme Robotics/ }))
+    expect(onSelect).toHaveBeenCalledWith('acme')
+  })
+})

package/src/components/navigation/__tests__/switcher-slot.test.tsx

@@ -0,0 +1,102 @@
+/**
+ * The Sidebar's contextual `switcher` slot (startsim-768w.21.1).
+ *
+ * Control-plane apps need a "which record am I scoped to?" control mounted in
+ * the rail itself — directly under the brand, above the nav sections — instead
+ * of round-tripping through an index page. The slot is a plain ReactNode so the
+ * rail stays generic; the foundry app passes an <EntitySwitcher>.
+ */
+import { render, screen } from '@testing-library/react'
+import { Sidebar } from '../sidebar'
+import { AppShell } from '../app-shell'
+
+jest.mock('@startsimpli/auth', () => ({
+  __esModule: true,
+  useAuth: () => ({
+    user: { id: 'u1', email: 'q@x.com' },
+    isLoading: false,
+    logout: jest.fn().mockResolvedValue(undefined),
+  }),
+  buildCentralAuthUrl: (flow: string, opts: { app: string }) =>
+    `https://auth.startsimpli.com/${flow}?app=${opts.app}`,
+}))
+
+const sections = [
+  { title: 'Main', links: [{ href: '/', label: 'Dashboard' }] },
+]
+
+/** True when `a` appears before `b` in document order. */
+function precedes(a: Element, b: Element) {
+  // eslint-disable-next-line no-bitwise
+  return Boolean(a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING)
+}
+
+describe('Sidebar switcher slot', () => {
+  it('renders the switcher between the logo and the nav', () => {
+    const { container } = render(
+      <Sidebar
+        appName="Foundry"
+        sections={sections}
+        switcher={<div data-testid="sw">Switcher</div>}
+      />
+    )
+
+    const switcher = screen.getByTestId('sw')
+    const logo = screen.getByText('Foundry')
+    const nav = container.querySelector('nav')!
+
+    expect(switcher).toBeInTheDocument()
+    expect(precedes(logo, switcher)).toBe(true)
+    expect(precedes(switcher, nav)).toBe(true)
+  })
+
+  it('renders nothing when no switcher is supplied (every existing caller is unaffected)', () => {
+    render(<Sidebar appName="Foundry" sections={sections} />)
+    expect(screen.queryByTestId('sw')).not.toBeInTheDocument()
+    expect(screen.getByText('Dashboard')).toBeInTheDocument()
+  })
+
+  it('hides the switcher when the rail is collapsed', () => {
+    render(
+      <Sidebar
+        appName="Foundry"
+        sections={sections}
+        defaultCollapsed
+        switcher={<div data-testid="sw">Switcher</div>}
+      />
+    )
+    expect(screen.queryByTestId('sw')).not.toBeInTheDocument()
+  })
+})
+
+describe('AppShell switcher forwarding', () => {
+  it('forwards the switcher through to the Sidebar rail', () => {
+    const { container } = render(
+      <AppShell
+        app="foundry"
+        appName="Foundry"
+        sections={sections}
+        switcher={<div data-testid="sw">Switcher</div>}
+      >
+        <p>Page content</p>
+      </AppShell>
+    )
+
+    const switcher = screen.getByTestId('sw')
+    const nav = container.querySelector('nav')!
+    expect(switcher).toBeInTheDocument()
+    expect(precedes(screen.getByText('Foundry'), switcher)).toBe(true)
+    expect(precedes(switcher, nav)).toBe(true)
+    expect(screen.getByText('Page content')).toBeInTheDocument()
+  })
+
+  it('renders without a switcher (prop is optional)', () => {
+    render(
+      <AppShell app="foundry" appName="Foundry" sections={sections}>
+        <p>Page content</p>
+      </AppShell>
+    )
+    expect(screen.queryByTestId('sw')).not.toBeInTheDocument()
+    expect(screen.getByText('Page content')).toBeInTheDocument()
+  })
+})

package/src/components/navigation/app-shell.tsx

@@ -36,6 +36,12 @@ export interface AppShellProps {
   appName: string;
   /** Sidebar navigation sections (label + href + optional icon). */
   sections: SidebarSection[];
+  /**
+   * Contextual switcher for the rail, rendered under the brand and above the
+   * nav — e.g. an <EntitySwitcher> over the foundries the user can see.
+   * Optional, so every existing caller is unaffected.
+   */
+  switcher?: ReactNode;
   /** Extra items rendered above "Log out" in the account menu (optional). */
   accountMenuExtra?: ReactNode;
   /** Loading label while the session bootstraps (default "Loading…"). */
@@ -47,6 +53,7 @@ export function AppShell({
   app,
   appName,
   sections,
+  switcher,
   accountMenuExtra,
   loadingLabel = 'Loading…',
   children,
@@ -118,6 +125,7 @@ export function AppShell({
       <Sidebar
         appName={appName}
         sections={sections}
+        switcher={switcher}
         userDropdown={userDropdown}
         collapsible
         collapsed={collapsed}

package/src/components/navigation/entity-switcher.tsx

@@ -0,0 +1,293 @@
+'use client'
+
+/**
+ * EntitySwitcher — a searchable "which record am I scoped to?" control
+ * (startsim-768w.21.1).
+ *
+ * Deliberately entity-agnostic: it takes `{ id, label, sublabel?, badge? }`
+ * items and hands back an id. It knows nothing about companies, foundries,
+ * projects or workspaces, so the same control serves all of them — the caller
+ * maps its domain objects into `EntitySwitcherItem[]`.
+ *
+ * Built on the existing Radix popover + Input primitives; no new dependency.
+ *
+ * Its first consumer is the dark `bg-gray-900` sidebar rail, so the defaults
+ * are translucent-over-dark and inherit the surrounding text colour rather
+ * than hard-coding a light-only look. Anything that doesn't suit a given
+ * surface is overridable via `triggerClassName` / `contentClassName`.
+ *
+ * a11y follows the WAI-ARIA combobox + listbox pattern:
+ *   - trigger is `role="combobox"` with `aria-expanded` / `aria-controls`
+ *   - the list is `role="listbox"`, rows are `role="option"`
+ *   - `aria-selected` marks the *current* entity (what the app is scoped to)
+ *   - `aria-activedescendant` (+ `data-highlighted`) tracks the *keyboard*
+ *     highlight, which moves with ArrowUp/ArrowDown independently of selection
+ */
+
+import * as React from 'react'
+import { Check, ChevronsUpDown } from 'lucide-react'
+import { cn } from '../../lib/utils'
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover'
+import { Input } from '../ui/input'
+
+export interface EntitySwitcherItem {
+  /** Stable identifier handed back to `onSelect`. */
+  id: string
+  /** Primary display text — also the first thing the filter matches on. */
+  label: string
+  /** Secondary line (slug, org, subtitle). Filtered on as well. */
+  sublabel?: string
+  /** Optional trailing adornment (status pill, count, icon). */
+  badge?: React.ReactNode
+}
+
+export interface EntitySwitcherProps {
+  /** Everything the user can switch to. */
+  items: EntitySwitcherItem[]
+  /** The id currently in scope; drives the trigger label + `aria-selected`. */
+  currentId?: string | null
+  /** Fired with the chosen item's id. Fires even when it re-picks `currentId`. */
+  onSelect: (id: string) => void
+  /** Filter input placeholder. */
+  placeholder?: string
+  /** Accessible name for the filter input. */
+  searchLabel?: string
+  /** Shown instead of the list when the filter matches nothing. */
+  emptyLabel?: string
+  /** Trigger text when `currentId` matches no item (or there is none yet). */
+  triggerPlaceholder?: string
+  /** Set false to drop the filter input (short lists). */
+  searchable?: boolean
+  /** Override the trigger chrome — e.g. to sit on a light surface. */
+  triggerClassName?: string
+  /** Override the popover panel chrome (width, padding, colours). */
+  contentClassName?: string
+  /** Disable the whole control. */
+  disabled?: boolean
+}
+
+function optionDomId(baseId: string, itemId: string) {
+  return `${baseId}-opt-${String(itemId).replace(/[^A-Za-z0-9_-]/g, '_')}`
+}
+
+export function EntitySwitcher({
+  items,
+  currentId,
+  onSelect,
+  placeholder = 'Search…',
+  searchLabel = 'Search',
+  emptyLabel = 'No matches',
+  triggerPlaceholder = 'Select…',
+  searchable = true,
+  triggerClassName,
+  contentClassName,
+  disabled,
+}: EntitySwitcherProps) {
+  const baseId = React.useId()
+  const listboxId = `${baseId}-listbox`
+  const inputId = `${baseId}-filter`
+
+  const [open, setOpen] = React.useState(false)
+  const [query, setQuery] = React.useState('')
+  const [highlight, setHighlight] = React.useState(0)
+
+  const inputRef = React.useRef<HTMLInputElement>(null)
+  const listRef = React.useRef<HTMLUListElement>(null)
+
+  const current = items.find((i) => i.id === currentId)
+
+  const filtered = React.useMemo(() => {
+    const q = query.trim().toLowerCase()
+    if (!q) return items
+    return items.filter(
+      (i) =>
+        i.label.toLowerCase().includes(q) ||
+        (i.sublabel ? i.sublabel.toLowerCase().includes(q) : false)
+    )
+  }, [items, query])
+
+  // Keep the highlight inside the (possibly just-filtered) list.
+  React.useEffect(() => {
+    setHighlight((h) => (filtered.length === 0 ? 0 : Math.min(h, filtered.length - 1)))
+  }, [filtered.length])
+
+  const handleOpenChange = (next: boolean) => {
+    setOpen(next)
+    if (next) {
+      setQuery('')
+      // Open on whatever is currently in scope, so Enter is a no-op re-pick
+      // rather than a surprise jump to the first row.
+      const idx = items.findIndex((i) => i.id === currentId)
+      setHighlight(idx >= 0 ? idx : 0)
+    }
+  }
+
+  const choose = (id: string) => {
+    onSelect(id)
+    setOpen(false)
+  }
+
+  const handleKeyDown = (event: React.KeyboardEvent) => {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault()
+      if (filtered.length === 0) return
+      setHighlight((h) => (h + 1) % filtered.length)
+      return
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      if (filtered.length === 0) return
+      setHighlight((h) => (h - 1 + filtered.length) % filtered.length)
+      return
+    }
+    if (event.key === 'Home') {
+      event.preventDefault()
+      setHighlight(0)
+      return
+    }
+    if (event.key === 'End') {
+      event.preventDefault()
+      setHighlight(Math.max(filtered.length - 1, 0))
+      return
+    }
+    if (event.key === 'Enter') {
+      const item = filtered[highlight]
+      if (!item) return
+      event.preventDefault()
+      choose(item.id)
+    }
+    // Escape is left to the popover's dismiss layer, which also restores
+    // focus to the trigger.
+  }
+
+  const activeItem = filtered[highlight]
+  const activeDescendant = activeItem ? optionDomId(baseId, activeItem.id) : undefined
+
+  // Keep the highlighted row in view on long lists.
+  React.useEffect(() => {
+    if (!open || !activeDescendant) return
+    const el = listRef.current?.querySelector<HTMLElement>(`#${CSS.escape(activeDescendant)}`)
+    el?.scrollIntoView?.({ block: 'nearest' })
+  }, [open, activeDescendant])
+
+  return (
+    <Popover open={open} onOpenChange={handleOpenChange}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          role="combobox"
+          aria-expanded={open}
+          aria-controls={listboxId}
+          aria-haspopup="listbox"
+          disabled={disabled}
+          className={cn(
+            'flex w-full items-center justify-between gap-2 rounded-md border border-white/15 bg-white/5 px-3 py-2',
+            'text-left text-sm font-medium text-inherit transition-colors',
+            'hover:bg-white/10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white/40',
+            'disabled:cursor-not-allowed disabled:opacity-50',
+            triggerClassName
+          )}
+        >
+          <span className="min-w-0 flex-1 truncate">{current ? current.label : triggerPlaceholder}</span>
+          <ChevronsUpDown className="h-4 w-4 flex-shrink-0 opacity-60" aria-hidden="true" />
+        </button>
+      </PopoverTrigger>
+
+      <PopoverContent
+        align="start"
+        className={cn('w-64 p-0', contentClassName)}
+        onOpenAutoFocus={(event) => {
+          // Focus the filter (or the list) rather than the panel itself, so the
+          // very first ArrowDown moves the highlight.
+          event.preventDefault()
+          if (searchable) inputRef.current?.focus()
+          else listRef.current?.focus()
+        }}
+        onKeyDown={handleKeyDown}
+      >
+        {searchable && (
+          <div className="border-b p-2">
+            <label className="sr-only" htmlFor={inputId}>
+              {searchLabel}
+            </label>
+            <Input
+              id={inputId}
+              ref={inputRef}
+              type="text"
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              placeholder={placeholder}
+              autoComplete="off"
+              aria-autocomplete="list"
+              aria-controls={listboxId}
+              aria-activedescendant={activeDescendant}
+              className="h-8"
+            />
+          </div>
+        )}
+
+        <ul
+          ref={listRef}
+          id={listboxId}
+          role="listbox"
+          tabIndex={searchable ? -1 : 0}
+          aria-label={searchLabel}
+          aria-activedescendant={searchable ? undefined : activeDescendant}
+          className="max-h-64 overflow-y-auto p-1 outline-none"
+        >
+          {filtered.map((item, index) => {
+            const isCurrent = item.id === currentId
+            const isHighlighted = index === highlight
+            return (
+              <li
+                key={item.id}
+                id={optionDomId(baseId, item.id)}
+                role="option"
+                aria-selected={isCurrent}
+                data-highlighted={isHighlighted}
+                onClick={() => choose(item.id)}
+                onMouseEnter={() => setHighlight(index)}
+                className={cn(
+                  'flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-sm',
+                  isHighlighted && 'bg-accent text-accent-foreground'
+                )}
+              >
+                <Check
+                  className={cn('h-4 w-4 flex-shrink-0', isCurrent ? 'opacity-100' : 'opacity-0')}
+                  aria-hidden="true"
+                />
+                <span className="min-w-0 flex-1">
+                  <span className="block truncate">{item.label}</span>
+                  {item.sublabel && (
+                    <span
+                      className={cn(
+                        'block truncate text-xs',
+                        // The sublabel has to follow the row's foreground, not
+                        // the panel's. `text-muted-foreground` is picked to sit
+                        // on `bg-popover`; left alone it stays that grey when
+                        // the row flips to `bg-accent`, and on a saturated
+                        // accent that lands at ~1.1:1 — browser-verified as
+                        // washed out to the point of unreadable
+                        // (startsim-768w.21.1.3). Dimming the accent foreground
+                        // instead keeps the primary/secondary hierarchy while
+                        // staying legible on whatever accent the theme sets.
+                        isHighlighted ? 'text-accent-foreground/80' : 'text-muted-foreground'
+                      )}
+                    >
+                      {item.sublabel}
+                    </span>
+                  )}
+                </span>
+                {item.badge ? <span className="flex-shrink-0">{item.badge}</span> : null}
+              </li>
+            )
+          })}
+        </ul>
+
+        {filtered.length === 0 && (
+          <div className="px-3 py-6 text-center text-sm text-muted-foreground">{emptyLabel}</div>
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}

package/src/components/navigation/index.ts

@@ -0,0 +1,6 @@
+// Navigation chrome: the app rail, the shell that assembles it, grouped nav
+// sections and the generic entity switcher that scopes the rail.
+export * from './sidebar'
+export * from './app-shell'
+export * from './grouped-nav'
+export * from './entity-switcher'

package/src/components/navigation/sidebar.tsx

@@ -27,6 +27,13 @@ export interface SidebarProps {
    * Navigation sections
    */
   sections: SidebarSection[];
+  /**
+   * Contextual switcher rendered directly under the logo, above the nav —
+   * "which record is this rail scoped to?" (e.g. an <EntitySwitcher> over the
+   * user's foundries). Hidden while collapsed: a 5rem rail can only show a
+   * truncated combobox, which is noise rather than navigation.
+   */
+  switcher?: ReactNode;
   /**
    * User dropdown content (rendered at bottom of sidebar)
    */
@@ -56,6 +63,7 @@ export interface SidebarProps {
 export function Sidebar({
   appName,
   sections,
+  switcher,
   userDropdown,
   className,
   collapsible = true,
@@ -99,6 +107,11 @@ export function Sidebar({
         </Link>
       </div>
 
+      {/* Contextual switcher (scope of this rail) */}
+      {switcher && !collapsed && (
+        <div className="px-4 pt-4">{switcher}</div>
+      )}
+
       {/* Navigation */}
       <nav className="flex-1 overflow-y-auto p-4 space-y-6">
         {sections.map((section, idx) => (