@reliability-design/web 1.4.6 → 1.4.7

package/dist/components/rel-textfield/README.md

@@ -1,106 +1,196 @@
 # rel-textfield
 
-## Overview
-
-A text input field component with support for labels, icons, validation states, and supporting text. Used for single-line text entry in forms and user interfaces.
+`<rel-textfield>` is the single-line and multi-line text input from the Figma "Text Field" component: a labelled control with three chromes (`default` outlined, `underline`, `legend` notched outline), three heights (32 / 40 / 48px), prefix and suffix blocks (icon, short text or slotted content), error / helper text and full-width or inline layout. Use it for free-text entry — names, emails, passwords, numbers, notes (`multiline`). For picking from a fixed list use `rel-select`; for type-ahead against a list use `rel-autocomplete`; for dates and times use the picker components, which reuse this field's chrome.
 
 ## Usage
 
 ```html
-<!-- Basic usage -->
-<rel-textfield label="Email" placeholder="Enter your email"></rel-textfield>
+<!-- Basic field -->
+<rel-textfield label="Email" placeholder="you@example.com" type="email"></rel-textfield>
+
+<!-- Sizes and chromes -->
+<rel-textfield label="Small" size="small"></rel-textfield>
+<rel-textfield label="Large" size="large"></rel-textfield>
+<rel-textfield label="Underline" variant="underline"></rel-textfield>
+<rel-textfield label="Legend" variant="legend"></rel-textfield>
+
+<!-- Label styles -->
+<rel-textfield label="Floating label" label-style="floating"></rel-textfield>
+<rel-textfield label-style="none" placeholder="Search orders" field-aria-label="Search orders"></rel-textfield>
+
+<!-- Leading icon, helper text, required -->
+<rel-textfield label="Search" prefixicon="search" helpertext="Type at least 3 characters" required></rel-textfield>
+
+<!-- Prefix / suffix text (Figma .Preffix / .Suffix) -->
+<rel-textfield label="Website" prefix-text="https://" prefix-style="fill"></rel-textfield>
+<rel-textfield label="Weight" suffix-text="kg" suffix-divider></rel-textfield>
+
+<!-- Slotted prefix / suffix content -->
+<rel-textfield label="Amount">
+  <span slot="prefix">$</span>
+  <rel-button slot="suffix" variant="ghost" size="small">Max</rel-button>
+</rel-textfield>
 
-<!-- With icons and supporting text -->
+<!-- Clickable trailing icon (e.g. password toggle) -->
 <rel-textfield
+  id="pw"
   label="Password"
   type="password"
-  leftIcon="🔒"
-  supportingText="Must be at least 8 characters">
+  righticon="eye"
+  clickable-right-icon
+  right-icon-aria-label="Show password">
 </rel-textfield>
+<script>
+  const pw = document.getElementById("pw");
+  pw.addEventListener("rel-right-icon-click", () => {
+    pw.type = pw.type === "password" ? "text" : "password";
+  });
+  pw.addEventListener("rel-change", (e) => console.log("typed:", e.detail));
+</script>
 
-<!-- No label — an accessible name is required in its place -->
-<rel-textfield
-  label-style="none"
-  placeholder="Search orders"
-  field-aria-label="Search orders">
-</rel-textfield>
+<!-- Error state -->
+<rel-textfield label="Username" value="a" error errormessage="Must be at least 3 characters"></rel-textfield>
+
+<!-- Multiline (textarea) -->
+<rel-textfield label="Notes" multiline rows="5" maxlength="500"></rel-textfield>
 
-<!-- Setting value via JavaScript -->
-<rel-textfield id="myField" label="Username"></rel-textfield>
+<!-- Read-only, disabled, inline width -->
+<rel-textfield label="Order ID" value="SO-4821" readonly></rel-textfield>
+<rel-textfield label="Disabled" disabled></rel-textfield>
+<rel-textfield id="qty" label="Quantity" type="number"></rel-textfield>
 <script>
-  const field = document.getElementById('myField');
-  field.value = 'john.doe';
+  // fullWidth defaults to true; a boolean attribute cannot express false, so unset it via the property
+  document.getElementById("qty").fullWidth = false;
 </script>
 ```
 
