@reliability-design/web 1.4.6 → 1.4.8

package/dist/components/rel-time-picker/README.md

@@ -1,199 +1,164 @@
 # rel-time-picker
 
-A fully accessible time picker component built with Lit for the Reliability Design System. Features a trigger button with an hour/minute (and AM/PM) column popover. Selections are held in draft state until Apply is clicked, mirroring the rel-range-picker interaction model.
-
-## Features
-
-- Trigger button with time-column popover (Hour / Min / AM-PM)
-- 12-hour and 24-hour display formats
-- Configurable minute intervals (1, 5, 10, 15, 30, …)
-- Draft state with Now / Cancel / Apply footer
-- Min/max time constraints
-- Optional clear button
-- Label, placeholder, helper text and error states
-- Standardized input API (mirrors rel-textfield / rel-date-picker)
-- Keyboard navigation and full ARIA support
-- Token-driven styling with `::part` hooks
-
-## Value format
-
-The committed `value` is **always 24-hour `"HH:mm"`** (e.g. `"09:30"`, `"17:05"`) regardless of the display `format`, so consumers get a consistent machine-readable string.
+Time selection field implementing the Figma "Time Picker" component (Reliability DS V1.0, node 8301:3771): an editable text field with a clock icon that opens a panel of Hour / Minute (/ Second / AM-PM) columns and a Now / Cancel / OK footer. Column picks are held as a draft until OK; the field also accepts free-form typed times ("930", "9:30 pm", "n" for now). The committed `value` is always 24-hour `"HH:mm"` (or `"HH:mm:ss"` with `seconds`) regardless of the display `format`. Use it for a single time of day; use `rel-date-picker` for dates and `rel-range-picker` for date ranges.
 
 ## Usage
 
-### Basic
-
 ```html
+<!-- Basic (12-hour display, 5-minute steps) -->
 <rel-time-picker></rel-time-picker>
-```
-
-### With Value
 
-```html
-<rel-time-picker value="09:30"></rel-time-picker>
-```
-
-### With Label
-
-```html
-<rel-time-picker label="Start time" placeholder="Select time"></rel-time-picker>
-```
+<!-- Value is always 24-hour HH:mm; the field shows it per `format` -->
+<rel-time-picker value="09:30" label="Start time"></rel-time-picker>
+<rel-time-picker value="17:05" format="24h"></rel-time-picker>
 
-### 24-hour format
+<!-- Seconds column; value becomes HH:mm:ss -->
+<rel-time-picker seconds value="17:05:30" format="24h"></rel-time-picker>
 
-```html
-<rel-time-picker format="24h" value="17:05"></rel-time-picker>
-```
-
-### Minute intervals
-
-```html
+<!-- Minute granularity of the column (typed entry still accepts any minute) -->
 <rel-time-picker minute-step="15"></rel-time-picker>
-<rel-time-picker minute-step="30"></rel-time-picker>
-```
+<rel-time-picker minute-step="1"></rel-time-picker>
 
-### With Min/Max
+<!-- Constrain to business hours (inclusive, HH:mm) -->
+<rel-time-picker min-time="09:00" max-time="17:30" placeholder="Business hours only"></rel-time-picker>
 
-```html
-<rel-time-picker
-  min-time="09:00"
-  max-time="17:30"
-  placeholder="Business hours only"
-></rel-time-picker>
-```
-
-### Clearable
-
-```html
+<!-- Clear button, helper / error text, required -->
 <rel-time-picker value="09:30" clearable></rel-time-picker>
-```
-
-### States
+<rel-time-picker label="Start time" helper-text="Local timezone"></rel-time-picker>
+<rel-time-picker label="Start time" error error-message="Select a valid time"></rel-time-picker>
+<rel-time-picker label="Start time" required></rel-time-picker>
 
-```html
+<!-- States -->
 <rel-time-picker value="09:30" disabled></rel-time-picker>
 <rel-time-picker value="09:30" readonly></rel-time-picker>
-<rel-time-picker error error-message="Select a valid time"></rel-time-picker>
-<rel-time-picker helper-text="Local timezone"></rel-time-picker>
-<rel-time-picker label="Start time" required></rel-time-picker>
-```
-
-### Sizes / layout
 
