@adia-ai/web-components 0.0.10 → 0.0.12

package/components/field/field.a2ui.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Field.json",
+  "title": "Field",
+  "description": "Labeled field wrapper. Composes a <label for=\"…\"> with a form control (input-ui, select-ui, textarea-ui, etc.) placed in the default slot, plus optional [slot=\"trailing\"] and [slot=\"action\"] regions. Auto-mints an id on the slotted control when missing so clicking the label focuses the control — an accessibility upgrade over setting label=\"…\" on the control directly, which has no [for] binding. Two layouts — stacked (default) and inline (the `inline` mode attribute collapses everything to a single row).",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "required": {
+      "description": "Renders a \"*\" marker on the label. Does not itself enforce validation — the slotted control's own `required` attr does that; this is a visual signal only.",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "Field"
+    },
+    "error": {
+      "description": "Validation error message rendered below the control in danger style. Takes precedence over `hint` in the same row, and carries role=\"alert\" so screen readers announce changes.",
+      "type": "string",
+      "default": ""
+    },
+    "hint": {
+      "description": "Help text rendered below the control in caption style. Wired into the slotted control's aria-describedby so screen readers announce it. Suppressed when `error` is set.",
+      "type": "string",
+      "default": ""
+    },
+    "inline": {
+      "description": "Lay out label, trailing, control, and action on a single row instead of the stacked default (mode attribute — changes grid geometry, not tokens). Hint/error still render on their own row below.",
+      "type": "boolean",
+      "default": false
+    },
+    "label": {
+      "description": "Label text rendered in the label row.",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "form",
+    "events": {},
+    "examples": [
+      {
+        "description": "A simple stacked email field with a trailing \"Required\" hint and a clear-button action adjacent to the input.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Field\",\n    \"label\": \"Email\",\n    \"children\": [\"email\", \"hint\", \"clear\"]\n  },\n  { \"id\": \"email\", \"component\": \"Input\", \"type\": \"email\", \"value\": \"you@example.com\" },\n  { \"id\": \"hint\",  \"component\": \"Text\",  \"slot\": \"trailing\", \"text\": \"Required\" },\n  { \"id\": \"clear\", \"component\": \"Button\", \"slot\": \"action\", \"icon\": \"x\", \"variant\": \"ghost\" }\n]",
+        "name": "stacked-email-field"
+      },
+      {
+        "description": "An inline search field — label beside the input, with a trailing keyboard-shortcut hint.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Field\",\n    \"label\": \"Search\",\n    \"inline\": true,\n    \"children\": [\"q\", \"kbd\"]\n  },\n  { \"id\": \"q\",   \"component\": \"Input\", \"type\": \"search\", \"placeholder\": \"Type…\" },\n  { \"id\": \"kbd\", \"component\": \"Kbd\",   \"slot\": \"trailing\", \"text\": \"⌘K\" }\n]",
+        "name": "inline-search-field"
+      }
+    ],
+    "keywords": [
+      "field",
+      "form",
+      "label",
+      "input",
+      "wrapper"
+    ],
+    "name": "AdiaField",
+    "related": [
+      "input",
+      "select",
+      "textarea",
+      "check",
+      "radio",
+      "switch",
+      "slider"
+    ],
+    "slots": {
+      "default": {
+        "description": "The form control — input-ui, select-ui, textarea-ui, check-ui, switch-ui, radio-ui, slider-ui, etc. Auto-id'd for the label's [for] binding."
+      },
+      "action": {
+        "description": "Button adjacent to the control for inline actions (clear, reset, help popover)."
+      },
+      "trailing": {
+        "description": "Secondary text or badge aligned with the label in the stacked layout (right-aligned) or between label and control in the inline layout."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "form": [
+        "field",
+        "label",
+        "input"
+      ],
+      "label": [
+        "field",
+        "form"
+      ]
+    },
+    "tag": "field-ui",
+    "tokens": {
+      "--field-error-color": {
+        "description": "Error text color (also drives the required-marker color)."
+      },
+      "--field-error-size": {
+        "description": "Error text size."
+      },
+      "--field-gap": {
+        "description": "Gap between rows/cells of the field grid."
+      },
+      "--field-hint-color": {
+        "description": "Hint text color."
+      },
+      "--field-hint-size": {
+        "description": "Hint text size."
+      },
+      "--field-label-color": {
+        "description": "Label foreground color."
+      },
+      "--field-label-size": {
+        "description": "Label font size."
+      },
+      "--field-label-weight": {
+        "description": "Label font weight."
+      },
+      "--field-required-color": {
+        "description": "Color of the `*` required marker on the label."
+      },
+      "--field-trailing-color": {
+        "description": "Trailing text color."
+      },
+      "--field-trailing-size": {
+        "description": "Trailing text size."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/field/field.css

@@ -0,0 +1,111 @@
+@scope (field-ui) {
+  :where(:scope) {
+    /* ── Tokens ── */
+    --field-gap:             var(--a-space-2);
+    --field-label-color:     var(--a-fg);
+    --field-label-size:      var(--a-ui-sm);
+    --field-label-weight:    var(--a-weight-medium);
+    --field-required-color:  var(--a-danger);
+    --field-trailing-color:  var(--a-fg-subtle);
+    --field-trailing-size:   var(--a-ui-tiny);
+    --field-hint-color:      var(--a-fg-muted);
+    --field-hint-size:       var(--a-ui-tiny);
+    --field-error-color:     var(--a-danger);
+    --field-error-size:      var(--a-ui-tiny);
+  }
+
+  /* ── Base — stacked: three flex rows stacked vertically.
+       Each row is its own flex container so `trailing` and `action`
+       size independently (the previous single-grid shared column 2
+       across rows and made them co-sized). ── */
+  :scope {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: var(--field-gap);
+  }
+
+  :scope > [data-row] {
+    display: flex;
+    align-items: center;
+    gap: var(--field-gap);
+    min-width: 0;
+  }
+
+  /* label-row — label grows, trailing auto-sizes and right-aligns. */
+  :scope > [data-row="label"] > [data-field-label] {
+    flex: 1 1 auto;
+    color: var(--field-label-color);
+    font-size: var(--field-label-size);
+    font-weight: var(--field-label-weight);
+    cursor: pointer;
+    min-width: 0;
+  }
+  :scope > [data-row="label"] > [data-field-label] > [data-field-required] {
+    color: var(--field-required-color);
+    margin-inline-start: 0.15em;
+    font-weight: var(--a-weight-bold);
+  }
+  :scope > [data-row="label"] > [slot="trailing"] {
+    flex: 0 0 auto;
+    color: var(--field-trailing-color);
+    font-size: var(--field-trailing-size);
+  }
+
+  /* control-row — control grows, action auto-sizes. */
+  :scope > [data-row="control"] > :not([slot="action"]) {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+  :scope > [data-row="control"] > [slot="action"] {
+    flex: 0 0 auto;
+  }
+
+  /* message-row — hint or error; collapsed via [hidden] when both empty. */
+  :scope > [data-row="message"] > [data-field-hint] {
+    color: var(--field-hint-color);
+    font-size: var(--field-hint-size);
+    line-height: 1.3;
+  }
+  :scope > [data-row="message"] > [data-field-error] {
+    color: var(--field-error-color);
+    font-size: var(--field-error-size);
+    line-height: 1.3;
+    font-weight: var(--a-weight-medium);
+  }
+
+  /* Hide the whole label-row when there's no label AND no trailing —
+     prevents an empty row stealing vertical gap. */
+  :scope:not([label]) > [data-row="label"] > [data-field-label] {
+    display: none;
+  }
+  :scope:not([label]) > [data-row="label"]:not(:has(> [slot="trailing"])) {
+    display: none;
+  }
+
+  /* ── Mode: inline — flatten label-row + control-row into a single
+       grid row. `display: contents` promotes the row wrappers' children
+       directly to :scope's grid, keeping per-cell independence. The
+       message-row stays a block row below. ── */
+  :scope[inline] {
+    display: grid;
+    grid-template-columns: auto auto 1fr auto;
+    grid-template-rows: auto auto;
+    gap: var(--field-gap);
+    align-items: center;
+  }
+  :scope[inline] > [data-row="label"],
+  :scope[inline] > [data-row="control"] {
+    display: contents;
+  }
+  :scope[inline] > [data-row="label"] > [data-field-label]        { grid-column: 1; grid-row: 1; justify-self: start; }
+  :scope[inline] > [data-row="label"] > [slot="trailing"]         { grid-column: 2; grid-row: 1; justify-self: start; }
+  :scope[inline] > [data-row="control"] > :not([slot="action"])   { grid-column: 3; grid-row: 1; }
+  :scope[inline] > [data-row="control"] > [slot="action"]         { grid-column: 4; grid-row: 1; justify-self: end; }
+  :scope[inline] > [data-row="message"] {
+    grid-column: 1 / -1;
+    grid-row: 2;
+    display: flex;
+    gap: var(--field-gap);
+  }
+}

package/components/field/field.js

@@ -0,0 +1,306 @@
+/**
+ * field-ui — Labeled field wrapper.
+ *
+ *   <field-ui label="Email" hint="We'll never share" required>
+ *     <input-ui value="you@example.com" type="email"></input-ui>
+ *     <span slot="trailing">Optional</span>
+ *     <button-ui slot="action" icon="x" aria-label="Clear"></button-ui>
+ *   </field-ui>
+ *
+ * Wraps a form control with its label + optional hint, error, trailing,
+ * 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).
+ *
+ * ### Layout — three internal flex rows
+ *
+ * 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:
+ *
+ *   <div data-row="label">    label [+required marker] [+trailing]  </div>
+ *   <div data-row="control">  control [+action]                     </div>
+ *   <div data-row="message">  hint or error                         </div>
+ *
+ * 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.
+ *
+ * ### 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.
+ */
+import { AdiaElement } from '../../core/element.js';
+
+class AdiaField extends AdiaElement {
+  static properties = {
+    label:    { type: String,  default: '',    reflect: true },
+    hint:     { type: String,  default: '',    reflect: true },
+    error:    { type: String,  default: '',    reflect: true },
+    required: { type: Boolean, default: false, reflect: true },
+    inline:   { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  #labelEl = null;
+  #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.
+  #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
+    focusable.focus();
+  };
+
+  connected() {
+    this.#ensureRowWrappers();
+    this.#ensureLabelElement();
+    this.#ensureHintElement();
+    this.#ensureErrorElement();
+    this.#restructure();
+    this.#bindForToControl();
+    this.#mo = new MutationObserver(() => {
+      if (this.#restructuring) return;
+      this.#restructure();
+      this.#bindForToControl();
+    });
+    this.#mo.observe(this, { childList: true, subtree: false });
+    this.#labelEl?.addEventListener('click', this.#onLabelClick);
+  }
+
+  disconnected() {
+    this.#mo?.disconnect();
+    this.#mo = null;
+    this.#labelEl?.removeEventListener('click', this.#onLabelClick);
+    this.#labelEl = null;
+    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.#labelMark) this.#labelMark.hidden = !this.required;
+    if (this.#hintEl) {
+      this.#hintEl.textContent = this.hint || '';
+      this.#hintEl.hidden = !this.hint || Boolean(this.error);
+    }
+    if (this.#errorEl) {
+      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]');
+    if (!this.#labelEl) {
+      const el = document.createElement('label');
+      el.setAttribute('data-field-label', '');
+      el.appendChild(document.createTextNode(this.label || ''));
+      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');
+      mark.setAttribute('data-field-required', '');
+      mark.setAttribute('aria-hidden', 'true');
+      mark.textContent = '*';
+      mark.hidden = true;
+      this.#labelEl.appendChild(mark);
+      this.#labelMark = mark;
+    }
+  }
+
+  #ensureHintElement() {
+    this.#hintEl = this.querySelector(':scope [data-field-hint]');
+    if (this.#hintEl) return;
+    const el = document.createElement('div');
+    el.setAttribute('data-field-hint', '');
+    el.setAttribute('id', AdiaField.#nextMsgId('hint'));
+    el.hidden = true;
+    this.#hintEl = el;
+  }
+
+  #ensureErrorElement() {
+    this.#errorEl = this.querySelector(':scope [data-field-error]');
+    if (this.#errorEl) return;
+    const el = document.createElement('div');
+    el.setAttribute('data-field-error', '');
+    el.setAttribute('id', AdiaField.#nextMsgId('err'));
+    el.setAttribute('role', 'alert');
+    el.hidden = true;
+    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();
+    if (!control) {
+      this.#labelEl.removeAttribute('for');
+      return;
+    }
+    if (!control.id) control.id = AdiaField.#nextId();
+    this.#labelEl.setAttribute('for', control.id);
+  }
+
+  /** Wire `aria-describedby` on the slotted control to the hint/error
+   *  ids. Keeps any consumer-set describedby ids; appends ours. */
+  #wireAriaDescribedBy() {
+    const ctrl = this.#findControl();
+    if (!ctrl) return;
+    const ours = new Set();
+    if (this.#hintEl && !this.#hintEl.hidden) ours.add(this.#hintEl.id);
+    if (this.#errorEl && !this.#errorEl.hidden) ours.add(this.#errorEl.id);
+    const existing = (ctrl.getAttribute('aria-describedby') || '')
+      .split(/\s+/).filter((s) => s && !s.startsWith('field-hint-') && !s.startsWith('field-err-'));
+    const merged = [...existing, ...ours].join(' ').trim();
+    if (merged) ctrl.setAttribute('aria-describedby', merged);
+    else ctrl.removeAttribute('aria-describedby');
+  }
+
+  /** The default-slot control — first child of control-row that isn't
+   *  assigned to `[slot="action"]`. */
+  #findControl() {
+    if (!this.#controlRow) return null;
+    for (const ch of this.#controlRow.children) {
+      if (ch.getAttribute('slot') === 'action') continue;
+      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. */
+  #firstFocusable(root) {
+    const SEL = 'input, textarea, select, button, [contenteditable], [tabindex]:not([tabindex="-1"])';
+    if (root.matches?.(SEL)) return root;
+    return root.querySelector?.(SEL) ?? null;
+  }
+
+  static #idSeq = 0;
+  static #nextId() {
+    AdiaField.#idSeq += 1;
+    return `field-ctl-${AdiaField.#idSeq}`;
+  }
+  static #msgSeq = 0;
+  static #nextMsgId(kind) {
+    AdiaField.#msgSeq += 1;
+    return `field-${kind}-${AdiaField.#msgSeq}`;
+  }
+}
+
+customElements.define('field-ui', AdiaField);
+export { AdiaField };