@adia-ai/web-components 0.0.14 → 0.0.16

package/components/field/field.js

@@ -11,37 +11,26 @@
  * and action regions. The host renders a real `<label for="…">` bound
  * to the slotted control's id (auto-minted when missing) so clicking
  * the label focuses the control — an affordance the previous
- * `<input-ui label="…">` pattern lacked (no `for` attr, just a shadow
- * slot).
+ * `<input-ui label="…">` pattern lacked.
  *
- * ### Layout — three internal flex rows
+ * ### Layout — single grid, slot-positioned
  *
- * field-ui owns three row wrappers inside its light DOM. Children are
- * reparented into the row that matches their role so each row's cell
- * widths are independent:
+ * field-ui is a CSS grid; children are placed by `[slot]` attribute:
  *
- *   <div data-row="label">    label [+required marker] [+trailing]  </div>
- *   <div data-row="control">  control [+action]                     </div>
- *   <div data-row="message">  hint or error                         </div>
+ *   slot="label"    → label cell      (mounted by field-ui)
+ *   slot="trailing" → row 1, right
+ *   (no slot)       → control cell
+ *   slot="action"   → adjacent to control
+ *   slot="hint"     → message row     (mounted by field-ui)
+ *   slot="error"    → message row     (mounted by field-ui)
  *
- * Per-row flex means `trailing` no longer dictates the width of
- * `action` (or vice versa). In the previous 2-column grid, column 2
- * was shared across rows, so `trailing="Required"` pushed the
- * `action` cell wider than the button needed. The three-row split
- * fixes that.
+ * The template adapts (via `:has()`) to which slots are present so empty
+ * tracks don't leak column-gap. Inline mode flattens the content slots
+ * onto a single row by retuning columns; message stays below.
  *
- * ### Inline mode
- *
- * `inline` collapses the three rows into a grid where label, trailing,
- * control, and action share one row and the message row sits below.
- * CSS uses `display: contents` on the label-row and control-row
- * wrappers in inline mode so their children flow directly into the
- * single grid row; no DOM restructure needed for the mode switch.
- *
- * A MutationObserver re-categorizes and re-parents children when the
- * slotted tree changes (e.g. the A2UI renderer swapping the control
- * during doc updates). Self-triggered mutations from our own
- * reparenting are debounced via a guard flag to prevent a loop.
+ * No DOM reparenting; CSS positions children directly. A small
+ * MutationObserver watches childList so a swapped-in control gets its
+ * `for=` and `aria-describedby` rebound.
  */
 import { AdiaElement } from '../../core/element.js';
 
@@ -60,41 +49,32 @@ class AdiaField extends AdiaElement {
   #labelMark = null;
   #hintEl = null;
   #errorEl = null;
-  #labelRow = null;
-  #controlRow = null;
-  #messageRow = null;
   #mo = null;
-  #restructuring = false;   // guard against MutationObserver self-trigger
 
-  // Label click handler — the native <label for="x"> affordance calls
-  // .focus() on the element with id "x". For a custom-element control
-  // like input-ui, that focuses the shadow/light host (tabindex=-1 by
-  // default), so focus falls through to body. Work around by finding
-  // the first focusable descendant inside the slotted control and
-  // focusing it explicitly.
+  // Label click → focus the first focusable descendant of the slotted
+  // control. The native `<label for="x">` affordance focuses the host
+  // by id, which for a custom-element control falls through to body
+  // (host typically tabindex=-1).
   #onLabelClick = (e) => {
     const ctrl = this.#findControl();
     if (!ctrl) return;
     const focusable = this.#firstFocusable(ctrl);
     if (!focusable) return;
-    e.preventDefault();  // prevent the native <label for> focus-host fallback
+    e.preventDefault();
     focusable.focus();
   };
 
   connected() {
-    this.#ensureRowWrappers();
     this.#ensureLabelElement();
     this.#ensureHintElement();
     this.#ensureErrorElement();
-    this.#restructure();
     this.#bindForToControl();
+    this.#labelEl?.addEventListener('click', this.#onLabelClick);
     this.#mo = new MutationObserver(() => {
-      if (this.#restructuring) return;
-      this.#restructure();
       this.#bindForToControl();
+      this.#wireAriaDescribedBy();
     });
