division-ds 0.2.0 → 0.3.0

package/public/manifest/components.json

@@ -1537,7 +1537,7 @@
           "name": "tone",
           "type": "'signal' | 'ok' | 'warning' | 'hostile'",
           "default": "'signal'",
-          "description": "The fill colour. signal paints accent.signal.fill to match Slider. On the track in light theme that’s a 2.15:1 contrast ratio, below the 3:1 a bar needs when it’s the only sign of progress. So set showValue there."
+          "description": "The fill colour. signal paints accent.signal.indicator to match Slider. On the track in light theme that’s a 2.15:1 contrast ratio, below the 3:1 a bar needs when it’s the only sign of progress. So set showValue there."
         },
         {
           "name": "className",
@@ -1738,7 +1738,7 @@
         }
       ],
       "dos": [
-        "Name the group with aria-label or a FormField legend.",
+        "Name the group: in a form, a fieldset legend that the RadioGroup points at with aria-labelledby; elsewhere, aria-label.",
         "Offer a default when one option really is the norm.",
         "Keep the set short. Past about seven options, use a Select."
       ],
@@ -1747,6 +1747,13 @@
         "Don't put a radio outside a RadioGroup. Both the roving focus and the value come from the group.",
         "Don't make choosing an option perform the action. Put a button after the group."
       ],
