@adia-ai/web-components 0.4.5 → 0.4.7

package/components/input/input.js

@@ -1,764 +1,17 @@
 /**
- * <input-ui> — Text input. The host IS the interactive surface.
- * Uses contenteditable for text entry, ElementInternals for form participation.
+ * `<input-ui>` — auto-registers the tag on import.
  *
- * Slots inside [slot="field"]:
- *   prefix → label → text → suffix → controls (number mode)
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- *   <input-ui label="Email" placeholder="you@acme.com"></input-ui>
- *   <input-ui label="Email" prefix="user" placeholder="you@acme.com"></input-ui>
- *   <input-ui placeholder="Search" prefix="magnifying-glass"></input-ui>
- *   <input-ui prefix="@" value="kim"></input-ui>
+ *   import { UIInput } from '@adia-ai/web-components/components/input/class';
  *
- *   <input-ui type="number" value="42" min="0" max="100" step="1"></input-ui>
- *   <input-ui type="number" value="9.99" step="0.01" precision="2" prefix="$"></input-ui>
- *
- * type="number" renders a contenteditable surface + [+]/[-] stepper buttons,
- * filters input to digits / minus / decimal, snaps to step, clamps to min/max,
- * and exposes ARIA spinbutton semantics. No native <input type=number>.
- *
- * type="password" still wraps a native <input> — only path that needs
- * `-webkit-text-security` disc masking, which only works on native inputs.
- *
- * label renders as a dim leading caption inside the chrome (next to the
- * value, sharing the input's border) — for stacked label / hint / error
- * compositions, wrap with field-ui.
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIFormElement } from '../../core/form.js';
-import { isIconName, whenIconRegistryReady } from '../../core/icons.js';
-
-const renderAffix = (v) => isIconName(v)
-  ? `<icon-ui name="${v}"></icon-ui>`
-  : v;
-
-class UIInput extends UIFormElement {
-  // Opt out of UIFormElement's per-control `label` deprecation warning.
-  // input-ui's `label` is a first-class API rendering an inline-leading
-  // caption inside the chrome with `aria-labelledby` wiring on the
-  // editable surface — not the inert above-the-field rendering that
-  // motivated the deprecation.
-  static labelDeprecated = false;
-
-  static properties = {
-    ...UIFormElement.properties,
-    placeholder: { type: String,  default: '', reflect: true },
-    type:        { type: String,  default: 'text', reflect: true },
-    label:       { type: String,  default: '', reflect: true },
-    prefix:      { type: String,  default: '', reflect: true },
-    suffix:      { type: String,  default: '', reflect: true },
-    raw:         { type: Boolean, default: false, reflect: true },
-    // ── Number mode ──
-    min:         { type: Number,  default: null, reflect: true },
-    max:         { type: Number,  default: null, reflect: true },
-    step:        { type: Number,  default: 1,    reflect: true },
-    precision:   { type: Number,  default: null, reflect: true },
-    // BCP-47 locale tag, e.g. "de-DE" / "fr-FR" / "en-IN". Default empty =
-    // en-US (`.` decimal separator, no thousands grouping). When set, the
-    // input accepts both `.` AND the locale's decimal separator (so en-US-
-    // formatted programmatic values still parse), and `#format` uses
-    // `Intl.NumberFormat` for display. Internal storage stays in JS-Number
-    // canonical form so `.value` round-trips through `Number(v)` unchanged.
-    locale:      { type: String,  default: '',   reflect: true },
-  };
-
-  static template = () => null;
-
-  #textEl = null;
-  #labelEl = null;
-  #upBtn = null;
-  #downBtn = null;
-  #valueAtFocus = '';
-  #repeatTimer = null;
-  #repeatDelayTimer = null;
-  #cachedSep = '.';
-  #cachedGroup = '';
-  #cachedSepFor = null;
-  static #labelSeq = 0;
-
-  // Hold-to-repeat tuning. Initial delay before autorepeat begins, and the
-  // interval between repeats. Values match the cadence of the native
-  // <input type="number"> spinner behavior in Chromium/Safari.
-  static #REPEAT_INITIAL_MS = 400;
-  static #REPEAT_INTERVAL_MS = 60;
-
-  get #isNativePassword() { return this.type === 'password'; }
-  get #isNumberMode()     { return this.type === 'number'; }
-
-  /** Parsed numeric value. NaN when empty or unparseable. When `locale` is
-   *  set, the value may carry the locale's decimal separator (e.g. "1,5" in
-   *  de-DE); we canonicalize to JS form before `Number(…)`. */
-  get valueAsNumber() {
-    const raw = String(this.value ?? '').trim();
-    if (!raw) return NaN;
-    const s = this.#toCanonical(raw);
-    if (s === '-' || s === '.' || s === '-.') return NaN;
-    const n = Number(s);
-    return Number.isFinite(n) ? n : NaN;
-  }
-  set valueAsNumber(n) {
-    if (!Number.isFinite(n)) { this.value = ''; return; }
-    this.value = this.#format(n);
-  }
-
-  connected() {
-    super.connected();
-    this.setAttribute('role', this.#isNumberMode ? 'spinbutton' : 'textbox');
-
-    if (!this.querySelector('[slot="text"]')) {
-      const labelId = this.label ? `input-label-${++UIInput.#labelSeq}` : '';
-      this.innerHTML = this.#shellHTML(labelId);
-    }
-
-    this.#textEl  = this.querySelector('[slot="text"]');
-    this.#labelEl = this.querySelector('[slot="label"]');
-    this.#upBtn   = this.querySelector('[data-step="up"]');
-    this.#downBtn = this.querySelector('[data-step="down"]');
-
-    if (!this.#isNativePassword && this.value) {
-      this.#textEl.textContent = this.#isNumberMode
-        ? this.#formatStored(this.value)
-        : this.value;
-    }
-
-    if (this.#textEl) {
-      this.#textEl.addEventListener('input',    this.#onInput);
-      this.#textEl.addEventListener('keydown',  this.#onKeydown);
-      this.#textEl.addEventListener('blur',     this.#onBlur);
-      this.#textEl.addEventListener('focus',    this.#onFocus);
-      this.#textEl.addEventListener('paste',    this.#onPaste);
-      if (this.#isNumberMode) {
-        this.#textEl.addEventListener('beforeinput', this.#onBeforeInput);
-      }
-    }
-
-    // pointerdown.preventDefault keeps focus on the contenteditable surface
-    // when the user pokes a stepper button with a pointing device. Same
-    // handler fires the initial step + arms hold-to-repeat; pointerup/leave/
-    // cancel on document stops it (the user can drag off the button to
-    // abort the repeat without lifting their finger first).
-    this.#upBtn?.addEventListener('pointerdown', this.#onStepperUpDown);
-    this.#downBtn?.addEventListener('pointerdown', this.#onStepperDownDown);
-    // Stop autorepeat on any pointer release, anywhere — captures the
-    // "drag-off-then-lift" abort path without per-button leave/cancel
-    // bookkeeping. Cheap; runs only while a stepper is held.
-
-    // In non-Vite static deploys, the icon registry loads asynchronously
-    // after the manifest fetch resolves. If our prefix/suffix were checked
-    // by isIconName() during that window, kebab-case icon names like
-    // "magnifying-glass" got baked into the DOM as literal text. Re-evaluate
-    // once the registry is ready and promote text-rendered affixes to
-    // <icon-ui>. (No-op on Vite dev where the promise resolves synchronously.)
-    if (this.prefix || this.suffix) {
-      whenIconRegistryReady.then(() => this.#promoteAffixes());
-    }
-  }
-
-  #shellHTML(labelId) {
-    const prefix  = this.prefix ? `<span slot="prefix">${renderAffix(this.prefix)}</span>` : '';
-    const label   = this.label  ? `<span slot="label" id="${labelId}">${this.label}</span>` : '';
-    const suffix  = this.suffix ? `<span slot="suffix">${renderAffix(this.suffix)}</span>` : '';
-    const labelby = labelId ? `aria-labelledby="${labelId}"` : '';
-
-    if (this.#isNativePassword) {
-      return `
-        <div slot="field">
-          ${prefix}${label}
-          <input slot="text" type="password" tabindex="0"
-                 placeholder="${this.placeholder}" value="${this.value || ''}"
-                 autocomplete="current-password" ${labelby}
-                 ${this.disabled ? 'disabled' : ''} ${this.readonly ? 'readonly' : ''} />
-          ${suffix}
-        </div>
-      `;
-    }
-
-    const editable = `
-      <span slot="text" contenteditable="plaintext-only" tabindex="0"
-            ${this.value ? '' : 'data-empty=""'}
-            ${labelby}
-            data-placeholder="${this.placeholder}"
-            ${this.#isNumberMode ? 'inputmode="decimal"' : ''}></span>`;
-
-    const controls = this.#isNumberMode ? `
-      <span slot="controls" data-controls aria-hidden="true">
-        <button-ui type="button" tabindex="-1" variant="ghost" size="xs"
-                   icon="caret-up" data-step="up" aria-label="Increase"></button-ui>
-        <button-ui type="button" tabindex="-1" variant="ghost" size="xs"
-                   icon="caret-down" data-step="down" aria-label="Decrease"></button-ui>
-      </span>` : '';
-
-    return `
-      <div slot="field"${this.#isNumberMode ? ' data-number' : ''}>
-        ${prefix}${label}${editable}${suffix}${controls}
-      </div>
-    `;
-  }
-
-  #promoteAffixes() {
-    if (!this.isConnected) return;
-    for (const which of ['prefix', 'suffix']) {
-      const value = this[which];
-      if (!value) continue;
-      const slot = this.querySelector(`:scope [slot="${which}"]`);
-      if (!slot) continue;
-      // Already an <icon-ui> — nothing to do.
-      if (slot.querySelector(':scope > icon-ui')) continue;
-      // Was rendered as text and the value is now a known icon — replace.
-      if (isIconName(value)) {
-        slot.replaceChildren();
-        const icon = document.createElement('icon-ui');
-        icon.setAttribute('name', value);
-        slot.appendChild(icon);
-      }
-    }
-  }
-
-  render() {
-    if (!this.#textEl) return;
-
-    const text = this.value ?? '';
-
-    if (this.#isNativePassword) {
-      this.#textEl.placeholder = this.placeholder;
-      this.#textEl.disabled = this.disabled;
-      this.#textEl.readOnly = this.readonly;
-      if (this.#textEl.value !== text) this.#textEl.value = text;
-    } else {
-      this.#textEl.setAttribute('data-placeholder', this.placeholder);
-      if (this.disabled || this.readonly) {
-        this.#textEl.contentEditable = 'false';
-      } else {
-        this.#textEl.contentEditable = 'plaintext-only';
-      }
-      // Sync programmatic value writes into the contenteditable surface.
-      // Skip when already in sync to avoid clobbering an in-flight edit's
-      // caret position. For number mode, render the formatted display, but
-      // only when the surface DOESN'T have focus (mid-edit reformat would
-      // wipe caret + lose the user's transient state like "9." → "9").
-      const display = this.#isNumberMode && document.activeElement !== this.#textEl
-        ? this.#formatStored(text)
-        : String(text);
-      if (this.#textEl.textContent !== display) {
-        this.#textEl.textContent = display;
-        this.#textEl.toggleAttribute('data-empty', !display);
-      }
-    }
-
-    if (this.#labelEl) this.#labelEl.textContent = this.label || '';
-
-    if (this.label) {
-      this.removeAttribute('aria-label');
-    } else if (this.placeholder) {
-      this.setAttribute('aria-label', this.placeholder);
-    } else {
-      this.removeAttribute('aria-label');
-    }
-
-    if (this.#isNumberMode) {
-      const n = this.valueAsNumber;
-      if (Number.isFinite(n)) {
-        this.setAttribute('aria-valuenow', String(n));
-        this.setAttribute('aria-valuetext', `${this.#format(n)}${this.suffix ? ' ' + this.suffix : ''}`);
-      } else {
-        this.removeAttribute('aria-valuenow');
-        this.removeAttribute('aria-valuetext');
-      }
-      if (this.min != null) this.setAttribute('aria-valuemin', String(this.min));
-      else this.removeAttribute('aria-valuemin');
-      if (this.max != null) this.setAttribute('aria-valuemax', String(this.max));
-      else this.removeAttribute('aria-valuemax');
-
-      const disableUp   = this.disabled || this.readonly || (this.max != null && Number.isFinite(n) && n >= this.max);
-      const disableDown = this.disabled || this.readonly || (this.min != null && Number.isFinite(n) && n <= this.min);
-      this.#upBtn?.toggleAttribute('disabled', !!disableUp);
-      this.#downBtn?.toggleAttribute('disabled', !!disableDown);
-    }
-  }
-
-  // ── Value sync + validation override ──
-
-  syncValue(val) {
-    val = val ?? this.value ?? '';
-    super.syncValue(String(val));
-    if (this.#isNumberMode) this.#runNumberConstraints(String(val));
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIInput } from './class.js';
 
-  validate() {
-    const baseValid = super.validate();
-    if (!this.#isNumberMode) return baseValid;
-    // super.validate cleared validity if all base constraints passed; layer
-    // number-specific checks on top.
-    if (!baseValid) return false;
-    const numValid = this.#runNumberConstraints(this.value ?? '');
-    if (!numValid) {
-      this.setAttribute('aria-invalid', 'true');
-      this.error = this.validationMessage;
-    }
-    return numValid;
-  }
-
-  #runNumberConstraints(val) {
-    const raw = String(val ?? '').trim();
-    // Empty is handled by `required` in the base class; nothing to check here.
-    if (!raw) return true;
-    // Canonicalize for `Number(…)` parse — when `locale` is set the raw
-    // value may carry the locale's decimal separator.
-    const s = this.#toCanonical(raw);
-    const n = Number(s);
-    if (!Number.isFinite(n)) {
-      this.internals.setValidity(
-        { badInput: true },
-        this.getAttribute('data-msg-bad-input') || 'Please enter a valid number.',
-        this,
-      );
-      return false;
-    }
-    if (this.min != null && n < this.min) {
-      this.internals.setValidity(
-        { rangeUnderflow: true },
-        this.getAttribute('data-msg-min') || `Value must be ${this.min} or greater.`,
-        this,
-      );
-      return false;
-    }
-    if (this.max != null && n > this.max) {
-      this.internals.setValidity(
-        { rangeOverflow: true },
-        this.getAttribute('data-msg-max') || `Value must be ${this.max} or less.`,
-        this,
-      );
-      return false;
-    }
-    return true;
-  }
-
-  // ── Number helpers ──
-
-  #decimals() {
-    if (this.precision != null) return Math.max(0, this.precision | 0);
-    const stepStr = String(this.step ?? 1);
-    return (stepStr.split('.')[1] || '').length;
-  }
-
-  /** Locale's decimal separator, or '.' for the default en-US-equivalent path.
-   *  Result cached per-locale on the host so `Intl.NumberFormat.formatToParts`
-   *  isn't called per keystroke. */
-  #decimalSep() {
-    if (!this.locale) return '.';
-    if (this.#cachedSepFor === this.locale) return this.#cachedSep;
-    this.#refreshSepCache();
-    return this.#cachedSep;
-  }
-
-  /** Locale's thousands/grouping separator (e.g. `,` in en-US, `.` in de-DE).
-   *  Returns '' for the default path (no locale → no grouping). Cached
-   *  alongside the decimal separator. */
-  #groupSep() {
-    if (!this.locale) return '';
-    if (this.#cachedSepFor === this.locale) return this.#cachedGroup;
-    this.#refreshSepCache();
-    return this.#cachedGroup;
-  }
-
-  #refreshSepCache() {
-    try {
-      const parts = new Intl.NumberFormat(this.locale).formatToParts(1234567.89);
-      this.#cachedSep   = parts.find((p) => p.type === 'decimal')?.value || '.';
-      this.#cachedGroup = parts.find((p) => p.type === 'group')?.value   || '';
-    } catch {
-      this.#cachedSep   = '.';
-      this.#cachedGroup = '';
-    }
-    this.#cachedSepFor = this.locale;
-  }
-
-  /** Convert a locale-formatted numeric string to the JS-canonical form
-   *  (decimal `.`, no thousands grouping). Strips group separators first so
-   *  "1.234,5" (de-DE) → "1234.5", "1,234.5" (en-US) → "1234.5". Pure string
-   *  transform; no validation. */
-  #toCanonical(s) {
-    const sep = this.#decimalSep();
-    const group = this.#groupSep();
-    let out = String(s);
-    if (group) out = out.split(group).join('');
-    if (sep !== '.') out = out.replace(new RegExp(`\\${sep}`, 'g'), '.');
-    return out;
-  }
-
-  /** Internal/edit-mode format: locale decimal separator, NO thousands
-   *  grouping. Used for `this.value` storage and for the textContent
-   *  rendering while the input is focused (so the user can edit without
-   *  the group separator jumping around as they type). */
-  #format(n) {
-    if (!Number.isFinite(n)) return '';
-    const d = this.#decimals();
-    if (this.locale) {
-      try {
-        return new Intl.NumberFormat(this.locale, {
-          minimumFractionDigits: d,
-          maximumFractionDigits: d,
-          useGrouping: false,
-        }).format(n);
-      } catch { /* fall through to JS toFixed */ }
-    }
-    return d > 0 ? n.toFixed(d) : String(Math.round(n));
-  }
-
-  /** Display-mode format: locale decimal separator + thousands grouping when
-   *  the locale supports it. Used for the textContent rendering when the
-   *  input is NOT focused (initial render + post-blur). Returns the same as
-   *  `#format` when no `locale` is set. */
-  #formatDisplay(n) {
-    if (!Number.isFinite(n)) return '';
-    if (!this.locale) return this.#format(n);
-    const d = this.#decimals();
-    try {
-      return new Intl.NumberFormat(this.locale, {
-        minimumFractionDigits: d,
-        maximumFractionDigits: d,
-        useGrouping: true,
-      }).format(n);
-    } catch { return this.#format(n); }
-  }
-
-  /** Display value derived from the stored string. During focus we leave
-   *  the user's raw text alone; otherwise reformat (e.g. "9.9" → "9.90"
-   *  for precision=2). Non-numeric stored strings pass through unchanged
-   *  so error-state visuals can echo what the user typed. */
-  #formatStored(stored) {
-    const s = String(stored ?? '');
-    if (!s) return '';
-    // Canonicalize before Number() — `.value` may carry the locale's
-    // decimal separator if the host has `locale` set.
-    const n = Number(this.#toCanonical(s));
-    if (!Number.isFinite(n)) return s;
-    // If the input is currently focused, render without grouping so the
-    // user can edit naturally; otherwise group when locale is set. Falls
-    // back to #format (ungrouped) when there's no locale.
-    return document.activeElement === this.#textEl
-      ? this.#format(n)
-      : this.#formatDisplay(n);
-  }
-
-  #snap(raw) {
-    const step = this.step || 1;
-    const base = this.min != null ? this.min : 0;
-    const stepped = Math.round((raw - base) / step) * step + base;
-    const clamped = Math.max(
-      this.min != null ? this.min : -Infinity,
-      Math.min(this.max != null ? this.max : Infinity, stepped),
-    );
-    return parseFloat(clamped.toFixed(10));
-  }
-
-  #stepBy(multiplier) {
-    if (this.disabled || this.readonly) return;
-    const step = (this.step || 1) * multiplier;
-    const current = Number.isFinite(this.valueAsNumber)
-      ? this.valueAsNumber
-      : (this.min != null ? this.min : 0);
-    const next = this.#snap(current + step);
-    if (next === this.valueAsNumber) return;
-    this.value = this.#format(next);
-    this.syncValue(this.value);
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-  }
-
-  // ── Event handlers ──
-
-  #onInput = () => {
-    let text;
-    if (this.#isNativePassword) {
-      text = this.#textEl.value || '';
-    } else if (this.#isNumberMode) {
-      // beforeinput filtered the keystroke; some browsers still let through
-      // composition or paste events that bypass beforeinput. Re-sanitize.
-      const raw = this.#textEl.textContent || '';
-      text = this.#sanitizeNumeric(raw);
-      if (text !== raw) {
-        // Soft-revert: restore filtered text + put caret at end. Rare path.
-        this.#textEl.textContent = text;
-        this.#placeCaretAtEnd();
-      }
-    } else {
-      text = this.#textEl.textContent || '';
-    }
-    this.value = text;
-    if (!this.#isNativePassword) this.#textEl.toggleAttribute('data-empty', !text);
-    this.syncValue(text);
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-  };
-
-  #onBeforeInput = (e) => {
-    // Allow deletions, formatting, composition — only gate text insertions.
-    const t = e.inputType;
-    if (!t || !t.startsWith('insert')) return;
-    if (t === 'insertCompositionText') return; // IME — let through, #onInput cleans up
-    const incoming = (e.data ?? '');
-    if (!incoming) return;
-    const current = this.#textEl.textContent || '';
-    const sel = window.getSelection();
-    // Build prospective string: replace selection (or insert at caret).
-    let start = current.length, end = current.length;
-    if (sel && sel.rangeCount && this.#textEl.contains(sel.anchorNode)) {
-      const r = sel.getRangeAt(0);
-      start = this.#offsetFromTextStart(r.startContainer, r.startOffset);
-      end   = this.#offsetFromTextStart(r.endContainer,   r.endOffset);
-      if (start > end) [start, end] = [end, start];
-    }
-    const prospective = current.slice(0, start) + incoming + current.slice(end);
-    if (!this.#isNumericProspect(prospective)) e.preventDefault();
-  };
-
-  #isNumericProspect(s) {
-    // Permissive while typing: allow lone '-', lone '.', and trailing '.'.
-    // Reject scientific notation, multiple decimals, multiple signs.
-    // When `locale` is set, accept both '.' AND the locale's decimal
-    // separator, and silently strip thousands-group separators (paste of
-    // "1,234.5" or "1.234,5" both validate).
-    const c = this.#toCanonical(s);
-    if (c === '' || c === '-' || c === '.' || c === '-.') {
-      return c === '' || c === '-' || (this.min == null || this.min < 0) ? true : false;
-    }
-    if (!/^-?\d*\.?\d*$/.test(c)) return false;
-    if (c.startsWith('-') && this.min != null && this.min >= 0) return false;
-    return true;
-  }
-
-  #sanitizeNumeric(s) {
-    // Strip everything but digits / one leading minus / one decimal point.
-    // The decimal mark is the locale's separator; characters that match the
-    // locale's group separator (e.g. `.` in de-DE, `,` in en-US) are silently
-    // dropped — never preserved in `this.value`. The blur handler re-renders
-    // with grouping for display via `#formatDisplay`.
-    //
-    // Note on programmatic `.value = "1.5"` in de-DE: that path doesn't run
-    // through sanitization (UIFormElement.value setter is string-only), so
-    // canonical-form programmatic values still parse correctly via
-    // `valueAsNumber` (which canonicalizes through `#toCanonical`). Only
-    // user-typed/-pasted input flows through this sanitizer, and there the
-    // locale interpretation (`.` = group when sep=`,`) is the correct read.
-    const sep = this.#decimalSep();
-    let out = '';
-    let sawDecimal = false;
-    for (let i = 0; i < s.length; i++) {
-      const c = s[i];
-      if (c >= '0' && c <= '9') out += c;
-      else if (c === '-' && out === '' && (this.min == null || this.min < 0)) out += c;
-      else if (c === sep && !sawDecimal) { out += sep; sawDecimal = true; }
-      // group separator and other punctuation silently dropped
-    }
-    return out;
-  }
-
-  #offsetFromTextStart(node, offset) {
-    // Walk the text descendants until we reach `node`, accumulating chars.
-    if (!this.#textEl.contains(node)) return 0;
-    let acc = 0;
-    const walker = document.createTreeWalker(this.#textEl, NodeFilter.SHOW_TEXT);
-    let n;
-    while ((n = walker.nextNode())) {
-      if (n === node) return acc + offset;
-      acc += n.textContent.length;
-    }
-    return node === this.#textEl ? offset : acc;
-  }
-
-  #placeCaretAtEnd() {
-    const sel = window.getSelection();
-    const range = document.createRange();
-    range.selectNodeContents(this.#textEl);
-    range.collapse(false);
-    sel.removeAllRanges();
-    sel.addRange(range);
-  }
-
-  #onKeydown = (e) => {
-    if (this.#isNumberMode) {
-      switch (e.key) {
-        case 'ArrowUp':   e.preventDefault(); this.#stepBy( 1);  return;
-        case 'ArrowDown': e.preventDefault(); this.#stepBy(-1);  return;
-        case 'PageUp':    e.preventDefault(); this.#stepBy( 10); return;
-        case 'PageDown':  e.preventDefault(); this.#stepBy(-10); return;
-        case 'Home':
-          if (this.min != null) { e.preventDefault(); this.#commitNumeric(this.min); }
-          return;
-        case 'End':
-          if (this.max != null) { e.preventDefault(); this.#commitNumeric(this.max); }
-          return;
-        case 'Escape':
-          e.preventDefault();
-          this.value = this.#valueAtFocus;
-          this.#textEl.textContent = this.#formatStored(this.value);
-          this.#textEl.toggleAttribute('data-empty', !this.value);
-          this.syncValue(this.value);
-          this.#textEl.blur();
-          return;
-        case 'Enter':
-          e.preventDefault();
-          // Commit normalized value before firing form events.
-          this.#commitOnBlur();
-          this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-          this.dispatchEvent(new Event('submit', { bubbles: true }));
-          return;
-      }
-      return;
-    }
-    if (e.key === 'Enter') {
-      e.preventDefault();
-      this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-      this.dispatchEvent(new Event('submit', { bubbles: true }));
-    }
-  };
-
-  #onFocus = () => {
-    this.#valueAtFocus = this.value ?? '';
-    // When focused: re-render textContent without thousands grouping so the
-    // user can edit naturally — group separators jumping mid-keystroke is
-    // disorienting. Only matters when `locale` is set AND the post-blur
-    // render added grouping; no-op for the default `.` path.
-    if (this.#isNumberMode && this.locale) {
-      const raw = String(this.value ?? '').trim();
-      if (!raw) return;
-      const n = Number(this.#toCanonical(raw));
-      if (!Number.isFinite(n)) return;
-      const ungrouped = this.#format(n);
-      if (this.#textEl.textContent !== ungrouped) this.#textEl.textContent = ungrouped;
-    }
-  };
-
-  #onBlur = () => {
-    if (this.#isNumberMode) this.#commitOnBlur();
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-  };
-
-  #commitOnBlur() {
-    const raw = String(this.value ?? '').trim();
-    if (!raw) return;
-    // Canonicalize before Number() — `this.value` may carry the locale's
-    // decimal separator (e.g. "1,5" in de-DE).
-    const n = Number(this.#toCanonical(raw));
-    if (!Number.isFinite(n)) return; // leave the bad input visible for the error UX
-    const snapped = this.#snap(n);
-    // `this.value` stores the ungrouped, locale-decimal form (round-trippable
-    // through #toCanonical → Number → #format). textContent shows the
-    // grouped display form when `locale` is set.
-    const stored    = this.#format(snapped);
-    const displayed = this.#formatDisplay(snapped);
-    if (this.value !== stored) {
-      this.value = stored;
-      this.syncValue(stored);
-      this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-    }
-    if (this.#textEl.textContent !== displayed) {
-      this.#textEl.textContent = displayed;
-      this.#textEl.toggleAttribute('data-empty', !displayed);
-    }
-  }
-
-  #commitNumeric(n) {
-    const snapped = this.#snap(n);
-    if (snapped === this.valueAsNumber) return;
-    this.value = this.#format(snapped);
-    this.syncValue(this.value);
-    this.#textEl.textContent = this.value;
-    this.#textEl.toggleAttribute('data-empty', !this.value);
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-  }
-
-  #onPaste = (e) => {
-    e.preventDefault();
-    const raw = e.clipboardData?.getData('text/plain') || '';
-    const text = this.#isNumberMode ? this.#sanitizeNumeric(raw) : raw;
-    document.execCommand('insertText', false, text);
-  };
-
-  // Hold-to-repeat: pointerdown fires the initial step + arms an autorepeat
-  // timer. The first repeat fires after REPEAT_INITIAL_MS; subsequent ones
-  // every REPEAT_INTERVAL_MS. pointerup on document stops everything. We
-  // also stop on a stale value (disabled at min/max boundary) so the
-  // browser doesn't keep firing input events for no-op increments.
-  #onStepperUpDown   = (e) => this.#startStepperHold(e, 1);
-  #onStepperDownDown = (e) => this.#startStepperHold(e, -1);
-
-  #startStepperHold(e, multiplier) {
-    // Keep focus on the editable surface when the button is pressed.
-    e.preventDefault();
-    if (this.disabled || this.readonly) return;
-    // Initial step fires immediately on press.
-    this.#stepBy(multiplier);
-    this.#stopStepperHold();
-    // Listen for release on document (cheap; only while held).
-    document.addEventListener('pointerup',     this.#onStepperRelease, { once: true });
-    document.addEventListener('pointercancel', this.#onStepperRelease, { once: true });
-    // Initial delay → then continuous repeat.
-    this.#repeatDelayTimer = window.setTimeout(() => {
-      this.#repeatDelayTimer = null;
-      this.#repeatTimer = window.setInterval(() => {
-        const before = this.valueAsNumber;
-        this.#stepBy(multiplier);
-        // Boundary hit → no-op; cancel to avoid wasted intervals + event spam.
-        if (this.valueAsNumber === before) this.#stopStepperHold();
-      }, UIInput.#REPEAT_INTERVAL_MS);
-    }, UIInput.#REPEAT_INITIAL_MS);
-  }
-
-  #onStepperRelease = () => this.#stopStepperHold();
-
-  #stopStepperHold() {
-    if (this.#repeatDelayTimer != null) {
-      window.clearTimeout(this.#repeatDelayTimer);
-      this.#repeatDelayTimer = null;
-    }
-    if (this.#repeatTimer != null) {
-      window.clearInterval(this.#repeatTimer);
-      this.#repeatTimer = null;
-    }
-    document.removeEventListener('pointerup',     this.#onStepperRelease);
-    document.removeEventListener('pointercancel', this.#onStepperRelease);
-  }
-
-  focus() { this.#textEl?.focus(); }
-
-  clear() {
-    this.value = '';
-    if (this.#textEl) {
-      if (this.#isNativePassword) {
-        this.#textEl.value = '';
-      } else {
-        this.#textEl.textContent = '';
-        this.#textEl.setAttribute('data-empty', '');
-      }
-    }
-    this.syncValue('');
-  }
-
-  disconnected() {
-    super.disconnected();
-    if (this.#textEl) {
-      this.#textEl.removeEventListener('input',    this.#onInput);
-      this.#textEl.removeEventListener('keydown',  this.#onKeydown);
-      this.#textEl.removeEventListener('blur',     this.#onBlur);
-      this.#textEl.removeEventListener('focus',    this.#onFocus);
-      this.#textEl.removeEventListener('paste',    this.#onPaste);
-      this.#textEl.removeEventListener('beforeinput', this.#onBeforeInput);
-    }
-    this.#upBtn?.removeEventListener('pointerdown', this.#onStepperUpDown);
-    this.#downBtn?.removeEventListener('pointerdown', this.#onStepperDownDown);
-    // Cancel any in-flight hold (the document-level pointerup listener
-    // is `{once: true}` so it self-cleans on fire; this also clears the
-    // timers if the host disconnects mid-hold).
-    this.#stopStepperHold();
-    this.#textEl = null;
-    this.#labelEl = null;
-    this.#upBtn = null;
-    this.#downBtn = null;
-  }
-}
-customElements.define('input-ui', UIInput);
+defineIfFree('input-ui', UIInput);
 
 export { UIInput };
-