@kouji-ui/core 0.0.3 → 0.1.1

package/src/textarea/textarea.ts

@@ -0,0 +1,235 @@
+import {
+  DestroyRef,
+  Directive,
+  ElementRef,
+  afterNextRender,
+  booleanAttribute,
+  computed,
+  effect,
+  inject,
+  input,
+} from '@angular/core';
+import { KjDisabled, KjFocusRing, KjFormControl } from '../primitives';
+import { KjSize, KjVariant, bindPresets } from '../presets';
+import { KJ_TEXTAREA_CONFIG } from './config';
+
+/**
+ * Number-attribute transform that preserves `undefined` instead of mapping it
+ * to `NaN` like Angular's built-in `numberAttribute`. Required so that
+ * `[kjMaxLength]="undefined"` keeps the host attribute removed rather than
+ * setting `maxlength="NaN"`.
+ *
+ * @internal
+ */
+function optionalNumberAttribute(v: number | string | undefined): number | undefined {
+  if (v == null || v === '') return undefined;
+  const n = typeof v === 'number' ? v : Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/** Resize behavior override for `<textarea kjTextarea>`. Maps to CSS `resize`. */
+export type KjTextareaResize = 'none' | 'vertical' | 'both';
+
+/** Auto-resize mode for `<textarea kjTextarea>`. */
+export type KjTextareaAutoresize = 'off' | 'auto';
+
+/**
+ * Enhances a native `<textarea>` with Angular forms integration, theme presets
+ * (`kjVariant` / `kjSize`), focus-ring + disabled/invalid reflection, optional
+ * auto-resize geometry, an optional character counter announcement, and a
+ * `kjResize` CSS override.
+ *
+ * Composes:
+ * - `KjFormControl` — `formControl` / `formControlName` / `ngModel` via CVA.
+ * - `KjVariant` / `KjSize` — `data-variant` / `data-size` for theme styling.
+ * - `KjFocusRing` — keyboard-only `data-focus-visible`.
+ * - `KjDisabled` — `aria-disabled` / `data-disabled` reflection.
+ *
+ * Auto-resize: when `kjAutoresize="auto"`, the directive measures
+ * `scrollHeight` on every input, clamps to `[kjMinRows, kjMaxRows]` rows, and
+ * pins `style.height` accordingly. The user drag-handle is forced off
+ * (`resize: none`) while auto-resize is on — mixing the two produces drift.
+ *
+ * Character counter: when `kjMaxLength` is set, the native `maxlength`
+ * attribute is bound. The directive exposes a `remaining()` signal and emits
+ * threshold-based ARIA announcements (≤ 20, ≤ 10, 0 remaining) to a polite
+ * live region declared by the wrapper or consumer — never per-keystroke.
+ *
+ * @example
+ * ```html
+ * <textarea kjTextarea rows="4" [formControl]="bio"></textarea>
+ *
+ * <textarea kjTextarea kjAutoresize="auto" [kjMinRows]="2" [kjMaxRows]="8"
+ *           [formControl]="bio"></textarea>
+ * ```
+ *
+ * @doc
+ *  @doc-file textarea.example.ts
+ * @doc-category Core/Inputs
+ * @doc-name textarea
+ * @doc-description Adds forms integration, focus ring, and optional auto-resize and character-count announcements to a textarea.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjTextarea]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize,    inputs: ['kjSize'] },
+    { directive: KjDisabled, inputs: ['kjDisabled'] },
+    KjFocusRing,
+    KjFormControl,
+  ],
+  providers: [...bindPresets(KJ_TEXTAREA_CONFIG)],
+  host: {
+    '[attr.aria-invalid]': 'formCtrl.touched() && kjInvalid() ? "true" : null',
+    '[attr.data-invalid]': 'formCtrl.touched() && kjInvalid() ? "" : null',
+    '[attr.disabled]': 'formCtrl.disabled() ? "" : null',
+    '[attr.maxlength]': 'kjMaxLength() ?? null',
+    '[attr.data-autoresize]': 'kjAutoresize() === "auto" ? "" : null',
+    '[style.resize]': 'effectiveResize()',
+    '(input)': 'onInput($any($event.target).value)',
+    '(blur)': 'formCtrl.notifyTouched()',
+  },
+})
+export class KjTextarea {
+  readonly formCtrl = inject(KjFormControl);
+  private readonly el = inject<ElementRef<HTMLTextAreaElement>>(ElementRef);
+  private readonly destroyRef = inject(DestroyRef);
+
+  /** Whether the textarea is in an invalid state. Combined with `touched` for ARIA. */
+  readonly kjInvalid = input(false, { transform: booleanAttribute });
+
+  /**
+   * Auto-resize mode. `'auto'` measures `scrollHeight` on each input and pins
+   * height between `kjMinRows` and `kjMaxRows`. `'off'` (default) leaves the
+   * height to native `rows` / CSS.
+   */
+  readonly kjAutoresize = input<KjTextareaAutoresize>('off');
+
+  /** Minimum rows when `kjAutoresize="auto"`. Falls back to native `rows`, then 1. */
+  readonly kjMinRows = input<number | undefined, number | string | undefined>(undefined, {
+    transform: optionalNumberAttribute,
+  });
+
+  /** Maximum rows when `kjAutoresize="auto"`. Beyond this, `overflow-y: auto`. */
+  readonly kjMaxRows = input<number | undefined, number | string | undefined>(undefined, {
+    transform: optionalNumberAttribute,
+  });
+
+  /** Native `maxlength`. Required for the character counter. */
+  readonly kjMaxLength = input<number | undefined, number | string | undefined>(undefined, {
+    transform: optionalNumberAttribute,
+  });
+
+  /**
+   * CSS `resize` override. Defaults to `'vertical'`. Forced to `'none'` when
+   * `kjAutoresize === 'auto'` regardless of the bound value.
+   */
+  readonly kjResize = input<KjTextareaResize>('vertical');
+
+  /** @internal Effective resize value once the autoresize override is applied. */
+  protected readonly effectiveResize = computed<KjTextareaResize>(() =>
+    this.kjAutoresize() === 'auto' ? 'none' : this.kjResize(),
+  );
+
+  /**
+   * Characters remaining before `kjMaxLength`. `null` when no max is set.
+   * Useful for wrappers that render a visible counter.
+   */
+  readonly remaining = computed<number | null>(() => {
+    const max = this.kjMaxLength();
+    if (max == null) return null;
+    const val = this.formCtrl.value();
+    const len = typeof val === 'string' ? val.length : 0;
+    return Math.max(0, max - len);
+  });
+
+  /**
+   * Threshold-based announcement string for the character counter, mirrored
+   * into a polite live region by the wrapper. Empty string when no
+   * announcement should fire on the current value (avoids per-keystroke
+   * chatter).
+   *
+   * Crosses at: `kjMaxLength - 20`, `kjMaxLength - 10`, `0` remaining.
+   */
+  readonly counterAnnouncement = computed<string>(() => {
+    const r = this.remaining();
+    if (r == null) return '';
+    if (r === 0) return 'Character limit reached';
+    if (r === 10) return '10 characters remaining';
+    if (r === 20) return '20 characters remaining';
+    return '';
+  });
+
+  constructor() {
+    // Reflect the CVA value signal back to the native textarea element. Same
+    // posture as KjInput: skip null/undefined so an external [value] attribute
+    // is preserved when no ngModel/formControl is wired.
+    effect(() => {
+      const val = this.formCtrl.value();
+      if (val == null) return;
+      const el = this.el.nativeElement;
+      if (el.value !== String(val)) {
+        el.value = String(val);
+      }
+    });
+
+    // Auto-resize: re-measure on every value change and on first paint. The
+    // `(input)` host binding also calls `measure()` so users see live growth
+    // even without a form binding.
+    effect(() => {
+      // Tracking dependencies — autoresize toggles, value, and rows bounds.
+      this.kjAutoresize();
+      this.kjMinRows();
+      this.kjMaxRows();
+      this.formCtrl.value();
+      this.measure();
+    });
+
+    afterNextRender(() => {
+      this.measure();
+      const onResize = () => this.measure();
+      window.addEventListener('resize', onResize);
+      this.destroyRef.onDestroy(() => window.removeEventListener('resize', onResize));
+    });
+  }
+
+  /** @internal — host (input) handler. */
+  onInput(value: string): void {
+    this.formCtrl.notifyChange(value);
+    if (this.kjAutoresize() === 'auto') {
+      this.measure();
+    }
+  }
+
+  /**
+   * Re-measures and pins the textarea height when `kjAutoresize === 'auto'`.
+   * Safe to call any time; no-op when auto-resize is off.
+   */
+  measure(): void {
+    if (this.kjAutoresize() !== 'auto') return;
+    const el = this.el.nativeElement;
+    if (!el || typeof el.scrollHeight !== 'number') return;
+
+    const cs = typeof getComputedStyle === 'function' ? getComputedStyle(el) : null;
+    if (!cs) return;
+
+    const lineHeight = parseFloat(cs.lineHeight) || parseFloat(cs.fontSize) * 1.4 || 20;
+    const paddingY = (parseFloat(cs.paddingTop) || 0) + (parseFloat(cs.paddingBottom) || 0);
+    const borderY = (parseFloat(cs.borderTopWidth) || 0) + (parseFloat(cs.borderBottomWidth) || 0);
+
+    const minRows = this.kjMinRows() ?? el.rows ?? 1;
+    const maxRows = this.kjMaxRows();
+
+    const minHeight = minRows * lineHeight + paddingY + borderY;
+    const maxHeight = maxRows != null ? maxRows * lineHeight + paddingY + borderY : Infinity;
+
+    // Collapse → measure → clamp. The transient 'auto' is single-frame.
+    el.style.height = 'auto';
+    const measured = el.scrollHeight;
+    const clamped = Math.max(minHeight, Math.min(measured, maxHeight));
+    el.style.height = `${clamped}px`;
+    el.style.overflowY = measured > maxHeight ? 'auto' : 'hidden';
+  }
+}

