@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/date-picker.json

@@ -0,0 +1,687 @@
+{
+  "family": "date-picker",
+  "ui": "date-picker",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Date field with a calendar popover."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle",
+      "plain"
+    ],
+    "placement": [
+      "bottom-start",
+      "bottom",
+      "bottom-end",
+      "top-start",
+      "top",
+      "top-end"
+    ],
+    "closeOnSelect": [
+      "auto",
+      "always",
+      "never"
+    ],
+    "calendar": [
+      "gregory"
+    ]
+  },
+  "members": {
+    "datePicker": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "placement": "bottom-start",
+        "closeOnSelect": "auto",
+        "calendar": "gregory",
+        "clearable": false
+      },
+      "capabilities": [
+        "value",
+        "open",
+        "placement",
+        "appearance",
+        "size",
+        "content",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "invalid",
+        "readonly",
+        "required",
+        "open"
+      ],
+      "parts": [
+        "root",
+        "control",
+        "trigger",
+        "positioner",
+        "content",
+        "presets",
+        "footer"
+      ]
+    }
+  },
+  "docs": {
+    "datePicker": {
+      "imports": {
+        "source": "import { DatePicker, DatePickerDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The outer box, carrying data-ui=\"date-picker\", the size, variant and calendar axes, data-open and the state attributes. className, style and every native attribute reach it."
+        },
+        {
+          "part": "control",
+          "element": "div",
+          "required": true,
+          "purpose": "The box the calendar is positioned against. It draws no frame: the date field inside it draws its own border, focus ring and states."
+        },
+        {
+          "part": "trigger",
+          "element": "button",
+          "required": true,
+          "purpose": "The calendar button, in the end slot of the date field. Its accessible name carries the chosen date in words, because focus returns to it when the calendar closes. It is always drawn, because ChromeOS turns Alt+ArrowDown into PageDown before the browser receives it."
+        },
+        {
+          "part": "positioner",
+          "element": "div, portalled to the end of the document",
+          "required": true,
+          "purpose": "The layer the calendar stands on. It carries data-ui=\"date-picker\" again, data-presentation (popover or sheet) and the position the positioner writes. It takes no pointer events of its own, so a press on the page around the surface reaches the page."
+        },
+        {
+          "part": "content",
+          "element": "div with role=\"dialog\"",
+          "required": true,
+          "purpose": "The painted surface, with the same accessible name as the trigger. Its width comes from the calendar inside it, not from the field it opens from."
+        },
+        {
+          "part": "presets",
+          "element": "div",
+          "required": false,
+          "purpose": "A column beside the calendar for your own shortcuts, drawn when presets is set. The Date Picker ships no list of shortcuts: the labels and dates belong to your product."
+        },
+        {
+          "part": "footer",
+          "element": "div",
+          "required": false,
+          "purpose": "A row under the calendar for your own actions, drawn when footer is set."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "PlainDate | DateRange | PlainDate[] | null",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "The selected value, whose shape follows selectionMode. Setting it makes the value controlled."
+        },
+        {
+          "name": "defaultValue",
+          "type": "PlainDate | DateRange | PlainDate[] | null",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "The starting value of an uncontrolled date picker. Read once, on the first render."
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Whether the calendar is showing. Setting it makes the open state controlled."
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DatePicker",
+          "description": "Whether the calendar shows on the first render. Focus does not move into it."
+        },
+        {
+          "name": "min",
+          "type": "PlainDate",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "The earliest date the field and the calendar accept. Earlier days are disabled in the calendar, and an earlier typed date marks the date picker invalid."
+        },
+        {
+          "name": "max",
+          "type": "PlainDate",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "The latest date the field and the calendar accept. Later days are disabled in the calendar, and a later typed date marks the date picker invalid."
+        },
+        {
+          "name": "isDateUnavailable",
+          "type": "(date: PlainDate) => boolean",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Returns true for a date the reader cannot choose. The calendar disables it, and a typed unavailable date marks the date picker invalid."
+        },
+        {
+          "name": "selectionMode",
+          "type": "'single' | 'range' | 'multiple'",
+          "defaultValue": "single",
+          "appliesTo": "DatePicker",
+          "description": "How many dates the calendar selects, and so the shape of the value. The field shows a single date only; for a start and an end, use DateRangePicker."
+        },
+        {
+          "name": "months",
+          "type": "number",
+          "defaultValue": "1",
+          "appliesTo": "DatePicker",
+          "description": "How many months the calendar draws side by side."
+        },
+        {
+          "name": "defaultView",
+          "type": "'day' | 'month' | 'year'",
+          "defaultValue": "day",
+          "appliesTo": "DatePicker",
+          "description": "The grid the calendar opens on."
+        },
+        {
+          "name": "weekNumbers",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DatePicker",
+          "description": "Adds a column of ISO 8601 week numbers to the calendar."
+        },
+        {
+          "name": "fixedWeeks",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "DatePicker",
+          "description": "Draws six rows for every month, so the surface keeps its height as the reader pages between months."
+        },
+        {
+          "name": "placement",
+          "type": "'bottom-start' | 'bottom' | 'bottom-end' | 'top-start' | 'top' | 'top-end'",
+          "defaultValue": "bottom-start",
+          "appliesTo": "DatePicker",
+          "description": "Where the calendar opens relative to the field. When it does not fit on that side, it opens on the other."
+        },
+        {
+          "name": "closeOnSelect",
+          "type": "'auto' | 'always' | 'never'",
+          "defaultValue": "auto",
+          "appliesTo": "DatePicker",
+          "description": "Whether choosing a day closes the calendar. auto closes it for a single date and keeps it open for a range or several dates, which need more than one press."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "the SlottedProvider locale, else en-US",
+          "appliesTo": "DatePicker",
+          "description": "A BCP 47 tag. Sets the order, separators and placeholders of the segments, the month and weekday names, the first day of the week and the date the trigger announces."
+        },
+        {
+          "name": "timeZone",
+          "type": "string",
+          "defaultValue": "the browser’s time zone",
+          "appliesTo": "DatePicker",
+          "description": "The IANA time zone that decides which day is today. The value itself has no time zone."
+        },
+        {
+          "name": "firstDayOfWeek",
+          "type": "number",
+          "defaultValue": "the locale’s",
+          "appliesTo": "DatePicker",
+          "description": "The day the calendar starts each week on, from 0 for Sunday to 6 for Saturday."
+        },
+        {
+          "name": "yearPivot",
+          "type": "number",
+          "defaultValue": "20",
+          "appliesTo": "DatePicker",
+          "description": "How a two-digit typed year resolves: a year up to this many years ahead of today is read in this century, and a later one in the previous century."
+        },
+        {
+          "name": "calendar",
+          "type": "'gregory'",
+          "defaultValue": "gregory",
+          "appliesTo": "DatePicker",
+          "description": "The calendar system. gregory is the only value today."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "DatePicker",
+          "description": "One step of the control scale for the field and the trigger. Inside a Field, an unset size follows the field."
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "DatePicker",
+          "description": "How much frame the field draws at rest: a border, a filled ground, or neither."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Disables the segments and the trigger, and takes both out of the tab order. Read from the enclosing Field when unset."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Keeps the date legible and focusable and disables the trigger, so the calendar cannot open. Read from the enclosing Field when unset."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Draws the frame and the focus ring in the danger tone and sets aria-invalid. A date outside min and max, or refused by isDateUnavailable, sets it on its own."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Sets aria-required on the field. Read from the enclosing Field when unset."
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DatePicker",
+          "description": "Adds a clear button to the field while it holds a date. It sets the value to null and returns focus to the field."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Adds a hidden input with this name that submits the date as an ISO 8601 string, such as 2026-09-30."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<DatePickerMessages>",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Replaces the trigger’s accessible name, key by key: choose while no date is set, and change, with the date in its {date} slot, once one is."
+        },
+        {
+          "name": "presets",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Your own shortcuts, drawn in a column beside the calendar."
+        },
+        {
+          "name": "footer",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Your own actions, drawn in a row under the calendar."
+        }
+      ],
+      "composition": [
+        {
+          "name": "DatePickerDefaultsProvider",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "application",
+          "description": "Sets timeZone, placement, closeOnSelect, calendar, size and variant for every DatePicker under it. A prop on one DatePicker wins."
+        },
+        {
+          "name": "render",
+          "type": "(props: DatePickerRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Renders the root as another element. Spread the props onto it: they carry the ref the calendar is positioned against."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<DatePickerHandle>",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "A handle with focus(), which focuses the first segment, and open() and close(), which show and hide the calendar without a controlled open prop. open() moves focus into the calendar."
+        },
+        {
+          "name": "onKeyDown",
+          "type": "KeyboardEventHandler",
+          "defaultValue": "—",
+          "appliesTo": "DatePicker",
+          "description": "Runs before Alt+ArrowDown is read. Calling event.preventDefault() keeps the shortcut for the page."
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: CalendarValue, request: ChangeRequest<CalendarValue>)",
+          "when": "Before the value changes, from the field or the calendar. request.reason is keyboard for typing and for the calendar’s keys, pointer for a press on a day, clear for the clear button and blur for a date completed when the field loses focus. request.cancel() keeps the current value."
+        },
+        {
+          "name": "onOpenChange",
+          "payload": "(open: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before the calendar opens or closes. request.reason is pointer for the trigger, keyboard for Alt+ArrowDown and for the handle’s open() and close(), escape for the Escape key, outsidePress for a press outside the surface and select for a chosen day. request.cancel() keeps the current state."
+        }
+      ],
+      "accessibility": [
+        "The trigger’s accessible name carries the chosen date in words, such as “Change date, Wednesday, September 30, 2026”. Focus returns to the trigger when the calendar closes from a chosen day or from Escape, so a screen reader announces the date there.",
+        "Opening the calendar from the trigger, from Alt+ArrowDown or from open() moves focus to the chosen day, or to today when no date is set. While the calendar is open, Tab and Shift+Tab cycle through the shortcuts, the calendar and the footer.",
+        "Escape closes in steps: while the calendar shows the month or year grid, Escape returns to the day grid; on the day grid, it closes the calendar and returns focus to the trigger.",
+        "Alt+ArrowDown is a shortcut, never the only way in. ChromeOS turns it into PageDown before the browser receives it, so the trigger is always drawn.",
+        "The surface has role=\"dialog\" and the same accessible name as the trigger. The trigger sets aria-expanded, and sets aria-controls only while the surface exists.",
+        "The field and the calendar refuse the same dates, from the same min, max and isDateUnavailable, so a date the calendar disables marks the field invalid when it is typed."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-border-width",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-radius",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-date-picker-content-border-color",
+    "--slotted-date-picker-content-color",
+    "--slotted-date-picker-content-padding",
+    "--slotted-date-picker-content-radius",
+    "--slotted-date-picker-content-shadow",
+    "--slotted-date-picker-invalid-focus-ring-color",
+    "--slotted-date-picker-radius",
+    "--slotted-date-picker-surface",
+    "--slotted-date-picker-trigger-active-background",
+    "--slotted-date-picker-trigger-color",
+    "--slotted-date-picker-trigger-hover-background",
+    "--slotted-date-picker-trigger-size",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-medium",
+    "--slotted-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-easing-exit",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-radius-lg",
+    "--slotted-shadow-md",
+    "--slotted-space-2",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-9",
+    "--slotted-surface-raised",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-z-index-popover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "A field, a trigger and a calendar, driven by the controls below the canvas. Type into the field, or press the trigger and move through the calendar with the arrow keys: both write the same value.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>Due date</FieldLabel>\n  <DatePicker name=\"dueDate\" onValueChange={setValue} value={value} />\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Size",
+      "note": "The three steps of the control scale. The trigger follows the field: its box is the icon plus one step of space, inside the frame, as in every other control with an inner button.",
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerSizes() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Shipped after</FieldLabel>\n        <DatePicker size=\"sm\" defaultValue={plainDate(2026, 9, 1)} />\n      </Field>\n      <Field>\n        <FieldLabel>Ship date</FieldLabel>\n        <DatePicker size=\"md\" defaultValue={plainDate(2026, 9, 30)} />\n      </Field>\n      <Field>\n        <FieldLabel>Move-in date</FieldLabel>\n        <DatePicker size=\"lg\" defaultValue={plainDate(2026, 11, 2)} />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "variants",
+      "title": "Variant",
+      "note": "How much frame the field draws at rest. The trigger keeps its calendar icon in all three.",
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerVariants() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Invoice date</FieldLabel>\n        <DatePicker variant=\"outline\" defaultValue={plainDate(2026, 9, 30)} />\n      </Field>\n      <Field>\n        <FieldLabel>Posting date</FieldLabel>\n        <DatePicker variant=\"subtle\" defaultValue={plainDate(2026, 9, 30)} />\n      </Field>\n      <Field>\n        <FieldLabel>Value date</FieldLabel>\n        <DatePicker variant=\"plain\" defaultValue={plainDate(2026, 10, 1)} />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "placement",
+      "title": "Where the surface opens",
+      "note": "A preference: when the calendar does not fit on that side, it opens on the other, and data-placement on the positioner records the side it took.",
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerPlacement() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Opens above, from the start edge</FieldLabel>\n        <DatePicker defaultValue={plainDate(2026, 9, 30)} placement=\"top-start\" />\n      </Field>\n      <Field>\n        <FieldLabel>Opens below, from the end edge</FieldLabel>\n        <DatePicker defaultValue={plainDate(2026, 9, 30)} placement=\"bottom-end\" />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "range-bounds",
+      "title": "Bounds",
+      "note": "min and max bound the field and the calendar together: the calendar disables the days outside them, and a typed date outside them marks the date picker invalid.",
+      "language": "tsx",
+      "source": "<DatePicker max={{ year: 2026, month: 12, day: 31 }} min={{ year: 2026, month: 1, day: 1 }} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "unavailable",
+      "title": "Days that are refused",
+      "note": "One function reaches the field and the calendar. A refused date marks the date picker invalid when it is typed, and is disabled in the calendar.",
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { dayOfWeek, plainDate, toISODate, type PlainDate } from '@slotted/core/date';\n\n/** Columbus Day, Veterans Day, Thanksgiving and Christmas Day, 2026. */\nconst HOLIDAYS = new Set(['2026-10-12', '2026-11-11', '2026-11-26', '2026-12-25']);\n\nconst isClosed = (date: PlainDate) =>\n  dayOfWeek(date) === 0 || dayOfWeek(date) === 6 || HOLIDAYS.has(toISODate(date));\n\nexport default function DatePickerUnavailable() {\n  return (\n    <Field>\n      <FieldLabel>Pickup date</FieldLabel>\n      <DatePicker defaultValue={plainDate(2026, 10, 13)} isDateUnavailable={isClosed} />\n      <FieldDescription>The Reno dock is closed on weekends and federal holidays.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "presets",
+      "title": "Shortcuts and actions",
+      "note": "The two slots you fill: shortcuts beside the calendar and actions under it. The Date Picker ships no list of shortcuts, because the labels and dates belong to your product.",
+      "language": "tsx",
+      "source": "import { useRef, useState } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { DatePicker, type DatePickerHandle } from '@slotted/react/date-picker';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { addDays, isPlainDate, plainDate, type PlainDate } from '@slotted/core/date';\n\nconst TODAY = plainDate(2026, 9, 30);\n\nconst PRESETS = [\n  { label: 'Today', date: TODAY },\n  { label: 'Tomorrow', date: addDays(TODAY, 1) },\n  { label: 'Next Monday', date: plainDate(2026, 10, 5) },\n  { label: 'In 2 weeks', date: addDays(TODAY, 14) },\n];\n\nexport default function DatePickerPresets() {\n  const picker = useRef<DatePickerHandle>(null);\n  const [date, setDate] = useState<PlainDate | null>(TODAY);\n\n  const choose = (next: PlainDate) => {\n    setDate(next);\n    picker.current?.close();\n  };\n\n  return (\n    <Field>\n      <FieldLabel>Dispatch date</FieldLabel>\n      <DatePicker\n        ref={picker}\n        onValueChange={(value) => setDate(isPlainDate(value) ? value : null)}\n        presets={PRESETS.map((preset) => (\n          <Button key={preset.label} size=\"sm\" variant=\"ghost\" onClick={() => choose(preset.date)}>\n            {preset.label}\n          </Button>\n        ))}\n        value={date}\n      />\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "Disabled and read-only both disable the trigger, so the calendar cannot open. Invalid draws the frame and the focus ring in the danger tone.",
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerStates() {\n  return (\n    <Stack gap={5}>\n      <Field invalid required>\n        <FieldLabel>Delivery date</FieldLabel>\n        <DatePicker defaultValue={plainDate(2026, 9, 28)} />\n        <FieldError>The delivery date is before the order date, September 30, 2026.</FieldError>\n      </Field>\n      <Field readOnly>\n        <FieldLabel>Order date</FieldLabel>\n        <DatePicker defaultValue={plainDate(2026, 9, 30)} />\n        <FieldDescription>Set when the order was placed.</FieldDescription>\n      </Field>\n      <Field disabled>\n        <FieldLabel>Return by</FieldLabel>\n        <DatePicker defaultValue={plainDate(2026, 10, 30)} />\n        <FieldDescription>Returns open once the order is delivered.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "forms",
+      "title": "In a form",
+      "note": "name adds a hidden input that submits the date as an ISO 8601 string, so a plain form post sends 2026-09-09 whether the reader typed the date or chose it.",
+      "language": "tsx",
+      "source": "<form action=\"/bookings\" method=\"post\">\n  <DatePicker name=\"checkIn\" required />\n  <Button type=\"submit\">Book</Button>\n</form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "narrow",
+      "title": "On a narrow touch screen",
+      "note": "Under 480 pixels on a coarse pointer, the calendar opens as a sheet attached to the bottom of the viewport. The markup stays the same, and data-presentation on the positioner records which presentation is showing.",
+      "language": "tsx",
+      "source": "import { useRef, useState } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { DatePicker, type DatePickerHandle } from '@slotted/react/date-picker';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { addDays, isPlainDate, plainDate, type PlainDate } from '@slotted/core/date';\n\nconst TODAY = plainDate(2026, 9, 30);\n\nexport default function DatePickerNarrow() {\n  const picker = useRef<DatePickerHandle>(null);\n  const [date, setDate] = useState<PlainDate | null>(null);\n\n  const choose = (next: PlainDate) => {\n    setDate(next);\n    picker.current?.close();\n  };\n\n  return (\n    <Field>\n      <FieldLabel>Proof of delivery date</FieldLabel>\n      <DatePicker\n        ref={picker}\n        onValueChange={(value) => setDate(isPlainDate(value) ? value : null)}\n        presets={\n          <>\n            <Button size=\"sm\" variant=\"ghost\" onClick={() => choose(TODAY)}>\n              Today\n            </Button>\n            <Button size=\"sm\" variant=\"ghost\" onClick={() => choose(addDays(TODAY, -1))}>\n              Yesterday\n            </Button>\n          </>\n        }\n        value={date}\n      />\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "DatePickerDefaultsProvider sets the time zone and the placement once, SlottedProvider sets the language and the trigger’s names, the ref returns focus(), open() and close(), and request.cancel() refuses a value before it is applied.",
+      "language": "tsx",
+      "source": "<DatePickerDefaultsProvider timeZone=\"America/Sao_Paulo\">\n  <DatePicker ref={handle} onValueChange={(value, request) => request.cancel()} />\n</DatePickerDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard",
+      "note": "Alt+ArrowDown opens the calendar from the field and moves focus to the chosen day. Escape closes it and returns focus to the trigger; while the calendar shows months or years, Escape first returns to the day grid.",
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerKeyboard() {\n  const [last, setLast] = useState('Focus the field and press Alt+ArrowDown.');\n\n  return (\n    <Field>\n      <FieldLabel>Dispatch date</FieldLabel>\n      <DatePicker\n        defaultValue={plainDate(2026, 9, 30)}\n        messages={{ choose: 'Choose dispatch date', change: 'Change dispatch date, {date}' }}\n        onOpenChange={(open, request) =>\n          setLast(`${open ? 'Opened' : 'Closed'} by ${request.reason}.`)\n        }\n      />\n      <FieldDescription>{last}</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "basic",
+      "title": "basic.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\n\nexport default function DatePickerBasic() {\n  return (\n    <Field>\n      <FieldLabel>Requested delivery date</FieldLabel>\n      <DatePicker name=\"deliveryDate\" />\n      <FieldDescription>Type the date or choose it from the calendar.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "bounds",
+      "title": "bounds.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerBounds() {\n  return (\n    <Field>\n      <FieldLabel>Delivery window</FieldLabel>\n      <DatePicker\n        defaultValue={plainDate(2026, 10, 15)}\n        max={plainDate(2026, 10, 31)}\n        min={plainDate(2026, 10, 1)}\n      />\n      <FieldDescription>Carriers book October 2026 only.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "clearable",
+      "title": "clearable.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerClearable() {\n  return (\n    <Field>\n      <FieldLabel>Hold shipment until</FieldLabel>\n      <DatePicker clearable defaultValue={plainDate(2026, 10, 9)} />\n      <FieldDescription>Clear the date to release the shipment.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "controlled",
+      "title": "controlled.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport {\n  addDays,\n  createDateFormat,\n  isPlainDate,\n  plainDate,\n  type PlainDate,\n} from '@slotted/core/date';\n\nconst TODAY = plainDate(2026, 9, 30);\nconst words = createDateFormat({ locale: 'en-US' });\n\nexport default function DatePickerControlled() {\n  const [followUp, setFollowUp] = useState<PlainDate | null>(addDays(TODAY, 7));\n\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Follow up with Harbor Freightways</FieldLabel>\n        <DatePicker\n          onValueChange={(value) => setFollowUp(isPlainDate(value) ? value : null)}\n          value={followUp}\n        />\n        <FieldDescription>\n          {followUp === null\n            ? 'No follow-up scheduled.'\n            : `Reminder on ${words.describe(followUp)}.`}\n        </FieldDescription>\n      </Field>\n      <Inline gap={2}>\n        <Button\n          size=\"sm\"\n          tone=\"secondary\"\n          variant=\"outline\"\n          onClick={() => setFollowUp(addDays(TODAY, 7))}\n        >\n          In 1 week\n        </Button>\n        <Button\n          size=\"sm\"\n          tone=\"secondary\"\n          variant=\"outline\"\n          onClick={() => setFollowUp(addDays(TODAY, 14))}\n        >\n          In 2 weeks\n        </Button>\n        <Button size=\"sm\" tone=\"secondary\" variant=\"ghost\" onClick={() => setFollowUp(null)}>\n          No follow-up\n        </Button>\n      </Inline>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "default-view",
+      "title": "default-view.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerDefaultView() {\n  return (\n    <Field>\n      <FieldLabel>Date of incorporation</FieldLabel>\n      <DatePicker defaultView=\"year\" max={plainDate(2026, 9, 30)} />\n      <FieldDescription>As printed on the certificate of incorporation.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { DatePicker, DatePickerDefaultsProvider } from '@slotted/react/date-picker';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerDefaults() {\n  return (\n    <DatePickerDefaultsProvider size=\"sm\" variant=\"subtle\" placement=\"bottom-end\">\n      <Stack gap={4}>\n        <Field>\n          <FieldLabel>Posted after</FieldLabel>\n          <DatePicker defaultValue={plainDate(2026, 9, 1)} />\n        </Field>\n        <Field>\n          <FieldLabel>Due before</FieldLabel>\n          <DatePicker defaultValue={plainDate(2026, 10, 31)} />\n        </Field>\n      </Stack>\n    </DatePickerDefaultsProvider>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "first-day",
+      "title": "first-day.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerFirstDay() {\n  return (\n    <Field>\n      <FieldLabel>Shift starts</FieldLabel>\n      <DatePicker defaultValue={plainDate(2026, 9, 30)} firstDayOfWeek={1} locale=\"en-US\" />\n      <FieldDescription>Rosters run Monday to Sunday.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "focus-and-open",
+      "title": "focus-and-open.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useRef } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { DatePicker, type DatePickerHandle } from '@slotted/react/date-picker';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerFocusAndOpen() {\n  const picker = useRef<DatePickerHandle>(null);\n\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Contract renewal date</FieldLabel>\n        <DatePicker ref={picker} defaultValue={plainDate(2027, 3, 31)} />\n      </Field>\n      <Inline gap={2}>\n        <Button\n          size=\"sm\"\n          tone=\"secondary\"\n          variant=\"outline\"\n          onClick={() => picker.current?.focus()}\n        >\n          Edit date\n        </Button>\n        <Button size=\"sm\" tone=\"secondary\" variant=\"outline\" onClick={() => picker.current?.open()}>\n          Open calendar\n        </Button>\n      </Inline>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "footer",
+      "title": "footer.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useRef } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { DatePicker, type DatePickerHandle } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerFooter() {\n  const picker = useRef<DatePickerHandle>(null);\n\n  return (\n    <Field>\n      <FieldLabel>Stock count date</FieldLabel>\n      <DatePicker\n        ref={picker}\n        closeOnSelect=\"never\"\n        defaultValue={plainDate(2026, 10, 3)}\n        footer={\n          <Button size=\"sm\" onClick={() => picker.current?.close()}>\n            Done\n          </Button>\n        }\n      />\n      <FieldDescription>The calendar stays open until you press Done.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "form",
+      "title": "form.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport type { SubmitEvent } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { Text } from '@slotted/react/typography';\nimport { compareDate, isPlainDate, plainDate, type PlainDate } from '@slotted/core/date';\n\nconst EARLIEST = plainDate(2026, 10, 1);\n\nexport default function DatePickerForm() {\n  const [date, setDate] = useState<PlainDate | null>(null);\n  const [submitted, setSubmitted] = useState(false);\n  const [saved, setSaved] = useState<string | null>(null);\n\n  const error =\n    date !== null && compareDate(date, EARLIEST) < 0\n      ? 'Choose October 1, 2026 or later.'\n      : submitted && date === null\n        ? 'Choose a delivery date.'\n        : '';\n\n  const submit = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    setSubmitted(true);\n    const value = new FormData(event.currentTarget).get('deliveryDate');\n    const valid = date !== null && compareDate(date, EARLIEST) >= 0;\n    setSaved(valid ? `Delivery booked for ${String(value)}.` : null);\n  };\n\n  const reset = () => {\n    setDate(null);\n    setSubmitted(false);\n    setSaved(null);\n  };\n\n  return (\n    <form noValidate onSubmit={submit} onReset={reset}>\n      <Stack gap={5}>\n        <Field required invalid={error === '' ? undefined : true}>\n          <FieldLabel>Delivery date</FieldLabel>\n          <DatePicker\n            min={EARLIEST}\n            name=\"deliveryDate\"\n            onValueChange={(value) => setDate(isPlainDate(value) ? value : null)}\n            value={date}\n          />\n          <FieldError live=\"polite\" reserve>\n            {error}\n          </FieldError>\n        </Field>\n        <Inline gap={3} align=\"center\">\n          <Button type=\"submit\">Book delivery</Button>\n          <Button type=\"reset\" tone=\"secondary\" variant=\"outline\">\n            Reset\n          </Button>\n          {saved && (\n            <Text size=\"sm\" tone=\"muted\">\n              {saved}\n            </Text>\n          )}\n        </Inline>\n      </Stack>\n    </form>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "invoice-due",
+      "title": "invoice-due.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport {\n  Select,\n  SelectContent,\n  SelectItem,\n  SelectTrigger,\n  SelectValue,\n} from '@slotted/react/select';\nimport { Stack } from '@slotted/react/stack';\nimport {\n  addDays,\n  createDateFormat,\n  isPlainDate,\n  plainDate,\n  type PlainDate,\n} from '@slotted/core/date';\n\nconst TERMS = [\n  { value: 'receipt', label: 'Due on receipt', days: 0 },\n  { value: 'net-15', label: 'Net 15', days: 15 },\n  { value: 'net-30', label: 'Net 30', days: 30 },\n  { value: 'net-60', label: 'Net 60', days: 60 },\n];\nconst words = createDateFormat({ locale: 'en-US' });\n\nexport default function DatePickerInvoiceDue() {\n  const [issued, setIssued] = useState<PlainDate | null>(plainDate(2026, 9, 30));\n  const [terms, setTerms] = useState('net-30');\n  const days = TERMS.find((option) => option.value === terms)?.days ?? 0;\n  const due = issued === null ? null : addDays(issued, days);\n\n  return (\n    <Stack gap={5}>\n      <Field required>\n        <FieldLabel>Invoice date</FieldLabel>\n        <DatePicker\n          onValueChange={(value) => setIssued(isPlainDate(value) ? value : null)}\n          value={issued}\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Payment terms</FieldLabel>\n        <Select\n          items={TERMS}\n          onValueChange={(next) => {\n            if (typeof next === 'string') setTerms(next);\n          }}\n          value={terms}\n        >\n          <SelectTrigger>\n            <SelectValue />\n          </SelectTrigger>\n          <SelectContent>\n            {TERMS.map((option) => (\n              <SelectItem key={option.value} value={option.value}>\n                {option.label}\n              </SelectItem>\n            ))}\n          </SelectContent>\n        </Select>\n      </Field>\n      <Field readOnly>\n        <FieldLabel>Due date</FieldLabel>\n        <DatePicker value={due} />\n        <FieldDescription>\n          {due === null ? 'Set the invoice date first.' : `Payment is due ${words.describe(due)}.`}\n        </FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "locale",
+      "title": "locale.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { plainDate } from '@slotted/core/date';\n\nconst SHIP_DATE = plainDate(2026, 9, 30);\n\nexport default function DatePickerLocale() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Ship date, United States (en-US)</FieldLabel>\n        <DatePicker defaultValue={SHIP_DATE} locale=\"en-US\" />\n      </Field>\n      <Field>\n        <FieldLabel>Ship date, United Kingdom (en-GB)</FieldLabel>\n        <DatePicker defaultValue={SHIP_DATE} locale=\"en-GB\" />\n      </Field>\n      <Field>\n        <FieldLabel>Ship date, Germany (de-DE)</FieldLabel>\n        <DatePicker defaultValue={SHIP_DATE} locale=\"de-DE\" />\n      </Field>\n      <Field>\n        <FieldLabel>Ship date, Japan (ja-JP)</FieldLabel>\n        <DatePicker defaultValue={SHIP_DATE} locale=\"ja-JP\" />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "months",
+      "title": "months.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { plainDate } from '@slotted/core/date';\n\nexport default function DatePickerMonths() {\n  return (\n    <Field>\n      <FieldLabel>Installation appointment</FieldLabel>\n      <DatePicker defaultValue={plainDate(2026, 10, 20)} months={2} />\n      <FieldDescription>Technicians book up to eight weeks ahead.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "report-date",
+      "title": "report-date.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useRef, useState } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { DatePicker, type DatePickerHandle } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { createDateFormat, isPlainDate, plainDate, type PlainDate } from '@slotted/core/date';\n\nconst TODAY = plainDate(2026, 9, 30);\nconst PRESETS = [\n  { label: 'Today', date: TODAY },\n  { label: 'End of last month', date: plainDate(2026, 8, 31) },\n  { label: 'End of last quarter', date: plainDate(2026, 6, 30) },\n  { label: 'End of fiscal 2025', date: plainDate(2025, 12, 31) },\n];\nconst words = createDateFormat({ locale: 'en-US' });\n\nexport default function DatePickerReportDate() {\n  const picker = useRef<DatePickerHandle>(null);\n  const [asOf, setAsOf] = useState<PlainDate | null>(plainDate(2026, 8, 31));\n\n  const choose = (next: PlainDate) => {\n    setAsOf(next);\n    picker.current?.close();\n  };\n\n  return (\n    <Field>\n      <FieldLabel>Balance sheet as of</FieldLabel>\n      <DatePicker\n        ref={picker}\n        max={TODAY}\n        onValueChange={(value) => setAsOf(isPlainDate(value) ? value : null)}\n        presets={PRESETS.map((preset) => (\n          <Button key={preset.label} size=\"sm\" variant=\"ghost\" onClick={() => choose(preset.date)}>\n            {preset.label}\n          </Button>\n        ))}\n        value={asOf}\n      />\n      <FieldDescription>\n        {asOf === null\n          ? 'Choose the closing date of the report.'\n          : `Balances close at the end of ${words.describe(asOf)}.`}\n      </FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "shipping-date",
+      "title": "shipping-date.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport {\n  addDays,\n  compareDate,\n  createDateFormat,\n  dayOfWeek,\n  isPlainDate,\n  plainDate,\n  toISODate,\n  type PlainDate,\n} from '@slotted/core/date';\n\nconst ORDERED = plainDate(2026, 9, 30);\nconst HOLIDAYS = new Set(['2026-10-12', '2026-11-11', '2026-11-26', '2026-12-25']);\nconst words = createDateFormat({ locale: 'en-US' });\n\nconst isBusinessDay = (date: PlainDate) =>\n  dayOfWeek(date) !== 0 && dayOfWeek(date) !== 6 && !HOLIDAYS.has(toISODate(date));\n\nconst addBusinessDays = (from: PlainDate, count: number) => {\n  let date = from;\n  for (let added = 0; added < count;) {\n    date = addDays(date, 1);\n    if (isBusinessDay(date)) added += 1;\n  }\n  return date;\n};\n\nconst businessDaysBetween = (from: PlainDate, to: PlainDate) => {\n  let count = 0;\n  for (let date = addDays(from, 1); compareDate(date, to) <= 0; date = addDays(date, 1)) {\n    if (isBusinessDay(date)) count += 1;\n  }\n  return count;\n};\n\nconst EARLIEST = addBusinessDays(ORDERED, 2);\nconst LATEST = addBusinessDays(ORDERED, 40);\n\nexport default function DatePickerShippingDate() {\n  const [date, setDate] = useState<PlainDate | null>(EARLIEST);\n\n  return (\n    <Field required>\n      <FieldLabel>Ship date</FieldLabel>\n      <DatePicker\n        isDateUnavailable={(day) => !isBusinessDay(day)}\n        max={LATEST}\n        min={EARLIEST}\n        onValueChange={(value) => setDate(isPlainDate(value) ? value : null)}\n        value={date}\n      />\n      <FieldDescription>\n        {date === null\n          ? 'Orders ship 2 to 40 business days after they are placed.'\n          : `Ships ${words.describe(date)}, ${businessDaysBetween(ORDERED, date)} business days after the order.`}\n      </FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "time-zones",
+      "title": "time-zones.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { Text } from '@slotted/react/typography';\nimport { isPlainDate, plainDate, toISODate, type PlainDate } from '@slotted/core/date';\n\nexport default function DatePickerTimeZones() {\n  const [date, setDate] = useState<PlainDate | null>(plainDate(2026, 9, 30));\n\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Settlement date, Auckland desk</FieldLabel>\n        <DatePicker\n          onValueChange={(value) => setDate(isPlainDate(value) ? value : null)}\n          timeZone=\"Pacific/Auckland\"\n          value={date}\n        />\n        <FieldDescription>Today is marked by the date in Auckland.</FieldDescription>\n      </Field>\n      <Text size=\"sm\" tone=\"muted\">\n        {date === null\n          ? 'Value: null'\n          : `Value: ${JSON.stringify(date)}, sent as ${toISODate(date)}`}\n      </Text>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "typing",
+      "title": "typing.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { isPlainDate, plainDate, toISODate } from '@slotted/core/date';\n\nconst REASONS: Record<string, string> = {\n  keyboard: 'from the keyboard',\n  pointer: 'pressed in the calendar',\n  clear: 'cleared',\n  blur: 'completed when the field lost focus',\n};\n\nexport default function DatePickerTyping() {\n  const [change, setChange] = useState('No change yet.');\n\n  return (\n    <Field>\n      <FieldLabel>Goods received on</FieldLabel>\n      <DatePicker\n        defaultValue={plainDate(2026, 9, 30)}\n        onValueChange={(value, request) => {\n          const date = isPlainDate(value) ? toISODate(value) : 'empty';\n          setChange(`${date}, ${REASONS[request.reason] ?? request.reason}.`);\n        }}\n      />\n      <FieldDescription>{change}</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "week-numbers",
+      "title": "week-numbers.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { isPlainDate, isoWeekNumber, plainDate, type PlainDate } from '@slotted/core/date';\n\nexport default function DatePickerWeekNumbers() {\n  const [date, setDate] = useState<PlainDate | null>(plainDate(2026, 9, 30));\n\n  return (\n    <Field>\n      <FieldLabel>Production run</FieldLabel>\n      <DatePicker\n        firstDayOfWeek={1}\n        onValueChange={(value) => setDate(isPlainDate(value) ? value : null)}\n        value={date}\n        weekNumbers\n      />\n      <FieldDescription>\n        {date === null ? 'No week planned.' : `Planned for week ${isoWeekNumber(date)}.`}\n      </FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    }
+  ]
+}