-    this.#mo.observe(this, { childList: true, subtree: false });
-    this.#labelEl?.addEventListener('click', this.#onLabelClick);
+    this.#mo.observe(this, { childList: true });
   }
 
   disconnected() {
@@ -105,14 +85,12 @@ class AdiaField extends AdiaElement {
     this.#labelMark = null;
     this.#hintEl = null;
     this.#errorEl = null;
-    this.#labelRow = null;
-    this.#controlRow = null;
-    this.#messageRow = null;
   }
 
   render() {
-    // Keep label / hint / error text in sync with reactive props.
-    if (this.#labelEl) this.#labelEl.childNodes[0] && (this.#labelEl.childNodes[0].nodeValue = this.label || '');
+    if (this.#labelEl) {
+      this.#labelEl.childNodes[0] && (this.#labelEl.childNodes[0].nodeValue = this.label || '');
+    }
     if (this.#labelMark) this.#labelMark.hidden = !this.required;
     if (this.#hintEl) {
       this.#hintEl.textContent = this.hint || '';
@@ -122,50 +100,24 @@ class AdiaField extends AdiaElement {
       this.#errorEl.textContent = this.error || '';
       this.#errorEl.hidden = !this.error;
     }
-    // Collapse the message row entirely when both are empty so the
-    // field's trailing gap doesn't stick out.
-    if (this.#messageRow) {
-      this.#messageRow.hidden = !this.hint && !this.error;
-    }
     this.#wireAriaDescribedBy();
   }
 
   // ── Private ───────────────────────────────────────────────────────
 
-  #ensureRowWrappers() {
-    this.#labelRow = this.querySelector(':scope > [data-row="label"]');
-    this.#controlRow = this.querySelector(':scope > [data-row="control"]');
-    this.#messageRow = this.querySelector(':scope > [data-row="message"]');
-    if (!this.#labelRow) {
-      this.#labelRow = this.#mkRow('label');
-      this.appendChild(this.#labelRow);
-    }
-    if (!this.#controlRow) {
-      this.#controlRow = this.#mkRow('control');
-      this.appendChild(this.#controlRow);
-    }
-    if (!this.#messageRow) {
-      this.#messageRow = this.#mkRow('message');
-      this.appendChild(this.#messageRow);
-    }
-  }
-
-  #mkRow(name) {
-    const d = document.createElement('div');
-    d.setAttribute('data-row', name);
-    return d;
-  }
-
   #ensureLabelElement() {
-    this.#labelEl = this.querySelector(':scope [data-field-label]');
+    this.#labelEl = this.querySelector(':scope > [data-field-label]');
     if (!this.#labelEl) {
       const el = document.createElement('label');
+      el.setAttribute('slot', 'label');
       el.setAttribute('data-field-label', '');
       el.appendChild(document.createTextNode(this.label || ''));
+      // Prepend so source-order matches visual order (label before
+      // control). Not strictly required since CSS uses grid-area, but
+      // it keeps DevTools / a11y tree readings sensible.
+      this.prepend(el);
       this.#labelEl = el;
     }
-    // Persistent required marker — hidden when !required. Lives as the
-    // label's last child so the stream reads "<label>*</label>".
     this.#labelMark = this.#labelEl.querySelector('[data-field-required]');
     if (!this.#labelMark) {
       const mark = document.createElement('span');
@@ -179,71 +131,30 @@ class AdiaField extends AdiaElement {
   }
 
   #ensureHintElement() {
-    this.#hintEl = this.querySelector(':scope [data-field-hint]');
+    this.#hintEl = this.querySelector(':scope > [data-field-hint]');
     if (this.#hintEl) return;
     const el = document.createElement('div');
+    el.setAttribute('slot', 'hint');
     el.setAttribute('data-field-hint', '');
     el.setAttribute('id', AdiaField.#nextMsgId('hint'));
     el.hidden = true;
+    this.appendChild(el);
     this.#hintEl = el;
   }
 
   #ensureErrorElement() {
-    this.#errorEl = this.querySelector(':scope [data-field-error]');
+    this.#errorEl = this.querySelector(':scope > [data-field-error]');
     if (this.#errorEl) return;
     const el = document.createElement('div');
+    el.setAttribute('slot', 'error');
     el.setAttribute('data-field-error', '');
     el.setAttribute('id', AdiaField.#nextMsgId('err'));
     el.setAttribute('role', 'alert');
     el.hidden = true;
+    this.appendChild(el);
     this.#errorEl = el;
   }
 
-  /** Sort light-DOM children into the appropriate row wrapper.
-   *  Idempotent — no-ops when a child already sits in its target row. */
-  #restructure() {
-    this.#restructuring = true;
-    try {
-      // Collect any children that are not already row wrappers or our
-      // managed elements. `Array.from` is snapshotted — moves during
-      // iteration don't re-index.
-      const loose = [...this.children].filter(
-        (ch) => ch !== this.#labelRow && ch !== this.#controlRow && ch !== this.#messageRow,
-      );
-      for (const ch of loose) {
-        this.#moveToRow(ch);
-      }
-      // Then relocate managed elements (they may have been created in
-      // a previous tick and still sit at :scope level).
-      if (this.#labelEl && this.#labelEl.parentElement !== this.#labelRow) {
-        this.#labelRow.prepend(this.#labelEl);
-      }
-      if (this.#hintEl && this.#hintEl.parentElement !== this.#messageRow) {
-        this.#messageRow.appendChild(this.#hintEl);
-      }
-      if (this.#errorEl && this.#errorEl.parentElement !== this.#messageRow) {
-        this.#messageRow.appendChild(this.#errorEl);
-      }
-      // Ensure the row order is label → control → message even after
-      // mutations re-append things.
-      if (this.lastElementChild !== this.#messageRow) {
-        this.appendChild(this.#messageRow);
-      }
-    } finally {
-      this.#restructuring = false;
-    }
-  }
-
-  #moveToRow(ch) {
-    const slot = ch.getAttribute?.('slot');
-    const target =
-      ch.matches?.('[data-field-label]') ? this.#labelRow :
-      slot === 'trailing'                 ? this.#labelRow :
-      ch.matches?.('[data-field-hint], [data-field-error]') ? this.#messageRow :
-      /* everything else (control, slot=action) */           this.#controlRow;
-    if (ch.parentElement !== target) target.appendChild(ch);
-  }
-
   #bindForToControl() {
     if (!this.#labelEl) return;
     const control = this.#findControl();
@@ -270,20 +181,17 @@ class AdiaField extends AdiaElement {
     else ctrl.removeAttribute('aria-describedby');
   }
 
-  /** The default-slot control — first child of control-row that isn't
-   *  assigned to `[slot="action"]`. */
+  /** The default-slot control — first child without a `slot` attribute. */
   #findControl() {
-    if (!this.#controlRow) return null;
-    for (const ch of this.#controlRow.children) {
-      if (ch.getAttribute('slot') === 'action') continue;
-      return ch;
+    for (const ch of this.children) {
+      if (!ch.hasAttribute('slot')) return ch;
     }
     return null;
   }
 
   /** First focusable descendant (or self) of `root`. Looks for native
    *  `<input>`, `<textarea>`, `<select>`, `<button>`, `[contenteditable]`,
-   *  and any `[tabindex]` ≥ 0. Traverses light DOM only. */
+   *  and any `[tabindex]` ≥ 0. Light DOM only. */
   #firstFocusable(root) {
     const SEL = 'input, textarea, select, button, [contenteditable], [tabindex]:not([tabindex="-1"])';
     if (root.matches?.(SEL)) return root;
@@ -291,15 +199,9 @@ class AdiaField extends AdiaElement {
   }
 
   static #idSeq = 0;
-  static #nextId() {
-    AdiaField.#idSeq += 1;
-    return `field-ctl-${AdiaField.#idSeq}`;
-  }
+  static #nextId() { return `field-ctl-${++AdiaField.#idSeq}`; }
   static #msgSeq = 0;
-  static #nextMsgId(kind) {
-    AdiaField.#msgSeq += 1;
-    return `field-${kind}-${AdiaField.#msgSeq}`;
-  }
+  static #nextMsgId(kind) { return `field-${kind}-${++AdiaField.#msgSeq}`; }
 }
 
 customElements.define('field-ui', AdiaField);

package/components/icon/icon.a2ui.json

@@ -27,7 +27,7 @@
       "default": ""
     },
     "size": {
-      "description": "Icon size. Accepts the named scale (xs/sm/md/lg/xl) or a pixel value as a string (\"12\", \"16\", \"24\", \"32\", \"48\"). Overrides --a-icon-size.",
+      "description": "Icon size. Accepts the named scale (`xs` 12px / `sm` 14px / `md` 16px / `lg` 20px / `xl` 32px / `2xl` 48px / `3xl` 64px / `4xl` 96px / `fill` 100% of parent) or a free-form pixel / rem / em value as a string (\"48\", \"3rem\", \"1.25em\"). Overrides the inherited `--a-icon-size` from the universal `[size]` system on ancestors.",
       "type": "string",
       "default": ""
     },

package/components/icon/icon.css

@@ -17,4 +17,20 @@
     width: 100%;
     height: 100%;
   }
+
+  /* ── Named size scale ─────────────────────────────────────────────
+     sm/md/lg are also driven by the universal `[size]` token system
+     on ancestors (tokens.css §SIZE PRESETS) — these rules let an
+     icon-ui set its own size locally. xs / xl / 2xl / 3xl / 4xl
+     extend the scale beyond the universal range for hero placeholder
+     contexts. `fill` matches the parent box. */
+  :scope[size="xs"]   { --icon-size: 0.75rem; }   /* 12px */
+  :scope[size="sm"]   { --icon-size: 0.875rem; }  /* 14px */
+  :scope[size="md"]   { --icon-size: 1rem; }      /* 16px */
+  :scope[size="lg"]   { --icon-size: 1.25rem; }   /* 20px */
+  :scope[size="xl"]   { --icon-size: 2rem; }      /* 32px */
+  :scope[size="2xl"]  { --icon-size: 3rem; }      /* 48px */
+  :scope[size="3xl"]  { --icon-size: 4rem; }      /* 64px */
+  :scope[size="4xl"]  { --icon-size: 6rem; }      /* 96px */
+  :scope[size="fill"] { --icon-size: 100%; }
 }

package/components/icon/icon.js

@@ -19,6 +19,24 @@ class AdiaIcon extends AdiaElement {
     if (this.label) this.setAttribute('aria-label', this.label);
     const svg = getIcon(this.name, this.weight || 'regular');
     if (svg && this.innerHTML !== svg) this.innerHTML = svg;
+
+    // Pixel / rem / em passthrough — `size="48"` → 48px,
+    // `size="3.5rem"` → 3.5rem. Named-scale values (xs/sm/md/lg/xl/
+    // 2xl/3xl/4xl/fill) are handled by `:scope[size="…"]` rules in
+    // icon.css; we only set --icon-size inline for free-form values.
+    if (this.size && this.#isFreeFormSize(this.size)) {
+      this.style.setProperty('--icon-size', this.#normalizeSize(this.size));
+    } else if (this.style.getPropertyValue('--icon-size')) {
+      this.style.removeProperty('--icon-size');
+    }
+  }
+
+  #isFreeFormSize(s) {
+    return /^\d+(\.\d+)?(px|rem|em)?$/.test(s);
+  }
+
+  #normalizeSize(s) {
+    return /^\d+(\.\d+)?$/.test(s) ? `${s}px` : s;
   }
 }
 customElements.define('icon-ui', AdiaIcon);

package/components/icon/icon.yaml

@@ -18,8 +18,12 @@ props:
     default: ""
   size:
     description: >-
-      Icon size. Accepts the named scale (xs/sm/md/lg/xl) or a pixel value
-      as a string ("12", "16", "24", "32", "48"). Overrides --a-icon-size.
+      Icon size. Accepts the named scale
+      (`xs` 12px / `sm` 14px / `md` 16px / `lg` 20px / `xl` 32px /
+      `2xl` 48px / `3xl` 64px / `4xl` 96px / `fill` 100% of parent)
+      or a free-form pixel / rem / em value as a string ("48", "3rem",
+      "1.25em"). Overrides the inherited `--a-icon-size` from the
+      universal `[size]` system on ancestors.
     type: string
     default: ""
   weight:

package/components/index.js

@@ -3,12 +3,19 @@
  * Import this single file to register all custom elements.
  */
 
+/* Side-effect import — auto-attaches the document-level MutationObserver
+   that drives `data-stream-*` attribute behavior on any element with a
+   settable `.data` property (chart-ui, table-ui, heatmap-ui, stat-ui,
+   list-ui). See packages/web-components/core/data-stream.js. */
+import '../core/data-stream.js';
+
 export { AdiaIcon } from './icon/icon.js';
 export { AdiaButton } from './button/button.js';
 export { AdiaInput } from './input/input.js';
 export { AdiaTextarea } from './textarea/textarea.js';
 export { AdiaCheck } from './check/check.js';
 export { AdiaRadio } from './radio/radio.js';
+export { AdiaOptionCard } from './option-card/option-card.js';
 export { AdiaSwitch } from './switch/switch.js';
 export { AdiaSlider } from './slider/slider.js';
 export { AdiaSelect } from './select/select.js';

package/components/input/input.a2ui.json

@@ -52,7 +52,7 @@
       "default": ""
     },
     "label": {
-      "description": "Label text rendered above the input field",
+      "description": "Inline label rendered as a leading caption inside the input chrome, between any prefix and the value. Wires aria-labelledby on the editable surface. For stacked label / hint / error compositions, wrap with field-ui.",
       "type": "string",
       "default": ""
     },

