@adia-ai/web-components 0.8.43 → 0.8.45

package/components/chart-legend/chart-legend.yaml

@@ -23,8 +23,12 @@ props:
     reflect: true
   items:
     description: >-
-      JSON array of {key, label, slot?, pct?} legend items. Takes precedence
-      over [for] when both are provided.
+      JSON array of {key, label, slot?, pct?, deemphasized?} legend items.
+      Takes precedence over [for] when both are provided. `deemphasized`
+      (REQ-R-007) mutes the row's swatch/label to the same muted-neutral
+      tier chart-ui's own internal legend uses for a de-emphasized series
+      (e.g. `composed@1:1`'s secondary line) — mirrored automatically from
+      a `[for]`-bound chart's own `.legendData`, or settable explicitly here.
     type: string
     default: ''
   shape:
@@ -38,7 +42,11 @@ props:
       - dashed
     reflect: true
   position:
-    description: Layout hint — drives flex-direction. Actual placement follows DOM order.
+    description: >-
+      Layout hint — drives flex-direction. Actual placement follows DOM
+      order. Superseded by a resolved `ratio` bucket (below) whenever one
+      is in effect; this is the pre-ADR-0074 fallback for a legend with
+      neither an explicit `ratio` nor a `[for]`-bound chart.
     type: string
     default: bottom
     enum:
@@ -47,6 +55,26 @@ props:
       - left
       - right
     reflect: true
+  ratio:
+    description: >-
+      Chart 2.0 legend layout bucket (ADR-0074, gh#1624 plan step 5,
+      REQ-R-005): 3:2 renders a horizontal row, 1:1 a wrapped 2-column
+      grid, 2:3 a vertical stacked list. An explicit value PINS the
+      bucket regardless of any bound chart. Unset (default) auto-mirrors
+      the `[for]`-bound chart's own resolved `data-ratio-resolved` bucket
+      — the legend never runs its own container-query classification,
+      since its own box is typically a thin strip with no studied aspect
+      of its own. With neither a pin nor a bound chart, no bucket
+      resolves and `position`'s flex-direction rules apply unchanged. The
+      resolved bucket reflects read-only onto the host as
+      `data-ratio-resolved`, mirroring chart-ui's own convention.
+    type: string
+    default: ""
+    enum:
+      - "3:2"
+      - "1:1"
+      - "2:3"
+    reflect: true
   interactive:
     description: >-
       Canonical opt-in spelling (ADR-0063, gh#1563) — the deprecated
@@ -107,6 +135,8 @@ a2ui:
       reason: 'Composition contract.'
     - rule: 'position attribute (top|bottom|left|right) places legend relative to its chart; interactive="false" disables interactivity.'
       reason: 'Layout + interaction knobs.'
+    - rule: 'ratio attribute (3:2|1:1|2:3, ADR-0074) selects the legend layout shape (row/grid/list); left unset it auto-mirrors a [for]-bound chart''s own resolved ratio.'
+      reason: 'Ratio-responsive layout contract, gh#1624 plan step 5.'
 anti_patterns: []
 examples:
   - name: standalone-with-items
@@ -119,6 +149,16 @@ examples:
           "items": "[{\"key\":\"revenue\",\"label\":\"Revenue\",\"slot\":0},{\"key\":\"users\",\"label\":\"Users\",\"slot\":1}]"
         }
       ]
+  - name: ratio-pinned-grid
+    description: Standalone legend pinned to the 1:1 (2-col grid) layout bucket.
+    a2ui: >-
+      [
+        {
+          "id": "legend", "component": "ChartLegend",
+          "ratio": "1:1",
+          "items": "[{\"key\":\"revenue\",\"label\":\"Revenue\",\"slot\":0},{\"key\":\"users\",\"label\":\"Users\",\"slot\":1},{\"key\":\"churn\",\"label\":\"Churn\",\"slot\":2},{\"key\":\"nps\",\"label\":\"NPS\",\"slot\":3}]"
+        }
+      ]
   - name: mirror-chart-by-id
     description: Legend mirrors a named chart's series data.
     a2ui: >-

package/components/combobox/combobox.a2ui.json

@@ -339,6 +339,9 @@
       "--combobox-match-bg": {
         "description": "Background for `<mark>` spans that highlight matched substrings"
       },
