division-ds 0.2.0 → 0.3.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Division DS: instructions for coding agents
 
-A React 19 + Tailwind 4 + Radix design system: 68 components, tokens in three layers, light and
+A React 19 + Tailwind 4 + Radix design system: 72 components, tokens in three layers, light and
 dark themes, WCAG 2.2 AA. This file is the entry point. It is short on purpose; everything it
 points to is generated from the code, so it is current.
 
@@ -51,7 +51,7 @@ installs these rules into that project's `AGENTS.md`, `GEMINI.md` and Cursor rul
 `.claude/skills/` (Claude Code).
 
 An agent that supports MCP can have the docs and the same checks as tools instead:
-`claude mcp add division-ds -- npx -y division-ds mcp` (`list_components`, `get_component`,
+`claude mcp add division-ds -- npx -y division-ds@0.3.0 mcp` (`list_components`, `get_component`,
 `search`, `get_tokens`, `validate_code`, `check_contrast`, `get_add_command`,
 `get_review_checklist`).
 
@@ -91,7 +91,7 @@ provider. A project that uses the components mounts both itself (step 4 of `inst
 `src/demo/states/` files are not part of the system.
 
 **What the system does not have.** No Popover, no Combobox (single value: use `Select`; several:
-`MultiSelect`), no date picker. Do not reach into `src/demo/` from a component.
+`MultiSelect`). Do not reach into `src/demo/` from a component.
 
 **Vocabulary.** Inside this repository, `npm run check:vocabulary` bans a list of words in `src/`,
 `scripts/` and `e2e/` (the list is `scripts/lib/vocabulary.mjs`; it is not published with the
@@ -116,7 +116,9 @@ The shell paints the page background (`surface.base`) and supplies the gutter; a
 own `max-w-*` and vertical spacing, and no page background. A form or an overlay is the
 exception: it paints `surface.base` on itself, so its field colours never depend on what is
 behind it. In a project that uses the components, your own root does this
-(step 4 of `install.md`).
+(step 4 of `install.md`). Toggle it with `setTheme()` from `src/lib/theme.ts`.
+
+**App navigation.** A few views: `Navbar` (`current: true` on the open one). Many: `Sidebar`.
 
 **Type.** Three families, as utilities: `font-display` (headings, figures), `font-body` (the
 default, set by the shell), `font-mono` (labels, code, tabular numbers). A page title is
@@ -151,6 +153,9 @@ bare and name it through its own `label` prop ("Role for Ilse Varga"). `Switch`,
 renders `ErrorSummary` at the top and focuses it; `useFieldErrors` holds the state (signature in
 `public/docs/helpers.md`).
 
+A `RadioGroup` in a form sits in a `<fieldset>` whose `<legend>` names it (code on the Radio
+page). A date is `DatePicker` in a `FormField`; its value is 'YYYY-MM-DD'.
+
 **Buttons.** Two or more buttons side by side need a parent with a gap
 (`flex flex-wrap gap-3`); `DialogFooter` and `CardFooter` already are one. A `Button` is
 `type="button"` unless you say `type="submit"`. A busy button takes `loading`, not `disabled`.
@@ -188,7 +193,8 @@ Tailwind), and nothing moves on its own: no autoplay.
 
 **Assistant copy.** A button names the action ("Summarize"), never "AI". Say "response", not
 "answer". No "please" or "!" in assistant labels. The interface says "Assistant"; only its own
-messages say "I".
+messages say "I". Response feedback: `ResponseFeedback` in `actions`.
+A value the assistant filled is `aiValue` on that `Input` or `Textarea` only; leaving it accepts it.
 <!-- rules:end -->
 
 ## Changing the system itself

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "division-ds",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Checks a project that uses Division DS components (raw colours, invented tokens, touching buttons, unknown props), and serves the docs and the same checks to agents over MCP.",
   "license": "MIT",
   "author": "Victor Ilioiu",

package/public/docs/components/accordion.md

@@ -13,6 +13,8 @@
 import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'src/components/molecules/accordion/Accordion'
 ```
 
+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 |

package/public/docs/components/ai-label.md

@@ -13,6 +13,8 @@
 import { AiLabel } from 'src/components/atoms/ai-label/AiLabel'
 ```
 
+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 |

package/public/docs/components/alert-dialog.md

@@ -13,6 +13,8 @@
 import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogFooter, AlertDialogTrigger } from 'src/components/organisms/alert-dialog/AlertDialog'
 ```
 
+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 |

package/public/docs/components/alert.md

@@ -13,6 +13,8 @@
 import { Alert } from 'src/components/molecules/alert/Alert'
 ```
 
+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 |

package/public/docs/components/approval-request.md

@@ -13,6 +13,8 @@
 import { ApprovalRequest } from 'src/components/molecules/approval-request/ApprovalRequest'
 ```
 
+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 parent that holds the state and sets it to approved or rejected in onApprove and onReject.

package/public/docs/components/auth-form.md

@@ -13,6 +13,8 @@
 import { AuthForm } from 'src/components/organisms/auth-form/AuthForm'
 ```
 
+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 |

package/public/docs/components/avatar-group.md

@@ -13,6 +13,8 @@
 import { AvatarGroup } from 'src/components/molecules/avatar-group/AvatarGroup'
 ```
 
+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
 
 - With overflowTooltip, the root <TooltipProvider>. AppShell and the demo layout each include one.

package/public/docs/components/avatar.md

@@ -13,6 +13,8 @@
 import { Avatar, avatarVariants, initialsFrom } from 'src/components/atoms/avatar/Avatar'
 ```
 
+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 |

package/public/docs/components/badge.md

@@ -13,6 +13,8 @@
 import { Badge, badgeVariants } from 'src/components/atoms/badge/Badge'
 ```
 
+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 |

package/public/docs/components/breadcrumbs.md

@@ -13,6 +13,8 @@
 import { Breadcrumbs, collapseCrumbs } from 'src/components/molecules/breadcrumbs/Breadcrumbs'
 ```
 
+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 |

package/public/docs/components/button.md

@@ -13,6 +13,8 @@
 import { Button, buttonVariants } from 'src/components/atoms/button/Button'
 ```
 
+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 |

package/public/docs/components/card.md

@@ -13,6 +13,8 @@
 import { Card, CardActions, CardBody, CardDescription, CardFooter, CardHeader, CardMedia, CardTitle, cardLinkClass } from 'src/components/molecules/card/Card'
 ```
 
+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 |

package/public/docs/components/carousel.md

@@ -13,6 +13,8 @@
 import { Carousel } from 'src/components/organisms/carousel/Carousel'
 ```
 
+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 |

package/public/docs/components/cart.md

@@ -13,6 +13,8 @@
 import { Cart } from 'src/components/organisms/cart/Cart'
 ```
 
+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 |

package/public/docs/components/chart-panel.md

@@ -13,6 +13,8 @@
 import { ChartPanel } from 'src/components/organisms/chart-panel/ChartPanel'
 ```
 
+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 |

package/public/docs/components/chat-message.md

@@ -4,6 +4,7 @@
 
 - **Best for:** Each turn inside a ChatThread.
 - **Not for:** Comments or an activity history between people: use Timeline.
+- **Also on this page:** `ResponseFeedback`
 - Molecule. Source: `src/components/molecules/chat-message/ChatMessage.tsx`
 - Rendered docs page: `/components/chat-message`
 
@@ -14,6 +15,8 @@ import { ChatMessage } from 'src/components/molecules/chat-message/ChatMessage'
 import { ResponseFeedback } from 'src/components/molecules/chat-message/ResponseFeedback'
 ```
 
+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 ChatThread around it. Outside one, a message still shows, but nothing announces it when it finishes.

package/public/docs/components/chat-thread.md

@@ -13,6 +13,8 @@
 import { ChatThread } from 'src/components/organisms/chat-thread/ChatThread'
 ```
 
+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 height, because the thread scrolls and the page doesn't. Use h-[28rem], or flex-1 min-h-0 inside a column.

package/public/docs/components/checkbox.md

@@ -13,6 +13,8 @@
 import { Checkbox } from 'src/components/atoms/checkbox/Checkbox'
 ```
 
+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 |

package/public/docs/components/checkout-form.md

@@ -13,6 +13,8 @@
 import { CheckoutForm, DELIVERY_OPTIONS } from 'src/components/organisms/checkout-form/CheckoutForm'
 ```
 
+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 |

package/public/docs/components/command-palette.md

@@ -13,11 +13,13 @@
 import { CommandPalette, filterCommands, groupCommands } from 'src/components/organisms/command-palette/CommandPalette'
 ```
 
+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 |
 |---|---|---|---|
-| `commands` | `Command[]` |  | Required. Each has id, label, group, keywords, shortcut, icon and onSelect. |
+| `commands` | `Command[]` |  | Required. Each has id, label, description (a quieter second line), group, keywords, shortcut, icon and onSelect. |
 | `open` | `boolean` |  | Open state when controlled, meaning your code decides whether it is open. |
 | `defaultOpen` | `boolean` | `false` | Starting open state when uncontrolled, meaning the palette keeps track of it itself. |
 | `onOpenChange` | `(open: boolean) => void` |  | Called on every open and close, including Escape and a click on the scrim (the dimmed backdrop). If you refuse the close, the chosen command stays ready to run until the user does anything else in the palette. Closing it yourself later counts as accepting it. |
@@ -26,6 +28,7 @@ import { CommandPalette, filterCommands, groupCommands } from 'src/components/or
 | `searchLabel` | `string` | `'Search commands'` | The search field's accessible name. |
 | `placeholder` | `string` | `'Type a command or search'` | Shown in the empty search field. |
 | `emptyMessage` | `string` | `'No matching commands'` | Shown when nothing matches the search. |
+| `filter` | `(commands: readonly Command[], query: string) => Command[]` | `filterCommands` | Your own matching and ranking. Gets every command and the query, returns the ones to show in order; groups follow that order. The docs site search uses it to rank with the same scorer as the MCP server. |
 | `ref` | `Ref<HTMLInputElement>` |  | The search field, while the palette is open. |
 
 ## Types and helpers
@@ -36,6 +39,8 @@ Exported beside the component, from the same file. Import a type with `import ty
 export type Command = {
   id: string
   label: string
+  /** A second, quieter line under the label, e.g. what a search result is for. */
+  description?: string
   /** Commands with the same group are drawn together under its heading. */
   group?: string
   /** Extra words a search matches on. */

package/public/docs/components/data-table.md

@@ -13,6 +13,8 @@
 import { DataTable, sortRows } from 'src/components/organisms/data-table/DataTable'
 ```
 
+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 |

package/public/docs/components/date-picker.md

@@ -0,0 +1,166 @@
+# DatePicker
+
+> One date, typed or picked. The field has a segment for the day, the month and the year, in the order your language writes them: type the digits and it moves on by itself, or use the arrow keys. The button inside it opens a calendar. The value is a plain 'YYYY-MM-DD' string with no time zone, so it means the same day for everyone. Calendar and DateField are exported too, for building your own.
+
+- **Best for:** One date: a delivery day, a deadline, a birthday.
+- **Not for:** A range: DateRangePicker. A time: TimeField.
+- **Also on this page:** `Calendar`, `DateField`
+- Molecule. Source: `src/components/molecules/date-picker/DatePicker.tsx`
+- Rendered docs page: `/components/date-picker`
+
+## Import
+
+```tsx
+import { Calendar } from 'src/components/molecules/date-picker/Calendar'
+import { DateField } from 'src/components/molecules/date-picker/DateField'
+import { DatePicker } from 'src/components/molecules/date-picker/DatePicker'
+```
+
+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 field. Inside a FormField, FormField sets it from its own label. |
+| `value` | `string ('YYYY-MM-DD' \| '')` |  | Controlled value (your page holds it). |
+| `defaultValue` | `string` | `''` | Starting value when the picker holds the value itself. |
+| `onValueChange` | `(value: string) => void` |  | Fires with a whole, real date, or '' when the field is emptied. A half-typed date does not fire. |
+| `min` | `string` |  | Earliest date, 'YYYY-MM-DD'. Earlier days are struck through; typing one marks the field invalid. |
+| `max` | `string` |  | Latest date, 'YYYY-MM-DD'. |
+| `isDateDisabled` | `(date: string) => boolean` |  | Days that cannot be picked, such as weekends or holidays. |
+| `locale` | `string` |  | A language tag such as 'en-GB' or 'de'. Sets the segment order, the separator, the month and day names and the first day of the week. Defaults to the browser's. |
+| `weekStartsOn` | `number` |  | 0 Sunday to 6 Saturday. Defaults to the locale's. |
+| `showToday` | `boolean` | `true` | Shows the Today button under the calendar when today can be picked. |
+| `disabled` | `boolean` | `false` | Disables the field and the calendar button. |
+| `name` | `string` |  | Submits the 'YYYY-MM-DD' value with a form, through a hidden input. |
+| `invalid` | `boolean` |  | Marks the field invalid. FormField sets it when there is an error. |
+| `required` | `boolean` |  | Marks the field required. FormField sets it. |
+| `id` | `string` |  | The field's id, so a FormField's error text can point at it. FormField sets it. |
+| `aria-describedby` | `string` |  | The ids of the help and error text. FormField sets it. |
+| `className` | `string` |  | Combined with the field's classes. |
+| `ref` | `Ref<HTMLDivElement>` |  | The field's group element. |
+| `trailing (DateField)` | `ReactNode` |  | Something inside the field after the segments. DatePicker puts its calendar button here. |
+| `bare (DateField)` | `boolean` | `false` | No border, fill or ring of its own, for two dates inside one border (DateRangePicker draws them). |
+| `onSelect (Calendar)` | `(date: string) => void` |  | A day was picked with a click, Enter or Space. |
+| `value (Calendar)` | `string \| null` |  | The picked day. Ignored when dayState is given. |
+| `month (Calendar)` | `string` |  | Any day in the first month shown. Controlled with onMonthChange. |
+| `defaultMonth (Calendar)` | `string` |  | The first month shown when the calendar holds it itself. Defaults to the value's month, or today's. |
+| `onMonthChange (Calendar)` | `(month: string) => void` |  | Fires with the new first month's 1st day. |
+| `dayState (Calendar)` | `(date: string) => 'single' \| 'start' \| 'end' \| 'start-end' \| 'middle' \| undefined` |  | Draws each day yourself, for a range or any other selection. |
+| `onDayEnter (Calendar)` | `(date: string) => void` |  | The keyboard or the pointer moved onto a day. A range uses it to preview the band. |
+| `numberOfMonths (Calendar)` | `1 \| 2` | `1` | Months side by side, stacked on narrow screens. |
+| `autoFocus (Calendar)` | `boolean` | `false` | Moves focus to the picked day, or today, when the calendar appears. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+/** How a day is drawn. `single` is one picked day; the rest belong to a range. */
+export type DayState = 'single' | 'start' | 'end' | 'start-end' | 'middle'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+<div className="w-full max-w-xs">
+  <DatePicker label="Delivery date" />
+</div>
+```
+
+### In a FormField, with help text
+
+```tsx
+<div className="w-full max-w-xs">
+  <FormField label="Trip date" help="Type it, or open the calendar.">
+    <DatePicker label="Trip date" />
+  </FormField>
+</div>
+```
+
+### Controlled: the page holds the value
+
+```tsx
+function Controlled() {
+  const [date, setDate] = useState('2026-11-14')
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-2">
+      <DatePicker label="Dispatch date" value={date} onValueChange={setDate} />
+      <span className="font-mono text-xs text-[var(--color-text-secondary)]">value: {date ? `'${date}'` : "''"}</span>
+    </div>
+  )
+}
+
+<Controlled />
+```
+
+### Limits: weekdays only, within the next two months
+
+```tsx
+const weekend = (date: string) => [0, 6].includes(new Date(`${date}T12:00:00Z`).getUTCDay())
+
+<div className="w-full max-w-xs">
+  <DatePicker label="Collection day" min="2026-11-02" max="2026-12-31" defaultValue="2026-11-16" isDateDisabled={weekend} />
+</div>
+```
+
+### US order and a Sunday start, from the locale
+
+```tsx
+<div className="w-full max-w-xs">
+  <DatePicker label="Ship date" locale="en-US" defaultValue="2026-11-14" />
+</div>
+```
+
+### The calendar on its own
+
+```tsx
+function InlineCalendar() {
+  const [date, setDate] = useState<string | null>(null)
+  return (
+    <div className="flex flex-col gap-2">
+      <Calendar value={date} onSelect={setDate} />
+      <span className="font-mono text-xs text-[var(--color-text-secondary)]">{date ? formatLong(date) : 'No day picked'}</span>
+    </div>
+  )
+}
+
+<InlineCalendar />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `0–9` | Types into the focused segment and moves on once it is full. |
+| `↑` `↓` | In the field: one more or one less in the segment. In the calendar: a week earlier or later. |
+| `←` `→` | In the field: the previous or next segment. In the calendar: the day before or after. |
+| `Backspace` | Clears the segment, or moves back when it is already empty. |
+| `Page Up` `Page Down` | The same day a month earlier or later. With Shift, a year. |
+| `Home` `End` | The first or last day of the week. |
+| `Enter` `Space` | Picks the focused day and closes the calendar. |
+| `Esc` | Closes the calendar without a change. |
+
+## Do
+
+- Store and send the 'YYYY-MM-DD' value as it is. It has no time zone, so it can't shift by a day.
+- Set min and max to the real limits, so days nobody can book are struck through rather than refused after the fact.
+- Wrap it in a FormField for a visible label, help text and errors.
+
+## Don't
+
+- Don't convert the value with new Date('2026-11-14'): that reads it as midnight UTC and can show the day before in the Americas.
+- Don't hide unavailable days. Struck through and announced, they explain themselves.
+- Don't use it for a date of birth without setting max to today.
+
+## Anatomy
+
+- **Field (DateField)**: A group named by the label, holding three spinbuttons (Day, Month, Year). Each says its value or "Empty". A date that does not exist (31 February) or falls outside min and max marks the field invalid.
+- **Calendar button**: A ghost IconButton inside the field. Its name includes the picked date: "Choose date, Saturday, 14 November 2026".
+- **Calendar**: A grid with one tab stop. Each day is a button named with the full date. The picked day is a solid accent square with a cut corner; today has aria-current and a short bar under its number. Days that can't be picked stay visible, struck through and announced as unavailable.
+- **Today**: A secondary Button under the calendar, shown only when today can be picked.

package/public/docs/components/date-presets.md

@@ -0,0 +1,111 @@
+# DatePresets
+
+> Named periods such as Last 7 days, one click each. The defaults: Today, Yesterday, Last 7 days, Last 30 days, This month, Last month, This year, or your own. An add-on: put it in a DateRangePicker's aside and it reads and sets the picker's range by itself, then closes it. On its own it is a list you give a value and an onSelect. Installs DateRangePicker and DatePicker with it.
+
+- **Best for:** Reports and logs, where people want the usual periods.
+- **Not for:** Exact dates: DateRangePicker alone.
+- Molecule. Source: `src/components/molecules/date-presets/DatePresets.tsx`
+- Rendered docs page: `/components/date-presets`
+
+## Import
+
+```tsx
+import { DatePresets, defaultPresets } from 'src/components/molecules/date-presets/DatePresets'
+```
+
+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 |
+|---|---|---|---|
+| `presets` | `DatePreset[]` | `defaultPresets()` | Each { label, range }. Make your own, or start from defaultPresets(today). |
+| `value` | `{ start: string; end: string }` |  | The current range. Inside a DateRangePicker it comes from the picker. |
+| `onSelect` | `(range: DateRange) => void` |  | A preset was chosen. Inside a DateRangePicker the picker also takes it and closes. |
+| `label` | `string` | `'Presets'` | The list's accessible name. |
+| `className` | `string` |  | Combined with the list's classes. |
+| `ref` | `Ref<HTMLDivElement>` |  | The list element. |
+| `defaultPresets()` | `(today?: string) => DatePreset[]` |  | The seven usual periods counted back from today ('YYYY-MM-DD'; defaults to the reader's today). Every one includes today. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type DatePreset = { label: string; range: DateRange }
+```
+
+```ts
+/** The usual periods, counted back from `today` (default: the reader's today). Each includes today. */
+export function defaultPresets(today: IsoDate = todayIso()): DatePreset[]
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Inside a DateRangePicker: no wiring
+
+```tsx
+<div className="w-full max-w-sm">
+  <DateRangePicker label="Activity" aside={<DatePresets />} />
+</div>
+```
+
+### On its own
+
+```tsx
+function OnItsOwn() {
+  const [range, setRange] = useState<DateRange>(defaultPresets()[2].range)
+  return (
+    <div className="flex flex-col gap-3">
+      <DatePresets value={range} onSelect={setRange} />
+      <span className="font-mono text-xs text-[var(--color-text-secondary)]">
+        {range.start} to {range.end}
+      </span>
+    </div>
+  )
+}
+
+<OnItsOwn />
+```
+
+### Your own periods
+
+```tsx
+<div className="w-full max-w-sm">
+  <DateRangePicker
+    label="Season"
+    aside={
+      <DatePresets
+        label="Seasons"
+        presets={[
+          { label: 'Winter 2026', range: { start: '2026-01-01', end: '2026-03-31' } },
+          { label: 'Spring 2026', range: { start: '2026-04-01', end: '2026-06-30' } },
+          { label: 'Summer 2026', range: { start: '2026-07-01', end: '2026-09-30' } },
+        ]}
+      />
+    }
+  />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the presets. |
+| `Enter` `Space` | Chooses the focused preset. |
+
+## Do
+
+- Keep the list short, seven or fewer.
+- Name periods the way your users say them: "This quarter" if they plan in quarters.
+
+## Don't
+
+- Don't offer a preset nobody can pick, such as a future period when max is today.
+
+## Anatomy
+
+- **List**: A group named "Presets". Each period is a button; the one matching the current range is pressed (aria-pressed) and filled.