@adia-ai/web-components 0.8.42 → 0.8.44

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/index.js

@@ -51,7 +51,6 @@ export { UIBadge } from './badge/badge.js';
 export { UIBreadcrumb } from './breadcrumb/breadcrumb.js';
 export { UICommand } from './command/command.js';
 export { UIColorArea } from './color-area/color-area.js';
-export { UIColorPicker } from './color-picker/color-picker.js';
 export { UIColorInput } from './color-input/color-input.js';
 export { UINoodles } from './noodles/noodles.js';
 export { UITable } from './table/table.js';
@@ -115,18 +114,15 @@ export { UISearch } from './search/search.js';
 export { UICombobox } from './combobox/combobox.js';
 export { UITagsInput } from './tags-input/tags-input.js';
 export { UIStat } from './stat/stat.js';
-export { UIProgressRow } from './progress-row/progress-row.js';
 export { UIActionList, UIActionItem } from './action-list/action-list.js';
 export { UIEmptyState } from './empty-state/empty-state.js';
 export { UICalendarGrid } from './calendar-grid/calendar-grid.js';
 export { UICalendarPicker } from './calendar-picker/calendar-picker.js';
 export { UIDateRangePicker } from './date-range-picker/date-range-picker.js';
 export { UITimePicker } from './time-picker/time-picker.js';
-export { UIDatetimePicker } from './datetime-picker/datetime-picker.js';
 export { UIEmbed } from './embed/embed.js';
 export { UIBlock } from './block/block.js';
 export { UIText } from './text/text.js';
-export { UIToggleGroup, UIToggleOption } from './toggle-group/toggle-group.js';
 export { UIToggleScheme } from './toggle-scheme/toggle-scheme.js';
 export { UIDemoToggle } from './demo-toggle/demo-toggle.js';
 export { UIRichText } from './richtext/richtext.js';

package/components/input/input.a2ui.json

