@adia-ai/web-components 0.8.43 → 0.8.44

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.d.ts

@@ -56,6 +56,8 @@ export type ContextMenuSelectEvent = CustomEvent<ContextMenuSelectEventDetail>;
 export class UIContextMenu extends UIElement {
   /** CSS selector(s) for target element(s). Empty = use default-slot child. */
   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;
 

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/noodles/noodles.a2ui.json

@@ -41,11 +41,6 @@
       "type": "boolean",
       "default": false
     },
-    "port-size": {
-      "description": "Port indicator dot size in pixels",
-      "type": "number",
-      "default": 10
-    },
     "portSize": {
       "description": "Port indicator size",
       "type": "number",
@@ -56,21 +51,11 @@
       "type": "boolean",
       "default": false
     },
-    "show-ports": {
-      "description": "Show port indicator dots. Defaults to true when editable",
-      "type": "boolean",
-      "default": false
-    },
     "showPorts": {
       "description": "Show port indicators",
       "type": "boolean",
       "default": false
     },
-    "stroke-width": {
-      "description": "Stroke width in pixels",
-      "type": "number",
-      "default": 2
-    },
     "strokeWidth": {
       "description": "Line stroke width",
       "type": "number",

package/components/noodles/noodles.yaml

@@ -30,10 +30,6 @@ props:
     description: Allow interactive creation/deletion of connections via drag
     type: boolean
     default: false
-  port-size:
-    description: Port indicator dot size in pixels
-    type: number
-    default: 10
   portSize:
     description: Port indicator size
     type: number
@@ -44,19 +40,11 @@ props:
     type: boolean
     default: false
     reflect: true
-  show-ports:
-    description: Show port indicator dots. Defaults to true when editable
-    type: boolean
-    default: false
   showPorts:
     description: Show port indicators
     type: boolean
     default: false
     attribute: show-ports
-  stroke-width:
-    description: Stroke width in pixels
-    type: number
-    default: 2
   strokeWidth:
     description: Line stroke width
     type: number

package/components/number-format/number-format.class.js

@@ -87,6 +87,16 @@ export class UINumberFormat extends UIElement {
     this.textContent = text;
     // Mirror raw value via aria-label so screen readers can read the
     // underlying number alongside the formatted glyphs.
+    //
+    // gh#1647 judgment call (triage-corrections comment, 2026-08-18):
+    // this aria-label is intentional component-owned chrome, not a
+    // consumer-overridable name — it mirrors the RAW underlying value
+    // ("42% (raw: 0.42)") specifically for a11y clarity, so a consumer
+    // override would likely defeat that purpose. Deliberately NOT ported
+    // to the value-tracking `#lastAutoAriaLabel` guard (core/a11y.js)
+    // that the other five gh#1647 primitives got — kept unconditional,
+    // auto-deriving on every render. Revisit only if a stated consumer
+    // need for overriding it surfaces.
     if (text && Number.isFinite(Number(this.value))) {
       this.setAttribute('aria-label', `${text} (raw: ${this.value})`);
     } else {

package/components/pagination/pagination.class.js

@@ -22,6 +22,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { KEY_MAP } from '../../core/template.js';
 
 export class UIPagination extends UIElement {
   static properties = {
@@ -48,10 +49,32 @@ export class UIPagination extends UIElement {
 
   connected() {
     if (!this.#nav) {
-      this.#nav = document.createElement('nav');
-      this.#nav.setAttribute('slot', 'nav');
-      this.#nav.setAttribute('aria-label', 'Pagination');
-      this.appendChild(this.#nav);
+      // Adopt a pre-existing server-rendered <nav slot="nav"> instead of
+      // unconditionally appending a fresh one — first-connect adoption
+      // (gh#1687). Steady-state reconcile is unaffected; this only guards
+      // the construction-time #nav field being null on upgrade.
+      this.#nav = this.querySelector(':scope > nav[slot="nav"]');
+      if (this.#nav) {
+        // Adopting an existing nav is only half the fix — reconcile()'s
+        // own keyed-diff (element.js) keys off a WeakMap-shaped
+        // `parent[KEY_MAP]` populated by THIS element's own prior render
+        // calls, which a freshly-parsed SSR fragment never has. Without
+        // seeding it here, the very first render treats every adopted
+        // child as unrecognized, stamps a full set of BRAND NEW nodes
+        // alongside them, and never removes the orphaned originals —
+        // silently doubling the button count inside the (correctly
+        // singular) adopted <nav>. Positionally zip the adopted
+        // children against the SAME key order #buildRange would
+        // produce right now; a shape mismatch (stale/hand-edited SSR
+        // markup) is left unseeded so reconcile falls back to its
+        // normal rebuild-from-scratch behavior instead of miskeying.
+        this.#seedKeyMapFromAdoptedNav();
+      } else {
+        this.#nav = document.createElement('nav');
+        this.#nav.setAttribute('slot', 'nav');
+        this.#nav.setAttribute('aria-label', 'Pagination');
+        this.appendChild(this.#nav);
+      }
     }
 
     if (!this.#bound) {
@@ -69,6 +92,67 @@ export class UIPagination extends UIElement {
     this.#bound = false;
   }
 
+  // Review finding (PR #1692) — the tag/marker a given item.type produces
+  // via #createItem(): ellipsis is a bare <span data-ellipsis>; prev/next/
+  // page are all <button-ui> distinguished by their own data-* marker
+  // (page additionally carries data-value). A same-LENGTH adopted child
+  // that doesn't match this shape (e.g. a plain <span> standing in for a
+  // page-cell <button-ui>) would still get SEEDED by a count-only check,
+  // then #updateItem() — which only sets attributes, never replaces the
+  // element — leaves it permanently the wrong tag. Checking shape here
+  // is what makes the fallback in #seedKeyMapFromAdoptedNav trustworthy.
+  #childMatchesItem(el, item) {
+    if (item.type === 'ellipsis') {
+      return el.tagName === 'SPAN' && el.hasAttribute('data-ellipsis');
+    }
+    if (el.tagName !== 'BUTTON-UI') return false;
+    if (item.type === 'prev') return el.hasAttribute('data-prev');
+    if (item.type === 'next') return el.hasAttribute('data-next');
+    return el.hasAttribute('data-page') && el.dataset.value === String(item.value);
+  }
+
+  // gh#1687 — see the call site's comment in connected(). Positionally
+  // zips the adopted nav's existing children against the key order the
+  // very next render() will compute, seeding reconcile()'s own
+  // `parent[KEY_MAP]` (element.js) so that render finds every item
+  // already present instead of stamping a duplicate full set.
+  #seedKeyMapFromAdoptedNav() {
+    const page = Math.max(1, Math.min(this.page, this.total));
+    const total = Math.max(1, this.total);
+    const siblings = Math.max(0, this.siblings);
+    const range = this.#buildRange(page, total, siblings);
+    const children = [...this.#nav.children];
+    const shapeMatches = children.length === range.length
+      && range.every((item, i) => this.#childMatchesItem(children[i], item));
+    if (!shapeMatches) {
+      // Review finding (PR #1692, two rounds) — a bare return here left
+      // the mismatch case worse off than doing nothing: reconcile()'s
+      // own cleanup loop only removes entries it finds IN
+      // `parent[KEY_MAP]`, so an unseeded map means every existing
+      // child is invisible to it — the next render() then stamps a
+      // full fresh set AND the stale adopted children survive alongside
+      // it (reproduced: 3 stale placeholder buttons + a correct fresh
+      // 9-item render = 12 nodes). Length alone isn't a reliable
+      // correlation signal either — a same-length fixture with the
+      // WRONG tag/marker per position (e.g. N bare <span>s standing in
+      // for N <button-ui> page-cells) would pass a count-only check and
+      // get seeded, then #updateItem() — attribute-only, never a tag
+      // swap — leaves it permanently wrong. Either kind of mismatch
+      // means the adopted markup can't be trusted to correlate with the
+      // next render's key order at all — abandon adoption for real:
+      // clear the stale children so the fallback is an actual clean
+      // rebuild, the same shape #nav would be in if it had just been
+      // freshly created.
+      this.#nav.replaceChildren();
+      return;
+    }
+    const map = new Map();
+    for (let i = 0; i < range.length; i++) {
+      map.set(range[i].key, children[i]);
+    }
+    this.#nav[KEY_MAP] = map;
+  }
+
   render() {
     if (!this.#nav) return;
 

package/components/popover/popover.d.ts

@@ -13,6 +13,8 @@
 import { UIElement } from '../../core/element.js';
 
 export class UIPopover extends UIElement {
+  /** Size the content panel to the trigger's width instead of max-content. Opt-in — the default (unset) keeps every existing consumer's content-sized panel unchanged. */
+  matchWidth: boolean;
   /** Pixel offset between the anchor and the popover. Renamed from `[gap]` (gh#1335) — a raw-px number can't share a name with the global Scale-grammar `[gap]` attribute (ADR-0053). */
   offset: number;
   /** Controls visibility via showPopover()/hidePopover() */

package/components/progress/progress.class.js

@@ -28,6 +28,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { syncAutoAriaLabel } from '../../core/a11y.js';
 
 export class UIProgress extends UIElement {
   static properties = {
@@ -42,6 +43,10 @@ export class UIProgress extends UIElement {
   #fill = null;
   #labelEl = null;
   #metaEl = null;
+  // gh#1647: tracks the aria-label VALUE this element itself last derived
+  // from `label`/`meta` (undefined when none) — value-tracking guard
+  // ported from tag.class.js/select.class.js (gh#1644/#1646).
+  #lastAutoAriaLabel = undefined;
 
   connected() {
     this.setAttribute('role', 'progressbar');
@@ -111,12 +116,12 @@ export class UIProgress extends UIElement {
       }
     }
 
-    // ARIA: label the control so screen readers announce "CPU, 42 percent".
-    if (this.label) {
-      this.setAttribute('aria-label', this.meta ? `${this.label}, ${this.meta}` : this.label);
-    } else {
-      this.removeAttribute('aria-label');
-    }
+    // ARIA: label the control so screen readers announce "CPU, 42 percent"
+    // — never clobbering a consumer's own aria-label (gh#1647,
+    // value-tracking guard ported from tag.class.js/select.class.js,
+    // gh#1644/#1646).
+    const ariaSource = this.label ? (this.meta ? `${this.label}, ${this.meta}` : this.label) : '';
+    this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, ariaSource);
   }
 
   disconnected() {

package/components/range/range.class.js

@@ -25,6 +25,7 @@
  */
 
 import { UIFormElement } from '../../core/form.js';
+import { syncAutoAriaLabel } from '../../core/a11y.js';
 
 export class UIRange extends UIFormElement {
   // Opt out of UIFormElement's per-control `label` deprecation warning.
@@ -52,6 +53,10 @@ export class UIRange extends UIFormElement {
   #dragging = false;
   #startX = 0;
   #startVal = 0;
+  // gh#1647: tracks the aria-label VALUE this element itself last derived
+  // from `label` (undefined when none) — value-tracking guard ported from
+  // tag.class.js/select.class.js (gh#1644/#1646).
+  #lastAutoAriaLabel = undefined;
 
   connected() {
     super.connected();
@@ -96,7 +101,10 @@ export class UIRange extends UIFormElement {
     this.setAttribute('aria-valuemax', this.max);
     this.setAttribute('aria-valuenow', this.value);
     this.setAttribute('aria-valuetext', `${this.value}${this.suffix ? ' ' + this.suffix : ''}`);
-    this.setAttribute('aria-label', this.label || '');
+
+    // A11y (gh#1647): never clobber a consumer's own aria-label
+    // (value-tracking guard, gh#1644/#1646).
+    this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, this.label || '');
 
     this.syncValue(String(this.value));
   }