@kouji-ui/core 0.0.3 → 0.1.1

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

@@ -0,0 +1,38 @@
+import { InjectionToken, Signal } from '@angular/core';
+import type { KjHourCycle, TimeParts } from './time-picker.format';
+
+/**
+ * Shared state published by `[kjTimePicker]` (the wrapper) and consumed by
+ * sibling segment / period directives.
+ *
+ * The wrapper owns the value, hour cycle, granularity and step config; each
+ * segment is a thin spinbutton that reads and writes through this contract.
+ */
+export interface KjTimePickerContext {
+  readonly value: Signal<TimeParts | null>;
+  readonly hourCycle: Signal<KjHourCycle>;
+  readonly showSeconds: Signal<boolean>;
+
+  readonly hourStep: Signal<number>;
+  readonly minuteStep: Signal<number>;
+  readonly secondStep: Signal<number>;
+
+  readonly min: Signal<TimeParts | null>;
+  readonly max: Signal<TimeParts | null>;
+
+  readonly disabled: Signal<boolean>;
+  readonly readonly: Signal<boolean>;
+  readonly invalid: Signal<boolean>;
+
+  /** Apply `n` step units to a segment. Carries on overflow. */
+  stepSegment(segment: 'hour' | 'minute' | 'second', units: number): void;
+  /** Set a segment's value directly. Clamps + carries / wraps per config. */
+  setSegment(segment: 'hour' | 'minute' | 'second', value: number): void;
+  /** Toggle AM / PM (hour ± 12, mod 24). No-op when not in 12h mode. */
+  togglePeriod(): void;
+  /** Set the meridiem explicitly. No-op when not in 12h mode. */
+  setMeridiem(period: 'am' | 'pm'): void;
+}
+
+/** DI token used to share the time-picker context with descendant directives. */
+export const KJ_TIME_PICKER = new InjectionToken<KjTimePickerContext>('KjTimePicker');

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