package/src/time-picker/index.ts

@@ -0,0 +1,15 @@
+export { KjTimePicker } from './time-picker';
+export {
+  KjTimePickerHours,
+  KjTimePickerMinutes,
+  KjTimePickerSeconds,
+} from './time-picker-segment';
+export { KjTimePickerMeridiem } from './time-picker-meridiem';
+export {
+  KJ_TIME_PICKER,
+  type KjTimePickerContext,
+} from './time-picker.context';
+export {
+  type TimeParts,
+  type KjHourCycle,
+} from './time-picker.format';

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

@@ -0,0 +1,123 @@
+import {
+  Directive,
+  LOCALE_ID,
+  booleanAttribute,
+  computed,
+  inject,
+  input,
+} from '@angular/core';
+import { KjFocusRing } from '../primitives';
+import { KJ_TIME_PICKER, KjTimePickerContext } from './time-picker.context';
+import { is12Hour } from './time-picker.format';
+
+/**
+ * AM/PM toggle directive. Only meaningful when the resolved hour cycle is
+ * `h11` or `h12`. Reflects `role="button"` + `aria-pressed` and toggles on
+ * Enter / Space / ArrowUp / ArrowDown.
+ *
+ * Per the WAI-ARIA APG **Toggle Button** pattern
+ * (<https://www.w3.org/WAI/ARIA/apg/patterns/button/>) the directive uses
+ * `aria-pressed="true"` for PM and `aria-pressed="false"` for AM.
+ *
+ * @example
+ * ```html
+ * <button type="button" kjTimePickerMeridiem></button>
+ * ```
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name time-picker
+ */
+@Directive({
+  selector: '[kjTimePickerMeridiem]',
+  standalone: true,
+  hostDirectives: [KjFocusRing],
+  host: {
+    '[attr.type]': '"button"',
+    '[attr.role]': '"button"',
+    '[attr.aria-pressed]': 'isPm() ? "true" : "false"',
+    '[attr.aria-label]': 'resolvedAriaLabel()',
+    '[attr.aria-disabled]': 'disabled() ? "true" : null',
+    '[attr.data-meridiem]': 'isPm() ? "pm" : "am"',
+    '[attr.disabled]': 'disabled() ? "" : null',
+    '[attr.hidden]': 'is12() ? null : ""',
+    '[textContent]': 'label()',
+    '(click)': 'onClick($event)',
+    '(keydown)': 'onKeydown($event)',
+  },
+})
+export class KjTimePickerMeridiem {
+  private readonly ctx = inject<KjTimePickerContext>(KJ_TIME_PICKER);
+  private readonly localeId = inject(LOCALE_ID);
+
+  /** Override the AM label. Defaults to a locale-derived string. */
+  readonly kjAmLabel = input<string | null>(null);
+  /** Override the PM label. Defaults to a locale-derived string. */
+  readonly kjPmLabel = input<string | null>(null);
+  /** Override the accessible label. */
+  readonly kjAriaLabel = input<string | null>(null);
+  /** Disable the toggle independently of the wrapper. */
+  readonly kjDisabled = input<boolean, unknown>(false, { transform: booleanAttribute });
+
+  /** @internal */
+  readonly isPm = computed(() => (this.ctx.value()?.hour ?? 0) >= 12);
+  /** @internal */
+  readonly is12 = computed(() => is12Hour(this.ctx.hourCycle()));
+
+  /** @internal */
+  readonly disabled = computed(() => this.kjDisabled() || this.ctx.disabled() || this.ctx.readonly());
+
+  /** @internal */
+  readonly label = computed(() => {
+    if (!this.is12()) return '';
+    const am = this.kjAmLabel() ?? localeMeridiem(this.localeId, false);
+    const pm = this.kjPmLabel() ?? localeMeridiem(this.localeId, true);
+    return this.isPm() ? pm : am;
+  });
+
+  /** @internal */
+  readonly resolvedAriaLabel = computed(() => this.kjAriaLabel() ?? 'Toggle AM/PM');
+
+  /** @internal */
+  onClick(event: Event): void {
+    if (this.disabled()) {
+      event.preventDefault();
+      return;
+    }
+    this.ctx.togglePeriod();
+  }
+
+  /** @internal */
+  onKeydown(event: KeyboardEvent): void {
+    if (this.disabled()) return;
+    switch (event.key) {
+      case 'Enter':
+      case ' ':
+      case 'Spacebar':
+        event.preventDefault();
+        this.ctx.togglePeriod();
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        this.ctx.setMeridiem('pm');
+        break;
+      case 'ArrowDown':
+        event.preventDefault();
+        this.ctx.setMeridiem('am');
+        break;
+    }
+  }
+}
+
+function localeMeridiem(locale: string, pm: boolean): string {
+  try {
+    const parts = new Intl.DateTimeFormat(locale, {
+      hour: 'numeric',
+      hour12: true,
+    }).formatToParts(new Date(2000, 0, 1, pm ? 13 : 9, 0, 0));
+    const dp = parts.find((p) => p.type === 'dayPeriod');
+    if (dp && dp.value) return dp.value;
+  } catch {
+    /* ignore */
+  }
+  return pm ? 'PM' : 'AM';
+}

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

