division-ds 0.1.1 → 0.2.0

package/public/docs/components/segmented-control.md

@@ -0,0 +1,124 @@
+# SegmentedControl
+
+> Two to five options in one framed row, with one selected. It changes what's on screen in place. Under the hood it's a radio group: Tab stops on it once, the arrow keys move and select, and the selected option has a signal fill with ink text.
+
+- **Best for:** Switching the view of the same content in place: Board or Table, 24 h or 7 d.
+- **Not for:** Panels of different content: use Tabs. A choice in a form: use Radio.
+- Molecule. Source: `src/components/molecules/segmented-control/SegmentedControl.tsx`
+- Rendered docs page: `/components/segmented-control`
+
+## Import
+
+```tsx
+import { SegmentedControl } from 'src/components/molecules/segmented-control/SegmentedControl'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. Names the group: "View", "Range". |
+| `options` | `readonly SegmentedControlOption[]` |  | Required. Two to five. |
+| `value` | `string` |  | Required. The selected option. |
+| `onValueChange` | `(value: string) => void` |  | Required. Called with the new value. |
+| `size` | `'sm' \| 'md'` | `'md'` | The same height as Button's sm or md. |
+| `className` | `string` |  | Added to the group. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the group. |
+| `value (SegmentedControlOption)` | `string` |  | Required. What onValueChange receives. |
+| `label (SegmentedControlOption)` | `string` |  | Required. Always shown. |
+| `icon (SegmentedControlOption)` | `ReactNode` |  | A lucide icon before the label, aria-hidden so screen readers skip it. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type SegmentedControlOption = {
+  value: string
+  /** Always shown. The icon, if any, sits before it. */
+  label: string
+  /** A lucide icon, aria-hidden: the label names the option. */
+  icon?: ReactNode
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A time range
+
+```tsx
+const RANGES = [
+  { value: '1h', label: '1 h' },
+  { value: '24h', label: '24 h' },
+  { value: '7d', label: '7 d' },
+  { value: '30d', label: '30 d' },
+]
+
+function RangeExample() {
+  const [range, setRange] = useState('24h')
+  return (
+    <div className="flex flex-col items-center gap-3">
+      <SegmentedControl label="Range" options={RANGES} value={range} onValueChange={setRange} />
+      <p className="font-body text-sm text-[var(--color-text-secondary)]">Showing the last {RANGES.find(option => option.value === range)?.label}.</p>
+    </div>
+  )
+}
+
+<RangeExample />
+```
+
+### Small, with icons, lined up with a small Button
+
+```tsx
+function ToolbarExample() {
+  const [view, setView] = useState('board')
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <SegmentedControl
+        label="View"
+        size="sm"
+        options={[
+          { value: 'board', label: 'Board', icon: <Columns3 /> },
+          { value: 'table', label: 'Table', icon: <Table /> },
+        ]}
+        value={view}
+        onValueChange={setView}
+      />
+      <Button size="sm" variant="secondary">
+        Export
+      </Button>
+    </div>
+  )
+}
+
+<ToolbarExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves into the group, onto the selected option, and out again. |
+| `ArrowLeft` `ArrowRight` | Moves to the previous or next option and selects it. Wraps round at the ends. |
+| `ArrowUp` `ArrowDown` | The same as Left and Right. |
+| `Space` | Selects the focused option, if it isn't selected already. |
+
+## Do
+
+- Use it where the change happens straight away and can be undone: the view, a time range, a unit.
+- Keep labels to a word or two; they're set in uppercase monospace.
+- Match the size to the buttons beside it: sm in a busy toolbar, md otherwise.
+
+## Don't
+
+- Don't use it for panels of different content; that's Tabs, which links each tab to its panel.
+- Don't use it for a choice that's sent with a form; that's a RadioGroup inside the form.
+- Don't drop the label. Every option keeps its words, even with an icon.
+
+## Anatomy
+
+- **Group**: A radiogroup named by label, framed with the control hairline. It scrolls sideways if it's too wide.
+- **Option**: A radio with a monospace label and an optional icon, the same height as a Button at sm or md.
+- **Selected option**: Signal fill, ink text, semibold. Its focus ring is drawn in ink.

