@kouji-ui/components 0.1.1

package/src/time-picker/_examples/index.ts

@@ -0,0 +1,8 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjTimePicker12HourExample } from './time-picker.12-hour.example';
+export { KjTimePickerExample } from './time-picker.example';
+export { KjTimePickerFormattedExample } from './time-picker.formatted.example';
+export { KjTimePickerRangeExample } from './time-picker.range.example';
+export { KjTimePickerUsageExample } from './time-picker.usage.example';
+export { KjTimePickerWithSecondsExample } from './time-picker.with-seconds.example';

package/src/time-picker/_examples/time-picker.12-hour.example.ts

@@ -0,0 +1,24 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTimePickerComponent } from '../time-picker';
+
+/**
+ * 12-hour time picker. The meridiem toggle (AM / PM) renders alongside the
+ * hour and minute segments; click or press Enter / Space to flip it.
+ */
+@Component({
+  selector: 'kj-time-picker-12-hour-example',
+  standalone: true,
+  imports: [KjTimePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: ` <kj-time-picker [(kjValue)]="time" kj12Hour kjAriaLabel="Meeting time" /> `,
+})
+export class KjTimePicker12HourExample {
+  readonly time = signal<Date | string>(new Date(2024, 0, 1, 14, 15, 0));
+}

package/src/time-picker/_examples/time-picker.example.ts

@@ -0,0 +1,24 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTimePickerComponent } from '../time-picker';
+
+/**
+ * Default 24-hour time picker. The wrapper renders zero-padded HH and MM
+ * spinbuttons; ArrowUp / ArrowDown step the focused segment.
+ */
+@Component({
+  selector: 'kj-time-picker-example',
+  standalone: true,
+  imports: [KjTimePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: ` <kj-time-picker [(kjValue)]="time" kjAriaLabel="Departure time" /> `,
+})
+export class KjTimePickerExample {
+  readonly time = signal<Date | string>(new Date(2024, 0, 1, 9, 30, 0));
+}

package/src/time-picker/_examples/time-picker.formatted.example.ts

@@ -0,0 +1,32 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTimePickerComponent } from '../time-picker';
+
+/**
+ * Emits ISO-8601 `'HH:mm'` strings instead of `Date` objects. Convenient when
+ * the back-end stores time-of-day directly and a `Date` round-trip would
+ * introduce a timezone hazard.
+ */
+@Component({
+  selector: 'kj-time-picker-formatted-example',
+  standalone: true,
+  imports: [KjTimePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      pre {
+        margin-top: var(--kj-space-md);
+        font: 0.875rem var(--kj-font-mono, ui-monospace);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-time-picker [(kjValue)]="time" kjValueShape="string" kjAriaLabel="Reminder time" />
+    <pre>Stored: {{ time() }}</pre>
+  `,
+})
+export class KjTimePickerFormattedExample {
+  readonly time = signal<Date | string>('08:30');
+}

package/src/time-picker/_examples/time-picker.range.example.ts

@@ -0,0 +1,54 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTimePickerComponent } from '../time-picker';
+
+/**
+ * Two pickers wired as a start / end range with a 15-minute step. The end
+ * picker's `kjMin` follows the current start value, so dragging the start
+ * past the end snaps the second segment forward.
+ */
+@Component({
+  selector: 'kj-time-picker-range-example',
+  standalone: true,
+  imports: [KjTimePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .row {
+        display: flex;
+        gap: var(--kj-space-md);
+        align-items: center;
+        flex-wrap: wrap;
+      }
+      label {
+        font: 0.875rem var(--kj-font-sans);
+        color: var(--kj-fg-default);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <label for="time-picker-range-start">Start</label>
+      <kj-time-picker
+        id="time-picker-range-start"
+        [(kjValue)]="start"
+        [kjStep]="15"
+        kjAriaLabel="Start time"
+      />
+      <label for="time-picker-range-end">End</label>
+      <kj-time-picker
+        id="time-picker-range-end"
+        [(kjValue)]="end"
+        [kjStep]="15"
+        [kjMin]="start()"
+        kjAriaLabel="End time"
+      />
+    </div>
+  `,
+})
+export class KjTimePickerRangeExample {
+  readonly start = signal<Date | string>(new Date(2024, 0, 1, 9, 0, 0));
+  readonly end = signal<Date | string>(new Date(2024, 0, 1, 17, 0, 0));
+}

package/src/time-picker/_examples/time-picker.usage.example.ts

@@ -0,0 +1,53 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTimePickerComponent } from '../time-picker';
+
+/**
+ * A walkthrough of the most common time-picker usages — 24-hour HH:MM, a
+ * 12-hour picker with AM/PM, and a formatted string output. Use this as the
+ * copy-paste starting point for new screens.
+ */
+@Component({
+  selector: 'kj-time-picker-usage-example',
+  standalone: true,
+  imports: [KjTimePickerComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+      .row {
+        display: flex;
+        gap: var(--kj-space-md);
+        align-items: center;
+      }
+      .readout {
+        font: 0.875rem var(--kj-font-sans);
+        color: var(--kj-fg-muted);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <kj-time-picker [(kjValue)]="meeting" kjAriaLabel="Meeting time" />
+      <span class="readout">{{ meeting() }}</span>
+    </div>
+
+    <div class="row">
+      <kj-time-picker [(kjValue)]="lunch" [kj12Hour]="true" kjAriaLabel="Lunch time" />
+      <span class="readout">{{ lunch() }}</span>
+    </div>
+
+    <div class="row">
+      <kj-time-picker [(kjValue)]="alarm" kjValueShape="string" kjAriaLabel="Alarm time" />
+      <span class="readout">{{ alarm() }}</span>
+    </div>
+  `,
+})
+export class KjTimePickerUsageExample {
+  readonly meeting = signal<Date | string>(new Date(2024, 0, 1, 9, 30));
+  readonly lunch = signal<Date | string>(new Date(2024, 0, 1, 12, 0));
+  readonly alarm = signal<Date | string>('07:00');
+}

package/src/time-picker/_examples/time-picker.with-seconds.example.ts

@@ -0,0 +1,24 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTimePickerComponent } from '../time-picker';
+
+/**
+ * Adds the (optional) seconds segment. Useful for sports timing, recording
+ * apps, or any time value where minute precision is too coarse.
+ */
+@Component({
+  selector: 'kj-time-picker-with-seconds-example',
+  standalone: true,
+  imports: [KjTimePickerComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: ` <kj-time-picker [(kjValue)]="time" kjShowSeconds kjAriaLabel="Lap time" /> `,
+})
+export class KjTimePickerWithSecondsExample {
+  readonly time = signal<Date | string>(new Date(2024, 0, 1, 0, 1, 23));
+}

package/src/time-picker/index.ts

@@ -0,0 +1 @@
+export { KjTimePickerComponent } from './time-picker';

package/src/time-picker/time-picker.css

@@ -0,0 +1,126 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-time-picker — wrapper around KjTimePicker + segment directives.
+
+   Three (or four) segmented spinbuttons sit inline. Each segment is a
+   2-character `<input>` with right-aligned text; the colon separator
+   between them is presentational. The meridiem toggle is a kj-button-
+   like surface that flips AM ↔ PM.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-time-picker {
+    --kj-time-picker-bg:               var(--kj-bg-field);
+    --kj-time-picker-fg:               var(--kj-fg-default);
+    --kj-time-picker-border-color:     var(--kj-border-default);
+    --kj-time-picker-border-width:     var(--kj-border);
+    --kj-time-picker-radius:           var(--kj-radius-field);
+    --kj-time-picker-padding-x:        var(--kj-space-md);
+    --kj-time-picker-font:             var(--kj-font-sans);
+    --kj-time-picker-font-size:        var(--kj-text-sm);
+    --kj-time-picker-segment-width:    2rem;
+    --kj-time-picker-meridiem-bg:      var(--kj-bg-surface);
+    --kj-time-picker-meridiem-fg:      var(--kj-fg-default);
+    /* Mirror `.kj-input` so a time-picker lines up vertically with sibling
+       inputs in a form row. Explicit height pins the box (sm/md/lg). Don't
+       set `align-self` here — when the parent is a column-flex stack
+       (e.g. <kj-form-field>'s label + control), `center` would horizontally
+       center this `inline-flex` host instead of leaving it at start. */
+    --kj-time-picker-height:           2.25rem;
+
+    display: inline-flex;
+    align-items: center;
+    gap: 0.125rem;
+    height: var(--kj-time-picker-height);
+    background: var(--kj-time-picker-bg);
+    color: var(--kj-time-picker-fg);
+    border: var(--kj-time-picker-border-width) solid var(--kj-time-picker-border-color);
+    border-radius: var(--kj-time-picker-radius);
+    padding: 0 var(--kj-time-picker-padding-x);
+    font: var(--kj-time-picker-font-size) / 1.4 var(--kj-time-picker-font);
+    transition: var(--kj-transition);
+  }
+  .kj-time-picker[data-size="sm"] { --kj-time-picker-height: 2rem;    --kj-time-picker-font-size: 0.8125rem; }
+  .kj-time-picker[data-size="lg"] { --kj-time-picker-height: 2.75rem; --kj-time-picker-font-size: 1rem; }
+
+  .kj-time-picker:focus-within {
+    --kj-time-picker-border-color: var(--kj-bg-primary);
+    outline: 2px solid var(--kj-bg-primary);
+    outline-offset: 2px;
+  }
+
+  .kj-time-picker[aria-invalid="true"] {
+    --kj-time-picker-border-color: var(--kj-bg-danger);
+  }
+
+  .kj-time-picker[data-disabled] {
+    opacity: 0.55;
+    cursor: not-allowed;
+  }
+
+  .kj-time-picker__segment {
+    width: var(--kj-time-picker-segment-width);
+    height: 100%;
+    background: transparent;
+    color: inherit;
+    border: 0;
+    padding: 0 0.25rem;
+    font: inherit;
+    font-variant-numeric: tabular-nums;
+    text-align: center;
+    appearance: textfield;
+    border-radius: var(--kj-radius-sm, 0.25rem);
+    transition: background var(--kj-transition);
+  }
+
+  .kj-time-picker__segment:focus {
+    outline: none;
+    background: color-mix(in oklab, var(--kj-bg-primary) 12%, transparent);
+  }
+
+  .kj-time-picker__segment[aria-invalid="true"] {
+    color: var(--kj-fg-danger);
+  }
+
+  .kj-time-picker__segment::-webkit-outer-spin-button,
+  .kj-time-picker__segment::-webkit-inner-spin-button {
+    appearance: none;
+    margin: 0;
+  }
+
+  .kj-time-picker__separator {
+    user-select: none;
+    color: color-mix(in oklab, var(--kj-time-picker-fg) 70%, transparent);
+  }
+
+  .kj-time-picker__meridiem {
+    margin-inline-start: var(--kj-space-sm);
+    min-width: 2.25rem;
+    min-height: 2.25rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--kj-time-picker-meridiem-bg);
+    color: var(--kj-time-picker-meridiem-fg);
+    border: 0;
+    border-radius: var(--kj-radius-field);
+    cursor: pointer;
+    font: inherit;
+    font-weight: 600;
+    transition: background var(--kj-transition), color var(--kj-transition);
+  }
+
+  .kj-time-picker__meridiem:hover {
+    background: color-mix(in oklab, var(--kj-fg-default) 8%, var(--kj-time-picker-meridiem-bg));
+  }
+
+  .kj-time-picker__meridiem[aria-pressed="true"] {
+    background: var(--kj-bg-primary);
+    color: var(--kj-fg-on-primary);
+  }
+
+  .kj-time-picker__meridiem[aria-disabled="true"] {
+    opacity: 0.4;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+}

package/src/time-picker/time-picker.playground.ts

@@ -0,0 +1,72 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjTimePickerComponent } from './time-picker';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. The value signal is a string so it
+ * round-trips through the text control cleanly.
+ */
+const value = signal<string>('09:30');
+const twelveHour = signal(false);
+const showSeconds = signal(false);
+const disabled = signal(false);
+const invalid = signal(false);
+
+@Component({
+  selector: 'kj-time-picker-playground',
+  standalone: true,
+  imports: [KjTimePickerComponent],
+  template: `
+    <kj-time-picker
+      [(kjValue)]="value"
+      kjValueShape="string"
+      [kj12Hour]="twelveHour()"
+      [kjShowSeconds]="showSeconds()"
+      [kjDisabled]="disabled()"
+      [kjInvalid]="invalid()"
+      kjAriaLabel="Time"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTimePickerPlaygroundDemo {
+  protected readonly value = value;
+  protected readonly twelveHour = twelveHour;
+  protected readonly showSeconds = showSeconds;
+  protected readonly disabled = disabled;
+  protected readonly invalid = invalid;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjTimePickerPlaygroundDemo,
+  state: {
+    value: value as unknown as ReturnType<typeof signal>,
+    twelveHour: twelveHour as unknown as ReturnType<typeof signal>,
+    showSeconds: showSeconds as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    invalid: invalid as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'text', name: 'value', label: 'value', placeholder: 'HH:MM' },
+    { kind: 'toggle', name: 'twelveHour', label: '12-hour' },
+    { kind: 'toggle', name: 'showSeconds', label: 'show seconds' },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+    { kind: 'toggle', name: 'invalid', label: 'invalid' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      value: string;
+      twelveHour: boolean;
+      showSeconds: boolean;
+      disabled: boolean;
+      invalid: boolean;
+    };
+    const attrs: string[] = [`[(kjValue)]="time"`, `kjValueShape="string"`];
+    if (s.twelveHour) attrs.push('[kj12Hour]="true"');
+    if (s.showSeconds) attrs.push('[kjShowSeconds]="true"');
+    if (s.disabled) attrs.push('[kjDisabled]="true"');
+    if (s.invalid) attrs.push('[kjInvalid]="true"');
+    attrs.push('kjAriaLabel="Time"');
+    return `<kj-time-picker\n  ${attrs.join('\n  ')}\n/>\n\n// time = signal('${s.value}')`;
+  },
+};

package/src/time-picker/time-picker.spec.ts

@@ -0,0 +1,77 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjTimePickerComponent } from './time-picker';
+
+@Component({
+  standalone: true,
+  imports: [KjTimePickerComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-time-picker
+      [(kjValue)]="value"
+      [kj12Hour]="twelveHour"
+      [kjShowSeconds]="showSeconds"
+      [kjStep]="step"
+      kjAriaLabel="Time"
+    />
+  `,
+})
+class HostComponent {
+  value = signal<Date | string | null>(new Date(2024, 0, 1, 9, 30, 0));
+  twelveHour = false;
+  showSeconds = false;
+  step = 1;
+}
+
+describe('KjTimePickerComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders the wrapper with two segments by default', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('.kj-time-picker');
+    expect(root).not.toBeNull();
+    const segments = root.querySelectorAll('.kj-time-picker__segment');
+    expect(segments.length).toBe(2);
+  });
+
+  test('forwards initial value to the hour and minute segments', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const hours = fixture.nativeElement.querySelector('.kj-time-picker__hours') as HTMLInputElement;
+    const minutes = fixture.nativeElement.querySelector(
+      '.kj-time-picker__minutes',
+    ) as HTMLInputElement;
+    expect(hours.getAttribute('aria-valuenow')).toBe('9');
+    expect(minutes.getAttribute('aria-valuenow')).toBe('30');
+  });
+
+  test('renders the meridiem toggle when kj12Hour is true', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.twelveHour = true;
+    fixture.detectChanges();
+    const meridiem = fixture.nativeElement.querySelector(
+      '.kj-time-picker__meridiem',
+    ) as HTMLButtonElement;
+    expect(meridiem).not.toBeNull();
+    expect(meridiem.getAttribute('aria-pressed')).toBe('false'); // 09:30 → AM
+  });
+
+  test('renders the seconds segment when kjShowSeconds is true', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.showSeconds = true;
+    fixture.detectChanges();
+    const seconds = fixture.nativeElement.querySelector('.kj-time-picker__seconds');
+    expect(seconds).not.toBeNull();
+  });
+
+  test('group conveys role="group"', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('.kj-time-picker');
+    expect(root.getAttribute('role')).toBe('group');
+  });
+});