@@ -0,0 +1,181 @@
+/**
+ * Internal time helpers for `[kjTimePicker]`.
+ *
+ * The component stores time-of-day as `TimeParts` and serialises to either
+ * `Date` or `string` on the CVA boundary. All comparisons and arithmetic run
+ * over `TimeParts`.
+ */
+
+/** Internal time-of-day shape. Always 0-based hours (0–23). */
+export interface TimeParts {
+  hour: number;   // 0–23
+  minute: number; // 0–59
+  second: number; // 0–59
+}
+
+/** Resolved hour cycle. `auto` is normalised away by the wrapper. */
+export type KjHourCycle = 'h11' | 'h12' | 'h23' | 'h24';
+
+/** Zero-pad a non-negative integer to 2 digits. */
+export function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+/** Resolve `'auto'` against a locale via `Intl.DateTimeFormat`. */
+export function resolveHourCycle(
+  cycle: KjHourCycle | 'auto',
+  locale: string,
+): KjHourCycle {
+  if (cycle !== 'auto') return cycle;
+  try {
+    const resolved = new Intl.DateTimeFormat(locale, { hour: 'numeric' })
+      // hourCycle exists at runtime but is missing from TS lib types
+      .resolvedOptions()['hourCycle' as keyof Intl.ResolvedDateTimeFormatOptions];
+    if (resolved === 'h11' || resolved === 'h12' || resolved === 'h23' || resolved === 'h24') {
+      return resolved;
+    }
+  } catch {
+    /* fall through */
+  }
+  return 'h23';
+}
+
+/** Whether the cycle uses a 12-hour AM/PM presentation. */
+export function is12Hour(cycle: KjHourCycle): boolean {
+  return cycle === 'h11' || cycle === 'h12';
+}
+
+/** Convert internal 0–23 hour into the displayable hour for a cycle. */
+export function toDisplayHour(hour24: number, cycle: KjHourCycle): number {
+  switch (cycle) {
+    case 'h11': return hour24 % 12;             // 0–11
+    case 'h12': return ((hour24 + 11) % 12) + 1; // 1–12
+    case 'h24': return hour24 === 0 ? 24 : hour24; // 1–24
+    case 'h23':
+    default:    return hour24;                   // 0–23
+  }
+}
+
+/** Inverse of `toDisplayHour`, given the meridiem (`am`/`pm`) for h11/h12. */
+export function fromDisplayHour(
+  display: number,
+  cycle: KjHourCycle,
+  meridiem: 'am' | 'pm',
+): number {
+  switch (cycle) {
+    case 'h11': {
+      const base = ((display % 12) + 12) % 12;
+      return meridiem === 'pm' ? base + 12 : base;
+    }
+    case 'h12': {
+      const base = ((display - 1 + 12) % 12);
+      return meridiem === 'pm' ? base + 12 : base;
+    }
+    case 'h24':
+      return display === 24 ? 0 : display;
+    case 'h23':
+    default:
+      return display;
+  }
+}
+
+/** Inclusive segment range for the cycle (display values). */
+export function hourBounds(cycle: KjHourCycle): { min: number; max: number } {
+  switch (cycle) {
+    case 'h11': return { min: 0, max: 11 };
+    case 'h12': return { min: 1, max: 12 };
+    case 'h24': return { min: 1, max: 24 };
+    case 'h23':
+    default:    return { min: 0, max: 23 };
+  }
+}
+
+/** Modular add helper for an inclusive [0, mod) wrap. */
+export function mod(n: number, m: number): number {
+  return ((n % m) + m) % m;
+}
+
+/** Compare two `TimeParts` by total seconds-of-day. */
+export function compareTime(a: TimeParts, b: TimeParts): number {
+  const sa = a.hour * 3600 + a.minute * 60 + a.second;
+  const sb = b.hour * 3600 + b.minute * 60 + b.second;
+  return sa - sb;
+}
+
+/** Test whether `t` is inside [min, max], with overnight-range support. */
+export function inRange(
+  t: TimeParts,
+  min: TimeParts | null,
+  max: TimeParts | null,
+): boolean {
+  if (min == null && max == null) return true;
+  if (min == null) return compareTime(t, max!) <= 0;
+  if (max == null) return compareTime(t, min) >= 0;
+  if (compareTime(min, max) <= 0) {
+    return compareTime(t, min) >= 0 && compareTime(t, max) <= 0;
+  }
+  // Overnight: outside [max, min].
+  return compareTime(t, min) >= 0 || compareTime(t, max) <= 0;
+}
+
+/** Format `TimeParts` as `'HH:mm'` / `'HH:mm:ss'`. */
+export function formatTimeString(t: TimeParts, withSeconds: boolean): string {
+  const base = `${pad2(t.hour)}:${pad2(t.minute)}`;
+  return withSeconds ? `${base}:${pad2(t.second)}` : base;
+}
+
+/** Parse `'HH:mm'` / `'HH:mm:ss'` (lenient: accepts missing seconds). */
+export function parseTimeString(s: string): TimeParts | null {
+  const m = /^(\d{1,2}):(\d{1,2})(?::(\d{1,2}))?$/.exec(s.trim());
+  if (!m) return null;
+  const hour = Number(m[1]);
+  const minute = Number(m[2]);
+  const second = m[3] != null ? Number(m[3]) : 0;
+  if (
+    !Number.isFinite(hour) || hour < 0 || hour > 23 ||
+    !Number.isFinite(minute) || minute < 0 || minute > 59 ||
+    !Number.isFinite(second) || second < 0 || second > 59
+  ) return null;
+  return { hour, minute, second };
+}
+
+/** Convert any accepted value-shape into internal `TimeParts | null`. */
+export function toParts(
+  value: Date | string | TimeParts | null | undefined,
+): TimeParts | null {
+  if (value == null) return null;
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return null;
+    return {
+      hour: value.getHours(),
+      minute: value.getMinutes(),
+      second: value.getSeconds(),
+    };
+  }
+  if (typeof value === 'string') return parseTimeString(value);
+  if (
+    typeof value === 'object' &&
+    typeof (value as TimeParts).hour === 'number' &&
+    typeof (value as TimeParts).minute === 'number'
+  ) {
+    return {
+      hour: (value as TimeParts).hour,
+      minute: (value as TimeParts).minute,
+      second: (value as TimeParts).second ?? 0,
+    };
+  }
+  return null;
+}
+
+/** Project `TimeParts` onto a `Date`, copying the date part from `reference`. */
+export function toDate(t: TimeParts, reference: Date): Date {
+  const d = new Date(reference.getTime());
+  d.setHours(t.hour, t.minute, t.second, 0);
+  return d;
+}
+
+/** Snap a value to the closest lattice point of `step` from `0`. */
+export function snapToStep(value: number, step: number): number {
+  if (step <= 0) return value;
+  return Math.round(value / step) * step;
+}

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

