@adia-ai/web-components 0.4.1 → 0.4.3

package/README.md

@@ -9,6 +9,18 @@ A2UI protocol messages into live DOM.
 > [`@adia-ai/a2ui-corpus`](../a2ui/corpus); the MCP server in
 > [`@adia-ai/a2ui-mcp`](../a2ui/mcp).
 
+## Install
+
+```bash
+npm install @adia-ai/web-components
+```
+
+For composite shells (admin / chat / editor / simple / theme clusters), pair with [`@adia-ai/web-modules`](../web-modules):
+
+```bash
+npm install @adia-ai/web-components @adia-ai/web-modules
+```
+
 ## Quick start
 
 ```html

package/components/field/field.test.js

@@ -112,15 +112,13 @@ describe('field-ui', () => {
     expect(input.hasAttribute('aria-describedby')).toBe(false);
   });
 
-  it.skip('renders an error element + suppresses hint when both set', async () => {
-    // SKIPPED 2026-05-10: pre-existing failure — the field-ui mirrors
-    // error from the CHILD control's .error getter (see field.js:51),
-    // not from <field-ui>'s own [error] attribute. This test was authored
-    // before that architecture change. Fix requires either (a) rewriting
-    // the test to set error on the child input via setCustomValidity() /
-    // UIFormElement.error, or (b) re-adding a [error] attribute reader
-    // on field-ui itself. Tracked for follow-up.
-    const f = mount('<field-ui label="E" hint="hi" error="Required"><input /></field-ui>');
+  it('renders an error element + suppresses hint when both set', async () => {
+    // Per field.js error-mirror architecture: field-ui reads .error from
+    // the CHILD UIFormElement control (not from its own attribute). So
+    // the test sets [error] on <input-ui> (UIFormElement-extending) — not
+    // <input> (raw HTML, no .error getter).
+    await import('../input/input.js');
+    const f = mount('<field-ui label="E" hint="hi"><input-ui error="Required"></input-ui></field-ui>');
     await tick();
     const hint = f.querySelector('[data-field-hint]');
     const err  = f.querySelector('[data-field-error]');
@@ -128,8 +126,11 @@ describe('field-ui', () => {
     expect(err?.hidden).toBe(false);
     expect(err?.getAttribute('role')).toBe('alert');
     expect(hint?.hidden).toBe(true);  // error wins
-    const input = f.querySelector('input');
-    expect(input.getAttribute('aria-describedby')).toBe(err.id);
+    // aria-describedby is set on the field-ui's CONTROL (the <input-ui>),
+    // not on its inner <input>. field-ui targets the control via
+    // #findControl() (first non-slot child).
+    const control = f.querySelector('input-ui');
+    expect(control.getAttribute('aria-describedby')).toBe(err.id);
   });
 
   it('renders the `*` required marker on the label when `required` is set', async () => {

package/components/input/input.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Input.json",
   "title": "Input",
-  "description": "Text input field with contenteditable or native input. Supports prefix/suffix icons, label, and form participation.",
+  "description": "Text input field with contenteditable surface. Supports prefix/suffix icons, label, form participation, and a `type=\"number\"` mode that renders [+]/[-] stepper buttons, numeric input filtering, and ARIA spinbutton semantics — no native `<input type=\"number\">` under the hood. Password type uses a native `<input>` (only path that still wraps native, for `-webkit-text-security` disc masking).",
   "type": "object",
   "allOf": [
     {
@@ -14,7 +14,7 @@
   ],
   "properties": {
     "type": {
-      "description": "Input type hint. Password type applies disc masking via -webkit-text-security.",
+      "description": "Input type. `password` wraps a native `<input>` for disc masking; `number` renders a contenteditable + stepper buttons (no native input). All other types use plain contenteditable.",
       "type": "string",
       "enum": [
         "text",
@@ -56,11 +56,26 @@
       "type": "string",
       "default": ""
     },
+    "locale": {
+      "description": "BCP-47 locale tag for `type=\"number\"`, e.g. `de-DE`, `fr-FR`, `en-IN`. When set, the input accepts both `.` AND the locale's decimal separator (e.g. `,` in de-DE), uses `Intl.NumberFormat` for display, and groups thousands on blur (e.g. en-US `1,234,567.89`, de-DE `1.234.567,89`). On focus, the input reverts to ungrouped form for easy editing. `.value` always stores the ungrouped, locale-decimal form so `Number(#toCanonical(v))` round-trips. Default empty = en-US-equivalent path (no behavior change).",
+      "type": "string",
+      "default": ""
+    },
+    "max": {
+      "description": "Maximum numeric value. Applies when `type=\"number\"`. Clamps + drives aria-valuemax + the [+] button's disabled state.",
+      "type": "number",
+      "default": null
+    },
     "maxlength": {
       "description": "Maximum character length for validation",
       "type": "number",
       "default": null
     },
+    "min": {
+      "description": "Minimum numeric value. Applies when `type=\"number\"`. Clamps + drives aria-valuemin + the [-] button's disabled state.",
+      "type": "number",
+      "default": null
+    },
     "minlength": {
       "description": "Minimum character length for validation",
       "type": "number",
@@ -81,6 +96,11 @@
       "type": "string",
       "default": ""
     },
+    "precision": {
+      "description": "Decimal places to display + clamp to, when `type=\"number\"`. Overrides the implicit decimal-count from `step` — e.g. `step=1 precision=2` formats \"10.00\".",
+      "type": "number",
+      "default": null
+    },
     "prefix": {
       "description": "Prefix text or icon rendered before the text surface (e.g., unit label, search icon)",
       "type": "string",
@@ -96,13 +116,18 @@
       "type": "boolean",
       "default": false
     },
+    "step": {
+      "description": "Stepper increment for `type=\"number\"`. Drives ↑/↓ ArrowUp/Down + [+]/[-] button magnitude. Also determines decimal-count for value formatting unless `precision` is set.",
+      "type": "number",
+      "default": 1
+    },
     "suffix": {
       "description": "Suffix text rendered after the text surface (e.g., unit like 'kg')",
       "type": "string",
       "default": ""
     },
     "value": {
-      "description": "Current input value, synced with contenteditable text surface",
+      "description": "Current input value, synced with contenteditable text surface. For `type=\"number\"`, this is the formatted numeric string; read `el.valueAsNumber` for the parsed Number.",
       "type": "string",
       "default": ""
     }
@@ -116,16 +141,41 @@
     "category": "input",
     "events": {
       "change": {
-        "description": "Fired on blur after the value has changed (bubbles)"
+        "description": "Fired on blur, Enter, or a stepper-button click (bubbles)"
       },
       "input": {
-        "description": "Fired on each keystroke as the user types (bubbles)"
+        "description": "Fired on each keystroke or stepper-button increment (bubbles)"
       },
       "submit": {
-        "description": "Fired when the form is submitted."
+        "description": "Fired when Enter commits the value."
       }
     },
     "examples": [
+      {
+        "description": "Number input with [+]/[-] stepper buttons, min/max bounds, and a quantity label. Use for product quantity, item count, or any bounded integer input.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Field\", \"label\": \"Quantity\",\n   \"children\": [\"qty\"]},\n  {\"id\": \"qty\", \"component\": \"Input\", \"type\": \"number\",\n   \"name\": \"quantity\", \"value\": \"1\", \"min\": 0, \"max\": 99, \"step\": 1}\n]",
+        "name": "quantity-stepper"
+      },
+      {
+        "description": "Currency number input with $ prefix, 2-decimal precision, and step 0.01. The stepper buttons increment by one cent.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Field\", \"label\": \"Price\",\n   \"children\": [\"price\"]},\n  {\"id\": \"price\", \"component\": \"Input\", \"type\": \"number\",\n   \"name\": \"price\", \"value\": \"9.99\", \"min\": 0, \"step\": 0.01,\n   \"precision\": 2, \"prefix\": \"$\"}\n]",
+        "name": "price-with-currency"
+      },
+      {
+        "description": "Weight number input with a kg suffix and 0.1 step for decigram precision.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Field\", \"label\": \"Weight\",\n   \"children\": [\"weight\"]},\n  {\"id\": \"weight\", \"component\": \"Input\", \"type\": \"number\",\n   \"name\": \"weight\", \"value\": \"70\", \"min\": 0, \"max\": 500,\n   \"step\": 0.1, \"suffix\": \"kg\"}\n]",
+        "name": "weight-with-unit"
+      },
+      {
+        "description": "Percent number input bounded 0..100 with a % suffix.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Field\", \"label\": \"Discount\",\n   \"children\": [\"pct\"]},\n  {\"id\": \"pct\", \"component\": \"Input\", \"type\": \"number\",\n   \"name\": \"discount\", \"value\": \"25\", \"min\": 0, \"max\": 100,\n   \"step\": 5, \"suffix\": \"%\"}\n]",
+        "name": "percent-bounded"
+      },
+      {
+        "description": "Number input allowing negative values, e.g. temperature offset.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Field\", \"label\": \"Temperature offset\",\n   \"children\": [\"temp\"]},\n  {\"id\": \"temp\", \"component\": \"Input\", \"type\": \"number\",\n   \"name\": \"temp\", \"value\": \"0\", \"min\": -100, \"max\": 100,\n   \"step\": 1, \"suffix\": \"°C\"}\n]",
+        "name": "temperature-negative"
+      },
       {
         "description": "Chat interface with message bubbles containing avatar and text pairs, plus an input footer.",
         "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"hdr\",\n      \"sec\",\n      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"title\"\n    ]\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Chat\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"messages\"\n    ]\n  },\n  {\n    \"id\": \"messages\",\n    \"component\": \"Column\",\n    \"gap\": \"3\",\n    \"children\": [\n      \"msg1\",\n      \"msg2\",\n      \"msg3\",\n      \"msg4\"\n    ]\n  },\n  {\n    \"id\": \"msg1\",\n    \"component\": \"Row\",\n    \"gap\": \"2\",\n    \"children\": [\n      \"a1\",\n      \"t1\"\n    ]\n  },\n  {\n    \"id\": \"a1\",\n    \"component\": \"Avatar\",\n    \"name\": \"User\",\n    \"size\": \"sm\"\n  },\n  {\n    \"id\": \"t1\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"Hello! Can you help me with something?\"\n  },\n  {\n    \"id\": \"msg2\",\n    \"component\": \"Row\",\n    \"gap\": \"2\",\n    \"children\": [\n      \"a2\",\n      \"t2\"\n    ]\n  },\n  {\n    \"id\": \"a2\",\n    \"component\": \"Avatar\",\n    \"name\": \"Assistant\",\n    \"size\": \"sm\"\n  },\n  {\n    \"id\": \"t2\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"Of course! I'd be happy to help. What do you need?\"\n  },\n  {\n    \"id\": \"msg3\",\n    \"component\": \"Row\",\n    \"gap\": \"2\",\n    \"children\": [\n      \"a3\",\n      \"t3\"\n    ]\n  },\n  {\n    \"id\": \"a3\",\n    \"component\": \"Avatar\",\n    \"name\": \"User\",\n    \"size\": \"sm\"\n  },\n  {\n    \"id\": \"t3\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"I need to build a dashboard layout.\"\n  },\n  {\n    \"id\": \"msg4\",\n    \"component\": \"Row\",\n    \"gap\": \"2\",\n    \"children\": [\n      \"a4\",\n      \"t4\"\n    ]\n  },\n  {\n    \"id\": \"a4\",\n    \"component\": \"Avatar\",\n    \"name\": \"Assistant\",\n    \"size\": \"sm\"\n  },\n  {\n    \"id\": \"t4\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"Great choice! Let me suggest some patterns for that.\"\n  },\n  {\n    \"id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"input-row\"\n    ]\n  },\n  {\n    \"id\": \"input-row\",\n    \"component\": \"Row\",\n    \"gap\": \"2\",\n    \"children\": [\n      \"chat-input\",\n      \"send-btn\"\n    ]\n  },\n  {\n    \"id\": \"chat-input\",\n    \"component\": \"Input\",\n    \"placeholder\": \"Type a message...\"\n  },\n  {\n    \"id\": \"send-btn\",\n    \"component\": \"Button\",\n    \"text\": \"Send\",\n    \"icon\": \"send\",\n    \"variant\": \"primary\"\n  }\n]",

package/components/input/input.css

@@ -115,7 +115,7 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     overflow: hidden;
   }
 
-  /* Text (native input — password, number) */
+  /* Text (native input — password only) */
   input[slot="text"] {
     border: none;
     background: transparent;
@@ -137,6 +137,114 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     pointer-events: none;
   }
 
+  /* ── Number mode (type="number") ──
+     Right-aligned digits with tabular-nums so rapid stepping doesn't
+     jitter the value horizontally. The stepper column is positioned
+     absolutely against the field's inline-end edge so it NEVER affects
+     the field's flex-sized height — number-mode inputs share the same
+     24/30/36px (sm/md/lg) baseline as text/email/password/etc. */
+  [data-number] [slot="text"] {
+    text-align: end;
+    font-variant-numeric: tabular-nums;
+    font-weight: var(--a-weight-medium, 500);
+    /* Reserve space for the absolutely-positioned controls column so the
+       value never collides with the stepper buttons. */
+    padding-inline-end: var(--input-controls-width, calc(var(--input-height) * 0.7));
+  }
+
+  /* Suffix sits flush after the value in number mode (no auto margin so
+     the value+suffix pair stays right-aligned together). */
+  [data-number] [slot="suffix"] {
+    margin-inline-start: 0;
+    /* Reserve space for the absolutely-positioned controls column so the
+       suffix never collides with the stepper buttons. The padding moves
+       from `[slot="text"]` to `[slot="suffix"]` when a suffix is present
+       — only one element needs the reservation since they're adjacent. */
+    margin-inline-end: var(--input-controls-width, calc(var(--input-height) * 0.7));
+  }
+  [data-number]:has([slot="suffix"]) [slot="text"] {
+    padding-inline-end: 0;
+  }
+
+  [data-number] {
+    position: relative;
+  }
+
+  [slot="controls"] {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-end: 0;
+    display: grid;
+    grid-template-rows: 1fr 1fr;
+    border-inline-start: 1px solid var(--input-border);
+    width: var(--input-controls-width, calc(var(--input-height) * 0.7));
+    user-select: none;
+    overflow: hidden;
+  }
+
+  [data-number] [slot="controls"] button-ui {
+    /* Defeat button-ui's intrinsic min-height (driven by --button-height) so
+       its content can't push past half the column height. Padding + border
+       are zeroed; the divider between the two buttons comes from the
+       :first-child border-bottom rule below. Override button-ui's
+       `display: inline-flex` to `flex` so `width: 100%` fills the grid
+       track instead of collapsing to content. */
+    display: flex;
+    --button-height: 0;
+    --button-radius: 0;
+    --button-bg: transparent;
+    --button-fg: var(--input-affix-fg);
+    --button-px: 0;
+    min-width: 0;
+    min-height: 0;
+    width: 100%;
+    height: 100%;
+    border: 0;
+    padding: 0;
+  }
+  /* Override icon-ui's self-declared --icon-size (which is `calc(1em +
+     0.125rem)` by default — the +0.125rem overshoot would push the icon
+     past the half-column cell). Targeting icon-ui directly is required
+     because its own `:where(:scope)` declaration of --icon-size wins over
+     any value inherited from its parent button-ui. Tying it to
+     --input-height keeps the chevron proportional across sm/md/lg. */
+  [data-number] [slot="controls"] icon-ui {
+    --icon-size: calc(var(--input-height) * 0.4);
+  }
+  [data-number] [slot="controls"] button-ui:hover {
+    --button-bg: var(--a-ui-bg-hover);
+    --button-fg: var(--a-ui-text);
+  }
+  [data-number] [slot="controls"] button-ui[disabled] {
+    --button-fg: var(--a-ui-text-disabled);
+    pointer-events: none;
+  }
+  /* Field-level focus ring sits OUTSIDE the chrome and would clip the
+     bottom-right corner of the controls column. Round the corners of the
+     buttons that touch the chrome edge so the focus ring follows the
+     field radius cleanly. The divider between the two buttons is the
+     inline-start border on the column + the bottom-border on the upper
+     button. */
+  [data-number] [slot="controls"] button-ui:first-child {
+    border-bottom: 1px solid var(--input-border);
+    border-start-end-radius: calc(var(--input-radius) - 1px);
+  }
+  [data-number] [slot="controls"] button-ui:last-child {
+    border-end-end-radius: calc(var(--input-radius) - 1px);
+  }
+
+  /* Raw mode strips the chrome — also strip the controls column's
+     border + corner radii. */
+  :scope[raw] [slot="controls"] {
+    margin-inline-end: 0;
+    border-inline-start: none;
+  }
+  :scope[raw] [data-number] [slot="controls"] button-ui:first-child,
+  :scope[raw] [data-number] [slot="controls"] button-ui:last-child {
+    border-bottom: none;
+    border-radius: 0;
+  }
+
   /* Prefix + Suffix — inline-flex so icon-ui (or any non-text affix
      content) centers vertically within the slot wrapper. Without
      this, an icon inside a default <span slot="prefix"> sits at the

package/components/input/input.js

@@ -3,13 +3,23 @@
  * Uses contenteditable for text entry, ElementInternals for form participation.
  *
  * Slots inside [slot="field"]:
- *   prefix → label → text → suffix
+ *   prefix → label → text → suffix → controls (number mode)
  *
  *   <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>
  *
+ *   <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.
@@ -38,55 +48,101 @@ class UIInput extends UIFormElement {
     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;
 
-  get #isNativeInput() {
-    return this.type === 'password' || this.type === 'number';
+  // 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', 'textbox');
+    this.setAttribute('role', this.#isNumberMode ? 'spinbutton' : 'textbox');
 
     if (!this.querySelector('[slot="text"]')) {
-      const useNative = this.#isNativeInput;
       const labelId = this.label ? `input-label-${++UIInput.#labelSeq}` : '';
-      this.innerHTML = `
-        <div slot="field">
-          ${this.prefix ? `<span slot="prefix">${renderAffix(this.prefix)}</span>` : ''}
-          ${this.label ? `<span slot="label" id="${labelId}">${this.label}</span>` : ''}
-          ${useNative
-            ? `<input slot="text" type="${this.type}" tabindex="0"
-                      placeholder="${this.placeholder}" value="${this.value || ''}"
-                      autocomplete="${this.type === 'password' ? 'current-password' : 'off'}"
-                      ${labelId ? `aria-labelledby="${labelId}"` : ''}
-                      ${this.disabled ? 'disabled' : ''} ${this.readonly ? 'readonly' : ''} />`
-            : `<span slot="text" contenteditable="plaintext-only" tabindex="0"
-                    ${this.value ? '' : 'data-empty=""'}
-                    ${labelId ? `aria-labelledby="${labelId}"` : ''}
-                    data-placeholder="${this.placeholder}"></span>`}
-          ${this.suffix ? `<span slot="suffix">${renderAffix(this.suffix)}</span>` : ''}
-        </div>
-      `;
+      this.innerHTML = this.#shellHTML(labelId);
     }
 
-    this.#textEl = this.querySelector('[slot="text"]');
+    this.#textEl  = this.querySelector('[slot="text"]');
     this.#labelEl = this.querySelector('[slot="label"]');
-    if (!this.#isNativeInput && this.value) this.#textEl.textContent = this.value;
+    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('paste', this.#onPaste);
+      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
@@ -98,6 +154,47 @@ class UIInput extends UIFormElement {
     }
   }
 
+  #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']) {
@@ -120,13 +217,12 @@ class UIInput extends UIFormElement {
   render() {
     if (!this.#textEl) return;
 
-    const text = this.value || '';
+    const text = this.value ?? '';
 
-    if (this.#isNativeInput) {
+    if (this.#isNativePassword) {
       this.#textEl.placeholder = this.placeholder;
       this.#textEl.disabled = this.disabled;
       this.#textEl.readOnly = this.readonly;
-      // Sync programmatic value writes (form.reset(), trait assignments).
       if (this.#textEl.value !== text) this.#textEl.value = text;
     } else {
       this.#textEl.setAttribute('data-placeholder', this.placeholder);
@@ -137,10 +233,15 @@ class UIInput extends UIFormElement {
       }
       // Sync programmatic value writes into the contenteditable surface.
       // Skip when already in sync to avoid clobbering an in-flight edit's
-      // caret position.
-      if (this.#textEl.textContent !== text) {
-        this.#textEl.textContent = text;
-        this.#textEl.toggleAttribute('data-empty', !text);
+      // 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);
       }
     }
 
@@ -153,19 +254,358 @@ class UIInput extends UIFormElement {
     } 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));
+  }
+
+  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 Event('input', { bubbles: true }));
+    this.dispatchEvent(new Event('change', { bubbles: true }));
+  }
+
+  // ── Event handlers ──
+
   #onInput = () => {
-    const text = this.#isNativeInput
-      ? (this.#textEl.value || '')
-      : (this.#textEl.textContent || '');
+    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.#isNativeInput) this.#textEl.toggleAttribute('data-empty', !text);
+    if (!this.#isNativePassword) this.#textEl.toggleAttribute('data-empty', !text);
     this.syncValue(text);
     this.dispatchEvent(new Event('input', { bubbles: true }));
   };
 
+  #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 Event('change', { bubbles: true }));
+          this.dispatchEvent(new Event('submit', { bubbles: true }));
+          return;
+      }
+      return;
+    }
     if (e.key === 'Enter') {
       e.preventDefault();
       this.dispatchEvent(new Event('change', { bubbles: true }));
@@ -173,22 +613,120 @@ class UIInput extends UIFormElement {
     }
   };
 
+  #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 Event('change', { bubbles: true }));
   };
 
+  #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 Event('input', { bubbles: true }));
+    }
+    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 Event('input', { bubbles: true }));
+    this.dispatchEvent(new Event('change', { bubbles: true }));
+  }
+
   #onPaste = (e) => {
     e.preventDefault();
-    const text = e.clipboardData?.getData('text/plain') || '';
+    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.#isNativeInput) {
+      if (this.#isNativePassword) {
         this.#textEl.value = '';
       } else {
         this.#textEl.textContent = '';
@@ -201,15 +739,26 @@ class UIInput extends UIFormElement {
   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('paste', this.#onPaste);
+      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);
 
 export { UIInput };
+

package/components/input/input.yaml

@@ -6,15 +6,19 @@ tag: input-ui
 component: Input
 category: input
 version: 1
-description: Text input field with contenteditable or native input. Supports prefix/suffix icons,
-  label, and form participation.
+description: Text input field with contenteditable surface. Supports prefix/suffix icons,
+  label, form participation, and a `type="number"` mode that renders [+]/[-] stepper buttons,
+  numeric input filtering, and ARIA spinbutton semantics — no native `<input type="number">`
+  under the hood. Password type uses a native `<input>` (only path that still wraps native,
+  for `-webkit-text-security` disc masking).
 props:
   name:
     description: Form control name for form data submission
     type: string
     default: ""
   type:
-    description: Input type hint. Password type applies disc masking via -webkit-text-security.
+    description: Input type. `password` wraps a native `<input>` for disc masking; `number` renders
+      a contenteditable + stepper buttons (no native input). All other types use plain contenteditable.
     type: string
     default: text
     enum:
@@ -60,6 +64,35 @@ props:
     description: Minimum character length for validation
     type: number
     default: null
+  min:
+    description: Minimum numeric value. Applies when `type="number"`. Clamps + drives aria-valuemin
+      + the [-] button's disabled state.
+    type: number
+    default: null
+  max:
+    description: Maximum numeric value. Applies when `type="number"`. Clamps + drives aria-valuemax
+      + the [+] button's disabled state.
+    type: number
+    default: null
+  step:
+    description: Stepper increment for `type="number"`. Drives ↑/↓ ArrowUp/Down + [+]/[-] button
+      magnitude. Also determines decimal-count for value formatting unless `precision` is set.
+    type: number
+    default: 1
+  precision:
+    description: Decimal places to display + clamp to, when `type="number"`. Overrides the implicit
+      decimal-count from `step` — e.g. `step=1 precision=2` formats "10.00".
+    type: number
+    default: null
+  locale:
+    description: BCP-47 locale tag for `type="number"`, e.g. `de-DE`, `fr-FR`, `en-IN`. When set,
+      the input accepts both `.` AND the locale's decimal separator (e.g. `,` in de-DE), uses
+      `Intl.NumberFormat` for display, and groups thousands on blur (e.g. en-US `1,234,567.89`,
+      de-DE `1.234.567,89`). On focus, the input reverts to ungrouped form for easy editing.
+      `.value` always stores the ungrouped, locale-decimal form so `Number(#toCanonical(v))`
+      round-trips. Default empty = en-US-equivalent path (no behavior change).
+    type: string
+    default: ""
   pattern:
     description: Regex pattern for validation. Tested as ^(?:pattern)$ against the value.
     type: string
@@ -87,16 +120,17 @@ props:
     type: string
     default: ""
   value:
-    description: Current input value, synced with contenteditable text surface
+    description: Current input value, synced with contenteditable text surface. For `type="number"`,
+      this is the formatted numeric string; read `el.valueAsNumber` for the parsed Number.
     type: string
     default: ""
 events:
   change:
-    description: Fired on blur after the value has changed (bubbles)
+    description: Fired on blur, Enter, or a stepper-button click (bubbles)
   input:
-    description: Fired on each keystroke as the user types (bubbles)
+    description: Fired on each keystroke or stepper-button increment (bubbles)
   submit:
-    description: "Fired when the form is submitted."
+    description: "Fired when Enter commits the value."
 slots:
   leading:
     description: Leading icon slot, sized to --content-height. Collapses text inline padding when present.
@@ -158,6 +192,57 @@ a2ui:
   rules: []
 anti_patterns: []
 examples:
+  - name: quantity-stepper
+    description: Number input with [+]/[-] stepper buttons, min/max bounds, and a quantity label.
+      Use for product quantity, item count, or any bounded integer input.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Field", "label": "Quantity",
+         "children": ["qty"]},
+        {"id": "qty", "component": "Input", "type": "number",
+         "name": "quantity", "value": "1", "min": 0, "max": 99, "step": 1}
+      ]
+  - name: price-with-currency
+    description: Currency number input with $ prefix, 2-decimal precision, and step 0.01.
+      The stepper buttons increment by one cent.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Field", "label": "Price",
+         "children": ["price"]},
+        {"id": "price", "component": "Input", "type": "number",
+         "name": "price", "value": "9.99", "min": 0, "step": 0.01,
+         "precision": 2, "prefix": "$"}
+      ]
+  - name: weight-with-unit
+    description: Weight number input with a kg suffix and 0.1 step for decigram precision.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Field", "label": "Weight",
+         "children": ["weight"]},
+        {"id": "weight", "component": "Input", "type": "number",
+         "name": "weight", "value": "70", "min": 0, "max": 500,
+         "step": 0.1, "suffix": "kg"}
+      ]
+  - name: percent-bounded
+    description: Percent number input bounded 0..100 with a % suffix.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Field", "label": "Discount",
+         "children": ["pct"]},
+        {"id": "pct", "component": "Input", "type": "number",
+         "name": "discount", "value": "25", "min": 0, "max": 100,
+         "step": 5, "suffix": "%"}
+      ]
+  - name: temperature-negative
+    description: Number input allowing negative values, e.g. temperature offset.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Field", "label": "Temperature offset",
+         "children": ["temp"]},
+        {"id": "temp", "component": "Input", "type": "number",
+         "name": "temp", "value": "0", "min": -100, "max": 100,
+         "step": 1, "suffix": "°C"}
+      ]
   - name: chat-interface
     description: Chat interface with message bubbles containing avatar and text pairs, plus an input footer.
     a2ui: >-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "exports": {