@adia-ai/web-components 0.4.1 → 0.4.2

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,21 @@
       "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 +91,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 +111,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 +136,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,75 @@ 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 },
   };
 
   static template = () => null;
 
   #textEl = null;
   #labelEl = null;
+  #upBtn = null;
+  #downBtn = null;
+  #valueAtFocus = '';
   static #labelSeq = 0;
 
-  get #isNativeInput() {
-    return this.type === 'password' || this.type === 'number';
+  get #isNativePassword() { return this.type === 'password'; }
+  get #isNumberMode()     { return this.type === 'number'; }
+
+  /** Parsed numeric value. NaN when empty or unparseable. */
+  get valueAsNumber() {
+    const s = String(this.value ?? '').trim();
+    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.
+    this.#upBtn?.addEventListener('pointerdown', this.#onStepperDown);
+    this.#downBtn?.addEventListener('pointerdown', this.#onStepperDown);
+    this.#upBtn?.addEventListener('click', this.#onStepUp);
+    this.#downBtn?.addEventListener('click', this.#onStepDown);
+
     // 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 +128,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 +191,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 +207,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 +228,256 @@ 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 s = String(val ?? '').trim();
+    // Empty is handled by `required` in the base class; nothing to check here.
+    if (!s) return true;
+    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;
+  }
+
+  #format(n) {
+    if (!Number.isFinite(n)) return '';
+    const d = this.#decimals();
+    return d > 0 ? n.toFixed(d) : String(Math.round(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 '';
+    const n = Number(s);
+    if (!Number.isFinite(n)) return s;
+    return this.#format(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.
+    if (s === '' || s === '-' || s === '.' || s === '-.') {
+      return s === '' || s === '-' || (this.min == null || this.min < 0) ? true : false;
+    }
+    if (!/^-?\d*\.?\d*$/.test(s)) return false;
+    if (s.startsWith('-') && this.min != null && this.min >= 0) return false;
+    return true;
+  }
+
+  #sanitizeNumeric(s) {
+    // Strip everything but digits / one leading minus / one decimal point.
+    let out = '';
+    let sawDot = 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 === '.' && !sawDot) { out += c; sawDot = true; }
+    }
+    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 +485,65 @@ class UIInput extends UIFormElement {
     }
   };
 
+  #onFocus = () => {
+    this.#valueAtFocus = this.value ?? '';
+  };
+
   #onBlur = () => {
+    if (this.#isNumberMode) this.#commitOnBlur();
     this.dispatchEvent(new Event('change', { bubbles: true }));
   };
 
+  #commitOnBlur() {
+    const raw = String(this.value ?? '').trim();
+    if (!raw) return;
+    const n = Number(raw);
+    if (!Number.isFinite(n)) return; // leave the bad input visible for the error UX
+    const snapped = this.#snap(n);
+    const formatted = this.#format(snapped);
+    if (this.value !== formatted) {
+      this.value = formatted;
+      this.syncValue(formatted);
+      this.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+    if (this.#textEl.textContent !== formatted) {
+      this.#textEl.textContent = formatted;
+      this.#textEl.toggleAttribute('data-empty', !formatted);
+    }
+  }
+
+  #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);
   };
 
+  #onStepperDown = (e) => {
+    // Keep focus on the editable surface when the button is pressed.
+    e.preventDefault();
+  };
+
+  #onStepUp = () => { this.#stepBy(1); };
+  #onStepDown = () => { this.#stepBy(-1); };
+
   focus() { this.#textEl?.focus(); }
 
   clear() {
     this.value = '';
     if (this.#textEl) {
-      if (this.#isNativeInput) {
+      if (this.#isNativePassword) {
         this.#textEl.value = '';
       } else {
         this.#textEl.textContent = '';
@@ -201,13 +556,21 @@ 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.#onStepperDown);
+    this.#downBtn?.removeEventListener('pointerdown', this.#onStepperDown);
+    this.#upBtn?.removeEventListener('click', this.#onStepUp);
+    this.#downBtn?.removeEventListener('click', this.#onStepDown);
     this.#textEl = null;
     this.#labelEl = null;
+    this.#upBtn = null;
+    this.#downBtn = null;
   }
 }
 customElements.define('input-ui', 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,26 @@ 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
   pattern:
     description: Regex pattern for validation. Tested as ^(?:pattern)$ against the value.
     type: string
@@ -87,16 +111,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 +183,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.2",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "exports": {