package/components/input/input.css

@@ -11,11 +11,8 @@
     --input-height:          var(--a-size);
     --input-px:              var(--a-ui-px);
     --input-font-size:       var(--a-ui-size);
-    --input-label-size:      var(--a-label-size);
-    --input-label-fg:        var(--a-label-color);
     --input-placeholder-fg:  var(--a-ui-text-placeholder);
     --input-affix-fg:        var(--a-ui-text-placeholder);
-    --input-gap:             var(--a-ui-py);
     --input-field-gap:       var(--a-space-1);
 
     /* ── Transitions ── */
@@ -23,10 +20,10 @@
     --input-easing:          var(--a-easing);
 
     /* ── State: hover/focus ── */
+    --input-bg-hover:        var(--a-ui-bg-hover);
     --input-fg-hover:        var(--a-fg);
     --input-affix-fg-hover:  var(--a-fg-subtle);
-    --input-fg-focus:        var(--a-fg);
-    --input-label-fg-focus:  var(--a-fg-subtle);
+    --input-fg-focus:        var(--a-fg-strong);
 
     /* ── State: disabled ── */
     --input-bg-disabled:     var(--a-ui-bg-disabled);
@@ -36,23 +33,20 @@
   :scope {
     /* ── Base ── */
     box-sizing: border-box;
-    display: flex;
-    flex-direction: column;
-    gap: var(--input-gap);
+    display: block;
   }
 