@@ -14,7 +14,7 @@
   ],
   "properties": {
     "type": {
-      "description": "Input type. `password` wraps a native `<input>` for disc masking; `number` renders a contenteditable + stepper buttons (no native input). `text`/`email`/`tel`/`url` use plain contenteditable. input-ui does NOT implement date/time/color/search affordances — those HTML5 type values render as a plain contenteditable with no calendar, clock, swatch, or search affordance (first-pass-VALID against this enum historically, but functionally broken generation output). Use the owning primitive instead — CalendarPicker for date (+ month/week, no dedicated granularity primitive exists), DatetimePicker for datetime-local, TimePicker for time, ColorInput/ColorPicker for color, Search for search. See anti_patterns.",
+      "description": "Input type. `password` wraps a native `<input>` for disc masking; `number` renders a contenteditable + stepper buttons (no native input). `text`/`email`/`tel`/`url` use plain contenteditable. input-ui does NOT implement date/time/color/search affordances — those HTML5 type values render as a plain contenteditable with no calendar, clock, swatch, or search affordance (first-pass-VALID against this enum historically, but functionally broken generation output). Use the owning primitive instead — CalendarPicker for date (+ month/week, no dedicated granularity primitive exists), CalendarPicker precision=\"minute\" for datetime-local, TimePicker for time, ColorInput/ColorArea for color, Search for search. See anti_patterns.",
       "type": "string",
       "enum": [
         "text",
@@ -165,8 +165,8 @@
         "wrong": "{\"component\": \"Input\", \"type\": \"date\"}\n"
       },
       {
-        "fix": "{\"component\": \"DatetimePicker\"}\n",
-        "why": "Same gap as \"date\" — no native datetime picker rendered. Use\nDatetimePicker for combined date + time input.\n",
+        "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 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 ColorPicker directly for the full OKLCH picker\nsurface.\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
@@ -272,11 +279,19 @@ export class UIInput extends UIFormElement {
       `;
     }
 
+    // Suppress browser-native suggestion/autofill affordances on the
+    // contenteditable surface (gh#1593) — a bespoke editable, not a real
+    // form <input>, so a browser's saved-values dropdown or spellcheck
+    // suggestion strip is always noise here, never a wanted feature.
+    // aria-autocomplete="none" documents the same intent for AT users.
     const editable = `
       <span slot="text" contenteditable="plaintext-only" tabindex="0"
             ${this.value ? '' : 'data-empty=""'}
             ${labelby}
             data-placeholder="${this.placeholder}"
+            autocomplete="off" aria-autocomplete="none"
+            autocorrect="off" autocapitalize="off" spellcheck="false"
+            data-lpignore="true" data-1p-ignore="true"
             ${this.#isNumberMode ? 'inputmode="decimal"' : ''}></span>`;
 
     const controls = this.#isNumberMode ? `
@@ -463,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.css

@@ -51,6 +51,11 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     /* ── State: disabled ── */
     --input-bg-disabled:     var(--a-ui-bg-disabled);
     --input-fg-disabled:     var(--a-ui-text-disabled);
+    /* gh#1595 — border kept full contrast on disabled; otp-input.css /
+       upload.css already alias this exact role for their own disabled
+       border, so this follows that sibling pattern rather than inventing
+       a new one. */
+    --input-border-disabled: var(--a-ui-border-disabled);
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
 }
 
@@ -381,6 +386,7 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
   :scope[disabled] [slot="field"] {
     background: var(--input-bg-disabled);
     color: var(--input-fg-disabled);
+    border-color: var(--input-border-disabled);
     cursor: not-allowed;
   }
 

package/components/input/input.yaml

@@ -33,8 +33,8 @@ props:
       against this enum historically, but functionally broken generation
       output). Use the owning primitive instead — CalendarPicker for date
       (+ month/week, no dedicated granularity primitive exists),
-      DatetimePicker for datetime-local, TimePicker for time,
-      ColorInput/ColorPicker for color, Search for search. See
+      CalendarPicker precision="minute" for datetime-local, TimePicker
+      for time, ColorInput/ColorArea for color, Search for search. See
       anti_patterns.
     type: string
     default: text
@@ -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]
@@ -291,8 +292,8 @@ a2ui:
       — text/email/password/number/tel/url (gh#1363 B10). Never
       set [type] to an HTML5 value input-ui doesn't render — route
       date/time/color/search intents to the owning primitive instead:
-      CalendarPicker, DatetimePicker, TimePicker, ColorInput (or
-      ColorPicker directly), Search. See anti_patterns.
+      CalendarPicker (precision="minute" for datetime-local), TimePicker,
+      ColorInput (or ColorArea directly), Search. See anti_patterns.
 anti_patterns:
   - wrong: |
       {"component": "Input", "type": "date"}
@@ -307,9 +308,11 @@ anti_patterns:
       {"component": "Input", "type": "datetime-local"}
     why: |
       Same gap as "date" — no native datetime picker rendered. Use
-      DatetimePicker for combined date + time input.
+      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 A2UI component now).
     fix: |
-      {"component": "DatetimePicker"}
+      {"component": "CalendarPicker", "precision": "minute"}
   - wrong: |
       {"component": "Input", "type": "time"}
     why: |
@@ -338,8 +341,9 @@ anti_patterns:
     why: |
       No native color swatch/picker rendered — just a plain text
       surface. Use ColorInput for a compact form-bearing swatch +
-      popover, or ColorPicker directly for the full OKLCH picker
-      surface.
+      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 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/menu/menu-item.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/MenuItem.json",
   "title": "MenuItem",
-  "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + description + value. (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1563.)",
+  "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + description + value. (The deprecated `subtitle` prop alias for `description` was cut in 0.8.43 — ADR-0063, gh#1563/gh#1617.)",
   "type": "object",
   "allOf": [
     {
@@ -14,7 +14,7 @@
   ],
   "properties": {
     "description": {
-      "description": "Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` — converges menu-item onto the ~20-component corpus majority that already names this concept `description`.",
+      "description": "Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` — converges menu-item onto the ~20-component corpus majority that already names this concept `description`. The deprecated `subtitle` prop alias was cut in 0.8.43 (gh#1617).",
       "type": "string",
       "default": ""
     },
@@ -31,11 +31,6 @@
       "type": "string",
       "default": ""
     },
-    "subtitle": {
-      "description": "DEPRECATED (ADR-0063, gh#1563) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.)",
-      "type": "string",
-      "default": ""
-    },
     "text": {
       "description": "Item label text.",
       "type": "string",
@@ -86,7 +81,7 @@
         "description": "Custom leading element override; falls through to `[icon]` prop if not slotted."
       },
       "subtitle": {
-        "description": "Custom secondary-line content override; falls through to the `[description]` prop (or its deprecated `[subtitle]` alias — ADR-0063, gh#1563) if not slotted. The slot's own name is unchanged by that rename — this is a distinct, deliberately-unrenamed surface."
+        "description": "Custom secondary-line content override; falls through to the `[description]` prop if not slotted (ADR-0063, gh#1563 — the deprecated `[subtitle]` prop alias was cut in 0.8.43, gh#1617). The slot's own name is unchanged by that rename — this is a distinct, deliberately-unrenamed surface."
       },
       "text": {
         "description": "Custom label content; falls through to `[text]` prop if not slotted."

package/components/menu/menu-item.yaml

@@ -13,7 +13,7 @@ component: MenuItem
 category: navigation
 version: 1
 description: |-
-  Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + description + value. (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1563.)
+  Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + description + value. (The deprecated `subtitle` prop alias for `description` was cut in 0.8.43 — ADR-0063, gh#1563/gh#1617.)
 
 props:
   icon:
@@ -24,21 +24,13 @@ props:
     description: Item label text.
     type: string
     default: ""
-  subtitle:
-    description: >-
-      DEPRECATED (ADR-0063, gh#1563) — use `description` instead. Same
-      type/default/rendered position; kept working as a dual-read compat
-      shim (one-time console.warn when it's the name that resolves).
-      Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface,
-      deliberately left unrenamed in this pass — see its own description.)
-    type: string
-    default: ""
   description:
     description: >-
       Optional secondary description line rendered under the label.
       Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` —
       converges menu-item onto the ~20-component corpus majority that
-      already names this concept `description`.
+      already names this concept `description`. The deprecated `subtitle`
+      prop alias was cut in 0.8.43 (gh#1617).
     type: string
     default: ""
   value:
@@ -64,9 +56,10 @@ slots:
   subtitle:
     description: >-
       Custom secondary-line content override; falls through to the
-      `[description]` prop (or its deprecated `[subtitle]` alias — ADR-0063,
-      gh#1563) if not slotted. The slot's own name is unchanged by that
-      rename — this is a distinct, deliberately-unrenamed surface.
+      `[description]` prop if not slotted (ADR-0063, gh#1563 — the
+      deprecated `[subtitle]` prop alias was cut in 0.8.43, gh#1617). The
+      slot's own name is unchanged by that rename — this is a distinct,
+      deliberately-unrenamed surface.
   trailing:
     description: Trailing element pinned to the far edge (shortcut hint, check mark).
 
@@ -98,13 +91,12 @@ a2ui:
       hint).
     - >-
       <action-item-ui> (child of <action-list-ui>) shares this row contract
-      (icon/text/subtitle/value/variant/disabled props, icon/text/subtitle/
-      trailing slot overrides) for inline, non-popover command rows — use
-      it instead when the surface isn't a <menu-ui> popover (#1363 C5).
-      NOTE (ADR-0063, gh#1563): <menu-item-ui>'s own `subtitle` PROP is now
-      a deprecated alias for `description` — <action-item-ui> still uses
-      `subtitle` as its own primary spelling and was NOT renamed in this
-      pass (flagged as a discovered follow-up candidate, not fixed here).
+      (icon/text/description/value/variant/disabled props, icon/text/
+      subtitle/trailing slot overrides) for inline, non-popover command
+      rows — use it instead when the surface isn't a <menu-ui> popover
+      (#1363 C5). Both components' deprecated `subtitle` PROP aliases for
+      `description` were cut in 0.8.43 (ADR-0063, gh#1563/gh#1571,
+      gh#1617); the `subtitle` SLOT on both is unchanged.
 
 keywords:
   - menu-item

package/components/menu/menu.class.js

@@ -258,13 +258,11 @@ export class UIMenuItem extends UIElement {
   static properties = {
     icon:     { type: String,  default: '', reflect: true },
     text:     { type: String,  default: '', reflect: true },
-    // ADR-0063 (gh#1563) — `subtitle` is DEPRECATED (menu-item was the sole
-    // ~20-component-corpus outlier using `subtitle` where every sibling
-    // uses `description`); `description` is canonical. `subtitle` stays
-    // declared (dual-read compat, 0.8.42). The `subtitle` SLOT (a separate
-    // surface — see menu-item.yaml) is deliberately unchanged; only the
-    // PROP renames.
-    subtitle: { type: String,  default: '', reflect: true },
+    // ADR-0063 (gh#1563) — `description` is canonical (menu-item was the
+    // sole ~20-component-corpus outlier using `subtitle`); the deprecated
+    // `subtitle` PROP dual-read shim was cut in 0.8.43 (gh#1617). The
+    // `subtitle` SLOT (a separate surface — see menu-item.yaml) is
+    // deliberately unchanged.
     description: { type: String, default: '', reflect: true },
     value:    { type: String,  default: '', reflect: true },
     variant:  { type: String,  default: 'default', reflect: true },
@@ -273,32 +271,12 @@ export class UIMenuItem extends UIElement {
 
   static template = () => null;
 
-  // ADR-0063 (gh#1563) one-shot-per-class deprecation warn for [subtitle].
-  static #warnedSubtitle = false;
-
   // Set when connected() stamped role="menuitem" itself; a consumer-provided
   // role (e.g. admin-roster's role="menuitemradio", gh#616) is never touched
   // — that consumer also owns tabindex and any checked-state aria.
   #roleStamped = false;
 
   connected() {
-    // ADR-0063 (gh#1563) compat shim — resolve BEFORE #stamp() reads
-    // `this.description`, so there's no wrong-then-right flash. New-name
-    // precedence: [description] wins outright when present; only fall
-    // back to (and mirror) [subtitle] when [description] is absent.
-    if (!this.hasAttribute('description') && this.hasAttribute('subtitle')) {
-      this.description = this.subtitle;
-      if (!UIMenuItem.#warnedSubtitle) {
-        UIMenuItem.#warnedSubtitle = true;
-        // eslint-disable-next-line no-console
-        console.warn(
-          '[AdiaUI] <menu-item-ui [subtitle]> is deprecated — use ' +
-          '[description] instead (ADR-0063, gh#1563). Kept working as-is; ' +
-          'no behavior change.',
-        );
-      }
-    }
-
     // role="menuitem" ONLY when actually inside a menu container. A menu-ui
     // closes by moving its items back into its own light DOM (see #hide()),
     // where there is no role="menu"/menubar ancestor — a bare role="menuitem"

package/components/menu/menu.d.ts

@@ -41,14 +41,12 @@ export class UIMenuDivider extends UIElement {
 }
 
 export class UIMenuItem extends UIElement {
-  /** Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` — converges menu-item onto the ~20-component corpus majority that already names this concept `description`. */
+  /** Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` — converges menu-item onto the ~20-component corpus majority that already names this concept `description`. The deprecated `subtitle` prop alias was cut in 0.8.43 (gh#1617). */
   description: string;
   /** Disabled state — blocks pointer + keyboard activation. */
   disabled: boolean;
   /** Optional leading Phosphor icon name. */
   icon: string;
-  /** DEPRECATED (ADR-0063, gh#1563) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.) */
-  subtitle: string;
   /** Item label text. */
   text: string;
   /** Stable identifier emitted via the parent menu's `select` event. */

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Pane.json",
   "title": "Pane",
-  "description": "Collapsible, resizable content panel — drag-resize handle on the\ninner edge when [side=\"leading\"] / [side=\"trailing\"], [resizable]\nopt-in. Used standalone for resizable two-pane layouts, or wrapped\nby <editor-sidebar> / <admin-sidebar> which DELEGATE drag to the\ninner pane-ui rather than reimplementing it. See pane.yaml's\na2ui.rules for the full composition contract.\n",
+  "description": "Collapsible, resizable content panel — drag-resize handle on the\ninner edge when [edge=\"leading\"] / [edge=\"trailing\"], [resizable]\nopt-in. Used standalone for resizable two-pane layouts, or wrapped\nby <editor-sidebar> / <admin-sidebar> which DELEGATE drag to the\ninner pane-ui rather than reimplementing it. See pane.yaml's\na2ui.rules for the full composition contract.\n",
   "type": "object",
   "allOf": [
     {
@@ -22,7 +22,7 @@
       "const": "Pane"
     },
     "edge": {
-      "description": "Opts a pane into horizontal-sibling chrome: suppresses the default\nfour-sided border and moves the resize grabber to the inner edge\n(right edge for `leading`, left edge for `trailing`). Also flips the\nresize-drag direction so `trailing` panes grow when dragged leftward.\nUnset keeps the pane-intrinsic chrome (full border, right-edge\ngrabber when resizable). Canonical spelling (ADR-0063, gh#1563)\nreplacing `side`.\n",
+      "description": "Opts a pane into horizontal-sibling chrome: suppresses the default\nfour-sided border and moves the resize grabber to the inner edge\n(right edge for `leading`, left edge for `trailing`). Also flips the\nresize-drag direction so `trailing` panes grow when dragged leftward.\nUnset keeps the pane-intrinsic chrome (full border, right-edge\ngrabber when resizable). Canonical spelling (ADR-0063, gh#1563) — the\ndeprecated `side` dual-read alias was cut in 0.8.43 (gh#1617).\n",
       "type": "string",
       "enum": [
         "",
@@ -45,16 +45,6 @@
       "description": "Component property: resizable.",
       "type": "boolean",
       "default": false
-    },
-    "side": {
-      "description": "DEPRECATED (ADR-0063, gh#1563) — use `edge` instead. Same type/default/enum; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0.",
-      "type": "string",
-      "enum": [
-        "",
-        "leading",
-        "trailing"
-      ],
-      "default": ""
     }
   },
   "required": [