@duro-app/ui 0.50.0 → 0.52.0

package/package.json

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

package/src/components/ActionBar/ActionBar.meta.ts

@@ -6,9 +6,10 @@ export const meta: ComponentMeta = {
   whenToUse: [
     'Bulk actions on table selections (delete, revoke, export)',
     'Multi-select workflows where actions apply to all selected items',
+    'Selection-scoped verbs on a canvas/editor surface (set `bottomOffset` to clear any bottom chrome such as zoom controls)',
   ],
   whenNotToUse: [
-    'Single-item actions — use inline buttons or a Menu',
+    'Single-item actions that have an inline home — use inline buttons or a Menu',
     'Persistent toolbars — use Inline with buttons',
   ],
   relatedTo: [

package/src/components/ActionBar/ActionBar.stories.tsx

@@ -11,6 +11,7 @@ interface ActionBarStoryArgs {
   onClearSelection: () => void
   selectedItemCount?: number
   isEmphasized?: boolean
+  bottomOffset?: number
 }
 
 const meta: Meta<ActionBarStoryArgs> = {
@@ -24,6 +25,11 @@ const meta: Meta<ActionBarStoryArgs> = {
       control: 'boolean',
       description: 'Whether the action bar uses the emphasized (inverse) style',
     },
+    bottomOffset: {
+      control: 'number',
+      description:
+        'Distance in px from the bottom of the viewport, for hosts whose bottom edge already carries chrome the bar must clear',
+    },
   },
 }
 
@@ -263,6 +269,35 @@ export const Hidden: Story = {
   render: () => <SelectableTable initialSelected={new Set()} />,
 }
 
+export const BottomOffset: Story = {
+  render: () => (
+    <>
+      <Table.Root>
+        <Table.Header>
+          <Table.Row>
+            <Table.HeaderCell>Name</Table.HeaderCell>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          <Table.Row>
+            <Table.Cell>Hero section</Table.Cell>
+          </Table.Row>
+        </Table.Body>
+      </Table.Root>
+      <ActionBar selectedItemCount={1} bottomOffset={72} onClearSelection={() => {}}>
+        <Button variant="secondary" size="small">
+          Resize
+        </Button>
+      </ActionBar>
+    </>
+  ),
+  play: async () => {
+    const toolbar = document.querySelector('[role="toolbar"]')
+    await expect(toolbar).toBeInTheDocument()
+    await expect(getComputedStyle(toolbar as Element).bottom).toBe('72px')
+  },
+}
+
 export const AllVariants: Story = {
   render: () => (
     <html.div style={storyStyles.wrapper}>

package/src/components/ActionBar/ActionBar.tsx

@@ -14,6 +14,12 @@ export interface ActionBarProps {
   onClearSelection: () => void
   /** Whether the bar can be dismissed. When false, the close button is hidden. @default true */
   dismissible?: boolean
+  /**
+   * Distance in px between the bar and the bottom of the viewport, for hosts
+   * with their own bottom chrome (zoom controls, players) the bar must clear.
+   * Defaults to the spacing.lg token.
+   */
+  bottomOffset?: number
   /** Action buttons to display. */
   children: ReactNode
 }
@@ -24,6 +30,7 @@ function ActionBarContent({
   isEmphasized = false,
   onClearSelection,
   dismissible = true,
+  bottomOffset,
   children,
 }: ActionBarProps) {
   const countStr = selectedItemCount === 'all' ? 'All' : `${selectedItemCount}`
@@ -33,7 +40,11 @@ function ActionBarContent({
     <html.div
       role="toolbar"
       aria-label={label}
-      style={[styles.overlay, isEmphasized && styles.overlayEmphasized]}
+      style={[
+        styles.overlay,
+        bottomOffset != null && styles.overlayOffset(bottomOffset),
+        isEmphasized && styles.overlayEmphasized,
+      ]}
     >
       <html.span style={[styles.selectedCount, isEmphasized && styles.selectedCountEmphasized]}>
         {label}

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

@@ -28,6 +28,9 @@ export const styles = css.create({
     zIndex: 50,
     maxWidth: 'calc(100vw - 48px)',
   },
+  overlayOffset: (bottom: number) => ({
+    bottom,
+  }),
   overlayEmphasized: {
     backgroundColor: colors.accent,
     borderColor: colors.accent,

package/src/components/Icon/Icon.tsx

@@ -21,6 +21,13 @@ export type IconName =
   | 'git-branch'
   | 'menu'
   | 'pin'
+  // Infrastructure / inventory glyphs
+  | 'server'
+  | 'hard-drive'
+  | 'box'
+  | 'image'
+  | 'tag'
+  | 'pie-chart'
   // People / access / admin glyphs
   | 'users'
   | 'user-plus'
@@ -159,6 +166,55 @@ const strokeIcons: Partial<Record<IconName, ReactNode>> = {
       <line x1="3" y1="18" x2="21" y2="18" />
     </>
   ),
+  // ---- infrastructure / inventory ----
+  // Two stacked rack units — hosts, nodes, machines.
+  server: (
+    <>
+      <rect x="2" y="2" width="20" height="8" rx="2" ry="2" />
+      <rect x="2" y="14" width="20" height="8" rx="2" ry="2" />
+      <line x1="6" y1="6" x2="6.01" y2="6" />
+      <line x1="6" y1="18" x2="6.01" y2="18" />
+    </>
+  ),
+  // Disk enclosure — volumes, persistent storage.
+  'hard-drive': (
+    <>
+      <line x1="22" y1="12" x2="2" y2="12" />
+      <path d="M5.45 5.11L2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z" />
+      <line x1="6" y1="16" x2="6.01" y2="16" />
+      <line x1="10" y1="16" x2="10.01" y2="16" />
+    </>
+  ),
+  // Isometric crate — a deployable unit of work.
+  box: (
+    <>
+      <path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z" />
+      <polyline points="3.27 6.96 12 12.01 20.73 6.96" />
+      <line x1="12" y1="22.08" x2="12" y2="12" />
+    </>
+  ),
+  // Picture frame — container images, artefacts.
+  image: (
+    <>
+      <rect x="3" y="3" width="18" height="18" rx="2" ry="2" />
+      <circle cx="8.5" cy="8.5" r="1.5" />
+      <polyline points="21 15 16 10 5 21" />
+    </>
+  ),
+  // Luggage tag — labels, annotations, metadata.
+  tag: (
+    <>
+      <path d="M20.59 13.41l-7.17 7.17a2 2 0 0 1-2.83 0L2 12V2h10l8.59 8.59a2 2 0 0 1 0 2.82z" />
+      <line x1="7" y1="7" x2="7.01" y2="7" />
+    </>
+  ),
+  // Share of a whole — quotas, budgets, utilisation.
+  'pie-chart': (
+    <>
+      <path d="M21.21 15.89A10 10 0 1 1 8 2.83" />
+      <path d="M22 12A10 10 0 0 0 12 2v10z" />
+    </>
+  ),
   // ---- people / access / admin ----
   users: (
     <>

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

@@ -2,31 +2,34 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    '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.',
+    'Vertical side navigation. `Section` is a labelled block that is always open — the default for primary navigation. `Group` is the same block behind a chevron (a disclosure) — reach for it only for a rare/advanced region, an unbounded data-driven list, or a rail long enough that flat stops reading as an overview; mixing the two in one rail is the healthy shape. `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',
+    'App-level sidebar navigation — flat `Section`s, every destination visible',
+    'Settings navigation with labelled regions',
+    '`Group` for a rare or advanced region tucked below the flat sections',
+    '`Group` when the entries are data-driven and unbounded (one per namespace, project, team)',
   ],
   whenNotToUse: [
+    'Collapsing the everyday destinations — a nav advertises where you can go; hiding the common ones behind a chevron costs a click each and removes them from scanning. Use `Section`.',
+    'Arbitrary-depth data browsing (file tree, resource drill-down) — that needs role="tree" with roving tabindex and typeahead, not a deeper SideNav',
     'In-page content switching — use Tabs',
     'Top-level horizontal nav — use Inline with LinkButton',
   ],
   anatomy: {
     required: ['Root', 'Item'],
-    optional: ['Group', 'Section'],
+    optional: ['Section', 'Group'],
   },
   relatedTo: [
     {component: 'Tabs', relationship: 'Tabs switch content in-place; SideNav navigates pages'},
     {component: 'PageShell', relationship: 'Often placed alongside PageShell'},
   ],
   example: `<SideNav.Root defaultValue="identities">
-  {/* Static, always-open sections with icons (flat menu) */}
+  {/* Default: always-open sections. Nothing is a click away from being seen. */}
   <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) */}
+  {/* Disclosure, earned: rarely visited, so it starts collapsed. */}
   <SideNav.Group label="Advanced" defaultExpanded={false}>
     <SideNav.Item value="plugins" icon={<Icon name="plug" size={18} />}>Plugins</SideNav.Item>
   </SideNav.Group>

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

@@ -14,18 +14,21 @@ const meta: Meta<typeof SideNav.Root> = {
 export default meta
 type Story = StoryObj<typeof SideNav.Root>
 
+// The default shape for primary navigation: labelled `Section`s, all open, no
+// chevrons. Every destination is visible and one click away — a nav's job is to
+// advertise where you can go, and a collapsed group does the opposite.
 export const Default: Story = {
   render: (args) => (
     <SideNav.Root {...args} defaultValue="dashboard">
-      <SideNav.Group label="Overview" defaultExpanded>
+      <SideNav.Section label="Overview">
         <SideNav.Item value="dashboard">Dashboard</SideNav.Item>
         <SideNav.Item value="analytics">Analytics</SideNav.Item>
-      </SideNav.Group>
-      <SideNav.Group label="Settings">
+      </SideNav.Section>
+      <SideNav.Section label="Settings">
         <SideNav.Item value="profile">Profile</SideNav.Item>
         <SideNav.Item value="security">Security</SideNav.Item>
         <SideNav.Item value="notifications">Notifications</SideNav.Item>
-      </SideNav.Group>
+      </SideNav.Section>
     </SideNav.Root>
   ),
   play: async ({canvas}) => {
@@ -34,6 +37,62 @@ export const Default: Story = {
 
     const activeItem = canvas.getByRole('button', {name: 'Dashboard'})
     await expect(activeItem).toHaveAttribute('aria-current', 'page')
+
+    // Nothing is hidden: no section is a disclosure, every item is reachable.
+    await expect(canvas.queryByRole('button', {name: 'Settings'})).toBeNull()
+    await expect(canvas.getByRole('button', {name: 'Notifications'})).toBeInTheDocument()
+
+    // Each section names its own group so a screen reader hears "Settings,
+    // group" rather than one undifferentiated run of buttons.
+    const groups = canvas.getAllByRole('group')
+    await expect(groups).toHaveLength(2)
+    await expect(groups[0]).toHaveAccessibleName('Overview')
+    await expect(groups[1]).toHaveAccessibleName('Settings')
+  },
+}
+
+// The healthy mix: flat sections carry the journey, and ONE collapsed Group
+// holds the region you visit rarely. Disclosure is for the seldom-used — never
+// for the everyday.
+export const SectionsWithOneDisclosedGroup: Story = {
+  render: (args) => (
+    <SideNav.Root {...args} defaultValue="identities">
+      <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="Audit">
+        <SideNav.Item value="audit" icon={<Icon name="file-text" size={18} />}>
+          Audit log
+        </SideNav.Item>
+      </SideNav.Section>
+      <SideNav.Group label="Advanced">
+        <SideNav.Item value="plugins" icon={<Icon name="plug" size={18} />}>
+          Plugins
+        </SideNav.Item>
+      </SideNav.Group>
+    </SideNav.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    // Everyday destinations: visible without interaction.
+    await expect(canvas.getByRole('button', {name: 'Identities'})).toBeInTheDocument()
+    await expect(canvas.getByRole('button', {name: 'Audit log'})).toBeInTheDocument()
+
+    // The rare one is disclosed, and says so.
+    const advanced = canvas.getByRole('button', {name: 'Advanced'})
+    await expect(advanced).toHaveAttribute('aria-expanded', 'false')
+    await expect(advanced).not.toHaveAttribute('aria-controls')
+    await expect(canvas.queryByRole('button', {name: 'Plugins'})).toBeNull()
+
+    await userEvent.click(advanced)
+    await expect(advanced).toHaveAttribute('aria-expanded', 'true')
+    const panelId = advanced.getAttribute('aria-controls')
+    await expect(panelId).toBeTruthy()
+    await expect(canvas.getByRole('button', {name: 'Plugins'})).toBeInTheDocument()
   },
 }
 

package/src/components/SideNav/SideNav.tsx

@@ -1,9 +1,35 @@
-import {type ReactNode, useState, useCallback, useRef, useEffect} from 'react'
+import {type ReactNode, useState, useCallback, useRef, useEffect, useId} from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
 import {useControllableValue} from '../../hooks/useControllableValue'
 import {SideNavContext, useSideNav} from './SideNavContext'
 
+/**
+ * SideNav has two ways to chunk a rail, and they are NOT interchangeable.
+ *
+ * `Section` — a labelled block that is always open. This is the DEFAULT for
+ * primary navigation. A nav's job is to advertise where you can go; an
+ * always-open list keeps the whole information architecture scannable and puts
+ * every destination one click away. The uppercase label does the chunking work
+ * on its own — you get the grouping benefit without hiding anything.
+ *
+ * `Group` — the same block behind a chevron (a disclosure). Collapsing costs
+ * every destination inside it an extra click and hides it from scanning, so it
+ * has to buy something back. It does when the region is:
+ *   • rare or advanced ("Advanced", "Danger zone", "Legacy") — disclose the
+ *     seldom-used, never the everyday;
+ *   • unbounded / data-driven (one entry per namespace, project, team) — you
+ *     cannot author-flatten a list whose length you don't control;
+ *   • one of many in a rail long enough (>~30 leaves) that a flat list stops
+ *     reading as an overview.
+ * The healthy shape is a mix: flat Sections for the journey, one collapsed
+ * Group at the bottom.
+ *
+ * Neither is a tree. Arbitrary-depth *data* browsing (a file tree, a
+ * namespace → resource drill-down) needs `role="tree"` with roving tabindex,
+ * typeahead and aria-level — a different component, not a deeper SideNav.
+ */
+
 // --- Root ---
 
 interface RootProps {
@@ -93,6 +119,8 @@ function Group({children, label, groupKey, defaultExpanded}: GroupProps) {
   const {expandedGroups, toggleGroup, expandGroup, activeValue} = useSideNav()
   const isExpanded = expandedGroups.has(key)
   const groupRef = useRef<HTMLDivElement>(null)
+  const triggerId = useId()
+  const panelId = useId()
 
   // Auto-expand if this group contains the active item. Uses expandGroup (not
   // toggleGroup) so it never races the defaultExpanded effect into a closed
@@ -125,9 +153,11 @@ function Group({children, label, groupKey, defaultExpanded}: GroupProps) {
     <html.div ref={groupRef} style={styles.group}>
       <html.button
         type="button"
+        id={triggerId}
         onClick={() => toggleGroup(key)}
         style={[styles.groupTrigger, hasActiveChild && styles.groupTriggerActive]}
         aria-expanded={isExpanded}
+        aria-controls={isExpanded ? panelId : undefined}
       >
         <html.span style={[styles.chevron, isExpanded && styles.chevronOpen]}>
           <svg
@@ -145,7 +175,11 @@ function Group({children, label, groupKey, defaultExpanded}: GroupProps) {
         </html.span>
         {label}
       </html.button>
-      {isExpanded && children}
+      {isExpanded ? (
+        <html.div id={panelId} role="group" aria-labelledby={triggerId} style={styles.items}>
+          {children}
+        </html.div>
+      ) : null}
     </html.div>
   )
 }
@@ -159,15 +193,24 @@ interface SectionProps {
 
 /**
  * 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).
+ * its items below. Unlike `Group` there is no chevron, toggle, or hidden state.
+ *
+ * Reach for this first — see the note at the top of this file for when a
+ * collapsible `Group` is the better call. The label is exposed as the group's
+ * accessible name, so a screen reader announces "Networking, group" on the way
+ * into its items instead of dropping the user into an undifferentiated run of
+ * thirty buttons.
  */
 function Section({children, label}: SectionProps) {
+  const labelId = useId()
   return (
     <html.div style={styles.section}>
-      <html.div style={styles.sectionLabel}>{label}</html.div>
-      {children}
+      <html.div id={labelId} style={styles.sectionLabel}>
+        {label}
+      </html.div>
+      <html.div role="group" aria-labelledby={labelId} style={styles.items}>
+        {children}
+      </html.div>
     </html.div>
   )
 }

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

@@ -51,6 +51,13 @@ export const styles = css.create({
   chevronOpen: {
     transform: 'rotate(90deg)',
   },
+  // The `role="group"` wrapper around a Section's / an expanded Group's items.
+  // Purely structural: it exists to carry the accessible name, so it must not
+  // change how the items stack.
+  items: {
+    display: 'flex',
+    flexDirection: 'column',
+  },
   // Static (non-collapsible) section — see SideNav.Section.
   section: {
     display: 'flex',