+### Deprecated aliases
+
+```html
+<!-- floatingLabel → label-style="floating" (kept permanently as an alias; no console notice) -->
+<rel-textfield label="Old spelling" floatinglabel></rel-textfield>
+<rel-textfield label="Canonical" label-style="floating"></rel-textfield>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-textfield.ts — do not edit; run readme-generate.mjs -->
+
 ## API
 
-### Attributes/Properties
-
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | - | Label text displayed above the input |
-| `label-style` | `"default" \| "floating" \| "none"` | - | Label presentation. `"none"` renders no label at all. Unset, the deprecated `floatingLabel` boolean decides |
-| `floatingLabel` | `boolean` | `false` | **Deprecated** — use `label-style="floating"`. Kept permanently as an alias |
-| `field-aria-label` | `string` | - | Accessible name for the input. Required with `label-style="none"` |
-| `field-aria-labelledby` | `string` | - | IDREF list of external element(s) naming the input. Wins over `field-aria-label` |
-| `placeholder` | `string` | `""` | Placeholder text |
-| `type` | `string` | `"text"` | Input type (text, email, password, etc.) |
-| `value` | `string` | `""` | Current input value |
-| `leftIcon` | `string` | - | Icon content on the left side |
-| `rightIcon` | `string` | - | Icon content on the right side |
-| `supportingText` | `string` | - | Helper or error text below input |
-| `state` | `"default" \| "focused" \| "error" \| "disabled"` | `"default"` | Visual state |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Size variant |
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `undefined` | Visible label text. Rendered above the control (default), inside it as a floating label (`labelStyle="floating"`) or as the notch of the `legend` variant; omitted entirely under `labelStyle="none"`. |
+| `placeholder` | `placeholder` | `string` | `""` | Placeholder shown while the field is empty. Under the floating label style it stays hidden until the field is focused. |
+| `type` | `type` | `string` | `"text"` | Native input `type` (`text`, `email`, `password`, `number`, …). Ignored when `multiline` is set. |
+| `value` | `value` | `string` | `""` | Current text. Updated on every keystroke; set it to control the field programmatically. |
+| `leftIcon` | `lefticon` | `string` | `undefined` | Legacy name for the leading icon (a `rel-icon` name). `prefixIcon` wins when both are set. |
+| `rightIcon` | `righticon` | `string` | `undefined` | Trailing `rel-icon` name rendered in the suffix block. Decorative unless `clickableRightIcon` is set. |
+| `clickableRightIcon` | `clickable-right-icon` | `boolean` | `false` | Makes the trailing icon interactive (pointer + focusable) and emits `rel-right-icon-click` — e.g. a password show/hide toggle or clear button. |
+| `rightIconAriaLabel` | `right-icon-aria-label` | `string` | `undefined` | Accessible label for the trailing icon when it is clickable. |
+| `prefixText` | `prefix-text` | `string` | `undefined` | Short text rendered before the input, e.g. `"http://"` or `"$"`. Sits in the same prefix block as `prefixIcon` and is styled by `prefixStyle`. |
+| `prefixStyle` | `prefix-style` | `"clear" \| "divider" \| "fill"` | `"clear"` | Visual treatment of the prefix block — applies to the prefix icon, text and slotted `prefix` content alike. See `TextFieldPrefixStyle`. |
+| `suffixText` | `suffix-text` | `string` | `undefined` | Short text rendered after the input, e.g. `"kg"` or `".00"`. Shares the suffix block with `rightIcon` and slotted `suffix` content. |
+| `suffixDivider` | `suffix-divider` | `boolean` | `false` | Draws a hairline between the input and the suffix block. |
+| `supportingText` | `supportingtext` | `string` | `undefined` | Legacy name for the helper line below the control. `helperText` wins when both are set. |
+| `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Legacy visual state. `"error"` / `"disabled"` behave like the `error` / `disabled` booleans, which are preferred and take precedence. Typing into a `state="error"` field resets it to `"default"` until the value is emptied again. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Control height — `small` 32px, `medium` 40px, `large` 48px — which also scales the text and the affix icons. |
+| `labelStyle` | `label-style` | `"default" \| "floating" \| "none"` | `undefined` | Label presentation. Left `undefined` the deprecated `floatingLabel` boolean decides, so existing markup keeps working; set explicitly and it wins. Declares `attribute` because Lit would otherwise only listen for the all-lowercase `labelstyle`. Reflected. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the input. Required when `labelStyle="none"`, since no `<label>` renders and a placeholder is not a valid naming mechanism. |
+| `fieldAriaLabelledby` | `field-aria-labelledby` | `string` | `undefined` | IDREF list of external element(s) naming the input. Wins over `fieldAriaLabel`. |
+| `variant` | `variant` | `"default" \| "underline" \| "legend"` | `"default"` | Field chrome: `default` outlined box, `underline` bottom border only, `legend` notched outline with the label sitting in the top border (native fieldset/legend). Reflected. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the input (not focusable, not editable) and dims the control. |
+| `required` | `required` | `boolean` | `false` | Marks the input required: sets native `required` / `aria-required` and appends an asterisk to the label. |
+| `multiline` | `multiline` | `boolean` | `false` | Renders a textarea instead of a single-line input (see `rows`). Prefix/suffix blocks and `type` are ignored in this mode. Reflected. |
+| `rows` | `rows` | `number` | `3` | Visible text rows of the textarea when `multiline` is set. |
+| `prefixIcon` | `prefixicon` | `string` | `undefined` | Leading `rel-icon` name rendered in the prefix block (preferred over the legacy `leftIcon`). |
+| `prefixIconAriaLabel` | `prefixiconarialabel` | `string` | `undefined` | Accessible label for the leading icon. Without it the icon is `aria-hidden` (decorative). |
+| `error` | `error` | `boolean` | `false` | Puts the field in the error state: danger border, `aria-invalid`, and `errorMessage` replacing the helper text. |
+| `errorMessage` | `errormessage` | `string` | `undefined` | Text shown below the control instead of `helperText` while the field is in the error state. |
+| `helperText` | `helpertext` | `string` | `undefined` | Helper line below the control (preferred over the legacy `supportingText`); linked to the input via `aria-describedby`. |
+| `readonly` | `readonly` | `boolean` | `false` | Makes the input read-only: focusable and selectable but not editable. |
+| `maxLength` | `maxlength` | `number` | `undefined` | Maximum number of characters (native `maxlength`). |
+| `name` | `name` | `string` | `undefined` | Form field name forwarded to the native input, for form submission and autofill. |
+| `fullWidth` | `fullwidth` | `boolean` | `true` | Fills the parent width as a block element (default). Unset it to render inline at the content's natural width. Reflected. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `floatingLabel` | `floatinglabel` | `boolean` | Use `labelStyle="floating"`. Kept permanently as an alias. |
+
+### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `focus` | `focus(options?: FocusOptions)` | Focuses the inner input/textarea (the host itself is not focusable). |
 
 ## Events
 
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `input-change` | `string` (the current value) | Fires when the input value changes through user interaction |
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `value` | bubbles / composed | Fired on every keystroke. Detail: the current text (`value`). |
+| `rel-right-icon-click` | — | bubbles / composed | Fired when the trailing icon is clicked or activated with Enter / Space while `clickableRightIcon` is set. No detail. |
 
 ## Slots
 
