@startsimpli/ui 0.4.84 → 0.4.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.84",
+  "version": "0.4.86",
   "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/api": "^0.5.53",
+    "@startsimpli/auth": "^0.4.32"
   },
   "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__/navigation.test.tsx

@@ -1,6 +1,9 @@
-import { render, screen, fireEvent } from '@testing-library/react'
+import { render, screen, fireEvent, within } from '@testing-library/react'
+import { usePathname } from 'next/navigation'
 import { Sidebar, SidebarLayout } from '../sidebar'
 
+const mockPathname = usePathname as unknown as jest.Mock
+
 // next/link and next/navigation are mocked via jest.config.js moduleNameMapper
 
 const sections = [
@@ -161,6 +164,105 @@ describe('Sidebar', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// The rail as PRIMARY nav (startsim-768w.21.3)
+// ---------------------------------------------------------------------------
+
+/**
+ * A control plane puts its whole section list in the rail — a foundry
+ * contributes nine scoped links under a titled group. That promotes the rail
+ * from "app shortcuts" to the thing you navigate with, and a tab strip used to
+ * provide two things for free that the rail owes back:
+ *
+ *  • the current item ANNOUNCED, not just tinted. Colour is not an accessible
+ *    name; `aria-current="page"` is the standard for "you are here".
+ *  • "current" decided by path SEGMENT, not by string prefix.
+ *    '/foundry/x/builds'.startsWith('/foundry/x/build') is true, so a prefix
+ *    test lights up two peer surfaces at once — and the nine foundry sections
+ *    include exactly that pair.
+ *
+ * Plus a section addressable by its title, so a consumer can assert "these
+ * links, under this group" without walking up from a heading — and a pathname
+ * that may legitimately be null (the hook returns null outside an app-router
+ * provider) instead of throwing.
+ */
+describe('Sidebar — which link is current (768w.21.3)', () => {
+  const railLinks = [
+    { href: '/', label: 'Foundries' },
+    { href: '/foundry/mcr/build', label: 'Build with AI' },
+    { href: '/foundry/mcr/builds', label: 'Builds' },
+    { href: '/foundry/mcr/members', label: 'Members' },
+  ]
+
+  const renderAt = (pathname: string | null) => {
+    mockPathname.mockReturnValue(pathname)
+    return render(<Sidebar appName="Foundry" sections={[{ links: railLinks }]} />)
+  }
+
+  const current = () =>
+    screen
+      .getAllByRole('link')
+      .filter((a) => a.getAttribute('aria-current') === 'page')
+      .map((a) => a.getAttribute('href'))
+
+  afterEach(() => {
+    mockPathname.mockReturnValue('/test-path')
+  })
+
+  it('announces the current link with aria-current="page"', () => {
+    renderAt('/foundry/mcr/members')
+    expect(current()).toEqual(['/foundry/mcr/members'])
+  })
+
+  it('does not let a prefix sibling light up too', () => {
+    renderAt('/foundry/mcr/builds')
+    expect(current()).toEqual(['/foundry/mcr/builds'])
+  })
+
+  it('keeps a link current on a deeper URL under it', () => {
+    renderAt('/foundry/mcr/members/u-42')
+    expect(current()).toEqual(['/foundry/mcr/members'])
+  })
+
+  it('marks the root link current only at the root', () => {
+    renderAt('/')
+    expect(current()).toEqual(['/'])
+  })
+
+  it('renders with no current link rather than throwing on a null pathname', () => {
+    // usePathname() is null outside an app-router provider — shared chrome gets
+    // rendered in harnesses and tests that have no router.
+    expect(() => renderAt(null)).not.toThrow()
+    expect(current()).toEqual([])
+  })
+
+  it('still tints the current link, so the marker and the pill agree', () => {
+    renderAt('/foundry/mcr/builds')
+    expect(screen.getByText('Builds').closest('a')).toHaveClass('bg-primary')
+    expect(screen.getByText('Build with AI').closest('a')).not.toHaveClass('bg-primary')
+  })
+})
+
+describe('Sidebar — titled groups (768w.21.3)', () => {
+  const sectionsWithTitle = [
+    { links: [{ href: '/', label: 'Foundries' }] },
+    { title: 'My Copyright', links: [{ href: '/foundry/mcr/members', label: 'Members' }] },
+  ]
+
+  it('exposes a titled section as a group carrying that name', () => {
+    render(<Sidebar appName="Foundry" sections={sectionsWithTitle} />)
+    const group = screen.getByRole('group', { name: 'My Copyright' })
+    expect(within(group).getByRole('link', { name: 'Members' })).toBeInTheDocument()
+    expect(within(group).queryByRole('link', { name: 'Foundries' })).toBeNull()
+  })
+
+  it('keeps the group name while collapsed, when the heading is hidden', () => {
+    render(<Sidebar appName="Foundry" sections={sectionsWithTitle} defaultCollapsed />)
+    expect(screen.queryByText('My Copyright')).toBeNull()
+    expect(screen.getByRole('group', { name: 'My Copyright' })).toBeInTheDocument()
+  })
+})
+
 // ---------------------------------------------------------------------------
 // SidebarLayout
 // ---------------------------------------------------------------------------

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}