division-ds 0.2.1 → 0.3.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Division DS: instructions for coding agents
 
-A React 19 + Tailwind 4 + Radix design system: 68 components, tokens in three layers, light and
+A React 19 + Tailwind 4 + Radix design system: 72 components, tokens in three layers, light and
 dark themes, WCAG 2.2 AA. This file is the entry point. It is short on purpose; everything it
 points to is generated from the code, so it is current.
 
@@ -51,7 +51,7 @@ installs these rules into that project's `AGENTS.md`, `GEMINI.md` and Cursor rul
 `.claude/skills/` (Claude Code).
 
 An agent that supports MCP can have the docs and the same checks as tools instead:
-`claude mcp add division-ds -- npx -y division-ds@0.2.1 mcp` (`list_components`, `get_component`,
+`claude mcp add division-ds -- npx -y division-ds@0.3.0 mcp` (`list_components`, `get_component`,
 `search`, `get_tokens`, `validate_code`, `check_contrast`, `get_add_command`,
 `get_review_checklist`).
 
@@ -91,7 +91,7 @@ provider. A project that uses the components mounts both itself (step 4 of `inst
 `src/demo/states/` files are not part of the system.
 
 **What the system does not have.** No Popover, no Combobox (single value: use `Select`; several:
-`MultiSelect`), no date picker. Do not reach into `src/demo/` from a component.
+`MultiSelect`). Do not reach into `src/demo/` from a component.
 
 **Vocabulary.** Inside this repository, `npm run check:vocabulary` bans a list of words in `src/`,
 `scripts/` and `e2e/` (the list is `scripts/lib/vocabulary.mjs`; it is not published with the
@@ -154,7 +154,7 @@ renders `ErrorSummary` at the top and focuses it; `useFieldErrors` holds the sta
 `public/docs/helpers.md`).
 
 A `RadioGroup` in a form sits in a `<fieldset>` whose `<legend>` names it (code on the Radio
-page). A date is `<Input type="date">` in a `FormField`.
+page). A date is `DatePicker` in a `FormField`; its value is 'YYYY-MM-DD'.
 
 **Buttons.** Two or more buttons side by side need a parent with a gap
 (`flex flex-wrap gap-3`); `DialogFooter` and `CardFooter` already are one. A `Button` is

package/package.json

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

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

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

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

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

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

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

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

@@ -0,0 +1,135 @@
+# DateRangePicker
+
+> 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.
+
+- **Best for:** A booking, a report window, a leave request.
+- **Not for:** One day: DatePicker.
+- Molecule. Source: `src/components/molecules/date-range-picker/DateRangePicker.tsx`
+- Rendered docs page: `/components/date-range-picker`
+
+## Import
+
+```tsx
+import { DateRangePicker, EMPTY_RANGE, useDateRangePicker } from 'src/components/molecules/date-range-picker/DateRangePicker'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. Names the field. Inside a FormField, FormField sets it. |
+| `value` | `{ start: string; end: string }` |  | Controlled range. Each end is 'YYYY-MM-DD' or ''. |
+| `defaultValue` | `{ start: string; end: string }` | `{ start: '', end: '' }` | Starting range when the picker holds it itself. |
+| `onValueChange` | `(range: DateRange) => void` |  | Fires when either end changes. Days picked in the calendar always arrive in order. |
+| `min` | `string` |  | Earliest date, 'YYYY-MM-DD'. |
+| `max` | `string` |  | Latest date, 'YYYY-MM-DD'. |
+| `isDateDisabled` | `(date: string) => boolean` |  | Days that cannot be picked. |
+| `locale` | `string` |  | Segment order, names and first day of the week. Defaults to the browser's. |
+| `weekStartsOn` | `number` |  | 0 Sunday to 6 Saturday. Defaults to the locale's. |
+| `aside` | `ReactNode` |  | Beside the months, in the popover. DatePresets reads and sets the range by itself here. |
+| `partLabels` | `[string, string]` | `['Start date', 'End date']` | The names of the two dates. |
+| `disabled` | `boolean` | `false` | Disables both dates and the button. |
+| `invalid` | `boolean` |  | Marks the field invalid. FormField sets it. |
+| `required` | `boolean` |  | Marks both dates required. FormField sets it. |
+| `name` | `string` |  | Submits name-start and name-end with a form. |
+| `id` | `string` |  | The field's id. FormField sets it. |
+| `aria-describedby` | `string` |  | The ids of the help and error text. FormField sets it. |
+| `className` | `string` |  | Combined with the field's classes. |
+| `ref` | `Ref<HTMLDivElement>` |  | The field's group element. |
+| `useDateRangePicker()` | `() => { value: DateRange; select: (range: DateRange) => void } \| null` |  | Inside the popover: the range, and a way to set it and close. For your own aside content. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+/** A start and an end, each 'YYYY-MM-DD' or '' while not chosen. */
+export type DateRange = { start: IsoDate | ''; end: IsoDate | '' }
+```
+
+```ts
+export const EMPTY_RANGE: DateRange = { start: '', end: '' }
+```
+
+```ts
+/** The open picker's range, and a way to set it and close. DatePresets reads it, so a preset in
+ *  `aside` needs no wiring. null outside a DateRangePicker. */
+export const useDateRangePicker = () => useContext(Context)
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+<div className="w-full max-w-sm">
+  <DateRangePicker label="Stay" />
+</div>
+```
+
+### With DatePresets beside the months
+
+```tsx
+<div className="w-full max-w-sm">
+  <FormField label="Report period" help="Pick a preset, or two days.">
+    <DateRangePicker label="Report period" aside={<DatePresets />} />
+  </FormField>
+</div>
+```
+
+### Controlled: the page holds the range
+
+```tsx
+function Controlled() {
+  const [range, setRange] = useState<DateRange>({ start: '2026-11-09', end: '2026-11-13' })
+  return (
+    <div className="flex w-full max-w-sm flex-col gap-2">
+      <DateRangePicker label="Leave" value={range} onValueChange={setRange} />
+      <span className="font-mono text-xs text-[var(--color-text-secondary)]">
+        start: {range.start || '—'}, end: {range.end || '—'}
+      </span>
+    </div>
+  )
+}
+
+<Controlled />
+```
+
+### Limits: November and December only
+
+```tsx
+<div className="w-full max-w-sm">
+  <DateRangePicker label="Rental" min="2026-11-01" max="2026-12-30" defaultValue={{ start: '2026-11-20', end: '2026-11-23' }} />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `0–9` `↑` `↓` | Types or steps the focused segment of either date. |
+| `←` `→` | In the field: the next segment, across both dates. In the calendar: the day before or after, moving the band. |
+| `Page Up` `Page Down` | A month earlier or later. With Shift, a year. |
+| `Enter` `Space` | Picks the start, then the end, which closes the calendar. |
+| `Esc` | Closes the calendar. A start picked without an end stays as the start. |
+
+## Do
+
+- 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.
+
+## Don't
+
+- 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
+
+- **Field**: 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.
+- **Calendar**: Two months, stacked on narrow screens. The ends are solid accent squares, the days between a light accent band.
+- **Hint**: "Pick the first day." or "Pick the last day.", under the months, announced when it changes.
+- **Aside**: An optional column beside the months, for DatePresets.

package/public/docs/components/time-field.md

@@ -0,0 +1,127 @@
+# TimeField
+
+> 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.
+
+- **Best for:** A pickup slot, a meeting start, a shift.
+- **Not for:** A duration: Input with a unit.
+- Molecule. Source: `src/components/molecules/time-field/TimeField.tsx`
+- Rendered docs page: `/components/time-field`
+
+## Import
+
+```tsx
+import { TimeField, hourCycleFor } from 'src/components/molecules/time-field/TimeField'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. Names the field. Inside a FormField, FormField sets it. |
+| `value` | `string ('HH:MM' \| '')` |  | Controlled value, 24-hour. |
+| `defaultValue` | `string` | `''` | Starting value when the field holds it itself. |
+| `onValueChange` | `(value: string) => void` |  | Fires with a whole time, or '' when emptied. |
+| `hourCycle` | `12 \| 24` |  | 12 adds an AM/PM segment. The value stays 24-hour. Defaults to the locale's clock. |
+| `step` | `number` | `30` | Minutes between the times in the list. |
+| `min` | `string` |  | Earliest time, 'HH:MM'. Earlier times are left out of the list; typing one marks the field invalid. |
+| `max` | `string` |  | Latest time, 'HH:MM'. |
+| `showSlots` | `boolean` | `true` | Shows the clock button and its list. |
+| `locale` | `string` |  | Decides the default clock. Defaults to the browser's. |
+| `disabled` | `boolean` | `false` | Disables the field and the button. |
+| `invalid` | `boolean` |  | Marks the field invalid. FormField sets it. |
+| `required` | `boolean` |  | Marks the field required. FormField sets it. |
+| `name` | `string` |  | Submits the 'HH:MM' value with a form. |
+| `id` | `string` |  | The field's id. FormField sets it. |
+| `aria-describedby` | `string` |  | The ids of the help and error text. FormField sets it. |
+| `className` | `string` |  | Combined with the field's classes. |
+| `ref` | `Ref<HTMLDivElement>` |  | The field's group element. |
+| `hourCycleFor()` | `(locale?: string) => 12 \| 24` |  | The locale's own clock. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+/** 'HH:MM', 24-hour, or '' for no time. */
+export type TimeValue = string
+```
+
+```ts
+/** 12 or 24, from the locale's own clock. */
+export function hourCycleFor(locale?: string): 12 | 24
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default, 24-hour
+
+```tsx
+<div className="w-36">
+  <TimeField label="Start time" hourCycle={24} />
+</div>
+```
+
+### 12-hour, with AM and PM
+
+```tsx
+<div className="w-40">
+  <TimeField label="Call time" hourCycle={12} defaultValue="14:30" />
+</div>
+```
+
+### With a DatePicker: a date and a time
+
+```tsx
+function DateAndTime() {
+  const [date, setDate] = useState('2026-11-14')
+  const [time, setTime] = useState('09:30')
+  return (
+    <div className="flex w-full max-w-md flex-col gap-3">
+      <div className="grid gap-3 sm:grid-cols-[1fr_9rem]">
+        <FormField label="Pickup date">
+          <DatePicker label="Pickup date" value={date} onValueChange={setDate} />
+        </FormField>
+        <FormField label="Pickup time">
+          <TimeField label="Pickup time" value={time} onValueChange={setTime} step={15} min="08:00" max="18:00" />
+        </FormField>
+      </div>
+      <span className="font-mono text-xs text-[var(--color-text-secondary)]">
+        {date && time ? `${date}T${time}` : 'Pick a date and a time'}
+      </span>
+    </div>
+  )
+}
+
+<DateAndTime />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `0–9` | Types the hour or minute and moves on once it is full. |
+| `A` `P` | On the AM/PM segment, sets AM or PM. |
+| `↑` `↓` | In the field: one more or one less. In the list: the next or previous time. |
+| `←` `→` | The previous or next segment. |
+| `Page Up` `Page Down` | In the list: six times earlier or later. |
+| `Enter` `Space` | In the list: picks the time and closes it. |
+| `Esc` | Closes the list without a change. |
+
+## Do
+
+- 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.
+
+## Don't
+
+- Don't parse 'HH:MM' with new Date(): keep it a string until you combine it with a date and a zone.
+
+## Anatomy
+
+- **Field**: A group named by the label: Hour, Minute and, on a 12-hour clock, AM or PM, each a spinbutton.
+- **Clock button**: A ghost IconButton. Its name includes the time: "Choose time, 14:30".
+- **Time list**: A listbox of times between min and max, every step minutes. It opens on the picked time, or the next slot after now.