@adia-ai/web-components 0.6.32 → 0.6.34

package/components/time-picker/time-picker.test.js

@@ -0,0 +1,287 @@
+/**
+ * time-picker-ui — SPEC-043
+ *
+ * Coverage:
+ *   - Stamp shape (precision × hour-cycle)
+ *   - Segment text sync from value
+ *   - Arrow Up / Down increments
+ *   - Page Up / Down + Home / End
+ *   - Tab equivalents (ArrowLeft / ArrowRight)
+ *   - Digit typing + auto-advance
+ *   - Form participation (name + ISO value)
+ *   - min / max → invalid event
+ *   - disabled / readonly behavior
+ *   - precision toggle re-stamps without losing hh/mm
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './time-picker.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+function segText(el, key) {
+  return el.querySelector(`[data-segment="${key}"]`)?.textContent || '';
+}
+
+function fireKey(el, key) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
+}
+
+describe('time-picker-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('renders with empty segments when no value is set', async () => {
+    const el = mount('<time-picker-ui></time-picker-ui>');
+    await tick();
+    expect(el.querySelector('[data-segment="hour"]')).not.toBeNull();
+    expect(el.querySelector('[data-segment="minute"]')).not.toBeNull();
+    expect(segText(el, 'hour')).toBe('');
+    expect(segText(el, 'minute')).toBe('');
+  });
+
+  it('populates hour/minute segments from value="09:30"', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    expect(segText(el, 'hour')).toBe('09');
+    expect(segText(el, 'minute')).toBe('30');
+  });
+
+  it('precision="second" stamps a seconds segment + separator', async () => {
+    const el = mount('<time-picker-ui precision="second" value="14:30:45"></time-picker-ui>');
+    await tick();
+    expect(el.querySelector('[data-segment="second"]')).not.toBeNull();
+    expect(segText(el, 'second')).toBe('45');
+  });
+
+  it('hour-cycle="h12" stamps a meridiem segment + 12h display', async () => {
+    const el = mount('<time-picker-ui hour-cycle="h12" value="14:30"></time-picker-ui>');
+    await tick();
+    const meridiem = el.querySelector('[data-segment="meridiem"]');
+    expect(meridiem).not.toBeNull();
+    expect(segText(el, 'hour')).toBe('02');
+    expect(segText(el, 'meridiem')).toBe('PM');
+  });
+
+  it('hour-cycle="h12" displays midnight as 12 AM', async () => {
+    const el = mount('<time-picker-ui hour-cycle="h12" value="00:15"></time-picker-ui>');
+    await tick();
+    expect(segText(el, 'hour')).toBe('12');
+    expect(segText(el, 'meridiem')).toBe('AM');
+  });
+
+  it('Arrow Up on hour segment increments by 1', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    const hour = el.querySelector('[data-segment="hour"]');
+    hour.focus();
+    fireKey(hour, 'ArrowUp');
+    await tick();
+    expect(el.value).toBe('10:30');
+  });
+
+  it('Arrow Down on minute segment decrements by step/60 minutes', async () => {
+    const el = mount('<time-picker-ui value="09:30" step="60"></time-picker-ui>');
+    await tick();
+    const min = el.querySelector('[data-segment="minute"]');
+    min.focus();
+    fireKey(min, 'ArrowDown');
+    await tick();
+    expect(el.value).toBe('09:29');
+  });
+
+  it('step="900" increments minute by 15 on Arrow Up', async () => {
+    const el = mount('<time-picker-ui value="09:30" step="900"></time-picker-ui>');
+    await tick();
+    const min = el.querySelector('[data-segment="minute"]');
+    min.focus();
+    fireKey(min, 'ArrowUp');
+    await tick();
+    expect(el.value).toBe('09:45');
+  });
+
+  it('Page Up increments by 10× the small step', async () => {
+    const el = mount('<time-picker-ui value="09:00"></time-picker-ui>');
+    await tick();
+    const min = el.querySelector('[data-segment="minute"]');
+    min.focus();
+    fireKey(min, 'PageUp');
+    await tick();
+    expect(el.value).toBe('09:10');
+  });
+
+  it('Home jumps to segment min; End jumps to segment max', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    const hour = el.querySelector('[data-segment="hour"]');
+    hour.focus();
+    fireKey(hour, 'Home');
+    await tick();
+    expect(el.value).toBe('00:30');
+    fireKey(hour, 'End');
+    await tick();
+    expect(el.value).toBe('23:30');
+  });
+
+  it('ArrowRight moves focus to next segment; ArrowLeft to previous', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    const hour = el.querySelector('[data-segment="hour"]');
+    const minute = el.querySelector('[data-segment="minute"]');
+    hour.focus();
+    fireKey(hour, 'ArrowRight');
+    await tick();
+    expect(document.activeElement).toBe(minute);
+    fireKey(minute, 'ArrowLeft');
+    await tick();
+    expect(document.activeElement).toBe(hour);
+  });
+
+  it('disabled prop blocks Arrow-key step', async () => {
+    const el = mount('<time-picker-ui value="09:30" disabled></time-picker-ui>');
+    await tick();
+    const hour = el.querySelector('[data-segment="hour"]');
+    fireKey(hour, 'ArrowUp');
+    await tick();
+    expect(el.value).toBe('09:30');
+  });
+
+  it('readonly prop blocks edits but keeps segments focusable', async () => {
+    const el = mount('<time-picker-ui value="09:30" readonly></time-picker-ui>');
+    await tick();
+    const hour = el.querySelector('[data-segment="hour"]');
+    expect(hour.getAttribute('tabindex')).toBe('0');
+    expect(hour.contentEditable).toBe('false');
+    hour.focus();
+    fireKey(hour, 'ArrowUp');
+    await tick();
+    expect(el.value).toBe('09:30');
+  });
+
+  it('min violation fires invalid + does not mutate value', async () => {
+    const el = mount('<time-picker-ui value="08:00" min="08:00" max="18:00"></time-picker-ui>');
+    await tick();
+    let captured = null;
+    el.addEventListener('invalid', (e) => { captured = e; });
+    const hour = el.querySelector('[data-segment="hour"]');
+    hour.focus();
+    fireKey(hour, 'ArrowDown');
+    await tick();
+    expect(captured).not.toBeNull();
+    expect(captured.detail.reason).toBe('min');
+    expect(el.value).toBe('08:00');
+  });
+
+  it('max violation fires invalid', async () => {
+    const el = mount('<time-picker-ui value="18:00" min="08:00" max="18:00"></time-picker-ui>');
+    await tick();
+    let captured = null;
+    el.addEventListener('invalid', (e) => { captured = e; });
+    const hour = el.querySelector('[data-segment="hour"]');
+    hour.focus();
+    fireKey(hour, 'ArrowUp');
+    await tick();
+    expect(captured).not.toBeNull();
+    expect(captured.detail.reason).toBe('max');
+    expect(el.value).toBe('18:00');
+  });
+
+  it('emits change with detail.segment on Arrow step', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    let captured = null;
+    el.addEventListener('change', (e) => { captured = e; });
+    const hour = el.querySelector('[data-segment="hour"]');
+    hour.focus();
+    fireKey(hour, 'ArrowUp');
+    await tick();
+    expect(captured).not.toBeNull();
+    expect(captured.detail).toEqual({ value: '10:30', segment: 'hour' });
+  });
+
+  it('precision="minute" → "second" re-stamps without losing hh/mm', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    expect(el.querySelector('[data-segment="second"]')).toBeNull();
+    el.precision = 'second';
+    await tick();
+    expect(el.querySelector('[data-segment="second"]')).not.toBeNull();
+    expect(segText(el, 'hour')).toBe('09');
+    expect(segText(el, 'minute')).toBe('30');
+  });
+
+  it('aria-valuemax matches segment max (h23 → 23 for hour)', async () => {
+    const el = mount('<time-picker-ui hour-cycle="h23"></time-picker-ui>');
+    await tick();
+    const hour = el.querySelector('[data-segment="hour"]');
+    expect(hour.getAttribute('aria-valuemax')).toBe('23');
+  });
+
+  it('aria-valuemax for hour is 12 in h12 cycle', async () => {
+    const el = mount('<time-picker-ui hour-cycle="h12"></time-picker-ui>');
+    await tick();
+    const hour = el.querySelector('[data-segment="hour"]');
+    expect(hour.getAttribute('aria-valuemax')).toBe('12');
+  });
+
+  it('aria-valuenow + aria-valuetext are populated from value', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    const hour = el.querySelector('[data-segment="hour"]');
+    const minute = el.querySelector('[data-segment="minute"]');
+    expect(hour.getAttribute('aria-valuenow')).toBe('9');
+    expect(minute.getAttribute('aria-valuenow')).toBe('30');
+    expect(hour.getAttribute('aria-valuetext')).toContain('hour');
+    expect(minute.getAttribute('aria-valuetext')).toContain('minute');
+  });
+
+  it('host role="group" + aria-label default', async () => {
+    const el = mount('<time-picker-ui></time-picker-ui>');
+    await tick();
+    expect(el.getAttribute('role')).toBe('group');
+    expect(el.hasAttribute('aria-label')).toBe(true);
+  });
+
+  it('clear() resets value to empty', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    el.clear();
+    await tick();
+    expect(el.value).toBe('');
+    expect(segText(el, 'hour')).toBe('');
+  });
+
+  it('stepUp() increments programmatically', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    el.stepUp('hour');
+    await tick();
+    expect(el.value).toBe('10:30');
+  });
+
+  it('value setter syncs segments', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    el.value = '11:45';
+    await tick();
+    expect(segText(el, 'hour')).toBe('11');
+    expect(segText(el, 'minute')).toBe('45');
+  });
+
+  it('focusing a segment sets [editing] + [segment="…"] on host', async () => {
+    const el = mount('<time-picker-ui value="09:30"></time-picker-ui>');
+    await tick();
+    const minute = el.querySelector('[data-segment="minute"]');
+    minute.focus();
+    await tick();
+    expect(el.hasAttribute('editing')).toBe(true);
+    expect(el.getAttribute('segment')).toBe('minute');
+  });
+});

package/components/time-picker/time-picker.yaml

@@ -0,0 +1,256 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UITimePicker
+tag: time-picker-ui
+status: stable
+component: TimePicker
+category: input
+version: 1
+description: >-
+  Time-of-day picker with discrete segments (hour, minute, optional second,
+  optional AM/PM). Each segment follows the WAI-ARIA Spinbutton pattern with
+  Arrow-key increment/decrement, Page Up/Down for larger jumps, Home/End for
+  segment min/max, and Tab to move between segments. Form-associated input
+  emitting ISO 8601 time string ("HH:mm" or "HH:mm:ss") via change events.
+  Per ADR-0025 no native form controls — segments are contenteditable spans
+  inside a custom host. SPEC-043.
+props:
+  name:
+    description: Form field name for FormData submission
+    type: string
+    default: ''
+  value:
+    description: Current time value as ISO 8601 ("HH:mm" or "HH:mm:ss"). Empty when no value selected.
+    type: string
+    default: ''
+  min:
+    description: Earliest selectable time as ISO 8601. Empty disables the constraint.
+    type: string
+    default: ''
+    reflect: true
+  max:
+    description: Latest selectable time as ISO 8601. Empty disables the constraint.
+    type: string
+    default: ''
+    reflect: true
+  step:
+    description: Per-Arrow-keypress increment in seconds. 60 = minute precision (default), 900 = 15-minute, 1 = second precision.
+    type: number
+    default: 60
+    reflect: true
+  precision:
+    description: Whether the seconds segment is exposed. `minute` (default) hides seconds; `second` adds the seconds segment + separator.
+    type: string
+    default: minute
+    enum:
+    - minute
+    - second
+    reflect: true
+  hourcycle:
+    description: |
+      Hour cycle. Empty (default) derives from the document locale — most
+      en-* locales resolve to `h23`. `h12` forces a 12-hour cycle with an
+      AM/PM (meridiem) segment; `h23` forces 24-hour cycle.
+    type: string
+    default: ''
+    enum:
+    - ''
+    - h12
+    - h23
+    reflect: true
+    attribute: hour-cycle
+  placeholder:
+    description: Per-segment placeholder text shown when a segment is empty. Defaults to "--".
+    type: string
+    default: '--'
+  disabled:
+    description: Disables interaction; dims the control
+    type: boolean
+    default: false
+    reflect: true
+  readonly:
+    description: Prevents editing while keeping the field focusable. Segments stay focusable for inspection.
+    type: boolean
+    default: false
+    reflect: true
+  required:
+    description: Marks the field as required for form validation. Sets aria-required.
+    type: boolean
+    default: false
+    reflect: true
+  locale:
+    description: BCP-47 locale tag used to derive hour-cycle when `hour-cycle` is empty. Falls back to `<html lang>` then to browser default.
+    type: string
+    default: ''
+events:
+  change:
+    description: Fired when the value commits (segment edit completes via Arrow / Tab / blur).
+    detail:
+      value:
+        type: string
+        description: Current value as ISO 8601 ("HH:mm" or "HH:mm:ss").
+      segment:
+        type: string
+        description: Which segment commit fired the event (`hour` | `minute` | `second` | `meridiem`).
+  input:
+    description: Fired on intermediate segment edits before commit.
+    detail:
+      value:
+        type: string
+        description: In-flight value as ISO 8601.
+  invalid:
+    description: Fired when a constraint is violated (min/max range, parse error).
+    detail:
+      value:
+        type: string
+        description: Value that failed validation.
+      reason:
+        type: string
+        description: Why it failed (`min` | `max` | `parse`).
+        enum:
+        - min
+        - max
+        - parse
+slots:
+  prefix:
+    description: Leading content (e.g. an `<icon-ui name="clock">`); sits before the hour segment.
+  suffix:
+    description: Trailing content (e.g. a timezone label); sits after the last segment.
+states:
+- name: idle
+  description: Default, ready for interaction.
+- name: editing
+  description: One segment is the focus target.
+  attribute: editing
+- name: disabled
+  description: Non-interactive; dimmed.
+  attribute: disabled
+- name: focused
+  description: Keyboard focus ring on the host.
+  selector: :focus-within
+traits:
+- focusable
+tokens:
+  --time-picker-bg:
+    description: Host background color.
+  --time-picker-fg:
+    description: Host text color.
+  --time-picker-fg-muted:
+    description: Muted text color (empty placeholder + separator).
+  --time-picker-border:
+    description: Host border color.
+  --time-picker-radius:
+    description: Host border radius.
+  --time-picker-px:
+    description: Host inline padding.
+  --time-picker-py:
+    description: Host block padding.
+  --time-picker-segment-bg-focus:
+    description: Focused segment background.
+  --time-picker-segment-fg-focus:
+    description: Focused segment text color.
+  --time-picker-separator-fg:
+    description: Separator (`:`) text color.
+requiredIcons: []
+a2ui:
+  rules:
+    - >-
+      `<time-picker-ui>` is the canonical standalone time-of-day picker.
+      Per ADR-0025 NEVER wrap a native `<input type="time">` — segments
+      are contenteditable spans + ElementInternals provides form
+      participation.
+    - >-
+      `value` MUST be ISO 8601 time `HH:mm` or `HH:mm:ss` (24-hour),
+      or empty string. Localized formats (e.g. "9:30 AM") are not
+      accepted; display formatting is derived from `hour-cycle`
+      regardless of how the value is stored.
+    - >-
+      `step` is in seconds. 60 = minute precision (default); 900 =
+      15-minute precision (meeting-time common); 1 = second precision
+      (requires `precision="second"`).
+    - >-
+      `precision="second"` exposes the seconds segment AND emits
+      `HH:mm:ss`. Default `precision="minute"` emits `HH:mm`.
+    - >-
+      `hour-cycle` overrides locale-derived behavior. Set explicitly
+      (`h12` / `h23`) when the surface needs a specific cycle (cron
+      editors, log queries, system surfaces).
+    - >-
+      For datetime selection use `<datetime-picker-ui>` (SPEC-038) —
+      it composes this primitive as its time pane.
+anti_patterns:
+  - wrong: |
+      {"component": "TimePicker", "value": "9:30 AM"}
+    why: |
+      Localized format is not a valid `value`. The contract requires ISO
+      8601 time (`HH:mm` or `HH:mm:ss`, 24-hour). The display format is
+      derived from `hourCycle` regardless of how the value is stored.
+    fix: |
+      {"component": "TimePicker", "value": "09:30"}
+  - wrong: |
+      {"component": "TimePicker", "value": "2026-05-24T09:30"}
+    why: |
+      Datetime string is invalid for TimePicker — the date portion is
+      not accepted. For datetime selection use the DatetimePicker
+      component.
+    fix: |
+      {"component": "DatetimePicker", "value": "2026-05-24T09:30"}
+  - wrong: |
+      {"component": "TimePicker", "children": [
+        {"component": "Input", "type": "time"}
+      ]}
+    why: |
+      Nesting a native time input violates ADR-0025 and bypasses
+      ElementInternals form participation.
+    fix: |
+      {"component": "TimePicker", "name": "field-name"}
+examples:
+- name: meeting-time-15min-step
+  description: Time-of-day picker with 15-minute step and business-hours bounds.
+  a2ui: |
+    [
+      {"id": "root", "component": "Field", "label": "Start time",
+       "children": ["t"]},
+      {"id": "t", "component": "TimePicker",
+       "name": "start-time", "value": "09:30",
+       "min": "08:00", "max": "18:00", "step": 900}
+    ]
+- name: log-cursor-second-precision
+  description: Time picker with second precision for a log-cursor query.
+  a2ui: |
+    [
+      {"id": "root", "component": "Field", "label": "Cursor",
+       "children": ["t"]},
+      {"id": "t", "component": "TimePicker",
+       "name": "cursor", "precision": "second", "step": 1,
+       "value": "14:30:45"}
+    ]
+- name: alarm-12h-cycle
+  description: Forced 12-hour cycle with AM/PM segment for an alarm picker.
+  a2ui: |
+    [
+      {"id": "root", "component": "Field", "label": "Alarm",
+       "children": ["t"]},
+      {"id": "t", "component": "TimePicker",
+       "name": "alarm", "hourCycle": "h12", "value": "07:00"}
+    ]
+keywords:
+- time
+- timepicker
+- time-picker
+- clock
+- hour
+- minute
+- spinbutton
+synonyms:
+  tags:
+  - TimeInput
+  - TimePicker
+  time:
+  - clock
+  - hour
+  - minute
+  - alarm
+related:
+- CalendarPicker
+- Field
+- Input