@kouji-ui/components 0.1.1

package/src/input-mask/_examples/input-mask.credit-card.example.ts

@@ -0,0 +1,90 @@
+import { Component, ElementRef, signal, viewChild, ChangeDetectionStrategy } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjInputMask, KJ_INPUT_MASK_PRESETS } from '@kouji-ui/core';
+import { KjFieldComponent, KjFieldLabelComponent } from '../../field/field';
+
+/**
+ * Credit-card form using `KJ_INPUT_MASK_PRESETS`. The `(kjComplete)` event on
+ * each field auto-advances focus to the next field — a common UX pattern for
+ * payment entry.
+ */
+@Component({
+  selector: 'kj-input-mask-credit-card-example',
+  standalone: true,
+  imports: [FormsModule, KjInputMask, KjFieldComponent, KjFieldLabelComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        max-width: 400px;
+      }
+      .card-form {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+      .card-row {
+        display: flex;
+        gap: var(--kj-space-md);
+      }
+      .card-row kj-field {
+        flex: 1;
+      }
+      input[kjInputMask] {
+        color: var(--kj-fg-default);
+        border: 1px solid var(--kj-border-default);
+        border-radius: var(--kj-radius-field, 0.375rem);
+        padding: var(--kj-space-sm) var(--kj-space-md);
+        font: var(--kj-text-sm) / 1.4 var(--kj-font-sans);
+        font-variant-numeric: tabular-nums;
+        width: 100%;
+      }
+      input[kjInputMask]:focus-visible {
+        outline: 2px solid var(--kj-fg-primary);
+        outline-offset: 2px;
+        border-color: var(--kj-fg-primary);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="card-form">
+      <kj-field>
+        <kj-field-label>Card number</kj-field-label>
+        <input
+          #cardNumber
+          kjInputMask
+          [kjMask]="presets.cardNumber"
+          [(ngModel)]="cardNumberValue"
+          (kjComplete)="expiryInput().nativeElement.focus()"
+        />
+      </kj-field>
+      <div class="card-row">
+        <kj-field>
+          <kj-field-label>Expiry (MM/YY)</kj-field-label>
+          <input
+            #expiry
+            kjInputMask
+            [kjMask]="presets.cardExpiry"
+            [(ngModel)]="expiryValue"
+            (kjComplete)="cvvInput().nativeElement.focus()"
+          />
+        </kj-field>
+        <kj-field>
+          <kj-field-label>CVV</kj-field-label>
+          <input #cvv kjInputMask kjMask="999" [(ngModel)]="cvvValue" />
+        </kj-field>
+      </div>
+    </div>
+  `,
+})
+export class KjInputMaskCreditCardExample {
+  readonly presets = KJ_INPUT_MASK_PRESETS;
+
+  readonly cardNumberValue = signal('');
+  readonly expiryValue = signal('');
+  readonly cvvValue = signal('');
+
+  readonly expiryInput = viewChild.required<ElementRef<HTMLInputElement>>('expiry');
+  readonly cvvInput = viewChild.required<ElementRef<HTMLInputElement>>('cvv');
+}

package/src/input-mask/_examples/input-mask.custom-tokens.example.ts

@@ -0,0 +1,87 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjInputMask } from '@kouji-ui/core';
+import { KjFieldComponent, KjFieldHelpComponent, KjFieldLabelComponent } from '../../field/field';
+
+/**
+ * Custom-tokens example — hex colour code `#HHHHHH` using a per-instance
+ * token `H` for `/[0-9A-Fa-f]/`.
+ *
+ * The `#` is treated as a literal (not in the token map), and the remaining
+ * six positions accept only hexadecimal characters.
+ */
+@Component({
+  selector: 'kj-input-mask-custom-tokens-example',
+  standalone: true,
+  imports: [
+    FormsModule,
+    KjInputMask,
+    KjFieldComponent,
+    KjFieldHelpComponent,
+    KjFieldLabelComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+        max-width: 400px;
+      }
+      input[kjInputMask] {
+        color: var(--kj-fg-default);
+        border: 1px solid var(--kj-border-default);
+        border-radius: var(--kj-radius-field, 0.375rem);
+        padding: var(--kj-space-sm) var(--kj-space-md);
+        font: var(--kj-text-sm) / 1.4 var(--kj-font-mono, monospace);
+        font-variant-numeric: tabular-nums;
+        width: 100%;
+      }
+      input[kjInputMask]:focus-visible {
+        outline: 2px solid var(--kj-fg-primary);
+        outline-offset: 2px;
+        border-color: var(--kj-fg-primary);
+      }
+      .preview {
+        margin-top: var(--kj-space-md);
+        display: flex;
+        align-items: center;
+        gap: var(--kj-space-sm);
+        font-size: var(--kj-text-sm);
+        color: var(--kj-fg-default);
+      }
+      .swatch {
+        display: inline-block;
+        width: 1.5rem;
+        height: 1.5rem;
+        border-radius: 0.25rem;
+        border: 1px solid var(--kj-border-default);
+        flex-shrink: 0;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-field>
+      <kj-field-label>Hex colour</kj-field-label>
+      <input
+        kjInputMask
+        kjMask="#HHHHHH"
+        [kjMaskTokens]="hexTokens"
+        kjMaskMode="masked"
+        [(ngModel)]="hex"
+      />
+      <kj-field-help>Six hexadecimal digits, e.g. #1A2B3C</kj-field-help>
+    </kj-field>
+    <div class="preview">
+      <span class="swatch" [style.background]="hex().length === 7 ? hex() : 'transparent'"></span>
+      <span>{{ hex() }}</span>
+    </div>
+  `,
+})
+export class KjInputMaskCustomTokensExample {
+  readonly hex = signal('#______');
+
+  /** Per-instance token map: H = hex digit. */
+  readonly hexTokens: Record<string, RegExp> = {
+    H: /[0-9A-Fa-f]/,
+  };
+}

package/src/input-mask/_examples/input-mask.date.example.ts

@@ -0,0 +1,61 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjInputMask, KJ_INPUT_MASK_PRESETS } from '@kouji-ui/core';
+import { KjFieldComponent, KjFieldHelpComponent, KjFieldLabelComponent } from '../../field/field';
+
+/**
+ * Date field using the `usDate` preset (`99/99/9999`).
+ * Demonstrates a common calendar-adjacent use case.
+ */
+@Component({
+  selector: 'kj-input-mask-date-example',
+  standalone: true,
+  imports: [
+    FormsModule,
+    KjInputMask,
+    KjFieldComponent,
+    KjFieldHelpComponent,
+    KjFieldLabelComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+        max-width: 400px;
+      }
+      input[kjInputMask] {
+        color: var(--kj-fg-default);
+        border: 1px solid var(--kj-border-default);
+        border-radius: var(--kj-radius-field, 0.375rem);
+        padding: var(--kj-space-sm) var(--kj-space-md);
+        font: var(--kj-text-sm) / 1.4 var(--kj-font-sans);
+        font-variant-numeric: tabular-nums;
+        width: 100%;
+      }
+      input[kjInputMask]:focus-visible {
+        outline: 2px solid var(--kj-fg-primary);
+        outline-offset: 2px;
+        border-color: var(--kj-fg-primary);
+      }
+      .value-display {
+        margin-top: var(--kj-space-md);
+        font-size: var(--kj-text-xs);
+        color: var(--kj-fg-muted);
+        font-family: var(--kj-font-mono, monospace);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-field>
+      <kj-field-label>Date of birth</kj-field-label>
+      <input kjInputMask [kjMask]="presets.usDate" [(ngModel)]="date" />
+      <kj-field-help>MM/DD/YYYY</kj-field-help>
+    </kj-field>
+    <p class="value-display">Raw value: {{ date() }}</p>
+  `,
+})
+export class KjInputMaskDateExample {
+  readonly presets = KJ_INPUT_MASK_PRESETS;
+  readonly date = signal('');
+}

package/src/input-mask/_examples/input-mask.example.ts

@@ -0,0 +1,61 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjInputMask } from '@kouji-ui/core';
+import { KjFieldComponent, KjFieldHelpComponent, KjFieldLabelComponent } from '../../field/field';
+
+/**
+ * Default usage example — phone number mask.
+ * Demonstrates `kjMaskMode="unmasked"` (default): the model value is raw
+ * digits; the mask shape is only a display concern.
+ */
+@Component({
+  selector: 'kj-input-mask-example',
+  standalone: true,
+  imports: [
+    FormsModule,
+    KjInputMask,
+    KjFieldComponent,
+    KjFieldLabelComponent,
+    KjFieldHelpComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+        max-width: 400px;
+      }
+      input[kjInputMask] {
+        color: var(--kj-fg-default);
+        border: 1px solid var(--kj-border-default);
+        border-radius: var(--kj-radius-field, 0.375rem);
+        padding: var(--kj-space-sm) var(--kj-space-md);
+        font: var(--kj-text-sm) / 1.4 var(--kj-font-sans);
+        font-variant-numeric: tabular-nums;
+        width: 100%;
+      }
+      input[kjInputMask]:focus-visible {
+        outline: 2px solid var(--kj-fg-primary);
+        outline-offset: 2px;
+        border-color: var(--kj-fg-primary);
+      }
+      .value-display {
+        margin-top: var(--kj-space-md);
+        font-size: var(--kj-text-xs);
+        color: var(--kj-fg-muted);
+        font-family: var(--kj-font-mono, monospace);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-field>
+      <kj-field-label>Phone number</kj-field-label>
+      <input kjInputMask kjMask="(999) 999-9999" [(ngModel)]="phone" />
+      <kj-field-help>Format: (###) ###-####</kj-field-help>
+    </kj-field>
+    <p class="value-display">Value: {{ phone() }}</p>
+  `,
+})
+export class KjInputMaskExample {
+  readonly phone = signal('');
+}

package/src/input-mask/_examples/input-mask.usage.example.ts

@@ -0,0 +1,44 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjInputMaskComponent } from '../input-mask';
+
+/**
+ * Common mask patterns assembled into one screen — phone, date, and credit
+ * card. Copy-paste starting point for masked forms.
+ */
+@Component({
+  selector: 'kj-input-mask-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjInputMaskComponent, FormsModule],
+  styles: [`
+    :host { display: flex; flex-direction: column; gap: var(--kj-space-md); max-width: 360px; }
+    label { font: 500 var(--kj-text-sm)/1.4 var(--kj-font-sans); }
+    .row { display: flex; flex-direction: column; gap: var(--kj-space-xs); }
+    code { font: var(--kj-text-xs)/1 var(--kj-font-mono); color: var(--kj-fg-muted); }
+  `],
+  template: `
+    <div class="row">
+      <label for="usage-phone">Phone</label>
+      <kj-input-mask id="usage-phone" kjMask="(999) 999-9999" [(ngModel)]="phone" />
+      <code>{{ phone() || '—' }}</code>
+    </div>
+
+    <div class="row">
+      <label for="usage-date">Date</label>
+      <kj-input-mask id="usage-date" kjMask="9999-99-99" [(ngModel)]="date" />
+      <code>{{ date() || '—' }}</code>
+    </div>
+
+    <div class="row">
+      <label for="usage-card">Card</label>
+      <kj-input-mask id="usage-card" kjMask="9999 9999 9999 9999" [(ngModel)]="card" />
+      <code>{{ card() || '—' }}</code>
+    </div>
+  `,
+})
+export class KjInputMaskUsageExample {
+  readonly phone = signal('');
+  readonly date = signal('');
+  readonly card = signal('');
+}

package/src/input-mask/_examples/input-mask.validation.example.ts

@@ -0,0 +1,80 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
+import { KjInputMask } from '@kouji-ui/core';
+import {
+  KjFieldComponent,
+  KjFieldErrorComponent,
+  KjFieldHelpComponent,
+  KjFieldLabelComponent,
+} from '../../field/field';
+
+/**
+ * Reactive form with `Validators.required` and the built-in `mask` validator.
+ *
+ * The mask validator fires automatically when the field has been partially
+ * filled — no extra wiring needed. Read `ctrl.errors?.mask` in your template
+ * to show a custom "incomplete" message.
+ */
+@Component({
+  selector: 'kj-input-mask-validation-example',
+  standalone: true,
+  imports: [
+    ReactiveFormsModule,
+    KjInputMask,
+    KjFieldComponent,
+    KjFieldLabelComponent,
+    KjFieldHelpComponent,
+    KjFieldErrorComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+        max-width: 400px;
+      }
+      input[kjInputMask] {
+        color: var(--kj-fg-default);
+        border: 1px solid var(--kj-border-default);
+        border-radius: var(--kj-radius-field, 0.375rem);
+        padding: var(--kj-space-sm) var(--kj-space-md);
+        font: var(--kj-text-sm) / 1.4 var(--kj-font-sans);
+        font-variant-numeric: tabular-nums;
+        width: 100%;
+      }
+      input[kjInputMask]:focus-visible {
+        outline: 2px solid var(--kj-fg-primary);
+        outline-offset: 2px;
+        border-color: var(--kj-fg-primary);
+      }
+      input[kjInputMask][aria-invalid='true'] {
+        border-color: var(--kj-fg-danger, #ef4444);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-field [kjInvalid]="phoneCtrl.invalid && phoneCtrl.touched">
+      <kj-field-label>Phone number</kj-field-label>
+      <input
+        kjInputMask
+        kjMask="(999) 999-9999"
+        [formControl]="phoneCtrl"
+        [kjInvalid]="phoneCtrl.invalid && phoneCtrl.touched"
+      />
+      <kj-field-help>US phone, e.g. (415) 555-0123</kj-field-help>
+      @if (phoneCtrl.touched && phoneCtrl.errors?.['required']) {
+        <kj-field-error>Phone number is required.</kj-field-error>
+      } @else if (phoneCtrl.touched && phoneCtrl.errors?.['mask']) {
+        <kj-field-error>
+          Please enter all {{ $any(phoneCtrl.errors)['mask']?.required }} digits ({{
+            $any(phoneCtrl.errors)['mask']?.filled
+          }}
+          of {{ $any(phoneCtrl.errors)['mask']?.required }} filled).
+        </kj-field-error>
+      }
+    </kj-field>
+  `,
+})
+export class KjInputMaskValidationExample {
+  readonly phoneCtrl = new FormControl('', [Validators.required]);
+}

package/src/input-mask/index.ts

@@ -0,0 +1,9 @@
+export { KjInputMaskComponent } from './input-mask';
+export {
+  KjInputMaskExample,
+  KjInputMaskUsageExample,
+  KjInputMaskCreditCardExample,
+  KjInputMaskDateExample,
+  KjInputMaskValidationExample,
+  KjInputMaskCustomTokensExample,
+} from './_examples';

package/src/input-mask/input-mask.css

@@ -0,0 +1,39 @@
+/* Input mask wrapper — inherits base input visual tokens */
+
+.kj-input-mask {
+  display: contents;
+}
+
+.kj-input-mask__input {
+  /* Inherits the same base-input tokens used by .kj-input. Explicit height
+     contract (matches input.css / button.css) so masked inputs line up with
+     sibling inputs in a form row. */
+  --kj-input-mask-height: 2.25rem;
+  background: var(--kj-bg-field);
+  color: var(--kj-fg-default);
+  border: var(--kj-border, 1px) solid var(--kj-border-default);
+  border-radius: var(--kj-radius-field, 0.375rem);
+  padding: 0 var(--kj-space-md, 0.75rem);
+  font: var(--kj-text-sm, 0.875rem) / 1.4 var(--kj-font-sans, sans-serif);
+  width: 100%;
+  height: var(--kj-input-mask-height);
+  font-variant-numeric: tabular-nums;
+}
+.kj-input-mask__input[data-size="sm"] { --kj-input-mask-height: 2rem;    font-size: 0.8125rem; }
+.kj-input-mask__input[data-size="lg"] { --kj-input-mask-height: 2.75rem; font-size: 1rem; }
+
+.kj-input-mask__input:focus-visible {
+  outline: 2px solid var(--kj-fg-primary);
+  outline-offset: 2px;
+  border-color: var(--kj-fg-primary);
+}
+
+.kj-input-mask__input[aria-invalid='true'] {
+  border-color: var(--kj-fg-danger, #ef4444);
+}
+
+.kj-input-mask__input[data-disabled],
+.kj-input-mask__input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}

package/src/input-mask/input-mask.playground.ts

@@ -0,0 +1,79 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjInputMaskComponent } from './input-mask';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Mask preset, mode, disabled,
+ * invalid, and auto-clear cover the surface the wrapper exposes. The
+ * mask preset is a chips list since the playground engine doesn't yet
+ * ship a free-text control validated against a token regex.
+ */
+const mask = signal<'(999) 999-9999' | '99/99/9999' | '9999 9999 9999 9999' | 'aaa-999'>(
+  '(999) 999-9999',
+);
+const maskMode = signal<'unmasked' | 'masked'>('unmasked');
+const disabled = signal(false);
+const invalid = signal(false);
+const autoClear = signal(false);
+
+@Component({
+  selector: 'kj-input-mask-playground',
+  standalone: true,
+  imports: [KjInputMaskComponent, FormsModule],
+  styles: [`:host { display: block; max-width: 360px; }`],
+  template: `
+    <kj-input-mask
+      [kjMask]="mask()"
+      [kjMaskMode]="maskMode()"
+      [kjDisabled]="disabled()"
+      [kjInvalid]="invalid()"
+      [kjAutoClear]="autoClear()"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjInputMaskPlaygroundDemo {
+  protected readonly mask = mask;
+  protected readonly maskMode = maskMode;
+  protected readonly disabled = disabled;
+  protected readonly invalid = invalid;
+  protected readonly autoClear = autoClear;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjInputMaskPlaygroundDemo,
+  state: {
+    mask: mask as unknown as ReturnType<typeof signal>,
+    maskMode: maskMode as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    invalid: invalid as unknown as ReturnType<typeof signal>,
+    autoClear: autoClear as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'mask',
+      label: 'mask',
+      options: ['(999) 999-9999', '99/99/9999', '9999 9999 9999 9999', 'aaa-999'],
+    },
+    { kind: 'chips', name: 'maskMode', label: 'mode', options: ['unmasked', 'masked'] },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+    { kind: 'toggle', name: 'invalid', label: 'invalid' },
+    { kind: 'toggle', name: 'autoClear', label: 'auto clear' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      mask: string;
+      maskMode: string;
+      disabled: boolean;
+      invalid: boolean;
+      autoClear: boolean;
+    };
+    const attrs: string[] = [`kjMask="${s.mask}"`, `kjMaskMode="${s.maskMode}"`];
+    if (s.disabled) attrs.push('[kjDisabled]="true"');
+    if (s.invalid) attrs.push('[kjInvalid]="true"');
+    if (s.autoClear) attrs.push('[kjAutoClear]="true"');
+    return `<kj-input-mask\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};

package/src/input-mask/input-mask.ts

@@ -0,0 +1,130 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  input,
+  output,
+} from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjInputMask } from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjInputMask` directive. Owns the visual
+ * shape of a masked text input. The inner `<input>` carries native input
+ * semantics (focus, form integration, validation).
+ *
+ * The component proxies all `KjInputMask` inputs and the `kjComplete` output.
+ * Use `[(ngModel)]` or `[formControl]` on the inner `<input>` for form wiring.
+ *
+ * @example
+ * ```html
+ * <kj-input-mask kjMask="(999) 999-9999" [(ngModel)]="phone" />
+ * ```
+ *
+ * @doc-example Default
+ *   Phone number mask — anchors the chrome and the `kjMaskMode="unmasked"` default.
+ *   @doc-file input-mask.example.ts
+ * @doc-example Usage
+ *   Common mask patterns assembled into one screen — phone, date, and credit card.
+ *   @doc-file input-mask.usage.example.ts
+ * @doc-example Credit card
+ *   16-digit mask with grouped quads.
+ *   @doc-file input-mask.credit-card.example.ts
+ * @doc-example Date
+ *   ISO `YYYY-MM-DD` mask with format-hint announcement for AT.
+ *   @doc-file input-mask.date.example.ts
+ * @doc-example Validation
+ *   Pairs `kjComplete` with reactive form validators to flag incomplete masks.
+ *   @doc-file input-mask.validation.example.ts
+ * @doc-example Custom tokens
+ *   Per-instance token map for masks beyond `9` / `A` / `*`.
+ *   @doc-file input-mask.custom-tokens.example.ts
+ *
+ * @doc-keyboard
+ *   Tab        — Moves focus into and out of the masked input (native semantics)
+ *   Backspace  — Removes the previous variable slot; static separators are skipped
+ *   Arrow keys — Move the caret across slots; the directive snaps over static chars
+ *
+ * @doc-aria
+ *   aria-invalid    — Reflected when [kjInvalid] is true (via the composed KjInput plumbing)
+ *   aria-describedby— Auto-augmented with the auto-generated format hint unless [kjFormatHint] is empty
+ *   data-mask-mode  — Mirrors [kjMaskMode] ("unmasked" | "masked") for CSS hooks
+ *
+ * @doc-touch
+ *   Height inherits the `kj-input` defaults — `md` is 36 px; use `data-size="lg"`
+ *   for primary touch fields so the slot-tap surface meets WCAG 2.5.5.
+ *
+ * @doc-a11y
+ *   `KjInputMask` auto-generates a screen-reader format hint from the mask
+ *   template (e.g. `'(999) 999-9999'` → "Format: (___) ___-____") and wires
+ *   it through `aria-describedby`. Override or suppress with `[kjFormatHint]`.
+ *   The native `<input>` underneath keeps full focus + caret semantics.
+ *
+ * @doc-related input,field,form,number-input
+ *
+ * @doc-css-var
+ *   --kj-input-mask-height — Explicit height of the masked input. Sizes (sm/lg via data-size) override.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name input-mask
+ * @doc-description Themed masked text input for phone numbers, dates, credit cards, and custom formats.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-input-mask',
+  standalone: true,
+  imports: [KjInputMask, FormsModule],
+  template: `
+    <input
+      kjInputMask
+      class="kj-input-mask__input"
+      [kjMask]="kjMask()"
+      [kjMaskTokens]="kjMaskTokens()"
+      [kjMaskMode]="kjMaskMode()"
+      [kjSlotChar]="kjSlotChar()"
+      [kjDisabled]="kjDisabled()"
+      [kjInvalid]="kjInvalid()"
+      [kjAutoClear]="kjAutoClear()"
+      [kjFormatHint]="kjFormatHint()"
+      (kjComplete)="kjComplete.emit()"
+    />
+  `,
+  styleUrl: './input-mask.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-input-mask' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjInputMaskComponent {
+  /** Mask template. Required. e.g. `'(999) 999-9999'`. */
+  readonly kjMask = input.required<string>();
+
+  /** Per-instance token overrides merged with the app-wide defaults. */
+  readonly kjMaskTokens = input<Record<string, RegExp>>({});
+
+  /**
+   * What value is committed to the FormControl.
+   * - `'unmasked'` (default) — raw alphanumerics.
+   * - `'masked'` — full display string.
+   */
+  readonly kjMaskMode = input<'unmasked' | 'masked'>('unmasked');
+
+  /** Placeholder char for empty variable slots. @default '_' */
+  readonly kjSlotChar = input<string>('_');
+
+  /** Disabled state. @default false */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+
+  /** Invalid state — wires to `aria-invalid` via the inner `KjInput`. @default false */
+  readonly kjInvalid = input(false, { transform: booleanAttribute });
+
+  /** Clear on blur if incomplete. @default false */
+  readonly kjAutoClear = input(false, { transform: booleanAttribute });
+
+  /** Override or suppress the auto-generated screen-reader format hint. */
+  readonly kjFormatHint = input<string>('');
+
+  /** Emits when every variable slot is filled. */
+  readonly kjComplete = output<void>();
+}