@adia-ai/web-components 0.6.33 → 0.6.35

package/components/time-picker/time-picker.css

@@ -0,0 +1,122 @@
+@scope (time-picker-ui) {
+  :where(:scope) {
+    /* ── Tokens ── */
+    --time-picker-bg-default:                  var(--a-ui-bg);
+    --time-picker-fg-default:                  var(--a-ui-text);
+    --time-picker-fg-muted-default:            var(--a-ui-text-placeholder);
+    --time-picker-border-default:              var(--a-ui-border);
+    --time-picker-border-hover-default:        var(--a-ui-border-hover);
+    --time-picker-radius-default:              var(--a-radius);
+    --time-picker-height-default:              var(--a-size);
+    --time-picker-px-default:                  var(--a-ui-px);
+    --time-picker-py-default:                  0;
+    --time-picker-gap-default:                 var(--a-space-1);
+    --time-picker-font-size-default:           var(--a-ui-size);
+
+    --time-picker-segment-radius-default:      var(--a-radius-sm);
+    --time-picker-segment-px-default:          var(--a-space-1);
+    --time-picker-segment-bg-focus-default:    var(--a-accent);
+    --time-picker-segment-fg-focus-default:    var(--a-accent-fg);
+
+    --time-picker-separator-fg-default:        var(--a-fg-muted);
+
+    --time-picker-focus-ring-default:          var(--a-focus-ring);
+    --time-picker-focus-ring-invalid-default:  var(--a-focus-ring-invalid);
+
+    --time-picker-duration-default:            var(--a-duration-fast);
+    --time-picker-easing-default:              var(--a-easing);
+  }
+
+  :scope {
+    /* ── Base ── */
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--time-picker-gap, var(--time-picker-gap-default));
+    min-height: var(--time-picker-height, var(--time-picker-height-default));
+    padding: var(--time-picker-py, var(--time-picker-py-default)) var(--time-picker-px, var(--time-picker-px-default));
+    background: var(--time-picker-bg, var(--time-picker-bg-default));
+    color: var(--time-picker-fg, var(--time-picker-fg-default));
+    border: 1px solid var(--time-picker-border, var(--time-picker-border-default));
+    border-radius: var(--time-picker-radius, var(--time-picker-radius-default));
+    font-family: inherit;
+    font-size: var(--time-picker-font-size, var(--time-picker-font-size-default));
+    font-variant-numeric: tabular-nums;
+    line-height: 1.4;
+    cursor: text;
+    transition:
+      border-color var(--time-picker-duration, var(--time-picker-duration-default)) var(--time-picker-easing, var(--time-picker-easing-default)),
+      background   var(--time-picker-duration, var(--time-picker-duration-default)) var(--time-picker-easing, var(--time-picker-easing-default)),
+      box-shadow   var(--time-picker-duration, var(--time-picker-duration-default)) var(--time-picker-easing, var(--time-picker-easing-default));
+  }
+
+  /* ── Segments ── */
+  :scope [data-segment] {
+    display: inline-block;
+    min-width: 2ch;
+    padding: 0 var(--time-picker-segment-px, var(--time-picker-segment-px-default));
+    text-align: center;
+    border-radius: var(--time-picker-segment-radius, var(--time-picker-segment-radius-default));
+    color: inherit;
+    background: transparent;
+    outline: none;
+    caret-color: transparent;
+    cursor: text;
+    transition:
+      background var(--time-picker-duration, var(--time-picker-duration-default)) var(--time-picker-easing, var(--time-picker-easing-default)),
+      color      var(--time-picker-duration, var(--time-picker-duration-default)) var(--time-picker-easing, var(--time-picker-easing-default));
+  }
+
+  /* Meridiem is a touch wider since it carries two letters (AM/PM). */
+  :scope [data-segment="meridiem"] {
+    min-width: 2.5ch;
+    text-transform: uppercase;
+  }
+
+  /* ── State: empty (placeholder via :empty) ── */
+  :scope [data-segment]:empty::before {
+    content: '--';
+    color: var(--time-picker-fg-muted, var(--time-picker-fg-muted-default));
+  }
+
+  /* ── State: focused segment ── */
+  :scope [data-segment]:focus,
+  :scope [data-segment]:focus-visible {
+    background: var(--time-picker-segment-bg-focus, var(--time-picker-segment-bg-focus-default));
+    color: var(--time-picker-segment-fg-focus, var(--time-picker-segment-fg-focus-default));
+    outline: none;
+  }
+
+  /* ── Separator ── */
+  :scope [data-separator] {
+    color: var(--time-picker-separator-fg, var(--time-picker-separator-fg-default));
+    pointer-events: none;
+    user-select: none;
+  }
+}
+
+/* hover rules — outside @scope (matches input-ui's Safari 17.x workaround). */
+time-picker-ui:not([disabled]):hover {
+  border-color: var(--time-picker-border-hover, var(--time-picker-border-hover-default));
+}
+
+/* Focus ring on the host when any segment is focused.
+   Canonical L3 ring; consumed via --time-picker-focus-ring (aliases --a-focus-ring). */
+time-picker-ui:not([disabled]):focus-within {
+  box-shadow: var(--time-picker-focus-ring, var(--time-picker-focus-ring-default));
+}
+
+time-picker-ui[aria-invalid="true"]:not([disabled]):focus-within,
+time-picker-ui[error]:not([disabled]):focus-within {
+  box-shadow: var(--time-picker-focus-ring-invalid, var(--time-picker-focus-ring-invalid-default));
+}
+
+/* Disabled / readonly affordance */
+time-picker-ui[disabled] {
+  opacity: var(--a-opacity-disabled, 0.5);
+  pointer-events: none;
+}
+
+time-picker-ui[readonly] [data-segment] {
+  cursor: default;
+}

