division-ds 0.1.2 → 0.2.1

package/public/docs/components/section-heading.md

@@ -0,0 +1,113 @@
+# SectionHeading
+
+> The heading that opens a section of a page: a title under a hairline, with an optional description and an optional action. The page tells it which heading level to use, because only the page knows its own outline.
+
+- **Best for:** Opening a section of a page, at the level that carries on the outline.
+- **Not for:** The page title: use PageHeader.
+- Molecule. Source: `src/components/molecules/section-heading/SectionHeading.tsx`
+- Rendered docs page: `/components/section-heading`
+
+## Import
+
+```tsx
+import { SectionHeading } from 'src/components/molecules/section-heading/SectionHeading'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` |  | Required. The heading text. |
+| `level` | `2 \| 3 \| 4` |  | Required, with no default. The heading level the page outline needs at this point. Leave it out and the code won't compile. |
+| `description` | `ReactNode` |  | One or two sentences under the title. |
+| `action` | `ReactNode` |  | A single control at the end of the row, usually a link to the full list. |
+| `index` | `number` |  | The section's position in a numbered run of sections, drawn above the title. It's decoration and never part of the heading's name. |
+| `id` | `string` |  | Goes on the heading element, not the wrapper, so a section can point aria-labelledby at it (that's how the section gets its name for screen readers). |
+| `className` | `string` |  | Added to the root. Where Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root element. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Title only
+
+```tsx
+<SectionHeading level={4} title="Top-rated replicas" />
+```
+
+### With a description and an action
+
+```tsx
+<SectionHeading
+  level={4}
+  title="Top-rated accessories"
+  description="Optics and parts, ordered by what the reviews say."
+  action={<Link href="#accessories">All accessories</Link>}
+/>
+```
+
+### Numbered, in a run
+
+```tsx
+<div className="flex flex-col gap-10">
+  <SectionHeading level={4} index={1} title="Replicas" description="Three lengths on one receiver." />
+  <SectionHeading level={4} index={2} title="Optics" description="A tube sight and a holo sight." />
+  <SectionHeading
+    level={4}
+    index={3}
+    title="Parts and accessories"
+    action={
+      <Button asChild variant="secondary" size="sm">
+        <a href="#parts">All parts</a>
+      </Button>
+    }
+  />
+</div>
+```
+
+### Naming its section
+
+```tsx
+<section aria-labelledby="section-heading-docs-care">
+  <SectionHeading
+    level={4}
+    id="section-heading-docs-care"
+    title="Care plans"
+    description="The section below is a region named “Care plans”. It takes that name from this heading, which carries the id."
+  />
+  <p className="mt-4 font-body text-sm text-[var(--color-text-primary)]">
+    A chrono check, a tune and upgrade fitting, billed monthly.
+  </p>
+</section>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the action, if there is one. The heading itself isn't a Tab stop. |
+
+## Do
+
+- Pass the level that carries on the page outline: h2 under the page h1, h3 inside an h2 section.
+- Give the heading an id and point the section at it with aria-labelledby, so the region has a name.
+- Name the action after where it goes: "All replicas", not "View all" four times on one page.
+- Number every section in a run, or none of them.
+
+## Don't
+
+- Don't use it as the page title. A page has one h1, and that isn't a section opener.
+- Don't pick a level for its size. The size is the same at every level; the level is about the outline.
+- Don't put more than one control in the action slot. A second one belongs in the section body.
+- Don't stack one straight under another. A section heading opens content, not a second heading.
+
+## Anatomy
+
+- **Rule**: A hairline along the top, in border.hairline-strong. It marks where the section starts.
+- **Index**: Optional. A two-digit number in monospace type, on its own line above the title, and aria-hidden so screen readers skip it. The leading zero is in numeral.pad and the digit in accent.signal.text. It sits above the title, not in front, so the title keeps the same left edge as its description and its section.
+- **Title**: The heading element, h2 to h4 (heading levels 2 to 4). Oxanium, uppercase, 20px (pixels), going up to 24px when the heading has 42rem or more of width.
+- **Description**: Optional. Body text in text.secondary, at most 60 characters a line.
+- **Action**: Optional. One control at the far end of the row. It drops under the text when there isn't room.

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

@@ -0,0 +1,126 @@
+# 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'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## 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,224 @@
+# 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'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## 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 accent.signal.indicator with accent.signal.indicator-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,145 @@
+# 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'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## 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.