-  :scope[data-direction="row"] {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-    align-items: center;
-  }
-
-  /* Label */
+  /* Inline label — sits inside [slot="field"] as a leading caption,
+     between [slot="prefix"] and [slot="text"]. Dim by default; shares
+     the input chrome border. For stacked label / hint / error, wrap
+     with field-ui. */
   [slot="label"] {
-    font-size: var(--input-label-size);
-    color: var(--input-label-fg);
+    flex-shrink: 0;
+    color: var(--input-affix-fg);
+    font-size: var(--input-font-size);
+    user-select: none;
+    pointer-events: none;
   }
-  [slot="label"][label]::after { content: attr(label); }
 
   /* Field container */
   [slot="field"] {
@@ -67,11 +61,18 @@
     color: var(--input-fg);
     font: inherit;
     font-size: var(--input-font-size);
-    line-height: 1;
+    /* line-height: 1.4 (not 1) so descender-bearing glyphs (g, j, p, q, y)
+       have room inside [slot="text"]'s line box. With line-height: 1 the
+       line box equals the em-square and descenders extend below it; the
+       overflow: hidden on [slot="text"] then clips them. The min-height
+       still controls overall chrome height — align-items: center keeps the
+       baseline centered regardless of line-height. */
+    line-height: 1.4;
     cursor: text;
     transition: border-color var(--input-duration) var(--input-easing);
   }
   :scope:not([disabled]) [slot="field"]:hover {
+    background: var(--input-bg-hover);
     border-color: var(--input-border-hover);
     color: var(--input-fg-hover);
   }