@@ -0,0 +1,318 @@
+import { DOCUMENT, isPlatformBrowser } from '@angular/common';
+import {
+  Directive,
+  ElementRef,
+  PLATFORM_ID,
+  booleanAttribute,
+  computed,
+  effect,
+  inject,
+  input,
+} from '@angular/core';
+import { KjFocusRing } from '../primitives';
+import { KJ_TIME_PICKER, KjTimePickerContext } from './time-picker.context';
+import {
+  KjHourCycle,
+  fromDisplayHour,
+  hourBounds,
+  is12Hour,
+  pad2,
+  toDisplayHour,
+} from './time-picker.format';
+
+type SegmentKind = 'hour' | 'minute' | 'second';
+
+/**
+ * Internal helper that wires a single time-segment `<input>` to the time-picker
+ * context. Concrete segments (`hours`, `minutes`, `seconds`) each set their
+ * `kind` and consume this base via composition through the directive class
+ * hierarchy.
+ *
+ * Each segment exposes the WAI-ARIA `spinbutton` contract
+ * (<https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/>) on its host:
+ * `aria-valuemin` / `aria-valuemax` / `aria-valuenow` / `aria-valuetext`.
+ * @doc
+ * @doc-name time-picker
+ */
+@Directive({ standalone: true })
+export abstract class KjTimePickerSegmentBase {
+  protected abstract readonly kind: SegmentKind;
+  protected readonly el = inject<ElementRef<HTMLInputElement>>(ElementRef);
+  private readonly platformId = inject(PLATFORM_ID);
+  private readonly doc = inject(DOCUMENT);
+  /** @internal */
+  readonly ctx = inject<KjTimePickerContext>(KJ_TIME_PICKER);
+
+  /** Forwarded to `[attr.aria-label]`. Defaults to a sensible English label. */
+  readonly kjAriaLabel = input<string | null>(null);
+
+  /** Disable typing. Stepping still works via Arrow keys when the directive is focused. */
+  readonly kjReadonly = input<boolean, unknown>(false, { transform: booleanAttribute });
+
+  /** Display value (zero-padded 2-digit string for the segment). */
+  readonly displayValue = computed(() => {
+    const parts = this.ctx.value();
+    if (parts == null) return '';
+    if (this.kind === 'minute') return pad2(parts.minute);
+    if (this.kind === 'second') return pad2(parts.second);
+    return pad2(toDisplayHour(parts.hour, this.ctx.hourCycle()));
+  });
+
+  /** `aria-valuemin` / `aria-valuemax` for the segment. */
+  readonly minBound = computed(() => {
+    if (this.kind === 'minute' || this.kind === 'second') return 0;
+    return hourBounds(this.ctx.hourCycle()).min;
+  });
+  readonly maxBound = computed(() => {
+    if (this.kind === 'minute' || this.kind === 'second') return 59;
+    return hourBounds(this.ctx.hourCycle()).max;
+  });
+
+  /** Current numeric value (display, in the segment's coordinate space). */
+  readonly numericValue = computed(() => {
+    const parts = this.ctx.value();
+    if (parts == null) return null;
+    if (this.kind === 'minute') return parts.minute;
+    if (this.kind === 'second') return parts.second;
+    return toDisplayHour(parts.hour, this.ctx.hourCycle());
+  });
+
+  readonly ariaValueText = computed(() => {
+    const v = this.numericValue();
+    if (v == null) return null;
+    return pad2(v);
+  });
+
+  readonly resolvedAriaLabel = computed(() => {
+    if (this.kjAriaLabel() != null) return this.kjAriaLabel();
+    if (this.kind === 'hour') return 'Hours';
+    if (this.kind === 'minute') return 'Minutes';
+    return 'Seconds';
+  });
+
+  readonly disabled = computed(() => this.ctx.disabled());
+  readonly effectiveReadonly = computed(() => this.kjReadonly() || this.ctx.readonly());
+
+  constructor() {
+    // Reflect numeric model to the input's text content.
+    effect(() => {
+      if (!isPlatformBrowser(this.platformId)) return;
+      const next = this.displayValue();
+      const el = this.el.nativeElement;
+      if (el && this.doc.activeElement !== el && el.value !== next) {
+        el.value = next;
+      }
+    });
+  }
+
+  /** @internal */
+  onFocus(): void {
+    const el = this.el.nativeElement;
+    if (el) el.select?.();
+  }
+
+  /** @internal */
+  onBlur(): void {
+    this.commitFromBuffer();
+  }
+
+  /** @internal */
+  onInput(event: Event): void {
+    const el = event.target as HTMLInputElement;
+    // Strip non-digits.
+    const filtered = el.value.replace(/\D+/g, '').slice(0, 2);
+    if (filtered !== el.value) el.value = filtered;
+  }
+
+  /** @internal */
+  onKeydown(event: KeyboardEvent): void {
+    if (this.ctx.disabled()) return;
+    switch (event.key) {
+      case 'ArrowUp':
+        event.preventDefault();
+        this.ctx.stepSegment(this.kind, 1);
+        break;
+      case 'ArrowDown':
+        event.preventDefault();
+        this.ctx.stepSegment(this.kind, -1);
+        break;
+      case 'Home': {
+        event.preventDefault();
+        const min = this.minBound();
+        const cycle = this.ctx.hourCycle();
+        if (this.kind === 'hour') {
+          const meridiem: 'am' | 'pm' = (this.ctx.value()?.hour ?? 0) >= 12 ? 'pm' : 'am';
+          this.ctx.setSegment('hour', is12Hour(cycle) ? fromDisplayHour(min, cycle, meridiem) : min);
+        } else {
+          this.ctx.setSegment(this.kind, min);
+        }
+        break;
+      }
+      case 'End': {
+        event.preventDefault();
+        const max = this.maxBound();
+        const cycle = this.ctx.hourCycle();
+        if (this.kind === 'hour') {
+          const meridiem: 'am' | 'pm' = (this.ctx.value()?.hour ?? 0) >= 12 ? 'pm' : 'am';
+          this.ctx.setSegment('hour', is12Hour(cycle) ? fromDisplayHour(max, cycle, meridiem) : max);
+        } else {
+          this.ctx.setSegment(this.kind, max);
+        }
+        break;
+      }
+      case 'Enter':
+        event.preventDefault();
+        this.commitFromBuffer();
+        break;
+    }
+  }
+
+  protected commitFromBuffer(): void {
+    if (this.effectiveReadonly() || this.ctx.disabled()) return;
+    const el = this.el.nativeElement;
+    if (!el) return;
+    const raw = el.value.trim();
+    if (raw === '') {
+      // Restore display from current model.
+      el.value = this.displayValue();
+      return;
+    }
+    const n = Number(raw);
+    if (!Number.isFinite(n)) {
+      el.value = this.displayValue();
+      return;
+    }
+    if (this.kind === 'minute' || this.kind === 'second') {
+      this.ctx.setSegment(this.kind, n);
+    } else {
+      const cycle = this.ctx.hourCycle();
+      if (is12Hour(cycle)) {
+        const meridiem: 'am' | 'pm' = (this.ctx.value()?.hour ?? 0) >= 12 ? 'pm' : 'am';
+        const hour24 = fromDisplayHour(n, cycle, meridiem);
+        this.ctx.setSegment('hour', hour24);
+      } else {
+        this.ctx.setSegment('hour', cycle === 'h24' && n === 24 ? 0 : n);
+      }
+    }
+  }
+}
+
+/**
+ * Hours segment. `role="spinbutton"` over a 2-digit hour value. Min/max depend
+ * on the resolved hour cycle (`h11`: 0–11, `h12`: 1–12, `h23`: 0–23,
+ * `h24`: 1–24).
+ *
+ * @example
+ * ```html
+ * <input kjTimePickerHours />
+ * ```
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name time-picker
+ */
+@Directive({
+  selector: '[kjTimePickerHours]',
+  standalone: true,
+  hostDirectives: [KjFocusRing],
+  host: {
+    '[attr.role]': '"spinbutton"',
+    '[attr.inputmode]': '"numeric"',
+    '[attr.aria-valuemin]': 'minBound()',
+    '[attr.aria-valuemax]': 'maxBound()',
+    '[attr.aria-valuenow]': 'numericValue() ?? null',
+    '[attr.aria-valuetext]': 'ariaValueText()',
+    '[attr.aria-label]': 'resolvedAriaLabel()',
+    '[attr.aria-readonly]': 'effectiveReadonly() ? "true" : null',
+    '[attr.aria-disabled]': 'disabled() ? "true" : null',
+    '[attr.disabled]': 'disabled() ? "" : null',
+    '[attr.readonly]': 'effectiveReadonly() ? "" : null',
+    '[attr.maxlength]': '2',
+    '(focus)': 'onFocus()',
+    '(blur)': 'onBlur()',
+    '(input)': 'onInput($event)',
+    '(keydown)': 'onKeydown($event)',
+  },
+})
+export class KjTimePickerHours extends KjTimePickerSegmentBase {
+  protected readonly kind = 'hour' as const;
+}
+
+/**
+ * Minutes segment. `role="spinbutton"`, range 0–59. ArrowUp / ArrowDown step
+ * by `kjStep` minutes (defaults to `1`).
+ *
+ * @example
+ * ```html
+ * <input kjTimePickerMinutes />
+ * ```
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name time-picker
+ */
+@Directive({
+  selector: '[kjTimePickerMinutes]',
+  standalone: true,
+  hostDirectives: [KjFocusRing],
+  host: {
+    '[attr.role]': '"spinbutton"',
+    '[attr.inputmode]': '"numeric"',
+    '[attr.aria-valuemin]': 'minBound()',
+    '[attr.aria-valuemax]': 'maxBound()',
+    '[attr.aria-valuenow]': 'numericValue() ?? null',
+    '[attr.aria-valuetext]': 'ariaValueText()',
+    '[attr.aria-label]': 'resolvedAriaLabel()',
+    '[attr.aria-readonly]': 'effectiveReadonly() ? "true" : null',
+    '[attr.aria-disabled]': 'disabled() ? "true" : null',
+    '[attr.disabled]': 'disabled() ? "" : null',
+    '[attr.readonly]': 'effectiveReadonly() ? "" : null',
+    '[attr.maxlength]': '2',
+    '(focus)': 'onFocus()',
+    '(blur)': 'onBlur()',
+    '(input)': 'onInput($event)',
+    '(keydown)': 'onKeydown($event)',
+  },
+})
+export class KjTimePickerMinutes extends KjTimePickerSegmentBase {
+  protected readonly kind = 'minute' as const;
+}
+
+/**
+ * Seconds segment (optional). `role="spinbutton"`, range 0–59.
+ *
+ * @example
+ * ```html
+ * <input kjTimePickerSeconds />
+ * ```
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name time-picker
+ */
+@Directive({
+  selector: '[kjTimePickerSeconds]',
+  standalone: true,
+  hostDirectives: [KjFocusRing],
+  host: {
+    '[attr.role]': '"spinbutton"',
+    '[attr.inputmode]': '"numeric"',
+    '[attr.aria-valuemin]': 'minBound()',
+    '[attr.aria-valuemax]': 'maxBound()',
+    '[attr.aria-valuenow]': 'numericValue() ?? null',
+    '[attr.aria-valuetext]': 'ariaValueText()',
+    '[attr.aria-label]': 'resolvedAriaLabel()',
+    '[attr.aria-readonly]': 'effectiveReadonly() ? "true" : null',
+    '[attr.aria-disabled]': 'disabled() ? "true" : null',
+    '[attr.disabled]': 'disabled() ? "" : null',
+    '[attr.readonly]': 'effectiveReadonly() ? "" : null',
+    '[attr.maxlength]': '2',
+    '(focus)': 'onFocus()',
+    '(blur)': 'onBlur()',
+    '(input)': 'onInput($event)',
+    '(keydown)': 'onKeydown($event)',
+  },
+})
+export class KjTimePickerSeconds extends KjTimePickerSegmentBase {
+  protected readonly kind = 'second' as const;
+}
+
+/** Re-exported for the period directive's use. */
+export type { KjHourCycle };