-```html
+<!-- Sizes (field 32 / 40 / 48px, panel 220 / 250 / 280px) and layout -->
 <rel-time-picker size="small"></rel-time-picker>
+<rel-time-picker size="medium"></rel-time-picker>
 <rel-time-picker size="large"></rel-time-picker>
-<rel-time-picker fullWidth></rel-time-picker>
-```
-
-### Form usage
+<rel-time-picker fullwidth label="Full width"></rel-time-picker>
 
-```html
+<!-- Form integration: `name` renders a hidden input carrying the value -->
 <form>
   <rel-time-picker name="startTime" label="Start time" required></rel-time-picker>
 </form>
-```
-
-The value is mirrored onto a hidden `<input name="...">` so native form submission works.
-
-### Programmatic Control (JavaScript)
 
-```javascript
-const picker = document.querySelector('rel-time-picker');
-
-// Set value (always 24h HH:mm)
-picker.value = '14:30';
-
-// Open programmatically
-picker.open = true;
-
-// Listen to changes (fired on Apply, and on clear with value: null)
-picker.addEventListener('rel-change', (e) => {
-  console.log('Selected time:', e.detail.value); // "14:30" | null
-});
-
-picker.addEventListener('rel-open-change', (e) => {
-  console.log('Open:', e.detail.open);
-});
+<!-- Programmatic control -->
+<rel-time-picker id="tp" clearable></rel-time-picker>
+<script>
+  const picker = document.getElementById('tp');
+  picker.value = '14:30';   // always 24h
+  picker.open = true;       // opens the panel and focuses the selected hour
+
+  picker.addEventListener('rel-change', (e) => {
+    console.log('time:', e.detail.value); // "14:30" | "14:30:00" | null (cleared)
+  });
+  picker.addEventListener('rel-open-change', (e) => {
+    console.log('open:', e.detail.open);
+  });
+</script>
 ```
 
-## Interaction model
+### Typed entry
 
-- Clicking a column entry updates the **draft** shown in the readout row; nothing is committed yet.
-- **Apply** commits the draft, emits `rel-change` and closes.
-- **Cancel**, `Escape` or an outside click discards the draft (same as rel-range-picker).
-- **Now** sets the draft to the current time, snapped to `minute-step` and clamped into `min-time`/`max-time`.
-- Picking an hour with no minute selected defaults the minute to `00`.
+Typing into the field and pressing `Enter` (or leaving the field) commits the text. Accepted forms are case- and whitespace-insensitive: `9` → 09:00, `930` / `0930` / `9:30` / `9.30` / `9 30` → 09:30, `093015` / `9:30:15` → 09:30:15, `9 pm` / `9:30p` → 21:00 / 21:30, `12am` → 00:00, `12 pm` → 12:00, and `n` / `now` → the current time. Unparseable text shows "Invalid time", a time outside `min-time` / `max-time` shows "Time out of range"; in both cases the text stays in the field for correction and the committed `value` is untouched.
 
-## Keyboard
+<!-- readme-gen:start -->
 
-| Key | Context | Action |
-| --- | --- | --- |
-| `Enter` / `Space` / `ArrowDown` | Trigger | Open the popover |
-| `ArrowUp` / `ArrowDown` | Column | Move and select the previous/next entry |
-| `ArrowLeft` / `ArrowRight` | Column | Jump between Hour / Min / AM-PM columns |
-| `Home` / `End` | Column | First / last entry |
-| `Enter` | Column | Select the entry and Apply |
-| `Escape` | Anywhere | Discard draft and close |
+<!-- Generated from rel-time-picker.ts — do not edit; run readme-generate.mjs -->
+
+## API
 