+      "--combobox-min-width": {
+        "description": "Intrinsic min-width floor on the host (default `20ch`, matching input-ui's own `--input-min-width` UA-baseline derivation) so a combobox in a shrinking flex/grid cell doesn't crush to unusable width. Set to `0` to opt back into full collapse (gh#1633)."
+      },
       "--combobox-option-bg-active": {
         "description": "Background for the currently active (arrow-navigated) option"
       },

package/components/combobox/combobox.class.js

@@ -41,6 +41,7 @@ import { UIFormElement } from '../../core/form.js';
 import { anchorPopover } from '../../core/anchor.js';
 import { untracked } from '../../core/signals.js';
 import { logicalSlotted } from '../../core/logical-children.js';
+import { syncAutoAriaLabel } from '../../core/a11y.js';
 
 function escapeHTML(s) {
   return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -103,6 +104,10 @@ export class UICombobox extends UIFormElement {
   #anchorCleanup = null;
   #rafId = null;
   #instanceId = `combobox-${++cbInstanceSeq}`;
+  // gh#1647: tracks the aria-label VALUE this element itself last derived
+  // from `placeholder` (undefined when none) — value-tracking guard
+  // ported from tag.class.js/select.class.js (gh#1644/#1646).
+  #lastAutoAriaLabel = undefined;
 
   // ── Stable handler refs (so removeEventListener finds them) ──
   #onInputEvent = () => this.#handleInput();
@@ -176,14 +181,10 @@ export class UICombobox extends UIFormElement {
       this.#labelEl.style.display = this.label ? '' : 'none';
     }
 
-    // aria-label fallback when no [label] is set.
-    if (this.label) {
-      this.removeAttribute('aria-label');
-    } else if (this.placeholder) {
-      this.setAttribute('aria-label', this.placeholder);
-    } else {
-      this.removeAttribute('aria-label');
-    }
+    // aria-label fallback when no [label] is set (gh#1647) — never clobber
+    // a consumer's own aria-label (value-tracking guard, gh#1644/#1646).
+    const ariaSource = this.label ? '' : (this.placeholder || '');
+    this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, ariaSource);
 
     // Toggle clear-button visibility when [clearable].
     if (this.#clearBtn) {

package/components/combobox/combobox.css

@@ -6,6 +6,15 @@
     --combobox-height:              var(--a-size);
     --combobox-px:                  var(--a-ui-px);
     --combobox-radius:              var(--a-radius);
+    /* gh#1633 / ADIA2-9136 (adiav2#12791) — the host's own `min-width: 0`
+       below (the ellipsis-reset trick, kept for [data-input] inside this
+       floor) had no intrinsic lower bound, so a combobox in a shrinking
+       flex/grid cell crushed to unusable width — the same gap already
+       fixed on --input-min-width (this family's reference; see input.css,
+       gh#781) and on --select-min-width (same fix, select.css). Same
+       ch-based UA-baseline derivation. Override to 0 to opt back into
+       full collapse. */
+    --combobox-min-width:           20ch;
 
     /* ── Typography ── */
     --combobox-font-size:           var(--a-ui-size);
@@ -62,7 +71,11 @@
     flex-direction: column;
     gap: var(--combobox-gap);
     position: relative;
-    min-width: 0;
+    /* Floored, not zeroed — see --combobox-min-width above (gh#1633).
+       [data-input]'s own `min-width: 0` further down stays 0: that one
+       exists so its value text can ellipsis-truncate INSIDE this floor,
+       not to guard the host's own collapse. */
+    min-width: var(--combobox-min-width);
     /* font-family floor on the host — internal input/options inherit it. */
     font-family: var(--combobox-font-family, var(--a-font-family-ui));
     font-size: var(--combobox-font-size);
@@ -326,9 +339,17 @@ combobox-ui [data-listbox] [role="group"] [data-group-label] {
   white-space: nowrap;
 }
 
-combobox-ui [data-empty],
-combobox-ui [data-loading],
-combobox-ui [data-footer] {
+/* Scoped to `[data-listbox]`'s own markers — gh#1700, same shape as
+   gh#1697/#1698. The input span (`[data-input]`) toggles the SAME
+   `data-empty` attribute for an unrelated reason (gating its own
+   `::before` placeholder pseudo) — a bare, unscoped `combobox-ui
+   [data-empty]` selector matched BOTH uses, and (being (0,1,1)) outranked
+   `[data-input]`'s own (0,1,0) padding/color/font-size, one property away
+   from repeating the command-ui leak. Scoping to the listbox container
+   removes the collision at its root. */
+combobox-ui [data-listbox] [data-empty],
+combobox-ui [data-listbox] [data-loading],
+combobox-ui [data-listbox] [data-footer] {
   padding: var(--a-space-2) var(--a-ui-px);
   color: var(--a-ui-text-muted);
   font-size: var(--a-ui-size);

package/components/combobox/combobox.yaml

@@ -257,6 +257,12 @@ tokens:
       tinted selected row.
   --combobox-match-bg:
     description: Background for `<mark>` spans that highlight matched substrings
+  --combobox-min-width:
+    description: >-
+      Intrinsic min-width floor on the host (default `20ch`, matching
+      input-ui's own `--input-min-width` UA-baseline derivation) so a
+      combobox in a shrinking flex/grid cell doesn't crush to unusable
+      width. Set to `0` to opt back into full collapse (gh#1633).
 requiredIcons:
   - caret-down
   - x-circle

package/components/command/command.css

@@ -221,7 +221,23 @@
   }
 
   /* ── Empty state ── */
-  [data-empty] {
+  /* Scoped to `[slot="list"]`'s own `[data-empty]` — gh#1697. The search
+     input (`& > header [slot="input"]`) toggles the SAME `data-empty`
+     attribute for an unrelated reason (gating its own `::before`
+     placeholder pseudo, per REQ above) — a bare, unscoped `[data-empty]`
+     selector matched BOTH uses, so this rule's `text-align: center` leaked
+     onto the input span whenever it was empty, centering the placeholder
+     (and, structurally, any text a consumer's own script inserted while
+     the attribute was still present). `padding`/`color` never leaked in
+     practice — `& > header [slot="input"]`'s own compound selector
+     (header-descendant + attribute, (0,1,1)) already outranks the bare
+     `[data-empty]` (0,1,0) for those two properties — but `text-align` had
+     no competing declaration anywhere else in this file, so the leaked
+     value won by default with nothing to lose against. Scoping the
+     selector to the list container removes the collision at its root
+     instead of only patching the one property a screenshot happened to
+     catch. */
+  [slot="list"] [data-empty] {
     padding: var(--command-py) var(--command-px);
     color: var(--command-empty-fg);
     text-align: center;

package/components/context-menu/context-menu.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ContextMenu.json",
   "title": "ContextMenu",
-  "description": "Right-click activated menu — the OS-native context-menu pattern as a\nweb component. Distinct from `menu-ui` (which is button-triggered):\nsame item shape (`menu-item-ui` children), different trigger surface\n(`contextmenu` event), and pointer-anchored positioning instead of\nelement-anchored. Pattern: WAI-APG Menu.\n\nTwo binding modes:\n **A. Wrap.** Default-slot child becomes the target:\n `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.\n **B. Selector.** Point at one or more existing elements via [for]:\n `<context-menu-ui for=\"#my-table\">...items</context-menu-ui>`.\n\nOn `contextmenu` event on a target: `preventDefault()`, position the\nmenu at the pointer coords, show via Popover API. Touch long-press\n(configurable via [long-press-ms]) does the same. Shift+F10 / Menu\nkey opens at the focused target's center for keyboard users.\n",
+  "description": "Right-click activated menu — the OS-native context-menu pattern as a\nweb component. Distinct from `menu-ui` (which is button-triggered):\nsame item shape (`menu-item-ui` children), different trigger surface\n(`contextmenu` event), and pointer-anchored positioning instead of\nelement-anchored. Pattern: WAI-APG Menu.\n\nTwo binding modes:\n **A. Wrap.** Default-slot child becomes the target:\n `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.\n **B. Selector.** Point at one or more existing elements via\n [target-selector]:\n `<context-menu-ui target-selector=\"#my-table\">...items</context-menu-ui>`.\n\nOn `contextmenu` event on a target: `preventDefault()`, position the\nmenu at the pointer coords, show via Popover API. Touch long-press\n(configurable via [long-press-ms]) does the same. Shift+F10 / Menu\nkey opens at the focused target's center for keyboard users.\n",
   "type": "object",
   "allOf": [
     {
@@ -17,7 +17,7 @@
       "const": "ContextMenu"
     },
     "for": {
-      "description": "CSS selector(s) for target element(s). Empty = use default-slot child.",
+      "description": "DEPRECATED alias for [target-selector] — still a CSS selector, NOT an id-ref. Honored when [target-selector] is unset, with a one-shot console.warn pointing consumers at the replacement. New authoring should use [target-selector].",
       "type": "string",
       "default": ""
     },
@@ -30,6 +30,11 @@
       "description": "Programmatic open state. Set true to open at target center.",
       "type": "boolean",
       "default": false
+    },
+    "targetSelector": {
+      "description": "CSS selector(s) for target element(s). Empty = use default-slot child. Ratified name (gh#1764/#1780, ADR-0079) for what [for] used to carry — [for] means an id-ref everywhere else in AdiaUI (table-toolbar-ui, chart-legend-ui, tooltip-ui); context-menu-ui's own selector meaning predates that convention and was a same-name/ different-contract collision (ADR-0053's no-shadowing doctrine).",
+      "type": "string",
+      "default": ""
     }
   },
   "required": [
@@ -39,7 +44,7 @@
   "x-adiaui": {
     "anti_patterns": [
       {
-        "fix": "Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui for=\"#my-target\">...items</context-menu-ui>`.",
+        "fix": "Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui target-selector=\"#my-target\">...items</context-menu-ui>`.",
         "why": "No target binding — the menu never opens.",
         "wrong": "<context-menu-ui>...just items...</context-menu-ui>"
       }

package/components/context-menu/context-menu.class.js

@@ -4,8 +4,16 @@
  * Two binding shapes:
  *   A. Wrap a target — first non-menu-item-ui default-slot child becomes
  *      the contextmenu host.
- *   B. Point at targets via [for="<selector>"] — useful for whole-table
- *      / whole-canvas menus where wrapping isn't practical.
+ *   B. Point at targets via [target-selector="<css-selector>"] — useful for
+ *      whole-table / whole-canvas menus where wrapping isn't practical.
+ *      [for] is a DEPRECATED alias for this (gh#1764/#1780, ADR-0079): `for=`
+ *      means an id-ref everywhere else in AdiaUI (table-toolbar-ui,
+ *      chart-legend-ui, tooltip-ui) — context-menu-ui's own pre-ruling [for]
+ *      carried a CSS-selector meaning instead, the exact same-attribute-
+ *      different-contract shape ADR-0053's no-shadowing doctrine forbids.
+ *      [target-selector] still resolves via `document.querySelectorAll()`
+ *      (multiple targets); a still-set legacy [for] is honored with a
+ *      one-shot console.warn pointing at the replacement.
  *
  * Architecture: reuses the existing anchor pattern (core/anchor.js) by
  * creating a virtual 1×1 anchor element at the pointer coords on each
@@ -23,8 +31,21 @@ import { anchorPopover } from '../../core/anchor.js';
 
 const LONG_PRESS_DEFAULT = 500;
 
+// DEPRECATED [for]-alias one-shot warning guard (gh#1764/#1780, ADR-0079) —
+// module-scope, matching this file's own idiom (a plain top-level const
+// rather than a lazily-created public static field, which stayed mutable
+// and externally visible for no reason).
+const warnedForDeprecated = new WeakSet();
+
 export class UIContextMenu extends UIElement {
   static properties = {
+    // gh#1764/#1780, ADR-0079 — the ratified replacement for the
+    // selector-flavored [for] below; a plain CSS selector, not an id-ref.
+    targetSelector: { type: String,  default: '',                 reflect: true, attribute: 'target-selector' },
+    // DEPRECATED — kept as a back-compat alias for `targetSelector` only.
+    // Honored (with a one-shot console.warn, see #legacyForSelector())
+    // whenever [target-selector] is unset. Never given id-ref semantics;
+    // the sweep did not attempt to dual-purpose this attribute.
     for:         { type: String,  default: '',                 reflect: true },
     open:        { type: Boolean, default: false,              reflect: true },
     longPressMs: { type: Number,  default: LONG_PRESS_DEFAULT, reflect: false, attribute: 'long-press-ms' },
@@ -97,11 +118,12 @@ export class UIContextMenu extends UIElement {
   }
 
   #resolveTargets() {
-    if (this.for) {
-      try { return [...document.querySelectorAll(this.for)]; }
+    const selector = this.targetSelector || this.#legacyForSelector();
+    if (selector) {
+      try { return [...document.querySelectorAll(selector)]; }
       catch (e) {
         // eslint-disable-next-line no-console
-        console.warn(`[context-menu-ui] invalid [for] selector: ${this.for}`, e);
+        console.warn(`[context-menu-ui] invalid [target-selector] selector: ${selector}`, e);
         return [];
       }
     }
@@ -113,6 +135,25 @@ export class UIContextMenu extends UIElement {
     return [];
   }
 
+  // DEPRECATED alias path (gh#1764/#1780, ADR-0079) — [for] used to carry
+  // context-menu-ui's own CSS-selector binding; [target-selector] is now
+  // the canonical name. Warn once per element, never per resolve (this
+  // runs on every #bindTargets() call, including reconnects).
+  #legacyForSelector() {
+    if (!this.for) return '';
+    if (!warnedForDeprecated.has(this)) {
+      warnedForDeprecated.add(this);
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[context-menu-ui] [for="${this.for}"] is deprecated — use ` +
+        `[target-selector="${this.for}"] instead. [for] now means an ` +
+        'id-ref everywhere else in AdiaUI; context-menu-ui\'s own prior ' +
+        '[for] carried a CSS-selector meaning (ADR-0079).',
+      );
+    }
+    return this.for;
+  }
+
   /* ── Trigger event handlers ──────────────────────────────────────── */
 
   #onContextMenu = (e) => {

package/components/context-menu/context-menu.d.ts

@@ -8,8 +8,9 @@ element-anchored. Pattern: WAI-APG Menu.
 Two binding modes:
  **A. Wrap.** Default-slot child becomes the target:
  `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.
- **B. Selector.** Point at one or more existing elements via [for]:
- `<context-menu-ui for="#my-table">...items</context-menu-ui>`.
+ **B. Selector.** Point at one or more existing elements via
+ [target-selector]:
+ `<context-menu-ui target-selector="#my-table">...items</context-menu-ui>`.
 
 On `contextmenu` event on a target: `preventDefault()`, position the
 menu at the pointer coords, show via Popover API. Touch long-press
@@ -54,10 +55,14 @@ export interface ContextMenuSelectEventDetail {
 export type ContextMenuSelectEvent = CustomEvent<ContextMenuSelectEventDetail>;
 
 export class UIContextMenu extends UIElement {
-  /** CSS selector(s) for target element(s). Empty = use default-slot child. */
+  /** DEPRECATED alias for [target-selector] — still a CSS selector, NOT an id-ref. Honored when [target-selector] is unset, with a one-shot console.warn pointing consumers at the replacement. New authoring should use [target-selector]. */
   for: string;
+  /** Long-press duration (ms) on touch devices to open the menu. */
+  longPressMs: number;
   /** Programmatic open state. Set true to open at target center. */
   open: boolean;
+  /** CSS selector(s) for target element(s). Empty = use default-slot child. Ratified name (gh#1764/#1780, ADR-0079) for what [for] used to carry — [for] means an id-ref everywhere else in AdiaUI (table-toolbar-ui, chart-legend-ui, tooltip-ui); context-menu-ui's own selector meaning predates that convention and was a same-name/ different-contract collision (ADR-0053's no-shadowing doctrine). */
+  targetSelector: string;
 
   addEventListener(type: 'context-menu-close', listener: (ev: ContextMenuCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'context-menu-open', listener: (ev: ContextMenuOpenEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/components/context-menu/context-menu.examples.md

@@ -17,7 +17,7 @@
 </context-menu-ui>
 ```
 
-## [for] selector mode — point at existing targets
+## [target-selector] mode — point at existing targets
 
 ```html
 <div style="display: grid; gap: var(--a-space-2);">
@@ -25,7 +25,7 @@
   <div data-row tabindex="0" style="padding: var(--a-space-3); border: 1px solid var(--md-sys-color-neutral-outline); border-radius: var(--a-radius-sm); background: var(--md-sys-color-neutral-background);">Row B — right-click</div>
   <div data-row tabindex="0" style="padding: var(--a-space-3); border: 1px solid var(--md-sys-color-neutral-outline); border-radius: var(--a-radius-sm); background: var(--md-sys-color-neutral-background);">Row C — right-click</div>
 </div>
-<context-menu-ui for='[data-chunk="context-menu-for"] [data-row]'>
+<context-menu-ui target-selector='[data-chunk="context-menu-for"] [data-row]'>
   <menu-item-ui value="edit" text="Edit"></menu-item-ui>
   <menu-item-ui value="duplicate" text="Duplicate"></menu-item-ui>
   <menu-divider-ui></menu-divider-ui>

package/components/context-menu/context-menu.yaml

@@ -15,8 +15,9 @@ description: |
   Two binding modes:
    **A. Wrap.** Default-slot child becomes the target:
    `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.
-   **B. Selector.** Point at one or more existing elements via [for]:
-   `<context-menu-ui for="#my-table">...items</context-menu-ui>`.
+   **B. Selector.** Point at one or more existing elements via
+   [target-selector]:
+   `<context-menu-ui target-selector="#my-table">...items</context-menu-ui>`.
 
   On `contextmenu` event on a target: `preventDefault()`, position the
   menu at the pointer coords, show via Popover API. Touch long-press
@@ -25,8 +26,24 @@ description: |
 composes:
   - menu-item-ui
 props:
+  targetSelector:
+    description: >-
+      CSS selector(s) for target element(s). Empty = use default-slot
+      child. Ratified name (gh#1764/#1780, ADR-0079) for what [for] used
+      to carry — [for] means an id-ref everywhere else in AdiaUI
+      (table-toolbar-ui, chart-legend-ui, tooltip-ui); context-menu-ui's
+      own selector meaning predates that convention and was a same-name/
+      different-contract collision (ADR-0053's no-shadowing doctrine).
+    type: string
+    default: ""
+    reflect: true
+    attribute: target-selector
   for:
-    description: CSS selector(s) for target element(s). Empty = use default-slot child.
+    description: >-
+      DEPRECATED alias for [target-selector] — still a CSS selector, NOT
+      an id-ref. Honored when [target-selector] is unset, with a one-shot
+      console.warn pointing consumers at the replacement. New authoring
+      should use [target-selector].
     type: string
     default: ""
     reflect: true
@@ -101,12 +118,12 @@ a2ui:
       reason: 'Trigger surface boundary.'
     - rule: 'Items are <menu-item-ui> children inside the default slot — same shape as <menu-ui> items.'
       reason: 'Single menu vocabulary.'
-    - rule: 'Bind target via wrap (default-slot first non-menu-item-ui child) OR [for] selector. The selector form is useful for whole-table or whole-canvas menus where wrapping isn''t practical.'
+    - rule: 'Bind target via wrap (default-slot first non-menu-item-ui child) OR [target-selector]. The selector form is useful for whole-table or whole-canvas menus where wrapping isn''t practical. [for] still works as a deprecated alias but new authoring should use [target-selector] (gh#1764/#1780, ADR-0079).'
       reason: 'Two binding shapes.'
 anti_patterns:
   - wrong: '<context-menu-ui>...just items...</context-menu-ui>'
     why: 'No target binding — the menu never opens.'
-    fix: 'Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui for="#my-target">...items</context-menu-ui>`.'
+    fix: 'Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui target-selector="#my-target">...items</context-menu-ui>`.'
 examples:
   - name: file-actions
     description: Right-click a file row for Open / Rename / Delete.

package/components/heatmap/heatmap.a2ui.json

@@ -53,6 +53,11 @@
     "component": {
       "const": "Heatmap"
     },
+    "data": {
+      "description": "Cell data as a JSON array of `{ r, c, v, label? }` objects, or set the `.data` property directly with an already-parsed array. Parsed on connect if the attribute is present and `.data` hasn't already been set programmatically.",
+      "type": "string",
+      "default": ""
+    },
     "noLegend": {
       "description": "Hide the Less/More legend strip",
       "type": "boolean",

package/components/heatmap/heatmap.d.ts

@@ -27,6 +27,8 @@ export class UIHeatmap extends UIElement {
   colorScheme: 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'data-ramp';
   /** Column count */
   cols: number;
+  /** Cell data as a JSON array of `{ r, c, v, label? }` objects, or set the `.data` property directly with an already-parsed array. Parsed on connect if the attribute is present and `.data` hasn't already been set programmatically. */
+  data: string;
   /** Hide the Less/More legend strip */
   noLegend: boolean;
   /** Row count */

package/components/heatmap/heatmap.yaml

@@ -25,6 +25,14 @@ props:
     enum:
       - square
       - wide
+  data:
+    description: >-
+      Cell data as a JSON array of `{ r, c, v, label? }` objects, or set the
+      `.data` property directly with an already-parsed array. Parsed on
+      connect if the attribute is present and `.data` hasn't already been
+      set programmatically.
+    type: string
+    default: ""
   colorScheme:
     description: Color ramp
     type: string

package/components/input/input.a2ui.json

@@ -166,7 +166,7 @@
       },
       {
         "fix": "{\"component\": \"CalendarPicker\", \"precision\": \"minute\"}\n",
-        "why": "Same gap as \"date\" — no native datetime picker rendered. Use\nCalendarPicker with precision=\"minute\" for combined date + time\ninput (DatetimePicker was a deprecated thin alias, cut in 0.8.43,\ngh#1617 — CalendarPicker is the sole tag now).\n",
+        "why": "Same gap as \"date\" — no native datetime picker rendered. Use\nCalendarPicker with precision=\"minute\" for combined date + time\ninput (DatetimePicker was a deprecated thin alias, cut in 0.8.43,\ngh#1617 — CalendarPicker is the sole A2UI component now).\n",
         "wrong": "{\"component\": \"Input\", \"type\": \"datetime-local\"}\n"
       },
       {
@@ -186,7 +186,7 @@
       },
       {
         "fix": "{\"component\": \"ColorInput\"}\n",
-        "why": "No native color swatch/picker rendered — just a plain text\nsurface. Use ColorInput for a compact form-bearing swatch +\npopover, or ColorArea directly for the full OKLCH picker surface\n(ColorPicker was a deprecated thin alias, cut in 0.8.43, gh#1617 —\nColorArea is the sole tag now).\n",
+        "why": "No native color swatch/picker rendered — just a plain text\nsurface. Use ColorInput for a compact form-bearing swatch +\npopover, or ColorArea directly for the full OKLCH picker surface\n(ColorPicker was a deprecated thin alias, cut in 0.8.43, gh#1617 —\nColorArea is the sole A2UI component now).\n",
         "wrong": "{\"component\": \"Input\", \"type\": \"color\"}\n"
       },
       {

package/components/input/input.class.js

@@ -53,6 +53,7 @@
 import { UIFormElement } from '../../core/form.js';
 import { isIconName, whenIconRegistryReady } from '../../core/icons.js';
 import { logicalSlotted } from '../../core/logical-children.js';
+import { syncAutoAriaLabel } from '../../core/a11y.js';
 
 const renderAffix = (v) => isIconName(v)
   ? `<icon-ui name="${v}"></icon-ui>`
@@ -106,6 +107,12 @@ export class UIInput extends UIFormElement {
   #cachedGroup = '';
   #cachedSepFor = null;
   static #labelSeq = 0;
+  // gh#1647: tracks the aria-label VALUE this element itself last derived
+  // from `placeholder` (undefined when none), so re-renders refresh/clear
+  // OUR name without ever clobbering a consumer's own aria-label —
+  // value-tracking guard ported from tag.class.js/select.class.js
+  // (gh#1644/#1646).
+  #lastAutoAriaLabel = undefined;
 
   // Hold-to-repeat tuning. Initial delay before autorepeat begins, and the
   // interval between repeats. Values match the cadence of the native
@@ -471,13 +478,11 @@ export class UIInput extends UIFormElement {
     // Re-resolve prefix/suffix from the live property each render (FEEDBACK-93).
     this.#syncAffixSlots();
 
-    if (this.label) {
-      this.removeAttribute('aria-label');
-    } else if (this.placeholder) {
-      this.setAttribute('aria-label', this.placeholder);
-    } else {
-      this.removeAttribute('aria-label');
-    }
+    // A11y (gh#1647): a visible `label` already names the field; otherwise
+    // fall back to `placeholder` — but never clobber a consumer's own
+    // aria-label (value-tracking guard, gh#1644/#1646).
+    const ariaSource = this.label ? '' : (this.placeholder || '');
+    this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, ariaSource);
 
     if (this.#isNumberMode) {
       const n = this.valueAsNumber;

package/components/input/input.yaml

@@ -264,9 +264,10 @@ a2ui:
       <input type="password"> for masking (per ADR-0025).
     - >-
       Wrap <input-ui> in <field-ui label="…" hint="…" error="…"> for
-      the canonical stacked label / hint / error chrome. The inline
-      [label] / [hint] / [error] props are also supported on the
-      primitive for compact use.
+      the canonical stacked label / hint / error chrome. input-ui itself
+      only supports inline [label] / [error] (gh#1669 — [hint] is a
+      field-ui-only prop; input-ui has no equivalent) — use field-ui
+      when a hint line is needed.
     - >-
       Form participation is implicit via UIFormElement. Set [name] for
       FormData submission; [required] / [disabled] / [readonly]
@@ -309,7 +310,7 @@ anti_patterns:
       Same gap as "date" — no native datetime picker rendered. Use
       CalendarPicker with precision="minute" for combined date + time
       input (DatetimePicker was a deprecated thin alias, cut in 0.8.43,
-      gh#1617 — CalendarPicker is the sole tag now).
+      gh#1617 — CalendarPicker is the sole A2UI component now).
     fix: |
       {"component": "CalendarPicker", "precision": "minute"}
   - wrong: |
@@ -342,7 +343,7 @@ anti_patterns:
       surface. Use ColorInput for a compact form-bearing swatch +
       popover, or ColorArea directly for the full OKLCH picker surface
       (ColorPicker was a deprecated thin alias, cut in 0.8.43, gh#1617 —
-      ColorArea is the sole tag now).
+      ColorArea is the sole A2UI component now).
     fix: |
       {"component": "ColorInput"}
   - wrong: |

package/components/integration-card/integration-card.d.ts

@@ -42,6 +42,8 @@ export class UIIntegrationCard extends UIElement {
   description: string;
   /** Disables the action button. */
   disabled: boolean;
+  /** When `status="error"`, the message to show below the description. Ignored for other statuses. */
+  errorMessage: string;
   /** Logo URL (preferred — renders as <img>) or icon name (renders as <icon-ui>). URLs are sniffed by presence of `/`. */
   logo: string;
   /** Display name shown as the card title. Required. */

package/components/nav/nav.a2ui.json

@@ -27,7 +27,7 @@
       "default": false
     },
     "heading": {
-      "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only.",
+      "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. For a VISIBLE kicker inside a primary-variant rail — or more than one kicker per <nav-ui> — hand-place <span data-nav-label> in the default slot instead; see slots below.",
       "type": "string",
       "default": ""
     },
@@ -108,7 +108,7 @@
     ],
     "slots": {
       "default": {
-        "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
+        "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers and <span data-nav-label> for hand-placed group-label kickers (titled runs of items/groups that aren't wrapped in a <nav-group-ui>). <span data-nav-label> renders with the same uppercase/tracking/muted kicker treatment as the [heading] ::before kicker, and is hidden alongside dividers whenever the primary-variant rail collapses ([collapsed] or ≤96px container width)."
       }
     },
     "states": [

package/components/nav/nav.css

@@ -32,7 +32,7 @@
     --nav-label-fg:        var(--a-fg-muted);
     --nav-label-font-size: var(--a-kicker-sm);
     --nav-label-weight:    var(--a-weight-medium);
-    --nav-label-px:        var(--a-space-2);
+    --nav-label-px:        var(--a-space-4);
     --nav-label-py:        var(--a-space-3) var(--a-space-1);
   }
 

package/components/nav/nav.d.ts

@@ -36,7 +36,7 @@ export class UINav extends UIElement {
   collapsed: boolean;
   /** Auto-place dividers between adjacent groups + items. */
   divider: boolean;
-  /** Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. */
+  /** Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. For a VISIBLE kicker inside a primary-variant rail — or more than one kicker per <nav-ui> — hand-place <span data-nav-label> in the default slot instead; see slots below. */
   heading: string;
   /** Opt out of the default single-expanded-group behavior. When unset, selecting a nav-item-ui collapses every nav-group-ui except the one containing the newly selected item (all, when the selection is ungrouped); manual multi-expansion still works up until the next selection. */
   multiExpand: boolean;