+      "pitfalls": [
+        {
+          "wrong": "<FormField label=\"Difficulty\" error={error}>\n  <RadioGroup>\n    <Radio value=\"easy\" />\n  </RadioGroup>\n</FormField>",
+          "right": "<fieldset aria-describedby={error ? 'difficulty-error' : undefined}>\n  <legend id=\"difficulty-label\" className=\"font-mono text-[11px] font-semibold uppercase tracking-[0.12em] text-[var(--color-text-primary)]\">\n    Difficulty\n  </legend>\n  <RadioGroup aria-labelledby=\"difficulty-label\" aria-required=\"true\" value={value} onValueChange={setValue} className=\"mt-2\">\n    {['easy', 'moderate', 'hard'].map(option => (\n      <div key={option} className=\"flex items-center gap-2\">\n        <Radio id={`difficulty-${option}`} value={option} invalid={Boolean(error)} />\n        <label htmlFor={`difficulty-${option}`} className=\"font-body text-sm\">{option}</label>\n      </div>\n    ))}\n  </RadioGroup>\n  {error ? (\n    <p id=\"difficulty-error\" className=\"mt-1.5 font-body text-sm text-[var(--color-accent-hostile-text)]\">{error}</p>\n  ) : null}\n</fieldset>",
+          "why": "FormField clones one control and gives it an id and a label; a group of radios has neither. The fieldset and legend name the group, the label styles match FormField, and the error is linked through aria-describedby. Give ErrorSummary the id of the first Radio so its link lands in the group."
+        }
+      ],
       "anatomy": [
         {
           "part": "RadioGroup",
@@ -2114,7 +2121,7 @@
         },
         {
           "part": "Item",
-          "description": "Highlighted rows use signal.fill with signal.ink. That’s the fill-selection grammar, the system’s rule for how a selection looks."
+          "description": "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."
         },
         {
           "part": "ItemIndicator",
@@ -2446,7 +2453,7 @@
         },
         {
           "part": "Range",
-          "description": "The filled span, in signal.fill."
+          "description": "The filled span, in accent.signal.indicator."
         },
         {
           "part": "Thumb",
@@ -2669,7 +2676,7 @@
         {
           "name": "spinnerVariants",
           "kind": "const",
-          "code": "export const spinnerVariants = cva(\n  // The arc takes `currentColor`, so a caller can recolour it with one text utility: Button does\n  // exactly that, so the arc matches whatever ink the button label is set in.\n  'inline-block shrink-0 text-[var(--color-accent-signal-fill)]',\n  {\n    variants: {\n      size: { sm: 'w-3.5 h-3.5', md: 'w-5 h-5', lg: 'w-6 h-6' },\n    },\n    defaultVariants: { size: 'md' },\n  }\n)",
+          "code": "export const spinnerVariants = cva(\n  // The arc takes `currentColor`, so a caller can recolour it with one text utility: Button does\n  // exactly that, so the arc matches whatever ink the button label is set in.\n  'inline-block shrink-0 text-[var(--color-accent-signal-indicator)]',\n  {\n    variants: {\n      size: { sm: 'w-3.5 h-3.5', md: 'w-5 h-5', lg: 'w-6 h-6' },\n    },\n    defaultVariants: { size: 'md' },\n  }\n)",
           "from": "src/components/atoms/spinner/Spinner"
         }
       ],
@@ -2692,7 +2699,7 @@
         },
         {
           "part": "Ring (ring)",
-          "description": "An SVG (Scalable Vector Graphics) track at 20% of currentColor, which is the surrounding text colour, plus an arc in currentColor. That's accent.signal.fill by default."
+          "description": "An SVG (Scalable Vector Graphics) track at 20% of currentColor, which is the surrounding text colour, plus an arc in currentColor. That's accent.signal.indicator by default."
         },
         {
           "part": "Blocks (conveyor)",
@@ -2843,11 +2850,11 @@
         },
         {
           "part": "Thumb",
-          "description": "A 16px (pixel) square, 3px from the track edge in both states, travelling 22px. Its position is the state signal. It's text.primary when off and accent.signal.fill when on. Held down, it stretches 4px away from the edge it rests on: to the right when off, to the left when on, so it never leaves the track. Flipped, it speeds up across the track, gets a little longer in flight and a little shorter against the far edge, then goes back to its own shape. One give, no bounce."
+          "description": "A 16px (pixel) square, 3px from the track edge in both states, travelling 22px. Its position is the state signal. It's text.primary when off and accent.signal.indicator when on. Held down, it stretches 4px away from the edge it rests on: to the right when off, to the left when on, so it never leaves the track. Flipped, it speeds up across the track, gets a little longer in flight and a little shorter against the far edge, then goes back to its own shape. One give, no bounce."
         },
         {
           "part": "Track fill",
-          "description": "The control fill, on and off. When it's on, only the border turns to signal.fill. The track doesn't fill with the accent, so the thumb is the one thing that changes colour during a flip."
+          "description": "The control fill, on and off. When it's on, only the border turns to accent.signal.indicator. The track doesn't fill with the accent, so the thumb is the one thing that changes colour during a flip."
         }
       ],
       "examples": [
@@ -4227,109 +4234,752 @@
           "description": "Small buttons under an assistant message. They aren't shown on a user message."
         },
         {
-          "name": "className",
+          "name": "className",
+          "type": "string",
+          "description": "Goes on the article."
+        },
+        {
+          "name": "onSubmit (ResponseFeedback)",
+          "type": "(vote: 'helpful' | 'not-helpful') => void | Promise<void>",
+          "description": "Required. Runs on a thumbs up or down. Return a promise to show \"Submitting feedback\" until it settles; a rejection puts the buttons back."
+        },
+        {
+          "name": "onDetail (ResponseFeedback)",
+          "type": "(text: string) => void",
+          "description": "Offers an optional, dismissable \"what was wrong\" box after a Not helpful vote. Leave it out for no such step."
+        },
+        {
+          "name": "className (ResponseFeedback)",
+          "type": "string",
+          "description": "Goes on the group."
+        }
+      ],
+      "api": [
+        {
+          "name": "ChatMessageRole",
+          "kind": "type",
+          "code": "export type ChatMessageRole = 'user' | 'assistant' | 'system'",
+          "from": "src/components/molecules/chat-message/ChatMessage"
+        },
+        {
+          "name": "FeedbackVote",
+          "kind": "type",
+          "code": "export type FeedbackVote = 'helpful' | 'not-helpful'",
+          "from": "src/components/molecules/chat-message/ResponseFeedback"
+        }
+      ],
+      "keyboard": [
+        {
+          "keys": [
+            "Tab"
+          ],
+          "does": "Moves to the controls inside the message: a ToolCall's details, an approval's buttons, the actions."
+        }
+      ],
+      "dos": [
+        "Keep streaming true until the last piece of text has arrived, then set it to false once.",
+        "Put tool calls and approvals in the assistant message where they happened, in order with its text.",
+        "Use a system line for events in the conversation itself: stopped, retried, context cleared.",
+        "Give every message an author, including a system line (\"Status\"). It names the article.",
+        "Put ResponseFeedback in the actions of a generated reply once it has finished streaming, so a vote rates the whole reply."
+      ],
+      "donts": [
+        "Don't animate the text in yourself. useStreamedText or your stream supplies it, and the thread handles announcing it.",
+        "Don't put actions on the person's own message. Editing a sent message is a different flow.",
+        "Don't colour the assistant's text. The bubble, the alignment and the author line already tell the roles apart."
+      ],
+      "pitfalls": [
+        {
+          "wrong": "<ChatMessage role=\"assistant\" author=\"Assistant\">{partial}<span className=\"animate-pulse\">▍</span></ChatMessage>",
+          "right": "<ChatMessage role=\"assistant\" author=\"Assistant\" streaming={!done}>{partial}</ChatMessage>",
+          "why": "streaming sets aria-busy, draws a caret that doesn't blink, and tells the thread to announce the text once, when it's finished. A hand-made blinking caret flashes for the whole stream."
+        }
+      ],
+      "anatomy": [
+        {
+          "part": "Article",
+          "description": "Named by the author line, so a screen reader hears who's speaking first. Has aria-busy while streaming."
+        },
+        {
+          "part": "Author line",
+          "description": "The author as a label in monospaced type, then the time in a <time dateTime> element."
+        },
+        {
+          "part": "Bubble (user)",
+          "description": "The person's words on surface.sunken, aligned right, at most 85% of the width."
+        },
+        {
+          "part": "Body (assistant)",
+          "description": "Full width, with no bubble: text, paragraphs, and ToolCall and ApprovalRequest blocks stacked in a column."
+        },
+        {
+          "part": "Caret",
+          "description": "A solid block in the signal colour after the last paragraph while streaming, drawn with the CSS ::after rule. It never blinks."
+        },
+        {
+          "part": "Actions",
+          "description": "Small buttons under an assistant message: Copy, Retry, and ResponseFeedback (thumbs up and down)."
+        },
+        {
+          "part": "System line",
+          "description": "A centred label in monospaced type between two thin lines: \"Assistant stopped\". Its author is there for screen readers only."
+        }
+      ],
+      "examples": [
+        {
+          "caption": "The three roles",
+          "source": "<div className=\"flex w-full max-w-xl flex-col gap-6\">\n  <ChatMessage role=\"user\" author=\"You\" time=\"2026-10-15T09:40:00+03:00\" timeLabel=\"09:40\">\n    Which replicas are running low at Depot 4?\n  </ChatMessage>\n  <ChatMessage\n    role=\"assistant\"\n    author=\"Assistant\"\n    time=\"2026-10-15T09:40:00+03:00\"\n    timeLabel=\"09:40\"\n    actions={\n      <>\n        <Button size=\"xs\" variant=\"ghost\" iconStart={<Copy />}>\n          Copy\n        </Button>\n        <Button size=\"xs\" variant=\"ghost\" iconStart={<RotateCcw />}>\n          Retry\n        </Button>\n      </>\n    }\n  >\n    Two are under their reorder point: the K-41 field radio (6 left, reorder at 10) and the trail\n    pack (3 left, reorder at 8). Everything else has at least two weeks of cover.\n  </ChatMessage>\n  <ChatMessage role=\"system\" author=\"Status\">\n    Assistant stopped\n  </ChatMessage>\n</div>"
+        },
+        {
+          "caption": "While the reply is still streaming in: aria-busy, an ARIA (Accessible Rich Internet Applications) attribute that tells screen readers the message isn't finished, and a cursor that doesn't blink",
+          "source": "<div className=\"flex w-full max-w-xl flex-col gap-6\">\n  <ChatMessage role=\"assistant\" author=\"Assistant\" streaming>\n    Depot 4 holds 1,240 replicas across 38 lines. The busiest\n  </ChatMessage>\n</div>"
+        },
+        {
+          "caption": "Feedback on a reply: thumbs up or down, one vote, and an optional detail step after Not helpful",
+          "source": "const pretendSend = () => new Promise<void>(resolve => setTimeout(resolve, 800))\n\n<div className=\"flex w-full max-w-xl flex-col gap-6\">\n  <ChatMessage\n    role=\"assistant\"\n    author=\"Assistant\"\n    actions={<ResponseFeedback onSubmit={pretendSend} onDetail={() => {}} />}\n  >\n    Depot 4 holds 1,240 replicas. Eleven are below their reorder point.\n  </ChatMessage>\n</div>"
+        }
+      ]
+    },
+    {
+      "name": "DatePicker",
+      "title": "Date picker",
+      "tier": "molecules",
+      "slug": "date-picker",
+      "summary": "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.",
+      "useWhen": "One date: a delivery day, a deadline, a birthday.",
+      "notFor": "A range: DateRangePicker. A time: TimeField.",
+      "source": "src/components/molecules/date-picker/DatePicker.tsx",
+      "docs": "/docs/components/date-picker.md",
+      "imports": [
+        {
+          "names": [
+            "Calendar"
+          ],
+          "from": "src/components/molecules/date-picker/Calendar"
+        },
+        {
+          "names": [
+            "DateField"
+          ],
+          "from": "src/components/molecules/date-picker/DateField"
+        },
+        {
+          "names": [
+            "DatePicker"
+          ],
+          "from": "src/components/molecules/date-picker/DatePicker"
+        }
+      ],
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "description": "Required. Names the field. Inside a FormField, FormField sets it from its own label."
+        },
+        {
+          "name": "value",
+          "type": "string ('YYYY-MM-DD' | '')",
+          "description": "Controlled value (your page holds it)."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "default": "''",
+          "description": "Starting value when the picker holds the value itself."
+        },
+        {
+          "name": "onValueChange",
+          "type": "(value: string) => void",
+          "description": "Fires with a whole, real date, or '' when the field is emptied. A half-typed date does not fire."
+        },
+        {
+          "name": "min",
+          "type": "string",
+          "description": "Earliest date, 'YYYY-MM-DD'. Earlier days are struck through; typing one marks the field invalid."
+        },
+        {
+          "name": "max",
+          "type": "string",
+          "description": "Latest date, 'YYYY-MM-DD'."
+        },
+        {
+          "name": "isDateDisabled",
+          "type": "(date: string) => boolean",
+          "description": "Days that cannot be picked, such as weekends or holidays."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "description": "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."
+        },
+        {
+          "name": "weekStartsOn",
+          "type": "number",
+          "description": "0 Sunday to 6 Saturday. Defaults to the locale's."
+        },
+        {
+          "name": "showToday",
+          "type": "boolean",
+          "default": "true",
+          "description": "Shows the Today button under the calendar when today can be picked."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "default": "false",
+          "description": "Disables the field and the calendar button."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "description": "Submits the 'YYYY-MM-DD' value with a form, through a hidden input."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "description": "Marks the field invalid. FormField sets it when there is an error."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "description": "Marks the field required. FormField sets it."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "description": "The field's id, so a FormField's error text can point at it. FormField sets it."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "description": "The ids of the help and error text. FormField sets it."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Combined with the field's classes."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "description": "The field's group element."
+        },
+        {
+          "name": "trailing (DateField)",
+          "type": "ReactNode",
+          "description": "Something inside the field after the segments. DatePicker puts its calendar button here."
+        },
+        {
+          "name": "bare (DateField)",
+          "type": "boolean",
+          "default": "false",
+          "description": "No border, fill or ring of its own, for two dates inside one border (DateRangePicker draws them)."
+        },
+        {
+          "name": "onSelect (Calendar)",
+          "type": "(date: string) => void",
+          "description": "A day was picked with a click, Enter or Space."
+        },
+        {
+          "name": "value (Calendar)",
+          "type": "string | null",
+          "description": "The picked day. Ignored when dayState is given."
+        },
+        {
+          "name": "month (Calendar)",
+          "type": "string",
+          "description": "Any day in the first month shown. Controlled with onMonthChange."
+        },
+        {
+          "name": "defaultMonth (Calendar)",
+          "type": "string",
+          "description": "The first month shown when the calendar holds it itself. Defaults to the value's month, or today's."
+        },
+        {
+          "name": "onMonthChange (Calendar)",
+          "type": "(month: string) => void",
+          "description": "Fires with the new first month's 1st day."
+        },
+        {
+          "name": "dayState (Calendar)",
+          "type": "(date: string) => 'single' | 'start' | 'end' | 'start-end' | 'middle' | undefined",
+          "description": "Draws each day yourself, for a range or any other selection."
+        },
+        {
+          "name": "onDayEnter (Calendar)",
+          "type": "(date: string) => void",
+          "description": "The keyboard or the pointer moved onto a day. A range uses it to preview the band."
+        },
+        {
+          "name": "numberOfMonths (Calendar)",
+          "type": "1 | 2",
+          "default": "1",
+          "description": "Months side by side, stacked on narrow screens."
+        },
+        {
+          "name": "autoFocus (Calendar)",
+          "type": "boolean",
+          "default": "false",
+          "description": "Moves focus to the picked day, or today, when the calendar appears."
+        }
+      ],
+      "api": [
+        {
+          "name": "DayState",
+          "kind": "type",
+          "code": "/** How a day is drawn. `single` is one picked day; the rest belong to a range. */\nexport type DayState = 'single' | 'start' | 'end' | 'start-end' | 'middle'",
+          "from": "src/components/molecules/date-picker/Calendar"
+        }
+      ],
+      "keyboard": [
+        {
+          "keys": [
+            "0–9"
+          ],
+          "does": "Types into the focused segment and moves on once it is full."
+        },
+        {
+          "keys": [
+            "↑",
+            "↓"
+          ],
+          "does": "In the field: one more or one less in the segment. In the calendar: a week earlier or later."
+        },
+        {
+          "keys": [
+            "←",
+            "→"
+          ],
+          "does": "In the field: the previous or next segment. In the calendar: the day before or after."
+        },
+        {
+          "keys": [
+            "Backspace"
+          ],
+          "does": "Clears the segment, or moves back when it is already empty."
+        },
+        {
+          "keys": [
+            "Page Up",
+            "Page Down"
+          ],
+          "does": "The same day a month earlier or later. With Shift, a year."
+        },
+        {
+          "keys": [
+            "Home",
+            "End"
+          ],
+          "does": "The first or last day of the week."
+        },
+        {
+          "keys": [
+            "Enter",
+            "Space"
+          ],
+          "does": "Picks the focused day and closes the calendar."
+        },
+        {
+          "keys": [
+            "Esc"
+          ],
+          "does": "Closes the calendar without a change."
+        }
+      ],
+      "dos": [
+        "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."
+      ],
+      "donts": [
+        "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": [
+        {
+          "part": "Field (DateField)",
+          "description": "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."
+        },
+        {
+          "part": "Calendar button",
+          "description": "A ghost IconButton inside the field. Its name includes the picked date: \"Choose date, Saturday, 14 November 2026\"."
+        },
+        {
+          "part": "Calendar",
+          "description": "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."
+        },
+        {
+          "part": "Today",
+          "description": "A secondary Button under the calendar, shown only when today can be picked."
+        }
+      ],
+      "examples": [
+        {
+          "caption": "Default",
+          "source": "<div className=\"w-full max-w-xs\">\n  <DatePicker label=\"Delivery date\" />\n</div>"
+        },
+        {
+          "caption": "In a FormField, with help text",
+          "source": "<div className=\"w-full max-w-xs\">\n  <FormField label=\"Trip date\" help=\"Type it, or open the calendar.\">\n    <DatePicker label=\"Trip date\" />\n  </FormField>\n</div>"
+        },
+        {
+          "caption": "Controlled: the page holds the value",
+          "source": "function Controlled() {\n  const [date, setDate] = useState('2026-11-14')\n  return (\n    <div className=\"flex w-full max-w-xs flex-col gap-2\">\n      <DatePicker label=\"Dispatch date\" value={date} onValueChange={setDate} />\n      <span className=\"font-mono text-xs text-[var(--color-text-secondary)]\">value: {date ? `'${date}'` : \"''\"}</span>\n    </div>\n  )\n}\n\n<Controlled />"
+        },
+        {
+          "caption": "Limits: weekdays only, within the next two months",
+          "source": "const weekend = (date: string) => [0, 6].includes(new Date(`${date}T12:00:00Z`).getUTCDay())\n\n<div className=\"w-full max-w-xs\">\n  <DatePicker label=\"Collection day\" min=\"2026-11-02\" max=\"2026-12-31\" defaultValue=\"2026-11-16\" isDateDisabled={weekend} />\n</div>"
+        },
+        {
+          "caption": "US order and a Sunday start, from the locale",
+          "source": "<div className=\"w-full max-w-xs\">\n  <DatePicker label=\"Ship date\" locale=\"en-US\" defaultValue=\"2026-11-14\" />\n</div>"
+        },
+        {
+          "caption": "The calendar on its own",
+          "source": "function InlineCalendar() {\n  const [date, setDate] = useState<string | null>(null)\n  return (\n    <div className=\"flex flex-col gap-2\">\n      <Calendar value={date} onSelect={setDate} />\n      <span className=\"font-mono text-xs text-[var(--color-text-secondary)]\">{date ? formatLong(date) : 'No day picked'}</span>\n    </div>\n  )\n}\n\n<InlineCalendar />"
+        }
+      ]
+    },
+    {
+      "name": "DatePresets",
+      "title": "Date presets",
+      "tier": "molecules",
+      "slug": "date-presets",
+      "summary": "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.",
+      "useWhen": "Reports and logs, where people want the usual periods.",
+      "notFor": "Exact dates: DateRangePicker alone.",
+      "source": "src/components/molecules/date-presets/DatePresets.tsx",
+      "docs": "/docs/components/date-presets.md",
+      "imports": [
+        {
+          "names": [
+            "DatePresets",
+            "defaultPresets"
+          ],
+          "from": "src/components/molecules/date-presets/DatePresets"
+        }
+      ],
+      "props": [
+        {
+          "name": "presets",
+          "type": "DatePreset[]",
+          "default": "defaultPresets()",
+          "description": "Each { label, range }. Make your own, or start from defaultPresets(today)."
+        },
+        {
+          "name": "value",
+          "type": "{ start: string; end: string }",
+          "description": "The current range. Inside a DateRangePicker it comes from the picker."
+        },
+        {
+          "name": "onSelect",
+          "type": "(range: DateRange) => void",
+          "description": "A preset was chosen. Inside a DateRangePicker the picker also takes it and closes."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "default": "'Presets'",
+          "description": "The list's accessible name."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Combined with the list's classes."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "description": "The list element."
+        },
+        {
+          "name": "defaultPresets()",
+          "type": "(today?: string) => DatePreset[]",
+          "description": "The seven usual periods counted back from today ('YYYY-MM-DD'; defaults to the reader's today). Every one includes today."
+        }
+      ],
+      "api": [
+        {
+          "name": "DatePreset",
+          "kind": "type",
+          "code": "export type DatePreset = { label: string; range: DateRange }",
+          "from": "src/components/molecules/date-presets/DatePresets"
+        },
+        {
+          "name": "defaultPresets",
+          "kind": "function",
+          "code": "/** The usual periods, counted back from `today` (default: the reader's today). Each includes today. */\nexport function defaultPresets(today: IsoDate = todayIso()): DatePreset[]",
+          "from": "src/components/molecules/date-presets/DatePresets"
+        }
+      ],
+      "keyboard": [
+        {
+          "keys": [
+            "Tab"
+          ],
+          "does": "Moves through the presets."
+        },
+        {
+          "keys": [
+            "Enter",
+            "Space"
+          ],
+          "does": "Chooses the focused preset."
+        }
+      ],
+      "dos": [
+        "Keep the list short, seven or fewer.",
+        "Name periods the way your users say them: \"This quarter\" if they plan in quarters."
+      ],
+      "donts": [
+        "Don't offer a preset nobody can pick, such as a future period when max is today."
+      ],
+      "anatomy": [
+        {
+          "part": "List",
+          "description": "A group named \"Presets\". Each period is a button; the one matching the current range is pressed (aria-pressed) and filled."
+        }
+      ],
+      "examples": [
+        {
+          "caption": "Inside a DateRangePicker: no wiring",
+          "source": "<div className=\"w-full max-w-sm\">\n  <DateRangePicker label=\"Activity\" aside={<DatePresets />} />\n</div>"
+        },
+        {
+          "caption": "On its own",
+          "source": "function OnItsOwn() {\n  const [range, setRange] = useState<DateRange>(defaultPresets()[2].range)\n  return (\n    <div className=\"flex flex-col gap-3\">\n      <DatePresets value={range} onSelect={setRange} />\n      <span className=\"font-mono text-xs text-[var(--color-text-secondary)]\">\n        {range.start} to {range.end}\n      </span>\n    </div>\n  )\n}\n\n<OnItsOwn />"
+        },
+        {
+          "caption": "Your own periods",
+          "source": "<div className=\"w-full max-w-sm\">\n  <DateRangePicker\n    label=\"Season\"\n    aside={\n      <DatePresets\n        label=\"Seasons\"\n        presets={[\n          { label: 'Winter 2026', range: { start: '2026-01-01', end: '2026-03-31' } },\n          { label: 'Spring 2026', range: { start: '2026-04-01', end: '2026-06-30' } },\n          { label: 'Summer 2026', range: { start: '2026-07-01', end: '2026-09-30' } },\n        ]}\n      />\n    }\n  />\n</div>"
+        }
+      ]
+    },
+    {
+      "name": "DateRangePicker",
+      "title": "Date range picker",
+      "tier": "molecules",
+      "slug": "date-range-picker",
+      "summary": "A start and an end date in one field, an add-on to DatePicker. Type both, or open two months side by side: the first day you pick is the start, the band follows you to the second, which sets the end and closes the calendar. Put DatePresets in `aside` for one-click periods like Last 7 days. Installs DatePicker with it.",
+      "useWhen": "A booking, a report window, a leave request.",
+      "notFor": "One day: DatePicker.",
+      "source": "src/components/molecules/date-range-picker/DateRangePicker.tsx",
+      "docs": "/docs/components/date-range-picker.md",
+      "imports": [
+        {
+          "names": [
+            "DateRangePicker",
+            "EMPTY_RANGE",
+            "useDateRangePicker"
+          ],
+          "from": "src/components/molecules/date-range-picker/DateRangePicker"
+        }
+      ],
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "description": "Required. Names the field. Inside a FormField, FormField sets it."
+        },
+        {
+          "name": "value",
+          "type": "{ start: string; end: string }",
+          "description": "Controlled range. Each end is 'YYYY-MM-DD' or ''."
+        },
+        {
+          "name": "defaultValue",
+          "type": "{ start: string; end: string }",
+          "default": "{ start: '', end: '' }",
+          "description": "Starting range when the picker holds it itself."
+        },
+        {
+          "name": "onValueChange",
+          "type": "(range: DateRange) => void",
+          "description": "Fires when either end changes. Days picked in the calendar always arrive in order."
+        },
+        {
+          "name": "min",
+          "type": "string",
+          "description": "Earliest date, 'YYYY-MM-DD'."
+        },
+        {
+          "name": "max",
+          "type": "string",
+          "description": "Latest date, 'YYYY-MM-DD'."
+        },
+        {
+          "name": "isDateDisabled",
+          "type": "(date: string) => boolean",
+          "description": "Days that cannot be picked."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "description": "Segment order, names and first day of the week. Defaults to the browser's."
+        },
+        {
+          "name": "weekStartsOn",
+          "type": "number",
+          "description": "0 Sunday to 6 Saturday. Defaults to the locale's."
+        },
+        {
+          "name": "aside",
+          "type": "ReactNode",
+          "description": "Beside the months, in the popover. DatePresets reads and sets the range by itself here."
+        },
+        {
+          "name": "partLabels",
+          "type": "[string, string]",
+          "default": "['Start date', 'End date']",
+          "description": "The names of the two dates."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "default": "false",
+          "description": "Disables both dates and the button."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "description": "Marks the field invalid. FormField sets it."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "description": "Marks both dates required. FormField sets it."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "description": "Submits name-start and name-end with a form."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "description": "The field's id. FormField sets it."
+        },
+        {
+          "name": "aria-describedby",
           "type": "string",
-          "description": "Goes on the article."
+          "description": "The ids of the help and error text. FormField sets it."
         },
         {
-          "name": "onSubmit (ResponseFeedback)",
-          "type": "(vote: 'helpful' | 'not-helpful') => void | Promise<void>",
-          "description": "Required. Runs on a thumbs up or down. Return a promise to show \"Submitting feedback\" until it settles; a rejection puts the buttons back."
+          "name": "className",
+          "type": "string",
+          "description": "Combined with the field's classes."
         },
         {
-          "name": "onDetail (ResponseFeedback)",
-          "type": "(text: string) => void",
-          "description": "Offers an optional, dismissable \"what was wrong\" box after a Not helpful vote. Leave it out for no such step."
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "description": "The field's group element."
         },
         {
-          "name": "className (ResponseFeedback)",
-          "type": "string",
-          "description": "Goes on the group."
+          "name": "useDateRangePicker()",
+          "type": "() => { value: DateRange; select: (range: DateRange) => void } | null",
+          "description": "Inside the popover: the range, and a way to set it and close. For your own aside content."
         }
       ],
       "api": [
         {
-          "name": "ChatMessageRole",
+          "name": "DateRange",
           "kind": "type",
-          "code": "export type ChatMessageRole = 'user' | 'assistant' | 'system'",
-          "from": "src/components/molecules/chat-message/ChatMessage"
+          "code": "/** A start and an end, each 'YYYY-MM-DD' or '' while not chosen. */\nexport type DateRange = { start: IsoDate | ''; end: IsoDate | '' }",
+          "from": "src/components/molecules/date-range-picker/DateRangePicker"
         },
         {
-          "name": "FeedbackVote",
-          "kind": "type",
-          "code": "export type FeedbackVote = 'helpful' | 'not-helpful'",
-          "from": "src/components/molecules/chat-message/ResponseFeedback"
+          "name": "EMPTY_RANGE",
+          "kind": "const",
+          "code": "export const EMPTY_RANGE: DateRange = { start: '', end: '' }",
+          "from": "src/components/molecules/date-range-picker/DateRangePicker"
+        },
+        {
+          "name": "useDateRangePicker",
+          "kind": "const",
+          "code": "/** The open picker's range, and a way to set it and close. DatePresets reads it, so a preset in\n *  `aside` needs no wiring. null outside a DateRangePicker. */\nexport const useDateRangePicker = () => useContext(Context)",
+          "from": "src/components/molecules/date-range-picker/DateRangePicker"
         }
       ],
       "keyboard": [
         {
           "keys": [
-            "Tab"
+            "0–9",
+            "↑",
+            "↓"
           ],
-          "does": "Moves to the controls inside the message: a ToolCall's details, an approval's buttons, the actions."
+          "does": "Types or steps the focused segment of either date."
+        },
+        {
+          "keys": [
+            "←",
+            "→"
+          ],
+          "does": "In the field: the next segment, across both dates. In the calendar: the day before or after, moving the band."
+        },
+        {
+          "keys": [
+            "Page Up",
+            "Page Down"
+          ],
+          "does": "A month earlier or later. With Shift, a year."
+        },
+        {
+          "keys": [
+            "Enter",
+            "Space"
+          ],
+          "does": "Picks the start, then the end, which closes the calendar."
+        },
+        {
+          "keys": [
+            "Esc"
+          ],
+          "does": "Closes the calendar. A start picked without an end stays as the start."
         }
       ],
       "dos": [
-        "Keep streaming true until the last piece of text has arrived, then set it to false once.",
-        "Put tool calls and approvals in the assistant message where they happened, in order with its text.",
-        "Use a system line for events in the conversation itself: stopped, retried, context cleared.",
-        "Give every message an author, including a system line (\"Status\"). It names the article.",
-        "Put ResponseFeedback in the actions of a generated reply once it has finished streaming, so a vote rates the whole reply."
+        "Add DatePresets in aside when people mostly want the usual periods.",
+        "Validate the length yourself if a range has a limit (a 30-day report), and say so in help text."
       ],
       "donts": [
-        "Don't animate the text in yourself. useStreamedText or your stream supplies it, and the thread handles announcing it.",
-        "Don't put actions on the person's own message. Editing a sent message is a different flow.",
-        "Don't colour the assistant's text. The bubble, the alignment and the author line already tell the roles apart."
-      ],
-      "pitfalls": [
-        {
-          "wrong": "<ChatMessage role=\"assistant\" author=\"Assistant\">{partial}<span className=\"animate-pulse\">▍</span></ChatMessage>",
-          "right": "<ChatMessage role=\"assistant\" author=\"Assistant\" streaming={!done}>{partial}</ChatMessage>",
-          "why": "streaming sets aria-busy, draws a caret that doesn't blink, and tells the thread to announce the text once, when it's finished. A hand-made blinking caret flashes for the whole stream."
-        }
+        "Don't use two separate DatePickers for a start and an end: nobody sees the band.",
+        "Don't reorder a typed range for the user; the field marks it invalid so they can see what they typed."
       ],
       "anatomy": [
         {
-          "part": "Article",
-          "description": "Named by the author line, so a screen reader hears who's speaking first. Has aria-busy while streaming."
-        },
-        {
-          "part": "Author line",
-          "description": "The author as a label in monospaced type, then the time in a <time dateTime> element."
-        },
-        {
-          "part": "Bubble (user)",
-          "description": "The person's words on surface.sunken, aligned right, at most 85% of the width."
-        },
-        {
-          "part": "Body (assistant)",
-          "description": "Full width, with no bubble: text, paragraphs, and ToolCall and ApprovalRequest blocks stacked in a column."
+          "part": "Field",
+          "description": "A group named by the label, holding two segmented dates (Start date, End date) and the calendar button. A typed end before the start marks it invalid."
         },
         {
-          "part": "Caret",
-          "description": "A solid block in the signal colour after the last paragraph while streaming, drawn with the CSS ::after rule. It never blinks."
+          "part": "Calendar",
+          "description": "Two months, stacked on narrow screens. The ends are solid accent squares, the days between a light accent band."
         },
         {
-          "part": "Actions",
-          "description": "Small buttons under an assistant message: Copy, Retry, and ResponseFeedback (thumbs up and down)."
+          "part": "Hint",
+          "description": "\"Pick the first day.\" or \"Pick the last day.\", under the months, announced when it changes."
         },
         {
-          "part": "System line",
-          "description": "A centred label in monospaced type between two thin lines: \"Assistant stopped\". Its author is there for screen readers only."
+          "part": "Aside",
+          "description": "An optional column beside the months, for DatePresets."
         }
       ],
       "examples": [
         {
-          "caption": "The three roles",
-          "source": "<div className=\"flex w-full max-w-xl flex-col gap-6\">\n  <ChatMessage role=\"user\" author=\"You\" time=\"2026-10-15T09:40:00+03:00\" timeLabel=\"09:40\">\n    Which replicas are running low at Depot 4?\n  </ChatMessage>\n  <ChatMessage\n    role=\"assistant\"\n    author=\"Assistant\"\n    time=\"2026-10-15T09:40:00+03:00\"\n    timeLabel=\"09:40\"\n    actions={\n      <>\n        <Button size=\"xs\" variant=\"ghost\" iconStart={<Copy />}>\n          Copy\n        </Button>\n        <Button size=\"xs\" variant=\"ghost\" iconStart={<RotateCcw />}>\n          Retry\n        </Button>\n      </>\n    }\n  >\n    Two are under their reorder point: the K-41 field radio (6 left, reorder at 10) and the trail\n    pack (3 left, reorder at 8). Everything else has at least two weeks of cover.\n  </ChatMessage>\n  <ChatMessage role=\"system\" author=\"Status\">\n    Assistant stopped\n  </ChatMessage>\n</div>"
+          "caption": "Default",
+          "source": "<div className=\"w-full max-w-sm\">\n  <DateRangePicker label=\"Stay\" />\n</div>"
         },
         {
-          "caption": "While the reply is still streaming in: aria-busy, an ARIA (Accessible Rich Internet Applications) attribute that tells screen readers the message isn't finished, and a cursor that doesn't blink",
-          "source": "<div className=\"flex w-full max-w-xl flex-col gap-6\">\n  <ChatMessage role=\"assistant\" author=\"Assistant\" streaming>\n    Depot 4 holds 1,240 replicas across 38 lines. The busiest\n  </ChatMessage>\n</div>"
+          "caption": "With DatePresets beside the months",
+          "source": "<div className=\"w-full max-w-sm\">\n  <FormField label=\"Report period\" help=\"Pick a preset, or two days.\">\n    <DateRangePicker label=\"Report period\" aside={<DatePresets />} />\n  </FormField>\n</div>"
         },
         {
-          "caption": "Feedback on a reply: thumbs up or down, one vote, and an optional detail step after Not helpful",
-          "source": "const pretendSend = () => new Promise<void>(resolve => setTimeout(resolve, 800))\n\n<div className=\"flex w-full max-w-xl flex-col gap-6\">\n  <ChatMessage\n    role=\"assistant\"\n    author=\"Assistant\"\n    actions={<ResponseFeedback onSubmit={pretendSend} onDetail={() => {}} />}\n  >\n    Depot 4 holds 1,240 replicas. Eleven are below their reorder point.\n  </ChatMessage>\n</div>"
+          "caption": "Controlled: the page holds the range",
+          "source": "function Controlled() {\n  const [range, setRange] = useState<DateRange>({ start: '2026-11-09', end: '2026-11-13' })\n  return (\n    <div className=\"flex w-full max-w-sm flex-col gap-2\">\n      <DateRangePicker label=\"Leave\" value={range} onValueChange={setRange} />\n      <span className=\"font-mono text-xs text-[var(--color-text-secondary)]\">\n        start: {range.start || '—'}, end: {range.end || '—'}\n      </span>\n    </div>\n  )\n}\n\n<Controlled />"
+        },
+        {
+          "caption": "Limits: November and December only",
+          "source": "<div className=\"w-full max-w-sm\">\n  <DateRangePicker label=\"Rental\" min=\"2026-11-01\" max=\"2026-12-30\" defaultValue={{ start: '2026-11-20', end: '2026-11-23' }} />\n</div>"
         }
       ]
     },
