division-ds 0.2.1 → 0.3.0

package/public/manifest/components.json

@@ -4340,6 +4340,649 @@
         }
       ]
     },
+    {
+      "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": "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": "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": "DateRange",
+          "kind": "type",
+          "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": "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": [
+            "0–9",
+            "↑",
+            "↓"
+          ],
+          "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": [
+        "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 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": "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": "Calendar",
+          "description": "Two months, stacked on narrow screens. The ends are solid accent squares, the days between a light accent band."
+        },
+        {
+          "part": "Hint",
+          "description": "\"Pick the first day.\" or \"Pick the last day.\", under the months, announced when it changes."
+        },
+        {
+          "part": "Aside",
+          "description": "An optional column beside the months, for DatePresets."
+        }
+      ],
+      "examples": [
+        {
+          "caption": "Default",
+          "source": "<div className=\"w-full max-w-sm\">\n  <DateRangePicker label=\"Stay\" />\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": "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>"
+        }
+      ]
+    },
     {
       "name": "DescriptionList",
       "title": "Description list",
@@ -7285,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",
@@ -8967,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",
@@ -9015,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>",
@@ -9025,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"
         },
         {