@reliability-design/web 1.4.2 → 1.4.3

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

@@ -0,0 +1,199 @@
+# 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.
+
+## Usage
+
+### Basic
+
+```html
+<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>
+```
+
+### 24-hour format
+
+```html
+<rel-time-picker format="24h" value="17:05"></rel-time-picker>
+```
+
+### Minute intervals
+
+```html
+<rel-time-picker minute-step="15"></rel-time-picker>
+<rel-time-picker minute-step="30"></rel-time-picker>
+```
+
+### With Min/Max
+
+```html
+<rel-time-picker
+  min-time="09:00"
+  max-time="17:30"
+  placeholder="Business hours only"
+></rel-time-picker>
+```
+
+### Clearable
+
+```html
+<rel-time-picker value="09:30" clearable></rel-time-picker>
+```
+
+### States
+
+```html
+<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
+<rel-time-picker size="small"></rel-time-picker>
+<rel-time-picker size="large"></rel-time-picker>
+<rel-time-picker fullWidth></rel-time-picker>
+```
+
+### Form usage
+
+```html
+<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);
+});
+```
+
+## Interaction model
+
+- 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`.
+
+## Keyboard
+
+| 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 |
+
+## 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 |
+
+## 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 |
+
+## CSS Parts
+
+| Part | Element |
+| --- | --- |
+| `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);
+}
+```
+
+## Design tokens
+
+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.