package/components/time-picker/time-picker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `<time-picker-ui>` — 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.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/time-picker
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export interface TimePickerChangeEventDetail {
+  /** Which segment commit fired the event (`hour` | `minute` | `second` | `meridiem`). */
+  segment: string;
+  /** Current value as ISO 8601 ("HH:mm" or "HH:mm:ss"). */
+  value: string;
+}
+
+export type TimePickerChangeEvent = CustomEvent<TimePickerChangeEventDetail>;
+export interface TimePickerInputEventDetail {
+  /** In-flight value as ISO 8601. */
+  value: string;
+}
+
+export type TimePickerInputEvent = CustomEvent<TimePickerInputEventDetail>;
+export interface TimePickerInvalidEventDetail {
+  /** Why it failed (`min` | `max` | `parse`). */
+  reason: 'min' | 'max' | 'parse';
+  /** Value that failed validation. */
+  value: string;
+}
+
+export type TimePickerInvalidEvent = CustomEvent<TimePickerInvalidEventDetail>;
+
+export class UITimePicker extends UIElement {
+  /** Marks the field as required for form validation. Sets aria-required. */
+  required: boolean;
+  /** Disables interaction; dims the control */
+  disabled: boolean;
+  /** 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.
+ */
+  hourcycle: '' | 'h12' | 'h23';
+  /** BCP-47 locale tag used to derive hour-cycle when `hour-cycle` is empty. Falls back to `<html lang>` then to browser default. */
+  locale: string;
+  /** Latest selectable time as ISO 8601. Empty disables the constraint. */
+  max: string;
+  /** Earliest selectable time as ISO 8601. Empty disables the constraint. */
+  min: string;
+  /** Form field name for FormData submission */
+  name: string;
+  /** Per-segment placeholder text shown when a segment is empty. Defaults to "--". */
+  placeholder: string;
+  /** Whether the seconds segment is exposed. `minute` (default) hides seconds; `second` adds the seconds segment + separator. */
+  precision: 'minute' | 'second';
+  /** Prevents editing while keeping the field focusable. Segments stay focusable for inspection. */
+  readonly: boolean;
+  /** Per-Arrow-keypress increment in seconds. 60 = minute precision (default), 900 = 15-minute, 1 = second precision. */
+  step: number;
+  /** Current time value as ISO 8601 ("HH:mm" or "HH:mm:ss"). Empty when no value selected. */
+  value: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITimePicker, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: TimePickerChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: TimePickerInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'invalid', listener: (ev: TimePickerInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/time-picker/time-picker.examples.md

@@ -0,0 +1,35 @@
+# time-picker — Examples
+
+## Default
+
+```html
+<time-picker-ui></time-picker-ui>
+```
+
+## value
+
+```html
+<field-ui label="Start time">
+  <time-picker-ui value="09:30"></time-picker-ui>
+</field-ui>
+```
+
+## 15-minute step
+
+```html
+<field-ui label="Meeting">
+  <time-picker-ui value="09:30" step="900"></time-picker-ui>
+</field-ui>
+```
+
+## Second precision
+
+```html
+<time-picker-ui precision="second" step="1" value="14:30:45"></time-picker-ui>
+```
+
+## 12-hour cycle
+
+```html
+<time-picker-ui hour-cycle="h12" value="07:00"></time-picker-ui>
+```

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

@@ -0,0 +1,17 @@
+/**
+ * `<time-picker-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UITimePicker } from '@adia-ai/web-components/components/time-picker/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UITimePicker } from './time-picker.class.js';
+
+defineIfFree('time-picker-ui', UITimePicker);
+
+export { UITimePicker };

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');
+  });
+});