@@ -0,0 +1,189 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { fireEvent } from '@testing-library/angular';
+import { afterEach, describe, expect, test } from 'vitest';
+import {
+  KjTimePicker,
+  KjTimePickerHours,
+  KjTimePickerMeridiem,
+  KjTimePickerMinutes,
+  KjTimePickerSeconds,
+} from './index';
+import { parseTimeString, toParts } from './time-picker.format';
+
+@Component({
+  standalone: true,
+  imports: [
+    KjTimePicker,
+    KjTimePickerHours,
+    KjTimePickerMinutes,
+    KjTimePickerSeconds,
+    KjTimePickerMeridiem,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div
+      kjTimePicker
+      [(kjValue)]="value"
+      [kj12Hour]="twelveHour()"
+      [kjHourCycle]="hourCycle()"
+      [kjShowSeconds]="showSeconds()"
+      [kjStep]="step()"
+      [kjValueShape]="valueShape()"
+    >
+      <input kjTimePickerHours data-testid="hours" />
+      <input kjTimePickerMinutes data-testid="minutes" />
+      @if (showSeconds()) {
+        <input kjTimePickerSeconds data-testid="seconds" />
+      }
+      <button
+        type="button"
+        kjTimePickerMeridiem
+        data-testid="meridiem"
+        aria-label="Toggle meridiem"
+      ></button>
+    </div>
+  `,
+})
+class HostComponent {
+  value = signal<Date | string | null>(new Date(2024, 0, 1, 9, 30, 0));
+  twelveHour = signal(false);
+  hourCycle = signal<'h11' | 'h12' | 'h23' | 'h24' | 'auto'>('h23');
+  showSeconds = signal(false);
+  step = signal(1);
+  valueShape = signal<'date' | 'string'>('date');
+}
+
+function setup(): {
+  fixture: ReturnType<typeof TestBed.createComponent<HostComponent>>;
+  root: HTMLElement;
+} {
+  TestBed.configureTestingModule({ imports: [HostComponent] });
+  const fixture = TestBed.createComponent(HostComponent);
+  fixture.detectChanges();
+  return { fixture, root: fixture.nativeElement };
+}
+
+describe('KjTimePicker (headless)', () => {
+  afterEach(() => TestBed.resetTestingModule());
+
+  test('wrapper is a group with role="group"', () => {
+    const { root } = setup();
+    const wrapper = root.querySelector('[kjTimePicker]') as HTMLElement;
+    expect(wrapper.getAttribute('role')).toBe('group');
+  });
+
+  test('hours and minutes segments expose role="spinbutton" + value attrs', () => {
+    const { root } = setup();
+    const hours = root.querySelector('[data-testid="hours"]') as HTMLInputElement;
+    const minutes = root.querySelector('[data-testid="minutes"]') as HTMLInputElement;
+    expect(hours.getAttribute('role')).toBe('spinbutton');
+    expect(minutes.getAttribute('role')).toBe('spinbutton');
+    expect(hours.getAttribute('aria-valuemin')).toBe('0');
+    expect(hours.getAttribute('aria-valuemax')).toBe('23');
+    expect(hours.getAttribute('aria-valuenow')).toBe('9');
+    expect(minutes.getAttribute('aria-valuenow')).toBe('30');
+  });
+
+  test('ArrowUp on minutes increments by step', () => {
+    const { fixture, root } = setup();
+    const minutes = root.querySelector('[data-testid="minutes"]') as HTMLInputElement;
+    fireEvent.keyDown(minutes, { key: 'ArrowUp' });
+    fixture.detectChanges();
+    expect(minutes.getAttribute('aria-valuenow')).toBe('31');
+  });
+
+  test('ArrowDown on minutes decrements by step', () => {
+    const { fixture, root } = setup();
+    const minutes = root.querySelector('[data-testid="minutes"]') as HTMLInputElement;
+    fireEvent.keyDown(minutes, { key: 'ArrowDown' });
+    fixture.detectChanges();
+    expect(minutes.getAttribute('aria-valuenow')).toBe('29');
+  });
+
+  test('ArrowUp on minutes carries into hours on overflow', () => {
+    const { fixture, root } = setup();
+    fixture.componentInstance.value.set(new Date(2024, 0, 1, 9, 59, 0));
+    fixture.detectChanges();
+    const minutes = root.querySelector('[data-testid="minutes"]') as HTMLInputElement;
+    fireEvent.keyDown(minutes, { key: 'ArrowUp' });
+    fixture.detectChanges();
+    const hours = root.querySelector('[data-testid="hours"]') as HTMLInputElement;
+    expect(minutes.getAttribute('aria-valuenow')).toBe('0');
+    expect(hours.getAttribute('aria-valuenow')).toBe('10');
+  });
+
+  test('Home / End jump to segment bounds', () => {
+    const { fixture, root } = setup();
+    const minutes = root.querySelector('[data-testid="minutes"]') as HTMLInputElement;
+    fireEvent.keyDown(minutes, { key: 'End' });
+    fixture.detectChanges();
+    expect(minutes.getAttribute('aria-valuenow')).toBe('59');
+    fireEvent.keyDown(minutes, { key: 'Home' });
+    fixture.detectChanges();
+    expect(minutes.getAttribute('aria-valuenow')).toBe('0');
+  });
+
+  test('12-hour mode toggles meridiem (aria-pressed) and h12 hour bounds', () => {
+    const { fixture, root } = setup();
+    fixture.componentInstance.twelveHour.set(true);
+    fixture.componentInstance.value.set(new Date(2024, 0, 1, 9, 30, 0));
+    fixture.detectChanges();
+    const meridiem = root.querySelector('[data-testid="meridiem"]') as HTMLButtonElement;
+    const hours = root.querySelector('[data-testid="hours"]') as HTMLInputElement;
+    expect(meridiem.getAttribute('aria-pressed')).toBe('false'); // AM at 09:30
+    expect(hours.getAttribute('aria-valuemin')).toBe('1');
+    expect(hours.getAttribute('aria-valuemax')).toBe('12');
+    expect(hours.getAttribute('aria-valuenow')).toBe('9');
+    meridiem.click();
+    fixture.detectChanges();
+    expect(meridiem.getAttribute('aria-pressed')).toBe('true');
+    // Hour stayed display-9 but advanced to PM internally → 21:30.
+    const v = fixture.componentInstance.value();
+    expect(v instanceof Date).toBe(true);
+    expect((v as Date).getHours()).toBe(21);
+  });
+
+  test('seconds segment renders only when kjShowSeconds=true', () => {
+    const { fixture, root } = setup();
+    expect(root.querySelector('[data-testid="seconds"]')).toBeNull();
+    fixture.componentInstance.showSeconds.set(true);
+    fixture.detectChanges();
+    expect(root.querySelector('[data-testid="seconds"]')).not.toBeNull();
+  });
+
+  test('emits a Date by default and a string when kjValueShape="string"', () => {
+    const { fixture, root } = setup();
+    const minutes = root.querySelector('[data-testid="minutes"]') as HTMLInputElement;
+    fireEvent.keyDown(minutes, { key: 'ArrowUp' });
+    fixture.detectChanges();
+    const v1 = fixture.componentInstance.value();
+    expect(v1 instanceof Date).toBe(true);
+
+    fixture.componentInstance.valueShape.set('string');
+    fixture.componentInstance.value.set('09:30');
+    fixture.detectChanges();
+    fireEvent.keyDown(minutes, { key: 'ArrowUp' });
+    fixture.detectChanges();
+    expect(typeof fixture.componentInstance.value()).toBe('string');
+    expect(fixture.componentInstance.value()).toBe('09:31');
+  });
+
+  test('parseTimeString round-trips via toParts', () => {
+    expect(parseTimeString('08:05')).toEqual({ hour: 8, minute: 5, second: 0 });
+    expect(parseTimeString('08:05:09')).toEqual({ hour: 8, minute: 5, second: 9 });
+    expect(parseTimeString('25:00')).toBeNull();
+    expect(toParts(new Date(2024, 0, 1, 11, 22, 33))).toEqual({ hour: 11, minute: 22, second: 33 });
+  });
+
+  test('kjStep on minutes advances by the configured amount', () => {
+    const { fixture, root } = setup();
+    fixture.componentInstance.step.set(15);
+    fixture.componentInstance.value.set(new Date(2024, 0, 1, 9, 30, 0));
+    fixture.detectChanges();
+    const minutes = root.querySelector('[data-testid="minutes"]') as HTMLInputElement;
+    fireEvent.keyDown(minutes, { key: 'ArrowUp' });
+    fixture.detectChanges();
+    expect(minutes.getAttribute('aria-valuenow')).toBe('45');
+  });
+});

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

@@ -0,0 +1,274 @@
+import {
+  Directive,
+  LOCALE_ID,
+  Signal,
+  booleanAttribute,
+  computed,
+  effect,
+  inject,
+  input,
+  model,
+  numberAttribute,
+  signal,
+} from '@angular/core';
+import { KjDisabled, KjFormControl } from '../primitives';
+import { KJ_TIME_PICKER, KjTimePickerContext } from './time-picker.context';
+import {
+  KjHourCycle,
+  TimeParts,
+  compareTime,
+  formatTimeString,
+  inRange,
+  is12Hour,
+  mod,
+  resolveHourCycle,
+  snapToStep,
+  toDate,
+  toParts,
+} from './time-picker.format';
+
+/**
+ * Root directive for the time picker. Owns the time-of-day model, the resolved
+ * hour cycle, segment bounds, the step config and the `KjFormControl` bridge.
+ *
+ * The directive renders no DOM of its own — it expects the consumer to project
+ * a row of `[kjTimePickerHours]`, `[kjTimePickerMinutes]`, optional
+ * `[kjTimePickerSeconds]`, and (when in 12h mode) `[kjTimePickerMeridiem]`
+ * children. State flows through the `KJ_TIME_PICKER` context.
+ *
+ * @example
+ * ```html
+ * <div kjTimePicker [(kjValue)]="time" [kjStep]="15">
+ *   <input kjTimePickerHours />
+ *   <span aria-hidden="true">:</span>
+ *   <input kjTimePickerMinutes />
+ *   <button kjTimePickerMeridiem></button>
+ * </div>
+ * ```
+ *
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name time-picker
+ * @doc-description Unstyled time-picker root that holds the time-of-day model and shares state with segment inputs.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjTimePicker]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjDisabled, inputs: ['kjDisabled'] },
+    KjFormControl,
+  ],
+  providers: [{ provide: KJ_TIME_PICKER, useExisting: KjTimePicker }],
+  exportAs: 'kjTimePicker',
+  host: {
+    'role': 'group',
+    '[attr.aria-disabled]': 'formCtrl.disabled() ? "true" : null',
+    '[attr.aria-readonly]': 'kjReadonly() ? "true" : null',
+    '[attr.aria-invalid]': 'ariaInvalid()',
+    '[attr.data-hour-cycle]': 'hourCycle()',
+  },
+})
+export class KjTimePicker implements KjTimePickerContext {
+  /** @internal */
+  readonly formCtrl = inject(KjFormControl);
+  private readonly localeId = inject(LOCALE_ID);
+
+  /** Two-way bindable time value. Accepts `Date`, `'HH:mm[:ss]'`, or `null`. */
+  readonly kjValue = model<Date | string | null>(null);
+
+  /** Output value shape. `'date'` emits a `Date`; `'string'` emits `'HH:mm[:ss]'`. */
+  readonly kjValueShape = input<'date' | 'string'>('date');
+
+  /** When true, force 12-hour AM/PM mode regardless of locale. */
+  readonly kj12Hour = input<boolean, unknown>(false, { transform: booleanAttribute });
+
+  /** Explicit hour cycle; `'auto'` resolves from the locale (or `kj12Hour`). */
+  readonly kjHourCycle = input<KjHourCycle | 'auto'>('auto');
+
+  /** Show the seconds segment. */
+  readonly kjShowSeconds = input<boolean, unknown>(false, { transform: booleanAttribute });
+
+  /** Minute step (canonical); ArrowUp / ArrowDown on the minutes segment use it. */
+  readonly kjStep = input<number, unknown>(1, { transform: numberAttribute });
+
+  /** Per-segment step overrides. */
+  readonly kjHourStep = input<number, unknown>(1, { transform: numberAttribute });
+  readonly kjMinuteStep = input<number | undefined, unknown>(undefined, {
+    transform: (v: unknown) => (v === undefined || v === null || v === '' ? undefined : numberAttribute(v)),
+  });
+  readonly kjSecondStep = input<number, unknown>(1, { transform: numberAttribute });
+
+  /** Lower / upper time-of-day bounds. Accept `Date`, `'HH:mm[:ss]'`, or `null`. */
+  readonly kjMin = input<Date | string | TimeParts | null>(null);
+  readonly kjMax = input<Date | string | TimeParts | null>(null);
+
+  /** Read-only state. */
+  readonly kjReadonly = input<boolean, unknown>(false, { transform: booleanAttribute });
+
+  /** External invalid signal. OR'd with bounds for `aria-invalid`. */
+  readonly kjInvalid = input<boolean, unknown>(false, { transform: booleanAttribute });
+
+  /** BCP-47 locale tag. Falls back to the injected `LOCALE_ID`. */
+  readonly kjLocale = input<string | undefined>(undefined);
+
+  /** Date used as the date part when emitting `Date` values. Defaults to `new Date()`. */
+  readonly kjReferenceDate = input<Date | undefined>(undefined);
+
+  // ── Internal state ────────────────────────────────────────────────────────
+
+  private readonly _parts = signal<TimeParts | null>(null);
+  /** Stable fallback reference Date when kjReferenceDate is undefined. */
+  private readonly _refDate = new Date();
+
+  /** @internal */
+  readonly value: Signal<TimeParts | null> = this._parts.asReadonly();
+
+  /** Resolved hour cycle (consumer-facing, via the context). */
+  readonly hourCycle: Signal<KjHourCycle> = computed(() => {
+    if (this.kj12Hour()) return 'h12';
+    return resolveHourCycle(this.kjHourCycle(), this.kjLocale() ?? this.localeId);
+  });
+
+  readonly showSeconds: Signal<boolean> = computed(() => this.kjShowSeconds());
+
+  readonly hourStep: Signal<number> = computed(() => Math.max(1, this.kjHourStep()));
+  readonly minuteStep: Signal<number> = computed(() => Math.max(1, this.kjMinuteStep() ?? this.kjStep()));
+  readonly secondStep: Signal<number> = computed(() => Math.max(1, this.kjSecondStep()));
+
+  readonly min: Signal<TimeParts | null> = computed(() => toParts(this.kjMin()));
+  readonly max: Signal<TimeParts | null> = computed(() => toParts(this.kjMax()));
+
+  readonly disabled: Signal<boolean> = computed(() => this.formCtrl.disabled());
+  readonly readonly: Signal<boolean> = computed(() => this.kjReadonly());
+  readonly invalid: Signal<boolean> = computed(() => this.kjInvalid() || this.outOfRange());
+
+  protected readonly outOfRange = computed(() => {
+    const v = this._parts();
+    if (v == null) return false;
+    return !inRange(v, this.min(), this.max());
+  });
+
+  protected readonly ariaInvalid = computed(() => {
+    const touched = this.formCtrl.touched();
+    const invalid = this.kjInvalid() || this.outOfRange();
+    return touched && invalid ? 'true' : null;
+  });
+
+  constructor() {
+    // Bridge model ↔ internal parts.
+    effect(() => {
+      const next = toParts(this.kjValue());
+      const cur = this._parts();
+      if (!partsEqual(cur, next)) this._parts.set(next);
+    });
+
+    // Bridge KjFormControl ↔ model. Reactive forms write through `writeValue`.
+    effect(() => {
+      const cvaValue = this.formCtrl.value();
+      if (cvaValue === undefined) return;
+      const next = toParts(cvaValue as Date | string | null);
+      if (!partsEqual(next, this._parts())) {
+        this._parts.set(next);
+      }
+    });
+  }
+
+  // ── KjTimePickerContext implementation ────────────────────────────────────
+
+  /** @internal */
+  stepSegment(segment: 'hour' | 'minute' | 'second', units: number): void {
+    if (this.formCtrl.disabled() || this.kjReadonly()) return;
+    const cur = this._parts() ?? defaultParts();
+    const step =
+      segment === 'hour' ? this.hourStep() :
+      segment === 'minute' ? this.minuteStep() :
+      this.secondStep();
+    let next: TimeParts;
+    if (segment === 'hour') {
+      next = { ...cur, hour: mod(cur.hour + units * step, 24) };
+    } else if (segment === 'minute') {
+      const total = cur.hour * 60 + cur.minute + units * step;
+      const wrapped = mod(total, 24 * 60);
+      next = { ...cur, hour: Math.floor(wrapped / 60), minute: wrapped % 60 };
+    } else {
+      const total = cur.hour * 3600 + cur.minute * 60 + cur.second + units * step;
+      const wrapped = mod(total, 24 * 3600);
+      next = {
+        hour: Math.floor(wrapped / 3600),
+        minute: Math.floor((wrapped % 3600) / 60),
+        second: wrapped % 60,
+      };
+    }
+    this.commit(next);
+  }
+
+  /** @internal */
+  setSegment(segment: 'hour' | 'minute' | 'second', value: number): void {
+    if (this.formCtrl.disabled() || this.kjReadonly()) return;
+    const cur = this._parts() ?? defaultParts();
+    const next: TimeParts = { ...cur };
+    if (segment === 'hour') next.hour = clamp(value, 0, 23);
+    else if (segment === 'minute') next.minute = clamp(value, 0, 59);
+    else next.second = clamp(value, 0, 59);
+    this.commit(next);
+  }
+
+  /** @internal */
+  togglePeriod(): void {
+    if (!is12Hour(this.hourCycle())) return;
+    if (this.formCtrl.disabled() || this.kjReadonly()) return;
+    const cur = this._parts() ?? defaultParts();
+    this.commit({ ...cur, hour: mod(cur.hour + 12, 24) });
+  }
+
+  /** @internal */
+  setMeridiem(period: 'am' | 'pm'): void {
+    if (!is12Hour(this.hourCycle())) return;
+    if (this.formCtrl.disabled() || this.kjReadonly()) return;
+    const cur = this._parts() ?? defaultParts();
+    const isPm = cur.hour >= 12;
+    if ((period === 'pm' && isPm) || (period === 'am' && !isPm)) return;
+    this.commit({ ...cur, hour: mod(cur.hour + 12, 24) });
+  }
+
+  // ── Internals ─────────────────────────────────────────────────────────────
+
+  private commit(next: TimeParts): void {
+    // Optionally snap step on commit. We only snap minutes / seconds when the
+    // canonical step is > 1, mirroring PrimeNG's `stepMinute` clamping.
+    let snapped = next;
+    if (this.minuteStep() > 1) {
+      snapped = { ...snapped, minute: clamp(snapToStep(snapped.minute, this.minuteStep()), 0, 59) };
+    }
+    if (this.secondStep() > 1) {
+      snapped = { ...snapped, second: clamp(snapToStep(snapped.second, this.secondStep()), 0, 59) };
+    }
+    if (partsEqual(snapped, this._parts())) return;
+    this._parts.set(snapped);
+    const out = this.serialise(snapped);
+    this.kjValue.set(out as Date | string | null);
+    this.formCtrl.notifyChange(out);
+  }
+
+  private serialise(t: TimeParts): Date | string | null {
+    if (this.kjValueShape() === 'string') {
+      return formatTimeString(t, this.showSeconds());
+    }
+    return toDate(t, this.kjReferenceDate() ?? this._refDate);
+  }
+}
+
+function partsEqual(a: TimeParts | null, b: TimeParts | null): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  return compareTime(a, b) === 0;
+}
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, n));
+}
+
+function defaultParts(): TimeParts {
+  return { hour: 0, minute: 0, second: 0 };
+}

package/src/toast/_examples/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { ToastBasicExample } from './toast.example';
+export { ToastFinanceExample } from './toast.finance.example';
+export { ToastRetroExample } from './toast.retro.example';