package/public/docs/components/select.md

@@ -0,0 +1,222 @@
+# Select
+
+> A single choice from a list, shown in a portalled listbox (a pop-up list rendered at the top level of the page, so nothing around it can clip it). Options come in as an array instead of as children, because the trigger, the panel and the look of each row are decisions the system makes once, not per use.
+
+- **Best for:** One choice from a list of about five options or more.
+- **Not for:** Several values: use MultiSelect. Fewer than about five options: use Radio.
+- Atom. Source: `src/components/atoms/select/Select.tsx`
+- Rendered docs page: `/components/select`
+
+## Import
+
+```tsx
+import { Select } from 'src/components/atoms/select/Select'
+```
+
+## Requires
+
+- A <FormField> around it. On its own the control has no label. FormField supplies the label, the help text and the error, and connects their ids so assistive tech (screen readers and similar tools) reads them together.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The trigger’s accessible name, the name a screen reader announces for it. |
+| `options` | `SelectOptionWithIcon[]` |  | { value, label, disabled?, icon? } rows shown in the listbox. Pass this or groups, never both. |
+| `groups` | `SelectGroup[]` |  | { label, options }[]: rows under headings. Pass this or options, never both. |
+| `placeholder` | `string` | `'Select…'` | Shown until a value is chosen. |
+| `value` | `string` |  | The selection, when you control it from outside. Following Radix’s own convention, pass it together with onValueChange. |
+| `defaultValue` | `string` |  | The starting selection, when the select manages it itself (uncontrolled). Pass this or value, never both. |
+| `onValueChange` | `(value: string) => void` |  | Fires with the new value when a row is chosen, whether the select is controlled or uncontrolled. |
+| `disabled` | `boolean` |  | Disables the whole control. |
+| `required` | `boolean` |  | Marks the control as required for form submission. |
+| `name` | `string` |  | The form field name, for native form submission. |
+| `inputSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Matches Input’s sizes so the two line up. |
+| `invalid` | `boolean` | `false` | Sets aria-invalid, which tells assistive tech the field has an error, and shows the invalid border. |
+| `className` | `string` |  | Merged with the trigger’s classes. Later Tailwind utilities (Tailwind is the CSS framework the system uses) win. |
+| `ref` | `Ref<HTMLButtonElement>` |  | Passed through to the trigger button. |
+| `id` | `string` |  | The trigger’s id. FormField sets it. |
+| `aria-describedby` | `string` |  | The ids of the help and error text, set on the trigger so a screen reader reads them with it. FormField sets it. |
+| `triggerProps` | `Omit<ComponentPropsWithoutRef<'button'>, 'aria-label' \| 'aria-invalid' \| 'className'>` |  | Extra props for the visible trigger button, e.g. data-testid. These are separate from the top-level rest, which goes to Radix’s Root (value, onValueChange, disabled, required, name, dir, form…) and never reaches an element on the page. aria-label and aria-invalid are typed away instead of being quietly overridden at runtime, because label and invalid already decide those. |
+| `...rest` | `Omit<Select.Root props, 'children'>, minus every aria-* key and data-testid` |  | Radix’s Root control props only. Every aria-* attribute and data-testid are typed away at the top level, because Root renders no element on the page, and anything that lands there vanishes with no error anywhere. Send them through triggerProps instead. children is typed away because this component renders its own Trigger and Portal. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type SelectOption = { value: string; label: string; disabled?: boolean }
+```
+
+```ts
+/** A Select row: a `SelectOption` plus an optional leading icon. Kept as its own type rather than
+ *  an `icon` field on `SelectOption`, because MultiSelect takes `SelectOption[]` too and renders
+ *  no icons: widening the shared type would let an icon compile there and vanish. */
+export type SelectOptionWithIcon = SelectOption & {
+  /** Leading glyph, aria-hidden: the label names the row. Not repeated in the trigger. */
+  icon?: ReactNode
+}
+```
+
+```ts
+/** A titled run of rows. The heading is not selectable; it names the group for screen readers. */
+export type SelectGroup = { label: string; options: SelectOptionWithIcon[] }
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Placeholder
+
+```tsx
+const SPEED_OPTIONS = [
+  { value: 'standard', label: 'Standard' },
+  { value: 'priority', label: 'Priority' },
+  { value: 'overnight', label: 'Overnight', disabled: true },
+]
+
+<Select label="Dispatch speed" options={SPEED_OPTIONS} placeholder="Choose a speed" />
+```
+
+### With a value
+
+```tsx
+const SPEED_OPTIONS = [
+  { value: 'standard', label: 'Standard' },
+  { value: 'priority', label: 'Priority' },
+  { value: 'overnight', label: 'Overnight', disabled: true },
+]
+
+<Select label="Dispatch speed" options={SPEED_OPTIONS} defaultValue="priority" />
+```
+
+### Groups with headings and icons
+
+```tsx
+const DELIVERY_GROUPS: SelectGroup[] = [
+  {
+    label: 'Courier',
+    options: [
+      { value: 'standard', label: 'Standard', icon: <Truck /> },
+      { value: 'priority', label: 'Priority', icon: <Zap /> },
+    ],
+  },
+  {
+    label: 'Collect',
+    options: [
+      { value: 'depot', label: 'Brasov depot', icon: <Package /> },
+      { value: 'field', label: 'At the field', icon: <Crosshair /> },
+    ],
+  },
+]
+
+<Select label="Delivery" groups={DELIVERY_GROUPS} placeholder="Choose delivery" />
+```
+
+### Sizes
+
+```tsx
+const TERRAIN_OPTIONS = [
+  { value: 'woodland', label: 'Woodland' },
+  { value: 'urban', label: 'Urban' },
+  { value: 'desert', label: 'Desert' },
+  { value: 'indoor', label: 'Indoor' },
+]
+
+<Select label="Terrain (small)" inputSize="sm" options={TERRAIN_OPTIONS} placeholder="Terrain" />
+<Select label="Terrain (medium)" inputSize="md" options={TERRAIN_OPTIONS} placeholder="Terrain" />
+<Select label="Terrain (large)" inputSize="lg" options={TERRAIN_OPTIONS} placeholder="Terrain" />
+```
+
+### Disabled control
+
+```tsx
+const SPEED_OPTIONS = [
+  { value: 'standard', label: 'Standard' },
+  { value: 'priority', label: 'Priority' },
+  { value: 'overnight', label: 'Overnight', disabled: true },
+]
+
+<Select label="Dispatch speed, unavailable" options={SPEED_OPTIONS} defaultValue="standard" disabled />
+```
+
+### Invalid
+
+```tsx
+const SPEED_OPTIONS = [
+  { value: 'standard', label: 'Standard' },
+  { value: 'priority', label: 'Priority' },
+  { value: 'overnight', label: 'Overnight', disabled: true },
+]
+
+<Select label="Dispatch speed" options={SPEED_OPTIONS} invalid placeholder="Choose a speed" />
+```
+
+### Beside an Input
+
+```tsx
+const TERRAIN_OPTIONS = [
+  { value: 'woodland', label: 'Woodland' },
+  { value: 'urban', label: 'Urban' },
+  { value: 'desert', label: 'Desert' },
+  { value: 'indoor', label: 'Indoor' },
+]
+
+<label className="flex flex-col gap-1 text-sm">
+  Call sign
+  <Input placeholder="Anvil-3" />
+</label>
+{/* Deliberately NOT a <label>. A <label> associates with a labelable element — input,
+    select, textarea, button among them — but Radix's trigger is a <button>, and a
+    <label> wrapping a button is inert: it neither names it nor forwards a click. The
+    Select's accessible name comes from its required `label` prop, and the visible text
+    here matches it exactly (SC 2.5.3, label in name). Wrapping it in a <label> would
+    have looked correct and done nothing. */}
+<div className="flex flex-col gap-1 text-sm">
+  <span>Terrain</span>
+  <Select label="Terrain" options={TERRAIN_OPTIONS} placeholder="Choose terrain" />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to the trigger. |
+| `Space` `Enter` | Opens the listbox. |
+| `↑` `↓` | Moves the highlight. |
+| `Home` `End` | Jumps to the first or last option. |
+| `A–Z` | Typeahead: jumps to the first option that starts with the letters you type. |
+| `Enter` | Selects the highlighted option and closes the list. |
+| `Esc` | Closes without selecting and puts focus back on the trigger. |
+
+## Do
+
+- Keep option labels short and written the same way.
+- Use a placeholder that says what’s being chosen.
+- Disable an unavailable option instead of removing it, so the list stops jumping around.
+- Below about five options, use radios instead.
+- Group rows under headings once the list mixes different kinds of thing, and keep each group to a handful.
+- Give every row an icon, or none of them.
+- Wrap it in a FormField for a visible label, help and error. FormField hands it the label.
+
+## Don't
+
+- Don't build a searchable select out of this. That's the command palette's job.
+- Don't use it for several values. That's MultiSelect, which shows each choice as a removable tag.
+- Don't put more than a couple of dozen options in it without search.
+- Don't make a group of one. A heading over a single row is just noise.
+- Don't style the trigger differently from Input. A form with mismatched control heights looks broken.
+- Don't bevel the trigger. It shares Input's frame and draws its own focus ring (the outline that shows which control the keyboard is on), and a cut corner would clip it. The listbox carries the crosshair instead: the shape lives on the surface, not on the control.
+- Don't pass aria-label or aria-invalid through triggerProps. Both are typed away, not overridable, because label and invalid already decide them.
+
+## Anatomy
+
+- **Trigger**: Uses exactly the same frame and styling as Input, so a select and a text field line up in a form.
+- **Value**: Shows the placeholder until something’s chosen.
+- **Content**: Portalled and positioned by Radix, the library of accessible building blocks this sits on. It slides down out of the trigger as it opens (M7; Radix’s Select closes at once, with no exit animation). It’s the one atom that carries the corner crosshair, because it’s a surface framing other content, and that’s what the crosshair marks. It’s also the shape that can’t be cut, since clip-path would clip the crosshair’s arms and the last row’s selection fill along with them.
+- **Item**: Highlighted rows use signal.fill with signal.ink. That’s the fill-selection grammar, the system’s rule for how a selection looks.
+- **ItemIndicator**: A tick on the selected row, so selection isn’t shown by the highlight alone.
+- **Item icon**: Optional. Sits before the label and is aria-hidden, an ARIA (Accessible Rich Internet Applications) attribute that hides it from assistive tech. It follows the row colour, so it turns ink on the highlight. It isn’t shown in the trigger.
+- **Group label**: Used with groups: a mono (monospaced font) heading over its rows that names the group for screen readers. It can’t be selected. A hairline separates the groups.