@@ -4917,7 +5567,7 @@
         {
           "name": "children",
           "type": "ReactElement",
-          "description": "Exactly one control: Input, Textarea, Select or QuantityStepper. A label set on a Select or QuantityStepper child is replaced by the FormField label."
+          "description": "Exactly one control: Input, Textarea, Select or QuantityStepper. A label set on a Select or QuantityStepper child is replaced by the FormField label. An id you give the control is kept (point an ErrorSummary entry at it); without one, FormField makes one up."
         },
         {
           "name": "className",
@@ -7278,6 +7928,225 @@
         }
       ]
     },
+    {
+      "name": "TimeField",
+      "title": "Time field",
+      "tier": "molecules",
+      "slug": "time-field",
+      "summary": "A time of day, an add-on to the date pickers. Hours and minutes are segments you type into or step with the arrow keys, like DateField; the clock button opens a list of times every step minutes. With a 12-hour clock there is an AM/PM segment. The value is 'HH:MM' on a 24-hour clock whatever is shown. Put it next to a DatePicker for a date and a time.",
+      "useWhen": "A pickup slot, a meeting start, a shift.",
+      "notFor": "A duration: Input with a unit.",
+      "source": "src/components/molecules/time-field/TimeField.tsx",
+      "docs": "/docs/components/time-field.md",
+      "imports": [
+        {
+          "names": [
+            "TimeField",
+            "hourCycleFor"
+          ],
+          "from": "src/components/molecules/time-field/TimeField"
+        }
+      ],
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "description": "Required. Names the field. Inside a FormField, FormField sets it."
+        },
+        {
+          "name": "value",
+          "type": "string ('HH:MM' | '')",
+          "description": "Controlled value, 24-hour."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "default": "''",
+          "description": "Starting value when the field holds it itself."
+        },
+        {
+          "name": "onValueChange",
+          "type": "(value: string) => void",
+          "description": "Fires with a whole time, or '' when emptied."
+        },
+        {
+          "name": "hourCycle",
+          "type": "12 | 24",
+          "description": "12 adds an AM/PM segment. The value stays 24-hour. Defaults to the locale's clock."
+        },
+        {
+          "name": "step",
+          "type": "number",
+          "default": "30",
+          "description": "Minutes between the times in the list."
+        },
+        {
+          "name": "min",
+          "type": "string",
+          "description": "Earliest time, 'HH:MM'. Earlier times are left out of the list; typing one marks the field invalid."
+        },
+        {
+          "name": "max",
+          "type": "string",
+          "description": "Latest time, 'HH:MM'."
+        },
+        {
+          "name": "showSlots",
+          "type": "boolean",
+          "default": "true",
+          "description": "Shows the clock button and its list."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "description": "Decides the default clock. Defaults to the browser's."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "default": "false",
+          "description": "Disables the field and the button."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "description": "Marks the field invalid. FormField sets it."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "description": "Marks the field required. FormField sets it."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "description": "Submits the 'HH:MM' value with a form."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "description": "The field's id. FormField sets it."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "description": "The ids of the help and error text. FormField sets it."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Combined with the field's classes."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "description": "The field's group element."
+        },
+        {
+          "name": "hourCycleFor()",
+          "type": "(locale?: string) => 12 | 24",
+          "description": "The locale's own clock."
+        }
+      ],
+      "api": [
+        {
+          "name": "TimeValue",
+          "kind": "type",
+          "code": "/** 'HH:MM', 24-hour, or '' for no time. */\nexport type TimeValue = string",
+          "from": "src/components/molecules/time-field/TimeField"
+        },
+        {
+          "name": "hourCycleFor",
+          "kind": "function",
+          "code": "/** 12 or 24, from the locale's own clock. */\nexport function hourCycleFor(locale?: string): 12 | 24",
+          "from": "src/components/molecules/time-field/TimeField"
+        }
+      ],
+      "keyboard": [
+        {
+          "keys": [
+            "0–9"
+          ],
+          "does": "Types the hour or minute and moves on once it is full."
+        },
+        {
+          "keys": [
+            "A",
+            "P"
+          ],
+          "does": "On the AM/PM segment, sets AM or PM."
+        },
+        {
+          "keys": [
+            "↑",
+            "↓"
+          ],
+          "does": "In the field: one more or one less. In the list: the next or previous time."
+        },
+        {
+          "keys": [
+            "←",
+            "→"
+          ],
+          "does": "The previous or next segment."
+        },
+        {
+          "keys": [
+            "Page Up",
+            "Page Down"
+          ],
+          "does": "In the list: six times earlier or later."
+        },
+        {
+          "keys": [
+            "Enter",
+            "Space"
+          ],
+          "does": "In the list: picks the time and closes it."
+        },
+        {
+          "keys": [
+            "Esc"
+          ],
+          "does": "Closes the list without a change."
+        }
+      ],
+      "dos": [
+        "Set step to the real booking grid, such as 15 for 15-minute slots.",
+        "Store the value with its date and the time zone it means, separately."
+      ],
+      "donts": [
+        "Don't parse 'HH:MM' with new Date(): keep it a string until you combine it with a date and a zone."
+      ],
+      "anatomy": [
+        {
+          "part": "Field",
+          "description": "A group named by the label: Hour, Minute and, on a 12-hour clock, AM or PM, each a spinbutton."
+        },
+        {
+          "part": "Clock button",
+          "description": "A ghost IconButton. Its name includes the time: \"Choose time, 14:30\"."
+        },
+        {
+          "part": "Time list",
+          "description": "A listbox of times between min and max, every step minutes. It opens on the picked time, or the next slot after now."
+        }
+      ],
+      "examples": [
+        {
+          "caption": "Default, 24-hour",
+          "source": "<div className=\"w-36\">\n  <TimeField label=\"Start time\" hourCycle={24} />\n</div>"
+        },
+        {
+          "caption": "12-hour, with AM and PM",
+          "source": "<div className=\"w-40\">\n  <TimeField label=\"Call time\" hourCycle={12} defaultValue=\"14:30\" />\n</div>"
+        },
+        {
+          "caption": "With a DatePicker: a date and a time",
+          "source": "function DateAndTime() {\n  const [date, setDate] = useState('2026-11-14')\n  const [time, setTime] = useState('09:30')\n  return (\n    <div className=\"flex w-full max-w-md flex-col gap-3\">\n      <div className=\"grid gap-3 sm:grid-cols-[1fr_9rem]\">\n        <FormField label=\"Pickup date\">\n          <DatePicker label=\"Pickup date\" value={date} onValueChange={setDate} />\n        </FormField>\n        <FormField label=\"Pickup time\">\n          <TimeField label=\"Pickup time\" value={time} onValueChange={setTime} step={15} min=\"08:00\" max=\"18:00\" />\n        </FormField>\n      </div>\n      <span className=\"font-mono text-xs text-[var(--color-text-secondary)]\">\n        {date && time ? `${date}T${time}` : 'Pick a date and a time'}\n      </span>\n    </div>\n  )\n}\n\n<DateAndTime />"
+        }
+      ]
+    },
     {
       "name": "Timeline",
       "title": "Timeline",
@@ -8960,7 +9829,7 @@
         {
           "name": "commands",
           "type": "Command[]",
-          "description": "Required. Each has id, label, group, keywords, shortcut, icon and onSelect."
+          "description": "Required. Each has id, label, description (a quieter second line), group, keywords, shortcut, icon and onSelect."
         },
         {
           "name": "open",
@@ -9008,6 +9877,12 @@
           "default": "'No matching commands'",
           "description": "Shown when nothing matches the search."
         },
+        {
+          "name": "filter",
+          "type": "(commands: readonly Command[], query: string) => Command[]",
+          "default": "filterCommands",
+          "description": "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."
+        },
         {
           "name": "ref",
           "type": "Ref<HTMLInputElement>",
@@ -9018,7 +9893,7 @@
         {
           "name": "Command",
           "kind": "type",
-          "code": "export type Command = {\n  id: string\n  label: string\n  /** Commands with the same group are drawn together under its heading. */\n  group?: string\n  /** Extra words a search matches on. */\n  keywords?: string[]\n  /** A hint shown on the option, e.g. \"N\". Display only: the palette does not bind it. */\n  shortcut?: string\n  /** Drawn aria-hidden; the label carries the meaning. */\n  icon?: ReactNode\n  onSelect: () => void\n}",
+          "code": "export type Command = {\n  id: string\n  label: string\n  /** A second, quieter line under the label, e.g. what a search result is for. */\n  description?: string\n  /** Commands with the same group are drawn together under its heading. */\n  group?: string\n  /** Extra words a search matches on. */\n  keywords?: string[]\n  /** A hint shown on the option, e.g. \"N\". Display only: the palette does not bind it. */\n  shortcut?: string\n  /** Drawn aria-hidden; the label carries the meaning. */\n  icon?: ReactNode\n  onSelect: () => void\n}",
           "from": "src/components/organisms/command-palette/CommandPalette"
         },
         {