-## Properties
+### Attributes / Properties
 
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `value` | `value` | `string \| null` | `null` | Committed time, 24h `"HH:mm"` |
-| `placeholder` | `placeholder` | `string` | `"Select time"` | Trigger text when empty |
-| `label` | `label` | `string \| null` | `null` | Field label |
-| `format` | `format` | `"12h" \| "24h"` | `"12h"` | Display format (value stays `HH:mm`) |
-| `minuteStep` | `minute-step` | `number` | `1` | Minute column granularity |
-| `minTime` | `min-time` | `string \| null` | `null` | Earliest selectable time (inclusive) |
-| `maxTime` | `max-time` | `string \| null` | `null` | Latest selectable time (inclusive) |
-| `disabled` | `disabled` | `boolean` | `false` | Disables all interaction |
-| `readonly` | `readonly` | `boolean` | `false` | Value shown, popover cannot open |
-| `required` | `required` | `boolean` | `false` | Renders `*` and sets `aria-required` |
-| `clearable` | `clearable` | `boolean` | `false` | Clear button when a value is set |
-| `open` | `open` | `boolean` | `false` | Controls / reflects popover state |
-| `error` | `error` | `boolean` | `false` | Error styling |
-| `invalid` | `invalid` | `boolean` | `false` | Alias for `error` |
-| `errorMessage` | `error-message` | `string` | — | Shown below when error/invalid |
-| `helperText` | `helper-text` | `string` | — | Assistive text below the field |
-| `name` | `name` | `string` | — | Form field name (hidden input) |
-| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Trigger size |
-| `fullWidth` | `fullWidth` | `boolean` | `false` | Fill the parent width |
-| `variant` | `variant` | `"outlined"` | `"outlined"` | Visual style |
+| `value` | `value` | `string \| null` | `null` | Committed time, 24-hour "HH:mm" or "HH:mm:ss" (e.g. "09:30", "17:05:30"). Reflected. |
+| `placeholder` | `placeholder` | `string` | `"Select time"` | Placeholder shown in the field while no value is committed and nothing is typed. |
+| `label` | `label` | `string \| null` | `null` | Field label rendered above the trigger; also the input's accessible name (unset → "Select time"). |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the field (0.6 opacity, no pointer events); the panel cannot open. Reflected. |
+| `required` | `required` | `boolean` | `false` | Renders the `*` mark after the label and sets `aria-required`; not enforced by the component. |
+| `readonly` | `readonly` | `boolean` | `false` | Shows the value but blocks typing and opening the panel. Reflected. |
+| `format` | `format` | `"12h" \| "24h"` | `"12h"` | Display format of the trigger text and hour column. Value stays 24-hour. |
+| `seconds` | `seconds` | `boolean` | `false` | Shows the seconds column; committed value becomes "HH:mm:ss". Reflected. |
+| `minuteStep` | `minute-step` | `number` | `5` | Minute granularity of the minutes column (1, 5, 10, 15, 30, …). |
+| `minTime` | `min-time` | `string \| null` | `null` | Earliest selectable time, "HH:mm" (inclusive). |
+| `maxTime` | `max-time` | `string \| null` | `null` | Latest selectable time, "HH:mm" (inclusive). |
+| `open` | `open` | `boolean` | `false` | Whether the panel is open. Settable from outside; opening resets the draft from `value` (programmatic changes do not fire `rel-open-change`). Reflected. |
+| `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) button inside the field while a value is set; clearing commits `null`. |
+| `error` | `error` | `boolean` | `false` | Error styling (danger border, `aria-invalid`) and shows `errorMessage` below the field. |
+| `invalid` | `invalid` | `boolean` | `false` | Alias for `error` (requested-API compat); either flag applies error styling. |
+| `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the field while `error` / `invalid` is set (falls back to the typed-entry parse error, then `helperText`). |
+| `helperText` | `helper-text` | `string` | `undefined` | Assistive text shown below the field when not in error. |
+| `name` | `name` | `string` | `undefined` | When set, renders a hidden `<input name="…">` carrying `value` for native form submission. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Trigger height on the shared field scale — small 32 / medium 40 / large 48px border-box; also sets the panel width (220 / 250 / 280px) and option row height (32 / 36 / 40px). Small lowers the trigger min-width from 160 to 128px. |
+| `variant` | `variant` | `"outlined"` | `"outlined"` | Visual style; only `"outlined"` exists today. Reflected. |
+| `fullWidth` | `fullwidth` | `boolean` | `false` | Fills the parent width (the host is inline-block with intrinsic width otherwise). The attribute is lowercase `fullwidth`. Reflected. |
 
 ## Events
 