package/public/docs/components/sheet.md

@@ -0,0 +1,143 @@
+# Sheet
+
+> A dialog that slides in from the side and runs the full height of the screen. Use it for filters, a menu on a narrow screen, or the details of one item next to a list.
+
+- **Best for:** Filters, navigation on a narrow screen, or one item's details next to a list, sliding in from the side.
+- **Not for:** A short confirmation: use Dialog or AlertDialog.
+- Organism. Source: `src/components/organisms/sheet/Sheet.tsx`
+- Rendered docs page: `/components/sheet`
+
+## Import
+
+```tsx
+import { Sheet, SheetClose, SheetContent, SheetTrigger } from 'src/components/organisms/sheet/Sheet'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open (Sheet)` | `boolean` |  | Whether it is open, when your code controls that (controlled mode). |
+| `defaultOpen (Sheet)` | `boolean` | `false` | Whether it starts open, when the component tracks its own state (uncontrolled mode). |
+| `onOpenChange (Sheet)` | `(open: boolean) => void` |  | Called on every open and close, including Escape and a click on the scrim. |
+| `asChild (Trigger)` | `boolean` |  | Uses its single child as the trigger instead of adding its own button. Pass a Button. |
+| `title (Content)` | `string` |  | Required. The visible heading, and the name screen readers say. |
+| `description (Content)` | `string` |  | Shown under the title. Screen readers read it as the accessible description. |
+| `side (Content)` | `'left' \| 'right'` | `'right'` | Which edge the sheet slides in from and stays attached to. |
+| `closeLabel (Content)` | `string` | `'Close'` | What screen readers call the close button. |
+| `className (Content)` | `string` |  | Added to the root classes. Where two Tailwind utility classes clash, the later one wins. |
+| `ref (Content)` | `Ref<HTMLDivElement>` |  | The element with the role dialog. |
+| `ref (Trigger)` | `Ref<HTMLButtonElement>` |  | The trigger button. |
+| `asChild (Close)` | `boolean` |  | Uses its single child as a control that closes the sheet. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Filters on the right
+
+```tsx
+function FiltersOnTheRightExample() {
+  const { toast } = useToast()
+  return (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button variant="secondary">Filter depots</Button>
+      </SheetTrigger>
+      <SheetContent title="Filters" description="Narrow the depot list.">
+        <fieldset className="flex flex-col gap-3">
+          <legend className="font-mono text-xs uppercase tracking-[0.12em] text-[var(--color-text-label)] mb-2">
+            Region
+          </legend>
+          <label className="flex items-center gap-2 min-h-6">
+            <Checkbox /> North
+          </label>
+          <label className="flex items-center gap-2 min-h-6">
+            <Checkbox /> South
+          </label>
+          <label className="flex items-center gap-2 min-h-6">
+            <Checkbox /> East
+          </label>
+          <label className="flex items-center gap-2 min-h-6">
+            <Checkbox /> West
+          </label>
+        </fieldset>
+        <div className="flex flex-wrap gap-3 mt-6">
+          <Button
+            variant="secondary"
+            onClick={() =>
+              toast({
+                title: 'Filters saved',
+                description: 'New depot lists open with these regions.',
+                tone: 'ok',
+              })
+            }
+          >
+            Save as default
+          </Button>
+          <SheetClose asChild>
+            <Button>Apply</Button>
+          </SheetClose>
+        </div>
+      </SheetContent>
+    </Sheet>
+  )
+}
+
+<FiltersOnTheRightExample />
+```
+
+### From the left
+
+```tsx
+const DEPOTS = ['Brasov north', 'Brasov south', 'Sibiu', 'Cluj', 'Timisoara', 'Oradea']
+
+function FromTheLeftExample() {
+  return (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button variant="secondary">Open depot list</Button>
+      </SheetTrigger>
+      <SheetContent side="left" title="Depots">
+        <ul role="list" className="flex flex-col gap-2">
+          {DEPOTS.map(depot => (
+            <li key={depot}>{depot}</li>
+          ))}
+        </ul>
+      </SheetContent>
+    </Sheet>
+  )
+}
+
+<FromTheLeftExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the next control inside the sheet, looping from the last back to the first. |
+| `Shift` `Tab` | Moves back, looping from the first to the last. |
+| `Esc` | Closes it and sends focus back to whatever opened it. |
+
+## Do
+
+- Use the right side for tools that act on the page, and the left for navigation.
+- Keep the apply action at the end of the body, which is where a keyboard user gets to last.
+- Close it after a choice that goes to another page.
+- Show a toast from inside a sheet when it helps. It appears inside the sheet, screen readers can reach it, and Escape still closes the sheet.
+
+## Don't
+
+- Don't put a second sheet on top of a sheet.
+- Don't use a sheet for a two-line confirmation. That's a dialog.
+- Don't hide the only way to reach a page inside a sheet on wide screens.
+
+## Anatomy
+
+- **Scrim**: The dimmed layer over the page, coloured surface.scrim. The page under it is hidden from screen readers and can't take focus. Clicking the scrim closes the sheet.
+- **Surface**: surface.base with a strong hairline border on its inner edge. It's full height, and 24rem wide or the width of the viewport (the visible browser area) minus 2rem. A rem is a unit based on the root text size, usually 16 pixels. Its motion is M7: when it closes, it slides back off its own edge while the scrim fades.
+- **Title**: Required. An h2 (a second-level heading), and the sheet's accessible name, the name screen readers say for it.
+- **Description**: Optional. The accessible description, which screen readers read after the name.
+- **Body**: The part that scrolls. When it is taller than the screen it scrolls on its own, while the title and close button stay put.
+- **Close**: A ghost icon button (no fill, just the icon) in the top right. It comes last when you move through with Tab.

package/public/docs/components/sidebar.md

@@ -0,0 +1,191 @@
+# Sidebar
+
+> The navigation down the side of an app. It holds groups of pages, each page with an icon and an optional count. Groups can fold away, and there is room for a header and an account line.
+
+- **Best for:** App navigation down the side: grouped pages with icons and counts.
+- **Not for:** A site header with a few links: use Navbar.
+- Organism. Source: `src/components/organisms/sidebar/Sidebar.tsx`
+- Rendered docs page: `/components/sidebar`
+
+## Import
+
+```tsx
+import { Sidebar } from 'src/components/organisms/sidebar/Sidebar'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The name screen readers give the navigation region. |
+| `groups` | `SidebarGroup[]` |  | Required. Each group has title, icon, items, collapsible and defaultOpen. |
+| `header` | `ReactNode` |  | Sits above the groups: a product name, a workspace switcher. |
+| `footer` | `ReactNode` |  | Pinned below the groups when the Sidebar has a height (h-full in a column layout): the signed-in account, a help link. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | Pass your router's link component here. Map href to its own prop, and pass className, aria-current and onClick through. |
+| `className` | `string` |  | Added to the root classes. Where two Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLElement>` |  | The nav element. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type SidebarItem = {
+  label: string
+  href: string
+  /** An icon, drawn aria-hidden; the label carries the meaning. */
+  icon?: ReactNode
+  current?: boolean
+  /** A number shown at the end of the item and read as part of its name ("Orders 12"). */
+  count?: number
+}
+```
+
+```ts
+export type SidebarGroup = {
+  /** Also the React key for this group; unique within a Sidebar. */
+  title: string
+  /** Drawn before the title, aria-hidden; the title alone names the group. */
+  icon?: ReactNode
+  items: SidebarItem[]
+  /** @default true */
+  collapsible?: boolean
+  /** Ignored when the group holds the current item, which always starts open. @default true */
+  defaultOpen?: boolean
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Dashboard navigation
+
+```tsx
+const GROUPS: SidebarGroup[] = [
+  {
+    title: 'Operations',
+    icon: <Warehouse />,
+    items: [
+      { label: 'Overview', href: '#overview', icon: <LayoutDashboard /> },
+      { label: 'Orders', href: '#orders', icon: <Package />, current: true, count: 12 },
+      { label: 'Shipments', href: '#shipments', icon: <Truck /> },
+      { label: 'Returns', href: '#returns', icon: <Inbox />, count: 3 },
+    ],
+  },
+  {
+    title: 'Catalogue',
+    icon: <Boxes />,
+    defaultOpen: false,
+    items: [
+      { label: 'Products', href: '#products', icon: <Box /> },
+      { label: 'Inventory', href: '#inventory', icon: <Map /> },
+    ],
+  },
+  {
+    title: 'Account',
+    icon: <UserCog />,
+    collapsible: false,
+    items: [
+      { label: 'Settings', href: '#settings', icon: <Settings /> },
+      { label: 'Team', href: '#team', icon: <Users /> },
+    ],
+  },
+]
+
+const HEADER = <p className="font-display font-semibold">Hexline ops</p>
+
+const FOOTER = <p className="text-xs text-[var(--color-text-secondary)]">Signed in as Ana Pop</p>
+
+<div className="max-w-64">
+  <Sidebar label="Dashboard navigation" groups={GROUPS} header={HEADER} footer={FOOTER} />
+</div>
+```
+
+### In a sheet on a narrow screen: picking a link closes the sheet, through renderLink
+
+```tsx
+const GROUPS: SidebarGroup[] = [
+  {
+    title: 'Operations',
+    icon: <Warehouse />,
+    items: [
+      { label: 'Overview', href: '#overview', icon: <LayoutDashboard /> },
+      { label: 'Orders', href: '#orders', icon: <Package />, current: true, count: 12 },
+      { label: 'Shipments', href: '#shipments', icon: <Truck /> },
+      { label: 'Returns', href: '#returns', icon: <Inbox />, count: 3 },
+    ],
+  },
+  {
+    title: 'Catalogue',
+    icon: <Boxes />,
+    defaultOpen: false,
+    items: [
+      { label: 'Products', href: '#products', icon: <Box /> },
+      { label: 'Inventory', href: '#inventory', icon: <Map /> },
+    ],
+  },
+  {
+    title: 'Account',
+    icon: <UserCog />,
+    collapsible: false,
+    items: [
+      { label: 'Settings', href: '#settings', icon: <Settings /> },
+      { label: 'Team', href: '#team', icon: <Users /> },
+    ],
+  },
+]
+
+const HEADER = <p className="font-display font-semibold">Hexline ops</p>
+
+const FOOTER = <p className="text-xs text-[var(--color-text-secondary)]">Signed in as Ana Pop</p>
+
+const closeOnChoose = ({ onClick, ...props }: LinkRenderProps) => (
+  <SheetClose asChild type={undefined}>
+    <a {...props} onClick={onClick} />
+  </SheetClose>
+)
+
+<Sheet>
+  <SheetTrigger asChild>
+    <Button variant="secondary">Open navigation</Button>
+  </SheetTrigger>
+  <SheetContent side="left" title="Navigation">
+    <Sidebar
+      label="Dashboard navigation, in a sheet"
+      groups={GROUPS}
+      header={HEADER}
+      footer={FOOTER}
+      renderLink={closeOnChoose}
+    />
+  </SheetContent>
+</Sheet>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through each group title that can fold, then each visible item. |
+| `Enter` | Follows an item, or folds and unfolds a group. |
+| `Space` | Folds and unfolds a group. |
+
+## Do
+
+- Only show counts for things that need attention: open orders, not total products.
+- Keep the group that holds the current page open.
+- On a narrow screen, put the whole sidebar in a Sheet behind a button.
+
+## Don't
+
+- Don't nest groups inside groups.
+- Don't show a count of zero. Leave it off.
+- Don't rely on icons alone. Every item keeps its label.
+
+## Anatomy
+
+- **nav**: The navigation region. Screen readers call it by the label prop.
+- **Group title**: A disclosure button (one that shows and hides the list) when the group can fold, plain text when it can't. It's text.secondary, so it still reads on a raised panel. Its list opens and closes by animating its height. Opening also fades and slides each item in, each one a little later than the one before (capped, so a long group never feels slow). Closing fades everything out together, all at once. If someone has asked their system for less motion (prefers-reduced-motion: reduce), both happen instantly.
+- **Item**: An icon, a label and an optional count. The current page gets the fill, plus aria-current, an ARIA attribute (Accessible Rich Internet Applications, the labels screen readers rely on) that tells screen readers this is the page you are on.
+- **Header**: Sits above the groups: a product name, a workspace switcher.
+- **Footer**: Pinned below the groups: the signed-in account, a help link.