-Default slot not used. All content controlled via properties.
+| Slot | Description |
+| --- | --- |
+| `prefix` | Custom content at the far left of the control (e.g. a unit dropdown); shares the prefix block with `prefixIcon` / `prefixText`. Hidden when `multiline` is set. |
+| `suffix` | Custom content at the far right of the control (e.g. an action button); shares the suffix block with `rightIcon` / `suffixText`. Hidden when `multiline` is set. |
 
 ## CSS Parts
 
-None exposed.
+| Part | Description |
+| --- | --- |
+| `label` | The visible label element (default and floating label styles) |
+| `input` | The native input / textarea |
+| `right-icon` | The trailing `rel-icon` |
+| `prefix` | The prefix block (leading icon, prefix text and the `prefix` slot) |
+| `suffix` | The suffix block (suffix text, trailing icon and the `suffix` slot) |
+| `helper` | The helper / error text line below the control |
+| `control` | The bordered control box (the fieldset in the legend variant) |
 
 ## Tokens / CSS Variables
 
-- `--rel-fonts-font-family`: Font family
-- `--rel-body-sm-regular-font-size`, `--rel-body-md-regular-font-size`: Font sizes
-- `--rel-fonts-weight-body-medium`: Font weight for label
-- `--rel-text-label`: Label color
-- `--rel-text-default`: Input text color
-- `--rel-text-placeholder`: Placeholder and icon color
-- `--rel-text-disabled`: Disabled text color
-- `--rel-border-default`: Default border color
-- `--rel-bg-info`: Focus border color
-- `--rel-border-danger`: Error state border color
-- `--rel-bg-surface`: Input background (light mode)
-- `--rel-bg-neutral-elevated-1`: Disabled background
-- `--rel-spacing-*`: Spacing tokens
-- `--rel-border-radius-sm`: Border radius
-- `--rel-field-label-reserve`: Height held for the absent label row under `label-style="none"`, so the input bottom-aligns with labelled siblings. Defaults to the label line-height plus the wrapper gap; set to `0` to collapse the row entirely in compact contexts (toolbars, table cells)
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-field-label-reserve` | `calc(var(--rel-body-sm-medium-line-height) + var(--rel-spacing-2xs))` | Height held for the absent label row under `labelStyle="none"` so the control bottom-aligns with labelled siblings; defaults to the label line-height plus the wrapper gap. Set to `0` to collapse the row entirely (toolbars, table cells). |
+
+<!-- readme-gen:end -->
 
 ## Accessibility
 
-- Associates `<label>` with input via `for`/`id`
-- With `label-style="none"` no `<label>` renders, so `field-aria-label` (or
-  `field-aria-labelledby`) must supply the accessible name — a placeholder is
-  not a valid naming mechanism. The component logs a console warning when both
-  are missing.
-- Supports native HTML5 input attributes (`required`, `disabled`, `readonly`, `maxlength`)
-- Focus ring visible on keyboard navigation (`:focus-visible`)
-- Error state communicated visually via border color
-- Supporting text can provide `aria-describedby` context
+- The visible `<label>` is linked to the native input via `for`/`id` (the host `id`, or a generated one). In the `legend` variant the input is instead named through `aria-labelledby` pointing at the `<legend>`.
+- With `label-style="none"` no label renders: `field-aria-labelledby` (wins) or `field-aria-label` must supply the accessible name. The component logs a console warning once when neither is set, because a placeholder is not a valid naming mechanism.
+- The input carries `aria-required`, `aria-invalid` (true in the error state) and `aria-describedby` pointing at the helper line. That line is always rendered with `aria-live="polite"`, so a change from helper text to `errorMessage` is announced.
+- The leading icon is `aria-hidden` unless `prefixIconAriaLabel` is set, in which case it becomes `role="img"` with that label. The trailing icon is `aria-hidden` unless `clickable-right-icon` is set, in which case it is `role="button"`, `tabindex="0"` and named by `right-icon-aria-label`.
+- No screen-reader announcements are made via `announce()`; the live helper region is the only announcement path.
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Focus the input; with `clickable-right-icon` the trailing icon is the next Tab stop |
+| `Enter` / `Space` (on the trailing icon) | Fires `rel-right-icon-click` (default prevented) |
+
+Focus behaviour: `focus()` on the host focuses the inner input / textarea (the host itself is not focusable). A mousedown anywhere on the control — border, legend notch, prefix / suffix padding — focuses the input like clicking a label would; presses on the input, a clickable icon or slotted content keep their native behaviour. The focused control shows a `--rel-border-strong` border plus a 1px ring; the `legend` variant recolours the border and legend only (a ring would strike through the notch).
 
 ## Notes / Edge Cases
 
-- The `state` prop overrides internal focus state if set explicitly
-- Icons are decorative (text content, not `<img>` elements)
-- Input type `password` does not auto-toggle visibility (use `rightIcon` for toggle button)
-- Error state must be set programmatically; no built-in validation
-- Disabled inputs cannot be focused or edited
+- Attribute spellings: props declared with an explicit `attribute` use kebab-case (`label-style`, `prefix-text`, `clickable-right-icon`, `field-aria-label`, …). The others have Lit's default all-lowercase attribute — `prefixicon`, `righticon`, `helpertext`, `errormessage`, `maxlength`, `fullwidth`, `supportingtext`, `floatinglabel` — see the Attribute column above. HTML attribute names are case-insensitive, so `helperText="…"` in markup also works.
+- Legacy names still work but the canonical ones win when both are set: `leftIcon` → `prefixIcon`, `supportingText` → `helperText`, `state="error"` → `error`, `state="disabled"` → `disabled`. `lefticon` / `righticon` attributes are also read once at connect time.
+- `errorMessage` replaces the helper line only while the field is in the error state **and** the message is set; otherwise the helper text stays visible. There is no built-in validation — set `error` from your form layer.
+- `state="error"` (legacy) auto-clears to `"default"` as soon as the user types a non-empty value and comes back once the value is emptied again; the `error` boolean never auto-clears.
+- `multiline` renders a `<textarea>` (`rows`, vertical resize, 80px minimum height). `type`, the prefix / suffix blocks and their slots are ignored in this mode (the slots stay mounted but hidden).
+- `fullWidth` defaults to `true` and reflects as `fullwidth`; without it the host becomes `inline-block` at its content width. To turn it off from HTML you must bind the property (`.fullWidth=${false}`), since a boolean attribute cannot express `false`.
+- `label-style="floating"`: the placeholder is hidden until the field is focused; the label floats onto the border when focused or filled. Internally the deprecated `floatingLabel` boolean is kept in sync with `labelStyle` and its reflected `floatinglabel` attribute is the styling hook, so both spellings render identically. With a `prefix-style="clear"` prefix the floated label slides back over the control's left edge (Figma "Floating Label"); `divider` / `fill` prefixes keep it after the block.
+- `variant="legend"` + `label-style="none"` drops the `<legend>` entirely so the top border runs continuous; a `fill` prefix is squared off in this variant because it cannot reach the notched top border.
+- `--rel-field-label-reserve` (see Component hooks) keeps a `label-style="none"` field bottom-aligned with labelled siblings; set it to `0` in toolbars or table cells.
+- Inside the prefix block the order is slotted content → icon → text (nearest the input); in the suffix block it is text → icon → slotted content. Clicking a non-interactive part of either block focuses the input.
+- The control height (32 / 40 / 48px) is explicit so the field lines up with `rel-select` and the date / time / range picker triggers; the textarea keeps the padding model and grows with `rows`.
+- In Figma, the `error` state's border has no focus ring; that matches the code (`box-shadow: none` in error).

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.