digitojs 1.0.0

package/dist/adapters/web-component.d.ts

@@ -0,0 +1,192 @@
+/**
+ * digito/web-component
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Framework-agnostic Web Component — <digito-input>
+ * Uses single hidden-input architecture for correct SMS autofill + a11y.
+ *
+ * Attributes:
+ *   length           Number of slots (default: 6)
+ *   type             Character set: numeric | alphabet | alphanumeric | any (default: numeric)
+ *   timer            Countdown seconds (default: 0 = no timer)
+ *   resend-after     Cooldown seconds before the built-in Resend re-enables (default: 30)
+ *   disabled         Boolean attribute — disables all input when present
+ *   separator-after  Slot index (1-based) or comma-separated list, e.g. "3" or "2,4" (default: none)
+ *   separator        Separator character to render (default: —)
+ *   name             Sets the hidden input's name attr for native form submission
+ *   placeholder      Character shown in empty slots (e.g. "○" or "_")
+ *   auto-focus       Boolean attribute — focus input on mount (default: true when absent)
+ *   select-on-focus  Boolean attribute — selects the current slot char on focus
+ *   blur-on-complete Boolean attribute — blurs the input when all slots are filled
+ *
+ * Events:
+ *   complete         CustomEvent<{ code: string }> — fired when all slots filled
+ *   expire           CustomEvent — fired when timer reaches zero
+ *   change           CustomEvent<{ code: string }> — fired on every input change
+ *
+ * DOM API:
+ *   el.reset()
+ *   el.setError(boolean)
+ *   el.setSuccess(boolean)
+ *   el.setDisabled(boolean)
+ *   el.getCode() -> string
+ *   el.pattern = /^[0-9A-F]$/     (JS property, not attribute)
+ *   el.pasteTransformer = fn       (JS property)
+ *   el.onComplete = code => {}     (JS property)
+ *   el.onResend   = () => {}       (JS property)
+ *   el.onFocus    = () => {}       (JS property)
+ *   el.onBlur     = () => {}       (JS property)
+ *   el.onInvalidChar = (char, i) => {} (JS property)
+ *
+ * @author  Olawale Balo — Product Designer + Design Engineer
+ * @license MIT
+ */
+declare class DigitoInput extends HTMLElement {
+    /**
+     * HTML attribute names whose changes trigger `attributeChangedCallback`.
+     * Any change to these attributes causes a full shadow DOM rebuild so the
+     * component always reflects its attribute state without manual reconciliation.
+     */
+    static observedAttributes: string[];
+    private slotEls;
+    private caretEls;
+    private hiddenInput;
+    private timerEl;
+    private timerBadgeEl;
+    private resendEl;
+    private timerCtrl;
+    private resendCountdown;
+    private digito;
+    private shadow;
+    private _isDisabled;
+    private _isSuccess;
+    private _pattern;
+    private _pasteTransformer;
+    private _onComplete;
+    private _onResend;
+    private _onFocus;
+    private _onBlur;
+    private _onInvalidChar;
+    /** Called when all slots are filled. Also dispatches the `complete` CustomEvent. */
+    set onComplete(fn: ((code: string) => void) | undefined);
+    /** Called when the built-in Resend button is clicked. */
+    set onResend(fn: (() => void) | undefined);
+    /** Fires when the hidden input receives focus. Set as JS property. */
+    set onFocus(fn: (() => void) | undefined);
+    /** Fires when the hidden input loses focus. Set as JS property. */
+    set onBlur(fn: (() => void) | undefined);
+    /**
+     * Fires when a typed character is rejected by type/pattern validation.
+     * Receives the character and the slot index it was attempted on.
+     * Set as JS property.
+     */
+    set onInvalidChar(fn: ((char: string, index: number) => void) | undefined);
+    /**
+     * Arbitrary per-character regex. When set, each typed/pasted character must
+     * match to be accepted. Takes precedence over the type attribute for
+     * character validation. Cannot be expressed as an HTML attribute — set as a
+     * JS property instead.
+     * @example el.pattern = /^[0-9A-F]$/
+     */
+    set pattern(re: RegExp | undefined);
+    /**
+     * Optional paste transformer function. Applied to raw clipboard text before
+     * filtering. Use to strip formatting (e.g. `"G-123456"` → `"123456"`).
+     * Cannot be expressed as an HTML attribute — set as a JS property.
+     * @example el.pasteTransformer = (raw) => raw.replace(/\s+|-/g, '')
+     */
+    set pasteTransformer(fn: ((raw: string) => string) | undefined);
+    constructor();
+    /** Called when the element is inserted into the DOM. Triggers the initial build. */
+    connectedCallback(): void;
+    /**
+     * Called when the element is removed from the DOM.
+     * Stops both timers and cancels any pending `onComplete` timeout to avoid
+     * callbacks firing after the element is detached.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Called when any observed attribute changes after the initial connection.
+     * Guards on `shadow.children.length > 0` so it does not fire before
+     * `connectedCallback` has completed the first build.
+     */
+    attributeChangedCallback(): void;
+    private get _length();
+    private get _type();
+    private get _timer();
+    private get _resendAfter();
+    private get _disabledAttr();
+    /** Parses `separator-after="2,4"` into `[2, 4]`. Filters NaN and zero values. */
+    private get _separatorAfter();
+    private get _separator();
+    /** `masked` is a boolean attribute — present means true, absent means false. */
+    private get _masked();
+    private get _maskChar();
+    private get _name();
+    private get _placeholder();
+    /**
+     * `auto-focus` defaults to `true` when the attribute is absent.
+     * Setting `auto-focus="false"` explicitly suppresses focus on mount.
+     */
+    private get _autoFocus();
+    private get _selectOnFocus();
+    private get _blurOnComplete();
+    /**
+     * Constructs the entire shadow DOM from scratch.
+     *
+     * Called on first connect, on every observed attribute change, and when
+     * certain JS-property setters (`pattern`, `pasteTransformer`, `onInvalidChar`)
+     * are assigned after mount. Tears down any running timer and resets the
+     * state machine before rebuilding to prevent duplicate intervals or stale
+     * closure references from the previous build.
+     */
+    private build;
+    /**
+     * Reconcile the shadow slot divs with the current core state using CSS class
+     * toggles. Called after every user action (input, keydown, paste, focus, click).
+     *
+     * Uses `this.shadow.activeElement` instead of `document.activeElement` to
+     * correctly detect focus within the shadow root across all browsers — the
+     * document active element is the host `<digito-input>` element, not the
+     * internal hidden input.
+     */
+    private syncSlotsToDOM;
+    /**
+     * Apply or remove the disabled state directly on existing DOM nodes without
+     * triggering a full rebuild. Used by both `build()` (initial disabled attr)
+     * and `setDisabled()` (runtime toggle).
+     */
+    private applyDisabledDOM;
+    /**
+     * Wire all event listeners to the hidden input element.
+     * Called once at the end of each `build()`. Because `build()` creates a fresh
+     * `hiddenInput` element, there is no need to `removeEventListener` — the old
+     * element is discarded and its listeners are garbage-collected with it.
+     *
+     * @param selectOnFocus  When `true`, focusing a filled slot selects its character.
+     * @param blurOnComplete When `true`, blurs the input after the last slot is filled.
+     */
+    private attachEvents;
+    /**
+     * Dispatch a `change` CustomEvent carrying the current code string.
+     * Fired after every input, paste, and backspace action.
+     * `composed: true` lets the event cross the shadow root boundary so host-page
+     * listeners registered with `el.addEventListener('change', ...)` receive it.
+     */
+    private dispatchChange;
+    /** Clear all slots, reset the timer display, and re-focus the hidden input. */
+    reset(): void;
+    /** Apply or clear the error state on all visual slots. */
+    setError(isError: boolean): void;
+    /** Apply or clear the success state on all visual slots. Stops the timer on success. */
+    setSuccess(isSuccess: boolean): void;
+    /**
+     * Enable or disable the input at runtime.
+     * Equivalent to toggling the `disabled` HTML attribute but without triggering
+     * a full rebuild. Re-enabling automatically restores focus to the active slot.
+     */
+    setDisabled(value: boolean): void;
+    /** Returns the current code as a joined string (e.g. `"123456"`). */
+    getCode(): string;
+}
+export { DigitoInput };
+//# sourceMappingURL=web-component.d.ts.map

package/dist/adapters/web-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-component.d.ts","sourceRoot":"","sources":["../../src/adapters/web-component.ts"],"names":[],"mappings":"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"}