@kouji-ui/core 0.0.4 → 0.1.1

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

@@ -0,0 +1,376 @@
+import type { CompiledMask, Slot } from './input-mask.compile';
+
+/** Callbacks injected into MaskEngine to decouple it from the DOM and Angular. */
+export interface MaskEngineCallbacks {
+  /** Returns the current display value in the input element. */
+  getValue(): string;
+  /** Sets the display value in the input element. */
+  setValue(value: string): void;
+  /** Returns the current caret position (selectionStart). */
+  getCaret(): number;
+  /** Moves the caret to the given position. */
+  setCaret(pos: number): void;
+  /** Called whenever the logical (raw or masked) value changes. */
+  notifyChange(value: string): void;
+}
+
+/** Options for constructing a MaskEngine. */
+export interface MaskEngineOptions {
+  getCompiled(): CompiledMask;
+  getSlotChar(): string;
+  getMaskMode(): 'unmasked' | 'masked';
+  callbacks: MaskEngineCallbacks;
+}
+
+/**
+ * Pure state machine for the input-mask keyboard/paste/caret behaviour.
+ * No Angular DI — constructed by the directive with callback closures.
+ *
+ * Responsibilities:
+ * - Intercept keydown (printable chars, Backspace, Delete, arrow keys).
+ * - Intercept paste events and sanitise clipboard content.
+ * - Reconstruct a display string from raw characters.
+ * - Emit the model value (raw or masked) via `notifyChange`.
+ */
+export class MaskEngine {
+  private _composing = false;
+
+  constructor(private readonly opts: MaskEngineOptions) {}
+
+  // ── Public event handlers ──────────────────────────────────────────────
+
+  /** Handle keyboard events. Printable chars, Backspace, Delete, navigation. */
+  onKeydown(e: KeyboardEvent): void {
+    if (this._composing) return;
+
+    const { key, ctrlKey, metaKey, altKey } = e;
+
+    // Pass through: ctrl/meta/alt combos (copy, paste, undo, …)
+    if (ctrlKey || metaKey || altKey) return;
+    // Pass through: Tab, Enter, Escape, function keys
+    if (['Tab', 'Enter', 'Escape'].includes(key) || key.startsWith('F')) return;
+
+    if (key === 'Backspace') {
+      e.preventDefault();
+      this._handleBackspace();
+      return;
+    }
+
+    if (key === 'Delete') {
+      e.preventDefault();
+      this._handleDelete();
+      return;
+    }
+
+    if (key === 'ArrowLeft') {
+      e.preventDefault();
+      this._snapCaret('prev');
+      return;
+    }
+
+    if (key === 'ArrowRight') {
+      e.preventDefault();
+      this._snapCaret('next');
+      return;
+    }
+
+    if (key === 'Home') {
+      e.preventDefault();
+      this._snapCaret('first');
+      return;
+    }
+
+    if (key === 'End') {
+      e.preventDefault();
+      this._snapCaret('last');
+      return;
+    }
+
+    // Printable character (single char, not a special key)
+    if (key.length === 1) {
+      e.preventDefault();
+      this._insertChar(key);
+    }
+  }
+
+  /** Handle the beforeinput event (IME, mobile keyboards). */
+  onBeforeInput(e: InputEvent): void {
+    if (this._composing) return;
+    if (!e.data) return;
+    if (e.inputType === 'insertText' || e.inputType === 'insertCompositionText') {
+      e.preventDefault();
+      for (const ch of e.data) {
+        this._insertChar(ch);
+      }
+    }
+  }
+
+  /** Handle paste events — sanitise clipboard text into the mask. */
+  onPaste(e: ClipboardEvent): void {
+    e.preventDefault();
+    const text = e.clipboardData?.getData('text') ?? '';
+    this._pasteText(text);
+  }
+
+  /** Composition start — hold off on keydown processing. */
+  onCompositionStart(): void {
+    this._composing = true;
+  }
+
+  /** Composition end — process the composed string. */
+  onCompositionEnd(e: CompositionEvent): void {
+    this._composing = false;
+    if (e.data) {
+      for (const ch of e.data) {
+        this._insertChar(ch);
+      }
+    }
+  }
+
+  /**
+   * Reconstruct a display string from a raw (unmasked) string.
+   * Fills variable slots in order with characters from `raw`.
+   * Returns the display string and the slot index after the last filled slot.
+   */
+  reconstructFromRaw(raw: string): { display: string; caretSlot: number } {
+    const { slots, variableIndices } = this.opts.getCompiled();
+    const slotChar = this.opts.getSlotChar();
+    const filled = new Array<string | null>(slots.length).fill(null);
+    let rawIdx = 0;
+
+    for (const varIdx of variableIndices) {
+      if (rawIdx >= raw.length) break;
+      const slot = slots[varIdx] as Extract<Slot, { kind: 'variable' }>;
+      const ch = raw[rawIdx];
+      if (slot.re.test(ch)) {
+        filled[varIdx] = ch;
+        rawIdx++;
+      } else {
+        rawIdx++;
+        // Try to keep going — skip non-matching raw chars
+        // (handles masked input passed via setValue)
+      }
+    }
+
+    const display = slots
+      .map((slot, i) =>
+        slot.kind === 'literal' ? slot.char : (filled[i] ?? slotChar),
+      )
+      .join('');
+
+    // caretSlot: position just after the last filled variable, or first empty
+    let caretSlot = variableIndices[0] ?? 0;
+    for (let i = variableIndices.length - 1; i >= 0; i--) {
+      if (filled[variableIndices[i]] !== null) {
+        caretSlot = (variableIndices[i + 1] ?? variableIndices[i]) + (i + 1 < variableIndices.length ? 0 : 1);
+        break;
+      }
+    }
+
+    return { display, caretSlot };
+  }
+
+  /**
+   * Reconstruct a display from a raw string, normalising the raw by stripping
+   * chars that don't fit the variable slot sequence. Used when writing from a
+   * form control setValue() call.
+   */
+  applyRawValue(raw: string): void {
+    const { slots, variableIndices } = this.opts.getCompiled();
+    const slotChar = this.opts.getSlotChar();
+    const filled = new Array<string | null>(slots.length).fill(null);
+
+    let rawIdx = 0;
+    for (const varIdx of variableIndices) {
+      if (rawIdx >= raw.length) break;
+      const slot = slots[varIdx] as Extract<Slot, { kind: 'variable' }>;
+      // skip chars that don't match (forgiving intake)
+      while (rawIdx < raw.length && !slot.re.test(raw[rawIdx])) {
+        rawIdx++;
+      }
+      if (rawIdx < raw.length) {
+        filled[varIdx] = raw[rawIdx];
+        rawIdx++;
+      }
+    }
+
+    const display = slots
+      .map((slot, i) =>
+        slot.kind === 'literal' ? slot.char : (filled[i] ?? slotChar),
+      )
+      .join('');
+
+    this.opts.callbacks.setValue(display);
+    this._emitModelValue(filled);
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────
+
+  private _getFilledSlots(): Array<string | null> {
+    const { slots } = this.opts.getCompiled();
+    const slotChar = this.opts.getSlotChar();
+    const display = this.opts.callbacks.getValue();
+    return slots.map((slot, i) => {
+      if (slot.kind === 'literal') return null;
+      const ch = display[i];
+      return ch && ch !== slotChar ? ch : null;
+    });
+  }
+
+  private _buildDisplay(filled: Array<string | null>): string {
+    const { slots } = this.opts.getCompiled();
+    const slotChar = this.opts.getSlotChar();
+    return slots
+      .map((slot, i) =>
+        slot.kind === 'literal' ? slot.char : (filled[i] ?? slotChar),
+      )
+      .join('');
+  }
+
+  private _emitModelValue(filled: Array<string | null>): void {
+    const { slots, variableIndices } = this.opts.getCompiled();
+    const mode = this.opts.getMaskMode();
+    let value: string;
+    if (mode === 'unmasked') {
+      value = variableIndices
+        .map(i => filled[i] ?? '')
+        .join('');
+    } else {
+      const slotChar = this.opts.getSlotChar();
+      value = slots
+        .map((slot, i) =>
+          slot.kind === 'literal' ? slot.char : (filled[i] ?? slotChar),
+        )
+        .join('');
+    }
+    this.opts.callbacks.notifyChange(value);
+  }
+
+  private _insertChar(ch: string): void {
+    const { variableIndices } = this.opts.getCompiled();
+    const { slots } = this.opts.getCompiled();
+    const caret = this.opts.callbacks.getCaret();
+    const filled = this._getFilledSlots();
+
+    // Find the next variable slot at or after caret
+    const targetIdx = variableIndices.find(i => i >= caret);
+    if (targetIdx === undefined) return; // mask is full or caret past end
+
+    const slot = slots[targetIdx] as Extract<Slot, { kind: 'variable' }>;
+    if (!slot.re.test(ch)) return; // char doesn't match slot regex
+
+    filled[targetIdx] = ch;
+    const display = this._buildDisplay(filled);
+    this.opts.callbacks.setValue(display);
+    this._emitModelValue(filled);
+
+    // Advance caret to next variable slot
+    const nextVar = variableIndices.find(i => i > targetIdx);
+    const newCaret = nextVar !== undefined ? nextVar : targetIdx + 1;
+    this.opts.callbacks.setCaret(newCaret);
+
+    // Check completion
+    const allFilled = variableIndices.every(i => filled[i] !== null);
+    if (allFilled) {
+      this.opts.callbacks.setCaret(variableIndices[variableIndices.length - 1] + 1);
+    }
+  }
+
+  private _handleBackspace(): void {
+    const { variableIndices } = this.opts.getCompiled();
+    const caret = this.opts.callbacks.getCaret();
+    const filled = this._getFilledSlots();
+
+    // Find the last variable slot before caret
+    const targets = variableIndices.filter(i => i < caret);
+    const targetIdx = targets[targets.length - 1];
+    if (targetIdx === undefined) return;
+
+    filled[targetIdx] = null;
+    const display = this._buildDisplay(filled);
+    this.opts.callbacks.setValue(display);
+    this._emitModelValue(filled);
+    this.opts.callbacks.setCaret(targetIdx);
+  }
+
+  private _handleDelete(): void {
+    const { variableIndices } = this.opts.getCompiled();
+    const caret = this.opts.callbacks.getCaret();
+    const filled = this._getFilledSlots();
+
+    // Find the variable slot at or after caret
+    const targetIdx = variableIndices.find(i => i >= caret);
+    if (targetIdx === undefined) return;
+
+    filled[targetIdx] = null;
+    const display = this._buildDisplay(filled);
+    this.opts.callbacks.setValue(display);
+    this._emitModelValue(filled);
+    this.opts.callbacks.setCaret(targetIdx);
+  }
+
+  private _snapCaret(direction: 'prev' | 'next' | 'first' | 'last'): void {
+    const { variableIndices } = this.opts.getCompiled();
+    if (variableIndices.length === 0) return;
+
+    const caret = this.opts.callbacks.getCaret();
+
+    if (direction === 'first') {
+      this.opts.callbacks.setCaret(variableIndices[0]);
+      return;
+    }
+    if (direction === 'last') {
+      this.opts.callbacks.setCaret(
+        variableIndices[variableIndices.length - 1] + 1,
+      );
+      return;
+    }
+    if (direction === 'prev') {
+      const prev = [...variableIndices].reverse().find(i => i < caret);
+      if (prev !== undefined) this.opts.callbacks.setCaret(prev);
+      return;
+    }
+    if (direction === 'next') {
+      const next = variableIndices.find(i => i > caret);
+      if (next !== undefined) this.opts.callbacks.setCaret(next);
+      return;
+    }
+  }
+
+  private _pasteText(text: string): void {
+    const { variableIndices } = this.opts.getCompiled();
+    const { slots } = this.opts.getCompiled();
+    const caret = this.opts.callbacks.getCaret();
+    const filled = this._getFilledSlots();
+
+    // Determine which variable slots we start filling from
+    const startVarPos = variableIndices.findIndex(i => i >= caret);
+    if (startVarPos === -1) return;
+
+    let textIdx = 0;
+    for (let vi = startVarPos; vi < variableIndices.length && textIdx < text.length; vi++) {
+      const slotIdx = variableIndices[vi];
+      const slot = slots[slotIdx] as Extract<Slot, { kind: 'variable' }>;
+      // Skip paste chars that don't match
+      while (textIdx < text.length && !slot.re.test(text[textIdx])) {
+        textIdx++;
+      }
+      if (textIdx < text.length) {
+        filled[slotIdx] = text[textIdx];
+        textIdx++;
+      }
+    }
+
+    const display = this._buildDisplay(filled);
+    this.opts.callbacks.setValue(display);
+    this._emitModelValue(filled);
+
+    // Set caret after the last filled slot
+    let lastFilledVar = variableIndices[startVarPos];
+    for (const vi of variableIndices) {
+      if (filled[vi] !== null) lastFilledVar = vi;
+    }
+    const nextVar = variableIndices.find(i => i > lastFilledVar);
+    this.opts.callbacks.setCaret(nextVar !== undefined ? nextVar : lastFilledVar + 1);
+  }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Predefined mask templates for common use cases.
+ *
+ * These are convenience string constants — not DI tokens, not hardcoded
+ * into the directive. Use them as `[kjMask]="presets.phoneUS"` or spread
+ * and extend per your app's locale needs.
+ *
+ * @example
+ * ```ts
+ * import { KJ_INPUT_MASK_PRESETS } from '@kouji-ui/core';
+ *
+ * @Component({ template: `<input kjInputMask [kjMask]="presets.phoneUS" />` })
+ * export class MyForm {
+ *   readonly presets = KJ_INPUT_MASK_PRESETS;
+ * }
+ * ```
+ */
+export const KJ_INPUT_MASK_PRESETS = {
+  phoneUS: '(999) 999-9999',
+  cardNumber: '9999 9999 9999 9999',
+  cardExpiry: '99/99',
+  isoDate: '9999-99-99',
+  usDate: '99/99/9999',
+} as const;

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

@@ -0,0 +1,304 @@
+import { Component } from '@angular/core';
+import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
+import { render } from '@testing-library/angular';
+import { describe, expect, it } from 'vitest';
+
+import { compileMask } from './input-mask.compile';
+import { MaskEngine } from './input-mask.engine';
+import { KjInputMask } from './input-mask';
+
+// ── compileMask ────────────────────────────────────────────────────────────────
+
+describe('compileMask', () => {
+  const tokens = { '9': /[0-9]/, 'a': /[A-Za-z]/, '*': /[A-Za-z0-9]/ };
+
+  it('splits a phone mask into literal and variable slots', () => {
+    const result = compileMask('(999) 999-9999', tokens);
+    expect(result.variableCount).toBe(10);
+    expect(result.literalCount).toBe(4);
+    expect(result.slots[0]).toEqual({ kind: 'literal', char: '(' });
+    expect(result.slots[1]).toMatchObject({ kind: 'variable', tokenId: '9' });
+  });
+
+  it('treats unknown token chars as literals', () => {
+    const result = compileMask('X99', tokens);
+    // X not in tokens → literal
+    expect(result.slots[0]).toEqual({ kind: 'literal', char: 'X' });
+    expect(result.slots[1]).toMatchObject({ kind: 'variable' });
+    expect(result.slots[2]).toMatchObject({ kind: 'variable' });
+    expect(result.variableCount).toBe(2);
+  });
+
+  it('handles escape syntax: \\9 → literal 9', () => {
+    const result = compileMask('\\99', tokens);
+    expect(result.slots[0]).toEqual({ kind: 'literal', char: '9' });
+    expect(result.slots[1]).toMatchObject({ kind: 'variable', tokenId: '9' });
+    expect(result.variableCount).toBe(1);
+  });
+
+  it('handles all-literal mask', () => {
+    const result = compileMask('---', tokens);
+    expect(result.variableCount).toBe(0);
+    expect(result.literalCount).toBe(3);
+  });
+
+  it('builds variableIndices correctly', () => {
+    // '9-9' → slot 0: variable, slot 1: literal, slot 2: variable
+    const result = compileMask('9-9', tokens);
+    expect(result.variableIndices).toEqual([0, 2]);
+  });
+
+  it('handles repeated escape sequences', () => {
+    const result = compileMask('\\9\\9', tokens);
+    expect(result.variableCount).toBe(0);
+    expect(result.slots).toEqual([
+      { kind: 'literal', char: '9' },
+      { kind: 'literal', char: '9' },
+    ]);
+  });
+
+  it('handles custom tokens', () => {
+    const customTokens = { H: /[0-9A-Fa-f]/ };
+    const result = compileMask('#HHHHHH', customTokens);
+    expect(result.slots[0]).toEqual({ kind: 'literal', char: '#' });
+    expect(result.variableCount).toBe(6);
+    const slot = result.slots[1] as Extract<(typeof result.slots)[0], { kind: 'variable' }>;
+    expect(slot.re.test('A')).toBe(true);
+    expect(slot.re.test('G')).toBe(false);
+  });
+});
+
+// ── MaskEngine ─────────────────────────────────────────────────────────────────
+
+describe('MaskEngine.reconstructFromRaw', () => {
+  const tokens = { '9': /[0-9]/, 'a': /[A-Za-z]/, '*': /[A-Za-z0-9]/ };
+
+  function makeEngine(mask: string, options?: { mode?: 'unmasked' | 'masked'; slotChar?: string }) {
+    let _value = '';
+    let _caret = 0;
+    let _emitted = '';
+
+    const compiled = compileMask(mask, tokens);
+    const engine = new MaskEngine({
+      getCompiled: () => compiled,
+      getSlotChar: () => options?.slotChar ?? '_',
+      getMaskMode: () => options?.mode ?? 'unmasked',
+      callbacks: {
+        getValue: () => _value,
+        setValue: (v) => { _value = v; },
+        getCaret: () => _caret,
+        setCaret: (p) => { _caret = p; },
+        notifyChange: (v) => { _emitted = v; },
+      },
+    });
+
+    return { engine, getValue: () => _value, getCaret: () => _caret, getEmitted: () => _emitted };
+  }
+
+  it('reconstructs phone from raw digits', () => {
+    const { engine, getValue } = makeEngine('(999) 999-9999');
+    engine.applyRawValue('4155551234');
+    expect(getValue()).toBe('(415) 555-1234');
+  });
+
+  it('reconstructs partial raw value', () => {
+    const { engine, getValue } = makeEngine('(999) 999-9999');
+    engine.applyRawValue('415');
+    expect(getValue()).toBe('(415) ___-____');
+  });
+
+  it('emits unmasked value by default', () => {
+    const { engine, getEmitted } = makeEngine('(999) 999-9999');
+    engine.applyRawValue('4155551234');
+    expect(getEmitted()).toBe('4155551234');
+  });
+
+  it('emits masked value when mode is masked', () => {
+    const { engine, getEmitted } = makeEngine('(999) 999-9999', { mode: 'masked' });
+    engine.applyRawValue('4155551234');
+    expect(getEmitted()).toBe('(415) 555-1234');
+  });
+
+  it('strips non-matching chars from raw (forgiving intake)', () => {
+    const { engine, getValue } = makeEngine('(999) 999-9999');
+    engine.applyRawValue('(415) 555-1234');
+    expect(getValue()).toBe('(415) 555-1234');
+  });
+});
+
+describe('MaskEngine keyboard interactions', () => {
+  const tokens = { '9': /[0-9]/, 'a': /[A-Za-z]/, '*': /[A-Za-z0-9]/ };
+
+  function makeEngine(mask: string) {
+    let _value = '(___) ___-____';
+    let _caret = 1; // starts after '('
+    let _emitted = '';
+
+    const compiled = compileMask(mask, tokens);
+    // Initialise display
+    const slotChar = '_';
+    _value = compiled.slots
+      .map(s => s.kind === 'literal' ? s.char : slotChar)
+      .join('');
+
+    const engine = new MaskEngine({
+      getCompiled: () => compiled,
+      getSlotChar: () => slotChar,
+      getMaskMode: () => 'unmasked',
+      callbacks: {
+        getValue: () => _value,
+        setValue: (v) => { _value = v; },
+        getCaret: () => _caret,
+        setCaret: (p) => { _caret = p; },
+        notifyChange: (v) => { _emitted = v; },
+      },
+    });
+
+    const key = (k: string) => {
+      engine.onKeydown(new KeyboardEvent('keydown', { key: k }));
+    };
+
+    return { engine, getValue: () => _value, getCaret: () => _caret, getEmitted: () => _emitted, key, setCaret: (p: number) => { _caret = p; } };
+  }
+
+  it('types a digit into the first variable slot', () => {
+    const { key, getValue, getEmitted } = makeEngine('(999) 999-9999');
+    // caret = 1 (first variable slot after '(')
+    key('4');
+    expect(getValue()[1]).toBe('4');
+    expect(getEmitted()).toBe('4');
+  });
+
+  it('rejects a non-matching character', () => {
+    const { key, getValue } = makeEngine('(999) 999-9999');
+    key('A'); // not a digit
+    expect(getValue()[1]).toBe('_');
+  });
+
+  it('backspace clears the previous variable slot', () => {
+    const s = makeEngine('(999) 999-9999');
+    s.key('4');
+    s.setCaret(2); // move to after slot 1
+    s.key('Backspace');
+    expect(s.getValue()[1]).toBe('_');
+  });
+});
+
+describe('MaskEngine paste', () => {
+  const tokens = { '9': /[0-9]/ };
+
+  function makeEngine(mask: string) {
+    let _value = '';
+    let _caret = 0;
+
+    const compiled = compileMask(mask, tokens);
+    _value = compiled.slots
+      .map(s => s.kind === 'literal' ? s.char : '_')
+      .join('');
+
+    const engine = new MaskEngine({
+      getCompiled: () => compiled,
+      getSlotChar: () => '_',
+      getMaskMode: () => 'unmasked',
+      callbacks: {
+        getValue: () => _value,
+        setValue: (v) => { _value = v; },
+        getCaret: () => _caret,
+        setCaret: (p) => { _caret = p; },
+        notifyChange: () => {},
+      },
+    });
+
+    return { engine, getValue: () => _value };
+  }
+
+  it('pastes digits filling the mask', () => {
+    const { engine, getValue } = makeEngine('9999');
+    const event = {
+      preventDefault: () => {},
+      clipboardData: { getData: () => '1234' },
+    } as unknown as ClipboardEvent;
+    engine.onPaste(event);
+    expect(getValue()).toBe('1234');
+  });
+
+  it('strips non-digit characters from paste', () => {
+    const { engine, getValue } = makeEngine('9999');
+    const event = {
+      preventDefault: () => {},
+      clipboardData: { getData: () => '12-34' },
+    } as unknown as ClipboardEvent;
+    engine.onPaste(event);
+    expect(getValue()).toBe('1234');
+  });
+});
+
+// ── KjInputMask directive ─────────────────────────────────────────────────────
+
+describe('KjInputMask directive', () => {
+  it('renders with type="text"', async () => {
+    const { container } = await render(
+      `<input kjInputMask kjMask="(999) 999-9999" />`,
+      { imports: [KjInputMask] },
+    );
+    expect(container.querySelector('input')!.getAttribute('type')).toBe('text');
+  });
+
+  it('sets inputmode=numeric for all-digit mask', async () => {
+    const { container } = await render(
+      `<input kjInputMask kjMask="9999" />`,
+      { imports: [KjInputMask] },
+    );
+    expect(container.querySelector('input')!.getAttribute('inputmode')).toBe('numeric');
+  });
+
+  it('sets inputmode=text for mixed mask', async () => {
+    const { container } = await render(
+      `<input kjInputMask kjMask="aaa-999" />`,
+      { imports: [KjInputMask] },
+    );
+    expect(container.querySelector('input')!.getAttribute('inputmode')).toBe('text');
+  });
+
+  it('sets placeholder from mask with slot chars', async () => {
+    const { container } = await render(
+      `<input kjInputMask kjMask="(999) 999-9999" />`,
+      { imports: [KjInputMask] },
+    );
+    expect(container.querySelector('input')!.getAttribute('placeholder')).toBe(
+      '(___) ___-____',
+    );
+  });
+
+  it('emits mask validation error when partially filled', async () => {
+    const ctrl = new FormControl('415');
+    @Component({
+      standalone: true,
+      imports: [KjInputMask, ReactiveFormsModule],
+      template: `<input kjInputMask kjMask="(999) 999-9999" [formControl]="ctrl" />`,
+    })
+    class Host {
+      ctrl = ctrl;
+    }
+    await render(Host);
+    // The mask validator should detect partial fill
+    // raw='415' = 3 chars out of 10 required
+    expect(ctrl.errors?.['mask']).toBeDefined();
+    expect(ctrl.errors?.['mask'].required).toBe(10);
+  });
+
+  it('returns null validator error when empty (required handles it)', async () => {
+    const ctrl = new FormControl('', [Validators.required]);
+    @Component({
+      standalone: true,
+      imports: [KjInputMask, ReactiveFormsModule],
+      template: `<input kjInputMask kjMask="(999) 999-9999" [formControl]="ctrl" />`,
+    })
+    class Host {
+      ctrl = ctrl;
+    }
+    await render(Host);
+    expect(ctrl.errors?.['mask']).toBeUndefined();
+    expect(ctrl.errors?.['required']).toBeDefined();
+  });
+});