@@ -90,9 +91,6 @@
   :scope[error]:not([disabled]):focus-within [slot="field"] {
     box-shadow: var(--input-focus-ring-invalid);
   }
-  :scope:not([disabled]):focus-within [slot="label"] {
-    color: var(--input-label-fg-focus);
-  }
 
   /* Text (contenteditable span) */
   [slot="text"] {
@@ -120,7 +118,7 @@
 
   /* Placeholder (contenteditable only) */
   span[slot="text"][data-empty]::before {
-    content: attr(aria-placeholder);
+    content: attr(data-placeholder);
     color: var(--input-placeholder-fg);
     pointer-events: none;
   }

package/components/input/input.js

@@ -2,9 +2,17 @@
  * <input-ui> — Text input. The host IS the interactive surface.
  * Uses contenteditable for text entry, ElementInternals for form participation.
  *
- * Supports prefix/suffix slots:
- *   <input-ui label="Weight" suffix="kg"></input-ui>
- *   <input-ui placeholder="Search" prefix="search"></input-ui>
+ * Slots inside [slot="field"]:
+ *   prefix → label → text → suffix
+ *
+ *   <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>
+ *
+ * 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.
  */
 
 import { AdiaFormElement } from '../../core/form.js';
@@ -15,6 +23,13 @@ const renderAffix = (v) => isIconName(v)
   : v;
 
 class AdiaInput extends AdiaFormElement {
+  // Opt out of AdiaFormElement's per-control `label` deprecation warning.
+  // input-ui's `label` is a first-class API rendering an inline-leading
+  // caption inside the chrome with `aria-labelledby` wiring on the
+  // editable surface — not the inert above-the-field rendering that
+  // motivated the deprecation.
+  static labelDeprecated = false;
+
   static properties = {
     ...AdiaFormElement.properties,
     placeholder: { type: String,  default: '', reflect: true },
@@ -28,6 +43,8 @@ class AdiaInput extends AdiaFormElement {
   static template = () => null;
 
   #textEl = null;
+  #labelEl = null;
+  static #labelSeq = 0;
 
   get #isNativeInput() {
     return this.type === 'password' || this.type === 'number';
@@ -39,24 +56,28 @@ class AdiaInput extends AdiaFormElement {
 
     if (!this.querySelector('[slot="text"]')) {
       const useNative = this.#isNativeInput;
+      const labelId = this.label ? `input-label-${++AdiaInput.#labelSeq}` : '';
       this.innerHTML = `
-        ${this.label ? `<label slot="label" label="${this.label}"></label>` : ''}
         <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=""'}
-                    aria-placeholder="${this.placeholder}"></span>`}
+                    ${labelId ? `aria-labelledby="${labelId}"` : ''}
+                    data-placeholder="${this.placeholder}"></span>`}
           ${this.suffix ? `<span slot="suffix">${renderAffix(this.suffix)}</span>` : ''}
         </div>
       `;
     }
 
     this.#textEl = this.querySelector('[slot="text"]');
+    this.#labelEl = this.querySelector('[slot="label"]');
     if (!this.#isNativeInput && this.value) this.#textEl.textContent = this.value;
 
     if (this.#textEl) {
@@ -75,7 +96,7 @@ class AdiaInput extends AdiaFormElement {
       this.#textEl.disabled = this.disabled;
       this.#textEl.readOnly = this.readonly;
     } else {
-      this.#textEl.setAttribute('aria-placeholder', this.placeholder);
+      this.#textEl.setAttribute('data-placeholder', this.placeholder);
       if (this.disabled || this.readonly) {
         this.#textEl.contentEditable = 'false';
       } else {
@@ -83,10 +104,15 @@ class AdiaInput extends AdiaFormElement {
       }
     }
 
-    const label = this.querySelector('[slot="label"]');
-    if (label && this.label) label.setAttribute('label', this.label);
+    if (this.#labelEl) this.#labelEl.textContent = this.label || '';
 
-    this.setAttribute('aria-label', this.label || this.placeholder || '');
+    if (this.label) {
+      this.removeAttribute('aria-label');
+    } else if (this.placeholder) {
+      this.setAttribute('aria-label', this.placeholder);
+    } else {
+      this.removeAttribute('aria-label');
+    }
   }
 
   #onInput = () => {
@@ -141,6 +167,7 @@ class AdiaInput extends AdiaFormElement {
       this.#textEl.removeEventListener('paste', this.#onPaste);
     }
     this.#textEl = null;
+    this.#labelEl = null;
   }
 }
 customElements.define('input-ui', AdiaInput);

package/components/input/input.yaml

@@ -47,7 +47,9 @@ props:
     type: string
     default: ""
   label:
-    description: Label text rendered above the input field
+    description: Inline label rendered as a leading caption inside the input chrome,
+      between any prefix and the value. Wires aria-labelledby on the editable
+      surface. For stacked label / hint / error compositions, wrap with field-ui.
     type: string
     default: ""
   maxlength: