@duro-app/ui 0.40.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -54,7 +54,8 @@
     }
   },
   "dependencies": {
-    "@duro-app/tokens": "^0.40.0"
+    "@tanstack/react-virtual": "^3.14.6",
+    "@duro-app/tokens": "^0.42.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/Icon/Icon.tsx

@@ -21,6 +21,12 @@ export type IconName =
   | 'git-branch'
   | 'menu'
   | 'pin'
+  // People / access / admin glyphs
+  | 'users'
+  | 'user-plus'
+  | 'mail'
+  | 'file-text'
+  | 'plug'
   // Color-mode glyphs
   | 'sun'
   | 'moon'
@@ -153,6 +159,46 @@ const strokeIcons: Partial<Record<IconName, ReactNode>> = {
       <line x1="3" y1="18" x2="21" y2="18" />
     </>
   ),
+  // ---- people / access / admin ----
+  users: (
+    <>
+      <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2" />
+      <circle cx="9" cy="7" r="4" />
+      <path d="M23 21v-2a4 4 0 0 0-3-3.87" />
+      <path d="M16 3.13a4 4 0 0 1 0 7.75" />
+    </>
+  ),
+  'user-plus': (
+    <>
+      <path d="M16 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2" />
+      <circle cx="8.5" cy="7" r="4" />
+      <line x1="20" y1="8" x2="20" y2="14" />
+      <line x1="23" y1="11" x2="17" y2="11" />
+    </>
+  ),
+  mail: (
+    <>
+      <path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z" />
+      <polyline points="22,6 12,13 2,6" />
+    </>
+  ),
+  'file-text': (
+    <>
+      <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+      <polyline points="14 2 14 8 20 8" />
+      <line x1="16" y1="13" x2="8" y2="13" />
+      <line x1="16" y1="17" x2="8" y2="17" />
+      <polyline points="10 9 9 9 8 9" />
+    </>
+  ),
+  plug: (
+    <>
+      <path d="M12 22v-5" />
+      <path d="M9 8V2" />
+      <path d="M15 8V2" />
+      <path d="M18 8v5a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V8Z" />
+    </>
+  ),
   pin: (
     <>
       <line x1="12" y1="17" x2="12" y2="22" />

package/src/components/SideNav/SideNav.meta.ts

@@ -2,27 +2,33 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Vertical side navigation with collapsible groups. Supports controlled and uncontrolled active item. Compound component — Root is required.',
-  whenToUse: ['App-level sidebar navigation', 'Settings navigation with grouped sections'],
+    'Vertical side navigation. Use collapsible `Group`s (chevron accordion) or static `Section`s (always-open headers) — or a mix. `Item`s take an optional `icon` and show an active left-marker. Supports controlled and uncontrolled active item. Compound component — Root is required.',
+  whenToUse: [
+    'App-level sidebar navigation',
+    'Settings navigation with grouped sections',
+    'Flat menu with labelled, always-open regions — use Section instead of Group',
+  ],
   whenNotToUse: [
     'In-page content switching — use Tabs',
     'Top-level horizontal nav — use Inline with LinkButton',
   ],
   anatomy: {
-    required: ['Root', 'Group', 'Item'],
+    required: ['Root', 'Item'],
+    optional: ['Group', 'Section'],
   },
   relatedTo: [
     {component: 'Tabs', relationship: 'Tabs switch content in-place; SideNav navigates pages'},
     {component: 'PageShell', relationship: 'Often placed alongside PageShell'},
   ],
-  example: `<SideNav.Root defaultValue="dashboard">
-  <SideNav.Group label="Main">
-    <SideNav.Item value="dashboard">Dashboard</SideNav.Item>
-    <SideNav.Item value="analytics">Analytics</SideNav.Item>
-  </SideNav.Group>
-  <SideNav.Group label="Settings" defaultExpanded={false}>
-    <SideNav.Item value="profile">Profile</SideNav.Item>
-    <SideNav.Item value="billing">Billing</SideNav.Item>
+  example: `<SideNav.Root defaultValue="identities">
+  {/* Static, always-open sections with icons (flat menu) */}
+  <SideNav.Section label="People & access">
+    <SideNav.Item value="identities" icon={<Icon name="users" size={18} />}>Identities</SideNav.Item>
+    <SideNav.Item value="grants" icon={<Icon name="key" size={18} />}>Grants</SideNav.Item>
+  </SideNav.Section>
+  {/* Or collapsible groups (accordion) */}
+  <SideNav.Group label="Advanced" defaultExpanded={false}>
+    <SideNav.Item value="plugins" icon={<Icon name="plug" size={18} />}>Plugins</SideNav.Item>
   </SideNav.Group>
 </SideNav.Root>`,
 }

package/src/components/SideNav/SideNav.stories.tsx

@@ -1,6 +1,7 @@
 import type {Meta, StoryObj} from '@storybook/react'
 import {expect, fn} from 'storybook/test'
 import {SideNav} from './SideNav'
+import {Icon} from '../Icon/Icon'
 
 const meta: Meta<typeof SideNav.Root> = {
   title: 'Components/SideNav',
@@ -31,7 +32,7 @@ export const Default: Story = {
     const nav = canvas.getByRole('navigation')
     await expect(nav).toBeInTheDocument()
 
-    const activeItem = canvas.getByText('Dashboard')
+    const activeItem = canvas.getByRole('button', {name: 'Dashboard'})
     await expect(activeItem).toHaveAttribute('aria-current', 'page')
   },
 }
@@ -74,7 +75,7 @@ export const DefaultExpandedWithActiveItem: Story = {
   play: async ({canvas}) => {
     const trigger = canvas.getByText('Settings')
     await expect(trigger).toHaveAttribute('aria-expanded', 'true')
-    const active = canvas.getByText('Security')
+    const active = canvas.getByRole('button', {name: 'Security'})
     await expect(active).toBeInTheDocument()
     await expect(active).toHaveAttribute('aria-current', 'page')
   },
@@ -91,9 +92,52 @@ export const Interactive: Story = {
     </SideNav.Root>
   ),
   play: async ({canvas, userEvent, args}) => {
-    const aboutItem = canvas.getByText('About')
+    const aboutItem = canvas.getByRole('button', {name: 'About'})
     await userEvent.click(aboutItem)
     await expect(args.onValueChange).toHaveBeenCalledWith('about')
     await expect(aboutItem).toHaveAttribute('aria-current', 'page')
   },
 }
+
+// Flat menu: static (non-collapsible) Section headers + per-item icons + the
+// active left-marker. This is the AppChrome-style layout — no chevrons, every
+// section always open.
+export const FlatWithIcons: Story = {
+  render: (args) => (
+    <SideNav.Root {...args} defaultValue="grants">
+      <SideNav.Section label="People & access">
+        <SideNav.Item value="identities" icon={<Icon name="users" size={18} />}>
+          Identities
+        </SideNav.Item>
+        <SideNav.Item value="grants" icon={<Icon name="key" size={18} />}>
+          Grants
+        </SideNav.Item>
+      </SideNav.Section>
+      <SideNav.Section label="Requests & invites">
+        <SideNav.Item value="invitations" icon={<Icon name="mail" size={18} />}>
+          Invitations
+        </SideNav.Item>
+        <SideNav.Item value="invites" icon={<Icon name="user-plus" size={18} />}>
+          User Invites
+        </SideNav.Item>
+      </SideNav.Section>
+    </SideNav.Root>
+  ),
+  play: async ({canvas, userEvent, args}) => {
+    // Static section headers render as plain text (no toggle button).
+    await expect(canvas.getByText('People & access')).toBeInTheDocument()
+    await expect(canvas.queryByRole('button', {name: 'People & access'})).toBeNull()
+
+    // All items are visible immediately (nothing is collapsed).
+    const grants = canvas.getByRole('button', {name: 'Grants'})
+    await expect(grants).toHaveAttribute('aria-current', 'page')
+    await expect(canvas.getByRole('button', {name: 'Identities'})).toBeInTheDocument()
+    await expect(canvas.getByRole('button', {name: 'User Invites'})).toBeInTheDocument()
+
+    // Selecting another item moves the active state.
+    const identities = canvas.getByRole('button', {name: 'Identities'})
+    await userEvent.click(identities)
+    await expect(args.onValueChange).toHaveBeenCalledWith('identities')
+    await expect(identities).toHaveAttribute('aria-current', 'page')
+  },
+}

package/src/components/SideNav/SideNav.tsx

@@ -150,14 +150,39 @@ function Group({children, label, groupKey, defaultExpanded}: GroupProps) {
   )
 }
 
+// --- Section ---
+
+interface SectionProps {
+  children: ReactNode
+  label: string
+}
+
+/**
+ * A static, non-collapsible grouping: an always-visible uppercase header with
+ * its items below. Unlike `Group` there is no chevron, toggle, or hidden state
+ * — use it when every section should stay open at a glance (a flat menu with
+ * labelled regions rather than an accordion).
+ */
+function Section({children, label}: SectionProps) {
+  return (
+    <html.div style={styles.section}>
+      <html.div style={styles.sectionLabel}>{label}</html.div>
+      {children}
+    </html.div>
+  )
+}
+
 // --- Item ---
 
 interface ItemProps {
   value: string
   children: ReactNode
+  /** Optional leading glyph (e.g. a design-system `<Icon />`). Inherits the
+   *  item's text color, so it turns accent when the item is active. */
+  icon?: ReactNode
 }
 
-function Item({value, children}: ItemProps) {
+function Item({value, children, icon}: ItemProps) {
   const {activeValue, onSelect, registerItem} = useSideNav()
   const isActive = activeValue === value
 
@@ -173,7 +198,13 @@ function Item({value, children}: ItemProps) {
       style={[styles.item, isActive && styles.itemActive]}
       aria-current={isActive ? 'page' : undefined}
     >
-      {children}
+      <html.span aria-hidden style={[styles.marker, isActive && styles.markerActive]} />
+      {icon ? (
+        <html.span aria-hidden style={styles.itemIcon}>
+          {icon}
+        </html.span>
+      ) : null}
+      <html.span style={styles.itemLabel}>{children}</html.span>
     </html.button>
   )
 }
@@ -181,5 +212,6 @@ function Item({value, children}: ItemProps) {
 export const SideNav = {
   Root,
   Group,
+  Section,
   Item,
 }

package/src/components/SideNav/styles.css.ts

@@ -51,12 +51,31 @@ export const styles = css.create({
   chevronOpen: {
     transform: 'rotate(90deg)',
   },
+  // Static (non-collapsible) section — see SideNav.Section.
+  section: {
+    display: 'flex',
+    flexDirection: 'column',
+  },
+  sectionLabel: {
+    paddingTop: spacing.md,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeXs,
+    fontWeight: typography.fontWeightSemibold,
+    textTransform: 'uppercase' as const,
+    letterSpacing: '0.06em',
+    color: colors.textMuted,
+  },
   item: {
+    position: 'relative',
     display: 'flex',
     alignItems: 'center',
+    gap: spacing.sm,
     paddingTop: '6px',
     paddingBottom: '6px',
-    paddingLeft: spacing.lg,
+    paddingLeft: spacing.md,
     paddingRight: spacing.md,
     fontFamily: typography.fontFamily,
     fontSize: typography.fontSizeSm,
@@ -92,5 +111,36 @@ export const styles = css.create({
   itemActive: {
     color: colors.accent,
     fontWeight: typography.fontWeightMedium,
+    backgroundColor: colors.bgCardHover,
+  },
+  // Active indicator — a bar at the rail's left edge that grows in on select.
+  marker: {
+    position: 'absolute',
+    left: 0,
+    top: '50%',
+    width: '3px',
+    height: 0,
+    transform: 'translateY(-50%)',
+    borderTopRightRadius: radii.full,
+    borderBottomRightRadius: radii.full,
+    backgroundColor: colors.accent,
+    transitionProperty: 'height',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
+  },
+  markerActive: {
+    height: '18px',
+  },
+  itemIcon: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    width: '18px',
+    height: '18px',
+  },
+  itemLabel: {
+    flexGrow: 1,
+    minWidth: 0,
   },
 })

package/src/components/VirtualTable/VirtualTable.meta.ts

@@ -0,0 +1,43 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Sortable data table that windows its rows above a threshold (default 150) with @tanstack/react-virtual, shows a floating position indicator, and reports the visible page so the caller can mirror it in the URL. Below the threshold it renders every row in one scroll (no pagination). URL-decoupled: pass initialPage + onVisiblePageChange. Web-only.',
+  whenToUse: [
+    'Long lists/tables (hundreds to tens of thousands of rows) held client-side',
+    'When you want a scroll position reflected in the URL + a "rows X–Y of Z" indicator',
+    'Admin tables that may grow — small today renders all rows, large windows automatically',
+  ],
+  whenNotToUse: [
+    'Small static tables where semantic markup matters — use Table / Table.FromTanstack',
+    'Server-paginated data (this windows an already-loaded array, it does not fetch on scroll)',
+  ],
+  anatomy: {
+    required: ['data', 'columns'],
+    optional: [
+      'sorting',
+      'onSortingChange',
+      'initialPage',
+      'onVisiblePageChange',
+      'rangeLabel',
+      'onRowClick',
+    ],
+  },
+  relatedTo: [
+    {
+      component: 'Table',
+      relationship: 'Table is semantic + paginated; VirtualTable windows large lists',
+    },
+  ],
+  example: `<VirtualTable
+  data={rows}
+  columns={columns}
+  sorting={sorting}
+  onSortingChange={setSorting}
+  initialPage={Number(params.get('page')) || 1}
+  onVisiblePageChange={({page}) =>
+    setParams((p) => { const n = new URLSearchParams(p); page > 1 ? n.set('page', String(page)) : n.delete('page'); return n }, {replace: true, preventScrollReset: true})}
+  rangeLabel={({from, to, total}) => t('table.range', {from, to, total})}
+  onRowClick={(row) => navigate(\`/things/\${row.id}\`)}
+/>`,
+}

package/src/components/VirtualTable/VirtualTable.stories.tsx

@@ -0,0 +1,89 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn, waitFor} from 'storybook/test'
+import {createColumnHelper} from '@tanstack/react-table'
+import {VirtualTable} from './VirtualTable'
+
+interface Item {
+  id: string
+  name: string
+  value: number
+}
+
+const col = createColumnHelper<Item>()
+const columns = [
+  col.accessor('name', {header: 'Name', enableSorting: true}),
+  col.accessor('value', {header: 'Value', enableSorting: true}),
+]
+
+const makeData = (n: number): Item[] =>
+  Array.from({length: n}, (_, i) => ({id: `r${i}`, name: `Row ${i}`, value: i}))
+
+const meta: Meta<typeof VirtualTable<Item>> = {
+  title: 'Components/VirtualTable',
+  component: VirtualTable,
+  args: {columns, getRowId: (r: Item) => r.id},
+}
+export default meta
+type Story = StoryObj<typeof VirtualTable<Item>>
+
+// Below the threshold: every row rendered, one scroll, no windowing/indicator.
+export const SmallList: Story = {
+  args: {data: makeData(10)},
+  play: async ({canvas}) => {
+    // 1 header row + 10 body rows.
+    await waitFor(() => expect(canvas.getAllByRole('row')).toHaveLength(11))
+    await expect(canvas.getByText('Row 0')).toBeInTheDocument()
+    await expect(canvas.getByText('Row 9')).toBeInTheDocument()
+    // No floating position indicator at this size.
+    await expect(canvas.queryByText(/\/ 10$/)).toBeNull()
+  },
+}
+
+// Above the threshold: only a window of rows hits the DOM + the indicator shows.
+export const Virtualized: Story = {
+  args: {
+    data: makeData(500),
+    maxHeight: 300,
+    rangeLabel: ({from, to, total}) => `${from}-${to} of ${total}`,
+    onVisiblePageChange: fn(),
+  },
+  play: async ({canvas}) => {
+    // Windowed: far fewer than 500 body rows are in the DOM.
+    await waitFor(() => {
+      const rows = canvas.getAllByRole('row')
+      expect(rows.length).toBeGreaterThan(1) // header + some
+      expect(rows.length).toBeLessThan(80) // NOT 501 — proof of windowing
+    })
+    // The floating position indicator is present, starting at row 1.
+    await expect(canvas.getByText(/^1-\d+ of 500$/)).toBeInTheDocument()
+  },
+}
+
+// Scrolling reports a new page (for URL sync) once past a page boundary.
+export const ScrollReportsPage: Story = {
+  args: {
+    data: makeData(500),
+    maxHeight: 300,
+    pageSize: 50,
+    rangeLabel: ({page, pages}) => `page ${page}/${pages}`,
+    onVisiblePageChange: fn(),
+  },
+  play: async ({canvas, args}) => {
+    const scroller = canvas.getByRole('table')
+    await waitFor(() => expect(canvas.getByText('page 1/10')).toBeInTheDocument())
+    // Wait past the 300ms mount suppress-write window (which stops the restore
+    // scroll from clobbering the URL) before scrolling for real.
+    await new Promise((r) => setTimeout(r, 400))
+    // Scroll well past the first 50-row page (row height ~44 → page ≈ 2200px).
+    scroller.scrollTo({top: 6000})
+    scroller.dispatchEvent(new Event('scroll'))
+    // The indicator reflects the new page (proves curPage recomputed on scroll)…
+    await waitFor(() => expect(canvas.queryByText('page 1/10')).toBeNull(), {timeout: 3000})
+    await expect(canvas.getByText(/^page \d+\/10$/).textContent).not.toBe('page 1/10')
+    // …and the visible-page callback fired so a caller could sync the URL.
+    await waitFor(() => expect(args.onVisiblePageChange).toHaveBeenCalled(), {timeout: 4000})
+    const calls = (args.onVisiblePageChange as ReturnType<typeof fn>).mock.calls
+    const maxPage = Math.max(...calls.map((c) => (c[0] as {page: number}).page))
+    await expect(maxPage).toBeGreaterThan(1)
+  },
+}