-| Event | Detail | Description |
-| --- | --- | --- |
-| `rel-change` | `{ value: string \| null }` | Fired on Apply and on clear |
-| `rel-open-change` | `{ open: boolean }` | Popover opened/closed |
-| `rel-focus` | — | Trigger received focus |
-| `rel-blur` | — | Trigger lost focus |
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-blur` | — | bubbles / composed | Fired when the text input loses focus (before any typed text is committed). No detail. |
+| `rel-change` | `{ value: newValue } / { value: null }` | bubbles / composed | Fired when a time is committed (OK, Enter / blur on typed text, the Now shortcut) or cleared. Detail: `{ value: string \| null }` — 24-hour "HH:mm" / "HH:mm:ss", or `null` after a clear. |
+| `rel-focus` | — | bubbles / composed | Fired when the text input receives focus. No detail. |
+| `rel-open-change` | `{ open: this.open } / { open: false }` | bubbles / composed | Fired whenever the panel opens or closes through user interaction. Detail: `{ open: boolean }`. |
 
-## CSS Parts
+## Slots
 
-| Part | Element |
+| Slot | Description |
 | --- | --- |
-| `base` | Outer wrapper |
-| `label` | Field label |
-| `trigger` | Trigger button |
-| `value` | Trigger value/placeholder text |
-| `icon` | Trailing clock icon |
-| `panel` | Popover panel |
-| `option` | Hour/minute/period entries |
-| `footer` | Now / Cancel / Apply row |
-| `helper` | Helper / error text |
-
-```css
-/* Example: widen the popover and restyle options */
-rel-time-picker::part(panel) {
-  box-shadow: var(--rel-shadows-shadow-400);
-}
-rel-time-picker::part(option) {
-  border-radius: var(--rel-border-radius-xs);
-}
-```
+| — | This element has no slots. |
 
-## Design tokens
+## CSS Parts
 
-Styling is fully token-driven: surfaces (`--rel-bg-surface`, `--rel-bg-surface-elevated`), borders (`--rel-border-default`, `--rel-border-strong`, `--rel-border-focus`, `--rel-border-danger`, `--rel-border-subtle`), text (`--rel-text-default`, `--rel-text-label`, `--rel-text-placeholder`, `--rel-text-danger`, `--rel-text-disabled`), selection (`--rel-action-brand-fill`, `--rel-action-brand-label-icons-primary`), spacing, radius, shadows and the `--rel-body-*` typography roles.
+| Part | Description |
+| --- | --- |
+| `base` | Outer wrapper; carries the size / error / readonly classes |
+| `label` | The field label above the trigger |
+| `trigger` | The field box that anchors the panel (wraps the text input and the icons) |
+| `value` | The editable text input showing the formatted time |
+| `icon` | The trailing clock icon |
+| `panel` | The popover panel (`role="dialog"`) |
+| `shortcuts` | The typed-shortcut chip row at the top of the panel (N → Now) |
+| `option` | Each hour / minute / second / AM-PM entry button |
+| `footer` | The Now / Cancel / OK row |
+| `helper` | The helper / error text live region under the field |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The editable field is an `<input type="text" role="combobox">` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-required` (from `required`), `aria-invalid` (from `error` / `invalid` / a typed-entry error) and `aria-describedby` pointing at the helper / error text. Its accessible name is the `label` (via `aria-labelledby`), falling back to `aria-label="Select time"`.
+- The clock icon is a button labelled "Open time panel" with its own `aria-expanded`; the optional clear button is labelled "Clear time". The required mark `*` is `aria-hidden`.
+- The panel is `role="dialog"` `aria-label="Choose time"`, promoted to the browser top layer (`popover="manual"`) so a modal / drawer ancestor cannot clip it. Each column is a `role="listbox"` named "Hours", "Minutes", "Seconds" or "AM or PM"; entries are `role="option"` buttons with `aria-selected`, and out-of-range entries are native `disabled`. Each column uses a roving `tabindex` (the selected entry, else the first).
+- The helper / error text (part `helper`) is a persistent `aria-live="polite"` region, so error messages and typed-entry errors are announced as they appear.
+- Focus: opening with the clock icon, `ArrowDown`, `Enter` or by setting `open` moves focus to the selected (or first enabled) hour without scrolling the page; opening by clicking into the field keeps focus in the input so typing continues to work. Cancel, `Escape` and OK return focus to the field; an outside click closes without refocusing.
+- Screen-reader announcement (shared `announce()` utility): "{formatted time} selected" when OK commits the draft.
+
+| Key | Where | Action |
+| --- | --- | --- |
+| Typing | Field | Edits the free-form text (see Typed entry); clears any previous parse error |
+| `Enter` | Field | Commit the typed text; if nothing was typed, open the panel (closed) or apply the draft (open) |
+| `ArrowDown` | Field | Open the panel, or move focus into the columns when already open |
+| `Escape` | Field | Revert uncommitted typed text; also closes the panel discarding the draft |
+| Blur | Field | Commit the typed text when focus leaves the component (moving into the panel does not commit) |
+| `ArrowUp` / `ArrowDown` | Column | Move to and select the previous / next enabled entry |
+| `ArrowLeft` / `ArrowRight` | Column | Jump to the previous / next column (Hour → Minute → Second → AM/PM) |
+| `Home` / `End` | Column | Select the first / last enabled entry |
+| `Enter` | Column | Select the entry and apply (OK) |
+| `N` | Panel | Commit the current time immediately (same as the "N → Now" chip) and close |
+| `Escape` | Anywhere | Discard the draft and close |
+
+## Notes / Edge Cases
+
+- `value` is always 24-hour `"HH:mm"`, or `"HH:mm:ss"` when `seconds` is set; the `format` prop only changes the field text and the hour column (`12h` shows 01–12 plus an AM/PM column, `24h` shows 00–23). An unparseable `value` renders as empty.
+- `min-time` / `max-time` are `"HH:mm"` (inclusive) and are compared at minute precision even with `seconds`. Hours with no in-range step minute and AM/PM periods with no enabled hour are disabled; picking an hour snaps the draft minute to the nearest in-range step.
+- Draft model: column clicks only update the draft; **OK** commits and fires `rel-change`; **Cancel**, `Escape` or an outside click discard it (and fire `rel-open-change` with `open: false`). The OK button is disabled until an hour is chosen; picking an hour with no minute defaults the minute to `00`; picking a minute or second first defaults the hour to the first enabled one.
+- Two "now" behaviours: the footer **Now** link sets the draft to the current time snapped to `minute-step` (and to the nearest enabled hour) — you still press OK; the `N` shortcut / typed `n` / the "N → Now" chip commit the current time immediately, clamped into `min-time` / `max-time`.
+- Typed entry is not limited to `minute-step`: `9:07` commits `09:07` even with `minute-step="15"`. Typing an empty string and committing behaves like the clear button (`rel-change` with `value: null`).
+- `minute-step` outside 1–60 falls back to 1; the seconds column is always step 1.
+- `invalid` is a non-deprecated alias of `error`; either flag applies error styling. The text below the field is `error-message`, else the typed-entry error, else `helper-text`.
+- Panel widths are fixed per `size` (220 / 250 / 280px, border-box) and capped to the viewport; it flips above the field when there is no room below and shrinks (columns scroll) rather than covering the field. Footer buttons are always small per the Figma spec; OK is narrowed to 60px min-width.
+- Setting `open` programmatically opens the panel and resets the draft from `value`; it does not fire `rel-open-change` (only user interaction does).
+- `fullWidth` reflects as the lowercase `fullwidth` attribute; the host is `inline-block` with intrinsic width otherwise.