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

package/dist/docs/time-picker.json

@@ -0,0 +1,677 @@
+{
+  "family": "time-picker",
+  "ui": "time-picker",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Time field with a picker 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"
+    ],
+    "unavailableOptions": [
+      "disable",
+      "hide"
+    ],
+    "hourCycle": [
+      12,
+      24
+    ],
+    "granularity": [
+      "hour",
+      "minute",
+      "second"
+    ]
+  },
+  "members": {
+    "timePicker": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "placement": "bottom-start",
+        "closeOnSelect": "auto",
+        "step": 900,
+        "unavailableOptions": "disable",
+        "granularity": "minute",
+        "clearable": false,
+        "maxOptions": 1440
+      },
+      "capabilities": [
+        "value",
+        "open",
+        "current",
+        "placement",
+        "appearance",
+        "size",
+        "content",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "invalid",
+        "readonly",
+        "required",
+        "open",
+        "selected",
+        "current"
+      ],
+      "parts": [
+        "root",
+        "control",
+        "trigger",
+        "positioner",
+        "content",
+        "head",
+        "now",
+        "presets",
+        "list",
+        "option",
+        "empty",
+        "footer"
+      ]
+    }
+  },
+  "docs": {
+    "timePicker": {
+      "imports": {
+        "source": "import { TimePicker, TimePickerDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The frame. Carries data-ui=\"time-picker\", the axes and the state attributes, including data-open. It draws no border of its own: the time-field inside draws one, and a second would be a second place to fix one defect."
+        },
+        {
+          "part": "control",
+          "element": "div",
+          "required": true,
+          "purpose": "The box the positioner measures, holding the field and the trigger. The surface hangs from this rather than from the button, so it lines up with the frame the reader sees."
+        },
+        {
+          "part": "trigger",
+          "element": "button",
+          "required": true,
+          "purpose": "Opens the panel, from inside the field’s end slot. Its accessible name carries the chosen time, because focus returns here when the surface closes. It carries aria-haspopup=\"listbox\", aria-expanded and aria-controls, and it is always drawn: ChromeOS turns Alt+ArrowDown into PageDown before the browser sees it."
+        },
+        {
+          "part": "positioner",
+          "element": "div",
+          "required": false,
+          "purpose": "The layer the surface stands on, portalled to the end of the document so nothing between the control and the root can clip it. It carries data-ui too — a stylesheet cannot reach a subtree that is no longer inside the root — plus data-placement and data-presentation."
+        },
+        {
+          "part": "content",
+          "element": "div",
+          "required": false,
+          "purpose": "The panel: one role=\"listbox\", at every step and every granularity. A column per unit was drawn and withdrawn, so there is no second role to get wrong."
+        },
+        {
+          "part": "head",
+          "element": "div",
+          "required": false,
+          "purpose": "Where the now control sits, above the list and below the consumer’s own shortcuts."
+        },
+        {
+          "part": "now",
+          "element": "button",
+          "required": false,
+          "purpose": "Writes the current time. It is the zero case of the field’s relative expression, drawn as one labelled press so a reader who never discovers + still has it."
+        },
+        {
+          "part": "presets",
+          "element": "div",
+          "required": false,
+          "purpose": "The consumer’s own shortcuts, in a column beside the list. This family ships no list of them: \"start of the shift\" is a business clock, and a library guessing at one would be guessing at an industry."
+        },
+        {
+          "part": "list",
+          "element": "div",
+          "required": false,
+          "purpose": "The rows, and the only thing that scrolls. Capped at eight and a half row pitches, so the half-row says the list continues; data-truncated says the list stops short of what the configuration asked for."
+        },
+        {
+          "part": "option",
+          "element": "div",
+          "required": false,
+          "purpose": "One whole time, as role=\"option\" with aria-selected. data-selected is the chosen row, data-current is where a key will act, and data-disabled is a time a bound or the predicate refuses."
+        },
+        {
+          "part": "empty",
+          "element": "div",
+          "required": false,
+          "purpose": "Drawn when no time is available at all — min above max, or a predicate that refuses every step. It is a sentence rather than an empty box, which is what MUI and Ant both leave behind."
+        },
+        {
+          "part": "footer",
+          "element": "div",
+          "required": false,
+          "purpose": "The consumer’s own actions, under the list."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "PlainTime | null",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Present means the consumer owns the value. The picker asks and waits rather than moving it."
+        },
+        {
+          "name": "defaultValue",
+          "type": "PlainTime | null",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "The value the picker starts from when nobody else writes one."
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Present means the consumer owns whether the surface is showing."
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TimePicker",
+          "description": "Whether the surface starts open."
+        },
+        {
+          "name": "highlightedValue",
+          "type": "PlainTime | null",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Where the reader is in the list. Present means the consumer owns it; the highlight is not the value, and moving it moves nothing."
+        },
+        {
+          "name": "defaultHighlightedValue",
+          "type": "PlainTime | null",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Where the highlight starts, before the panel places it on the chosen time."
+        },
+        {
+          "name": "min",
+          "type": "PlainTime",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "The earliest time the list offers and the value accepts."
+        },
+        {
+          "name": "max",
+          "type": "PlainTime",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "The latest time the list offers and the value accepts."
+        },
+        {
+          "name": "isTimeUnavailable",
+          "type": "(time: PlainTime) => boolean",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Refuses particular times. A refused row is disabled by default rather than dropped."
+        },
+        {
+          "name": "step",
+          "type": "number",
+          "defaultValue": "900",
+          "appliesTo": "TimePicker",
+          "description": "Seconds between two offered times, counting from min when it is stated and from midnight when it is not. Ignored when options states the list."
+        },
+        {
+          "name": "options",
+          "type": "readonly PlainTime[]",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "The times to offer, stated rather than stepped, in the consumer’s own order. It is what makes an irregular list and a second-level set expressible, and why this family needs no column panel."
+        },
+        {
+          "name": "maxOptions",
+          "type": "number",
+          "defaultValue": "1440",
+          "appliesTo": "TimePicker",
+          "description": "How many rows the list may reach — a whole day at a one-minute step. Beyond it the list is cut, data-truncated says so, and the rest is typed into the field."
+        },
+        {
+          "name": "unavailableOptions",
+          "type": "'disable' | 'hide'",
+          "defaultValue": "disable",
+          "appliesTo": "TimePicker",
+          "description": "What a refused row looks like. Disabling is the default because a list that drops rows is a list whose step nobody can infer."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "SlottedProvider",
+          "appliesTo": "TimePicker",
+          "description": "BCP 47. Decides how every row is written. Unset, the language in force decides."
+        },
+        {
+          "name": "timeZone",
+          "type": "string",
+          "defaultValue": "runtime",
+          "appliesTo": "TimePicker",
+          "description": "Which zone answers \"what time is it now\", for the opening position and the now control."
+        },
+        {
+          "name": "hourCycle",
+          "type": "12 | 24",
+          "defaultValue": "locale",
+          "appliesTo": "TimePicker",
+          "description": "The question a consumer asks about the clock, passed through to the field and the rows."
+        },
+        {
+          "name": "granularity",
+          "type": "'hour' | 'minute' | 'second'",
+          "defaultValue": "minute",
+          "appliesTo": "TimePicker",
+          "description": "The smallest unit the field draws and the rows carry."
+        },
+        {
+          "name": "referenceTime",
+          "type": "PlainTime",
+          "defaultValue": "now",
+          "appliesTo": "TimePicker",
+          "description": "What \"now\" means for the opening position, the now control and the field’s durations."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "TimePicker",
+          "description": "The type step, matching the field around it."
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "TimePicker",
+          "description": "How much frame the control shows at rest."
+        },
+        {
+          "name": "placement",
+          "type": "'bottom-start' | 'bottom' | 'bottom-end' | 'top-start' | 'top' | 'top-end'",
+          "defaultValue": "bottom-start",
+          "appliesTo": "TimePicker",
+          "description": "Where the surface starts, before the positioner reads the room."
+        },
+        {
+          "name": "closeOnSelect",
+          "type": "'auto' | 'always' | 'never'",
+          "defaultValue": "auto",
+          "appliesTo": "TimePicker",
+          "description": "Whether choosing closes the surface. auto closes, because one press chooses a whole time."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Unstated rather than false, so the picker defers to the field around it."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Readable and focusable, and not changeable."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Unstated rather than false. Retargets the focus ring."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Unstated rather than false."
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TimePicker",
+          "description": "Draws the field’s own clear button."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "The name the hidden input carries the HH:mm:ss string under."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<TimePickerMessages>",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Words laid over the language in force, key by key: the trigger’s name while nothing is chosen (choose) and once a time is (change, with a {time} slot), the now control (now), the empty panel (empty) and the description of a list cut short (truncated)."
+        },
+        {
+          "name": "presets",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "The consumer’s own shortcuts, beside the list."
+        },
+        {
+          "name": "footer",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "The consumer’s own actions, under the list."
+        }
+      ],
+      "composition": [
+        {
+          "name": "TimePickerDefaultsProvider",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "application",
+          "description": "Sets step, maxOptions, unavailableOptions, placement, closeOnSelect, timeZone, hourCycle, granularity, size and variant once for everything under it. The locale and the words come from SlottedProvider."
+        },
+        {
+          "name": "renderOption",
+          "type": "(state: TimePickerOptionState) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Draws what is inside one row. The row itself — its role, its states, its keyboard and its target size — stays the family’s."
+        },
+        {
+          "name": "render",
+          "type": "(props: TimePickerRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Substitutes the element the frame renders, carrying the ref the positioner measures against."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<TimePickerHandle>",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "focus() puts the reader on the first segment of the field; open() and close() move the surface without a pointer."
+        },
+        {
+          "name": "onKeyDown",
+          "type": "KeyboardEventHandler",
+          "defaultValue": "—",
+          "appliesTo": "TimePicker",
+          "description": "Runs before the family acts, on the control and on the list alike, and calling preventDefault stops it acting at all."
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: PlainTime | null, request: TimeFieldChangeRequest)",
+          "when": "Before the value moves, and cancellable. It arrives from the field when a typed run ends, and from the panel when a row is chosen — with reason \"select\" there. The request carries the segments and whether a duration crossed midnight."
+        },
+        {
+          "name": "onOpenChange",
+          "payload": "(open: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before the surface opens or closes, and cancellable. The reason says which of pointer, keyboard, escape, outsidePress or select moved it — a boolean cannot, and a consumer who has to guess writes the wrong handler."
+        },
+        {
+          "name": "onHighlightedValueChange",
+          "payload": "(value: PlainTime | null, request: ChangeRequest<PlainTime | null>)",
+          "when": "Before the highlight moves. Selection does not follow focus here: the highlight is where a key will act and the value is what was chosen, and a reader arrowing through ninety-six quarter-hours would otherwise emit ninety-six value requests."
+        }
+      ],
+      "accessibility": [
+        "The panel is one role=\"listbox\" in every configuration the family has, so the trigger says aria-haspopup=\"listbox\" everywhere and there is no second role a reader has to learn. A column per unit was drawn and withdrawn, and with it the dialog role a popup of several listboxes would have needed.",
+        "Focus is real inside the list — a roving tabindex, not aria-activedescendant — because the reader is inside the list rather than typing into a control that must keep focus. The pattern’s own rule for where focus lands is taken whole: the selected option, or the first when none is selected.",
+        "Selection does not follow focus. The listbox pattern lists it as optional and warns it can degrade accessibility, and here it would emit one value request per option as a reader arrows through ninety-six quarter-hours.",
+        "The trigger’s accessible name carries the chosen time, because focus returns to it when the surface closes — which is where a reader is told what was chosen, and what the APG names as an accessibility feature of its own example.",
+        "A list cut at maxOptions says so twice: data-truncated in the DOM for a stylesheet, and the panel’s accessible description for a reader, naming that the remaining times are typed into the field rather than listed."
+      ]
+    }
+  },
+  "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-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-radius-sm",
+    "--slotted-shadow-md",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-9",
+    "--slotted-surface-raised",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-time-picker-content-border-color",
+    "--slotted-time-picker-content-color",
+    "--slotted-time-picker-content-min-inline-size",
+    "--slotted-time-picker-content-padding",
+    "--slotted-time-picker-content-radius",
+    "--slotted-time-picker-content-shadow",
+    "--slotted-time-picker-invalid-focus-ring-color",
+    "--slotted-time-picker-label-color",
+    "--slotted-time-picker-list-block-size",
+    "--slotted-time-picker-now-color",
+    "--slotted-time-picker-option-current-background",
+    "--slotted-time-picker-option-hover-background",
+    "--slotted-time-picker-option-radius",
+    "--slotted-time-picker-option-selected-background",
+    "--slotted-time-picker-option-selected-color",
+    "--slotted-time-picker-option-selected-hover-background",
+    "--slotted-time-picker-radius",
+    "--slotted-time-picker-sheet-inline-size",
+    "--slotted-time-picker-surface",
+    "--slotted-time-picker-trigger-active-background",
+    "--slotted-time-picker-trigger-color",
+    "--slotted-time-picker-trigger-hover-background",
+    "--slotted-time-picker-trigger-size",
+    "--slotted-tone-accent-on-solid",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-accent-solid-hover",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-z-index-popover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One picker with every axis on it, driven by the controls below the canvas. Open it with the clock, type into the field, and press Alt+ArrowDown to open the panel without leaving the segments.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>Hora de início</FieldLabel>\n  <TimePicker clearable locale=\"pt-BR\" name=\"inicio\" step={900} />\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "panel",
+      "title": "One panel shape",
+      "note": "A listbox of whole times, at every step. 09:15 is legible at a glance where a 15 in a column of minutes is legible only beside the column next to it — and one axis is what makes Home, End, type-ahead and the arrows all mean something.",
+      "language": "tsx",
+      "source": "<TimePicker defaultOpen locale=\"pt-BR\" step={1800} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "explicit",
+      "title": "The times a consumer states",
+      "note": "No step describes a clinic open at 09:00, 09:20, 11:40 and 13:45, and a predicate only subtracts from times that fall on one. options hands the panel exactly the times it should offer, in the order it should offer them — and it is half the answer to why this family needs no column panel.",
+      "language": "tsx",
+      "source": "<TimePicker\n  locale=\"pt-BR\"\n  options={[\n    { hour: 9, minute: 0, second: 0 },\n    { hour: 9, minute: 20, second: 0 },\n    { hour: 13, minute: 45, second: 0 },\n  ]}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "seconds",
+      "title": "Seconds, chosen from a surface",
+      "note": "The other half of the same answer. A day at a one-second step is 86 400 rows and not a list; a stated set of marks is four. The field beside the panel types any second the list does not offer.",
+      "language": "tsx",
+      "source": "<TimePicker\n  granularity=\"second\"\n  locale=\"pt-BR\"\n  options={[\n    { hour: 0, minute: 0, second: 15 },\n    { hour: 0, minute: 0, second: 30 },\n    { hour: 0, minute: 0, second: 45 },\n  ]}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "step",
+      "title": "The step, and where it counts from",
+      "note": "A step in seconds, counting from min when it is stated and from midnight when it is not — the platform’s own rule for input[type=time], and one no surveyed panel states. A value off the step is not invalid: the field still types 09:15 when the panel offers 09:07.",
+      "language": "tsx",
+      "source": "<>\n  <TimePicker step={3600} />\n  <TimePicker step={1800} />\n  <TimePicker min={{ hour: 9, minute: 7, second: 0 }} step={900} />\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "range-bounds",
+      "title": "Bounds",
+      "note": "min and max fence both the list and the value. The panel offers nothing outside them, and a value outside them is invalid whatever the field around the picker says.",
+      "language": "tsx",
+      "source": "<TimePicker max={{ hour: 18, minute: 0, second: 0 }} min={{ hour: 9, minute: 0, second: 0 }} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "unavailable",
+      "title": "Times the product refuses",
+      "note": "isTimeUnavailable answers a lunch break or a booked slot. By default the row stays and is disabled — a list that drops rows is a list whose step nobody can infer — and unavailableOptions=\"hide\" is the consumer’s choice to drop it anyway.",
+      "language": "tsx",
+      "source": "<>\n  <TimePicker isTimeUnavailable={(time) => time.hour === 12} />\n  <TimePicker isTimeUnavailable={(time) => time.hour === 12} unavailableOptions=\"hide\" />\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "now",
+      "title": "The current time, in one press",
+      "note": "The control at the head of the panel writes the time it is now. It is the zero case of the field’s relative expression, drawn as a labelled press so a reader who never discovers + still has it.",
+      "language": "tsx",
+      "source": "<TimePicker messages={{ now: 'Agora' }} referenceTime={{ hour: 9, minute: 47, second: 0 }} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "relative",
+      "title": "The field keeps every key it had",
+      "note": "The panel complements the typing and never replaces it, which is what docs/component-features.md §6 asks for. Alt+ArrowDown opens the panel and leaves focus in the segments; + still opens a duration; and the highlight follows what is typed.",
+      "language": "tsx",
+      "source": "<TimePicker defaultOpen referenceTime={{ hour: 14, minute: 40, second: 0 }} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "presets",
+      "title": "Shortcuts and actions",
+      "note": "Two slots the family ships empty: a column of the consumer’s own shortcuts beside the list, and a row of their own actions under it. The surface stops being the anchor’s width when the shortcuts are there, so the times keep a column worth reading.",
+      "language": "tsx",
+      "source": "<TimePicker\n  footer={<Button size=\"sm\">Aplicar</Button>}\n  presets={<Button size=\"sm\">Início do turno</Button>}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Size",
+      "note": "The three steps the control can be, and the panel answers each: the row height and the eight-and-a-half-row cap are counted in the same unit, so a dense panel shows the same number of times in less room.",
+      "language": "tsx",
+      "source": "<>\n  <TimePicker size=\"sm\" />\n  <TimePicker size=\"md\" />\n  <TimePicker size=\"lg\" />\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "Variant",
+      "note": "How much frame the control shows at rest. The panel does not change with it: a surface floating over the page has its own ground whatever the control below it looks like.",
+      "language": "tsx",
+      "source": "<>\n  <TimePicker variant=\"outline\" />\n  <TimePicker variant=\"subtle\" />\n  <TimePicker variant=\"plain\" />\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "placement",
+      "title": "Where it opens",
+      "note": "The side and alignment the surface starts from, before the positioner reads the room and moves it. What the engine resolved is written back as data-placement, so a stylesheet can answer the side it actually landed on.",
+      "language": "tsx",
+      "source": "<>\n  <TimePicker placement=\"bottom-start\" />\n  <TimePicker placement=\"top-end\" />\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "Read-only keeps the value readable and the panel shut; disabled answers no press at all; invalid retargets the ring on the control and on the trigger together. The row of options has its own four, and the chosen row answers the pointer in its own tone rather than turning grey.",
+      "language": "tsx",
+      "source": "<>\n  <TimePicker readOnly />\n  <TimePicker invalid />\n  <TimePicker disabled />\n  <TimePicker required />\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "forms",
+      "title": "In a form",
+      "note": "The value reaches a plain form post as an HH:mm:ss string through the field’s hidden input, so a server reads it without any JavaScript touching the control.",
+      "language": "tsx",
+      "source": "<form action=\"/agendar\" method=\"post\">\n  <Field>\n    <FieldLabel>Hora de início</FieldLabel>\n    <TimePicker name=\"inicio\" required />\n  </Field>\n</form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "narrow",
+      "title": "Narrow",
+      "note": "The panel takes the anchor’s width, floored so a narrow field never produces a column too tight to read a time in and capped so a wide form never stretches one column of times across a page. Below 480 pixels on a finger it becomes a sheet, and the DOM says which it is.",
+      "language": "tsx",
+      "source": "<div className=\"slotted-demo-measure\">\n  <TimePicker locale=\"pt-BR\" />\n</div>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "The provider sets the step and the labels once; renderOption draws the row without owning it; render substitutes the frame; and the ref carries focus(), open() and close().",
+      "language": "tsx",
+      "source": "<TimePickerDefaultsProvider step={1200}>\n  <TimePicker ref={handle} renderOption={(option) => <span>{option.label}</span>} />\n</TimePickerDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard",
+      "note": "Alt+ArrowDown opens the panel from the field and leaves focus there; the trigger’s ArrowDown moves focus into the list; inside it the arrows walk, Home and End reach the ends, PageUp and PageDown cross one hour boundary each, digits jump, and Enter chooses. Escape closes and puts focus back on the trigger.",
+      "language": "tsx",
+      "source": "<TimePicker\n  onKeyDown={(event) => {\n    if (event.key === 'Escape') clearSelection();\n  }}\n/>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}