@adia-ai/web-components 0.8.41 → 0.8.42

package/components/pane/pane.class.js

@@ -32,12 +32,13 @@
  *   resizable    — boolean, enables drag-to-resize (width)
  *   min-width    — minimum width when resizing (default: 200)
  *   max-width    — maximum width when resizing (default: 600)
- *   side         — 'leading' | 'trailing' | '' (default). When set, the
+ *   edge         — 'leading' | 'trailing' | '' (default). When set, the
  *                  pane is treated as a horizontal sibling: the default
  *                  four-sided border is suppressed, only the inner-edge
  *                  border is drawn, the resize grabber moves to that
  *                  inner edge, and the resize-drag direction flips so
- *                  trailing panes grow when dragged leftward.
+ *                  trailing panes grow when dragged leftward. `side` is a
+ *                  deprecated dual-read alias (ADR-0063, gh#1563).
  *
  * JS API:
  *   pane.collapsed = true/false
@@ -58,11 +59,20 @@ export class UIPane extends UIElement {
     resizable:  { type: Boolean, default: false, reflect: true },
     minWidth:   { type: Number,  default: 200, attribute: 'min-width', reflect: true },
     maxWidth:   { type: Number,  default: 9999, attribute: 'max-width', reflect: true },
+    // ADR-0063 (gh#1563) — `side` is DEPRECATED; `edge` is the canonical
+    // spelling (same type/default/enum). `side` stays declared (dual-read
+    // compat, 0.8.42); `#resolveEdge()` (called from connected()) mirrors
+    // an old-only value onto `edge` + warns once. Internal usage below
+    // reads `edge` exclusively.
     side:       { type: String,  default: '', reflect: true },
+    edge:       { type: String,  default: '', reflect: true },
   };
 
   static template = () => null;
 
+  // ADR-0063 (gh#1563) one-shot-per-class deprecation warn for [side].
+  static #warnedSide = false;
+
   #resizeEl = null;
   #dragging = false;
   #startX = 0;
@@ -72,6 +82,25 @@ export class UIPane extends UIElement {
   #bound = false;
 
   connected() {
+    // ADR-0063 (gh#1563) compat shim — resolve BEFORE the first render so
+    // there's no wrong-then-right flash. New-name precedence: [edge] wins
+    // outright when present; only fall back to (and mirror) [side] when
+    // [edge] is absent from markup. `edge` defaults `''` (not a
+    // true-default Boolean), so a live hasAttribute() check here is
+    // reliable — no gh#961 self-stamp interference (see chart-legend.class.js
+    // for that failure mode with a true-default Boolean).
+    if (!this.hasAttribute('edge') && this.hasAttribute('side')) {
+      this.edge = this.side;
+      if (!UIPane.#warnedSide) {
+        UIPane.#warnedSide = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[AdiaUI] <pane-ui [side]> is deprecated — use [edge] instead ' +
+          '(ADR-0063, gh#1563). Kept working as-is; no behavior change.',
+        );
+      }
+    }
+
     if (!this.#bound) {
       this.#bound = true;
 
@@ -164,7 +193,7 @@ export class UIPane extends UIElement {
     // is anchored on the RIGHT side of its flex row — dragging leftward
     // should GROW the pane (grabber moves further left = more width),
     // not shrink it. Negate dx in that case.
-    const sign = this.side === 'trailing' ? -1 : 1;
+    const sign = this.edge === 'trailing' ? -1 : 1;
     const dx = (e.clientX - this.#startX) * sign;
     const w = Math.max(this.minWidth, Math.min(this.maxWidth, this.#startW + dx));
     this.style.width = `${w}px`;

package/components/pane/pane.css

@@ -63,20 +63,23 @@
     transition: none;
   }
 
-  /* Side-aware border treatment.
+  /* Edge-aware border treatment. ADR-0063 (gh#1563): `[edge]` is the
+     canonical attribute — pane.class.js's connected() mirrors an
+     old-only `[side]` value onto `[edge]` before the first render, so
+     selecting on `[edge=...]` alone covers both spellings.
      `leading`  — pane sits at the leading edge of a horizontal row, so
                   the only visual separator it needs is on its trailing
                   edge (right in LTR).
      `trailing` — mirror: only a leading-edge border (left in LTR).
-     Default (no side attr) keeps the full 4-sided border. */
-  :scope[side="leading"],
-  :scope[side="trailing"] {
+     Default (no edge attr) keeps the full 4-sided border. */
+  :scope[edge="leading"],
+  :scope[edge="trailing"] {
     border: none;
   }
-  :scope[side="leading"] {
+  :scope[edge="leading"] {
     border-inline-end: 1px solid var(--pane-border);
   }
-  :scope[side="trailing"] {
+  :scope[edge="trailing"] {
     border-inline-start: 1px solid var(--pane-border);
   }
 
@@ -184,11 +187,13 @@
   }
 
   /* ── Resize handle ──
-     Default (no side) positions the grabber on the right edge. When
-     `side="trailing"` is set, flip the grabber to the left edge so it
+     Default (no edge) positions the grabber on the right edge. When
+     `edge="trailing"` is set, flip the grabber to the left edge so it
      sits on the pane's "inner" side (where it meets the sibling
      content/pane in a horizontal row). `inset-inline-*` lets the rules
-     stay LTR/RTL-safe. */
+     stay LTR/RTL-safe. `side="trailing"` is a deprecated dual-read alias
+     (ADR-0063, gh#1563) — pane.class.js's connected() mirrors it onto
+     `[edge]` before the first render, so this selector alone covers both. */
   [slot="resize"] {
     position: absolute;
     top: 0;
@@ -202,7 +207,7 @@
     z-index: 1;
   }
 
-  :scope[side="trailing"] > [slot="resize"] {
+  :scope[edge="trailing"] > [slot="resize"] {
     inset-inline-end: auto;
     inset-inline-start: 0;
   }

package/components/pane/pane.d.ts

@@ -23,19 +23,22 @@ export type PaneToggleEvent = CustomEvent<unknown>;
 export class UIPane extends UIElement {
   /** Component property: collapsed. */
   collapsed: boolean;
-  /** Component property: maxWidth. */
-  maxWidth: number;
-  /** Component property: minWidth. */
-  minWidth: number;
-  /** Component property: resizable. */
-  resizable: boolean;
   /** Opts a pane into horizontal-sibling chrome: suppresses the default
 four-sided border and moves the resize grabber to the inner edge
 (right edge for `leading`, left edge for `trailing`). Also flips the
 resize-drag direction so `trailing` panes grow when dragged leftward.
 Unset keeps the pane-intrinsic chrome (full border, right-edge
-grabber when resizable).
+grabber when resizable). Canonical spelling (ADR-0063, gh#1563)
+replacing `side`.
  */
+  edge: '' | 'leading' | 'trailing';
+  /** Component property: maxWidth. */
+  maxWidth: number;
+  /** Component property: minWidth. */
+  minWidth: number;
+  /** Component property: resizable. */
+  resizable: boolean;
+  /** 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. */
   side: '' | 'leading' | 'trailing';
 
   addEventListener(type: 'toggle', listener: (ev: PaneToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/components/pane/pane.yaml

@@ -36,6 +36,18 @@ props:
     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
+    default: ''
+    enum:
+    - ''
+    - leading
+    - trailing
+    reflect: true
+  edge:
     description: 'Opts a pane into horizontal-sibling chrome: suppresses the default
 
       four-sided border and moves the resize grabber to the inner edge
@@ -46,7 +58,9 @@ props:
 
       Unset keeps the pane-intrinsic chrome (full border, right-edge
 
-      grabber when resizable).
+      grabber when resizable). Canonical spelling (ADR-0063, gh#1563)
+
+      replacing `side`.
 
       '
     type: string

package/components/swatch/swatch.yaml

@@ -154,7 +154,7 @@ tokens:
     description: Color of the focus + selected ring when [selectable] is set.
 a2ui:
   rules:
-    - rule: 'Use to display a single color sample with optional label. For interactive color picking use <color-picker-ui>.'
+    - rule: 'Use to display a single color sample with optional label. For interactive color picking use <color-area-ui>.'
       reason: 'Swatch is read-only display; picker is input.'
     - rule: 'Inside design-token displays or palette grids; not for general decoration.'
       reason: 'Semantic purpose: color sample.'

package/components/table-toolbar/table-toolbar.class.js

@@ -57,6 +57,18 @@ function popoverHead(text) {
   return el;
 }
 
+// `col.label` is sometimes set to an nbsp or a bare space — the idiom
+// consumers use on render-only columns (e.g. `_cancel` / `_download` /
+// `_replay`) to keep the TABLE header cell blank while still rendering a
+// custom cell. That whitespace is truthy, so a plain `col.label || col.key`
+// fallback never engages and popover rows (filter / sort / columns) render
+// with no visible text. Trim before testing so the fallback only skips when
+// a label is genuinely present, never when it's intentional whitespace.
+function columnLabel(col) {
+  const label = col.label;
+  return typeof label === 'string' && label.trim() ? label : col.key;
+}
+
 const SELECT_THRESHOLD = 50;
 const SAMPLE_LIMIT     = 500;
 
@@ -530,7 +542,7 @@ export class UITableToolbar extends UIElement {
       const row = document.createElement('field-ui');
       row.setAttribute('data-filter-row', '');
       row.setAttribute('inline', '');
-      row.setAttribute('label', col.label || col.key);
+      row.setAttribute('label', columnLabel(col));
 
       const shape = detectFilterShape(col, data);
       const current = filters[col.key];
@@ -637,7 +649,7 @@ export class UITableToolbar extends UIElement {
       const dir = dirByKey.get(col.key);
       const row = document.createElement('menu-item-ui');
       row.setAttribute('data-sort-row', '');
-      row.setAttribute('text', col.label || col.key);
+      row.setAttribute('text', columnLabel(col));
       row.dataset.key = col.key;
       if (dir) row.dataset.active = dir;
 
@@ -731,7 +743,7 @@ export class UITableToolbar extends UIElement {
       const row = document.createElement('field-ui');
       row.setAttribute('data-columns-row', '');
       row.setAttribute('inline', '');
-      row.setAttribute('label', col.label || col.key);
+      row.setAttribute('label', columnLabel(col));
 
       const check = document.createElement('check-ui');
       if (!col.hidden) check.setAttribute('checked', '');

package/core/icons.js

@@ -306,6 +306,11 @@ function discoverRequiredIcons() {
     'agent-trace-ui',
     'calendar-picker-ui',
     'color-picker-ui',
+    // ADR-0063 (gh#1563) — color-picker-ui's real implementation moved to
+    // color-area-ui (the new canonical tag); color-picker-ui is now a thin
+    // deprecated alias. Both need to resolve here since either tag may be
+    // the one actually defined+used on a given page.
+    'color-area-ui',
     'command-ui',
     'pane-ui',
     'select-ui',

package/custom-elements.json

@@ -137,7 +137,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Child of <action-list-ui>. One actionable row — icon + label + optional subtitle, forwards activation to the parent action-list. Row contract converges on <menu-item-ui>: icon/text/subtitle/value/variant/disabled props and icon/text/subtitle/trailing slot overrides (#1363 C5).",
+          "description": "Child of <action-list-ui>. One actionable row — icon + label + optional description, forwards activation to the parent action-list. Row contract converges on <menu-item-ui>: icon/text/description/value/variant/disabled props and icon/text/subtitle/trailing slot overrides (#1363 C5). (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1571.)",
           "name": "UIActionItem",
           "tagName": "action-item-ui",
           "superclass": {
@@ -164,7 +164,14 @@
               "type": {
                 "text": "string"
               },
-              "description": "Optional secondary description line rendered under the label."
+              "description": "DEPRECATED (ADR-0063, gh#1571) — 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.)"
+            },
+            {
+              "name": "description",
+              "type": {
+                "text": "string"
+              },
+              "description": "Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1571) replacing `subtitle` — converges action-item onto the same spelling <menu-item-ui> adopted under gh#1563."
             },
             {
               "name": "value",
@@ -201,7 +208,7 @@
             },
             {
               "name": "subtitle",
-              "description": "Custom secondary-line content override; falls through to [subtitle] prop if not slotted."
+              "description": "Custom secondary-line content override; falls through to the [description] prop (or its deprecated [subtitle] alias — ADR-0063, gh#1571) if not slotted. The slot's own name is unchanged by that rename — this is a distinct, deliberately-unrenamed surface."
             },
             {
               "name": "trailing",
@@ -2151,7 +2158,15 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When set, rows are non-interactive <span>s (no click, no toggle)."
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `interactive` instead. When set (and `interactive` is absent), rows are non-interactive <span>s (no click, no toggle). Kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0."
+            },
+            {
+              "name": "interactive",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Canonical opt-in spelling (ADR-0063, gh#1563) replacing `static`'s opt-out polarity. Rows are interactive <button>-role badges by default — this default stays `true` in 0.8.42 (deliberately NOT flipped yet; the 0.9.0 cut inverts it to `false` after a full consumer scan of every `<chart-legend-ui>` tag per the ADR)."
             },
             {
               "name": "on-toggle",
@@ -2233,7 +2248,15 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When true, suppress the overlaid average line"
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `noAverage` instead. Same meaning, same default; kept working as a dual-read compat shim (one- time console.warn when it's the name that resolves). Removed in 0.9.0."
+            },
+            {
+              "name": "no-average",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When true, suppress the overlaid average line. Canonical spelling (ADR-0063, gh#1563) replacing `hideAverage`."
             },
             {
               "name": "hide-grid",
@@ -2241,7 +2264,15 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Hide gridlines"
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `noGrid` instead. Same meaning, same default; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0."
+            },
+            {
+              "name": "no-grid",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Hide gridlines. Canonical spelling (ADR-0063, gh#1563) replacing `hideGrid`."
             },
             {
               "name": "hide-values",
@@ -2249,7 +2280,15 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Hide value labels"
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `noValues` instead. Same meaning, same default; kept working as a dual-read compat shim (one- time console.warn when it's the name that resolves). Removed in 0.9.0."
+            },
+            {
+              "name": "no-values",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Hide value labels. Canonical spelling (ADR-0063, gh#1563) replacing `hideValues`."
             },
             {
               "name": "corner-radius",
@@ -2844,13 +2883,135 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "components/color-area/color-area.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated input emitting OKLCH color strings; canonical color authoring surface in the AdiaUI token system. Use for color input in design tools or theming UIs; for simple color swatches use <swatch-ui> or <color-input-ui> instead. Renamed from `<color-picker-ui>` (ADR-0063, gh#1563 — `-picker` is reserved for the outer trigger + popover composite shape; this is the inline substrate, mirroring <calendar-grid-ui>'s naming precedent). `<color-picker-ui>` is now a thin deprecated alias subclassing this component.",
+          "name": "UIColorArea",
+          "tagName": "color-area-ui",
+          "superclass": {
+            "name": "UIElement",
+            "module": "/core/element.js"
+          },
+          "attributes": [
+            {
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "description": "Form field name"
+            },
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Disables all interaction"
+            },
+            {
+              "name": "format",
+              "type": {
+                "text": "string"
+              },
+              "default": "hex",
+              "description": "Output format for the value property"
+            },
+            {
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "default": "#3b82f6",
+              "description": "Current color as hex string"
+            },
+            {
+              "name": "maxChroma",
+              "type": {
+                "text": "number"
+              },
+              "default": "Infinity",
+              "description": "Generation constraint (v0.4.9 §99h, FEEDBACK-02 OKLCH chroma channel to at most this value before commit. Out-of- bound mutations round-trip to the nearest in-bound equivalent + fire `constraint-clamp`. Default Infinity (no constraint)."
+            },
+            {
+              "name": "maxL",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "Generation constraint — clamp OKLCH lightness to at most this value (0..1). Default 1 (no constraint)."
+            },
+            {
+              "name": "minL",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "Generation constraint — clamp OKLCH lightness to at least this value (0..1). Default 0 (no constraint)."
+            },
+            {
+              "name": "hueDriftMax",
+              "type": {
+                "text": "number"
+              },
+              "default": "NaN",
+              "description": "Generation constraint — maximum allowed signed-shortest-path hue deviation (degrees) from [base-hue] (or the first-committed hue if [base-hue] is unset). Default NaN (no constraint). Wrap-aware so a drift of 350 degrees resolves as -10."
+            },
+            {
+              "name": "baseHue",
+              "type": {
+                "text": "number"
+              },
+              "default": "NaN",
+              "description": "Reference hue (degrees) for the [hue-drift-max] constraint. Default NaN — falls back to the picker's hue at first commit so the consumer can pre-seed the picker and constrain drift from that initial value."
+            }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired on every color change"
+            },
+            {
+              "name": "input",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired during continuous interaction (drag)"
+            },
+            {
+              "name": "constraint-clamp",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired immediately before `change` / `input` when one or more consumer-declared constraints (max-chroma / max-l / min-l / hue-drift-max) clamped a channel away from the user-requested value. detail.clamps is an array of axis-specific clamp records."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "color-area-ui",
+          "declaration": {
+            "name": "UIColorArea",
+            "module": "./components/color-area/color-area.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "components/color-input/color-input.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "Compact form-bearing color input — opens a popover-anchored `<color-picker-ui>` from an inline swatch button. §302 (v0.5.12, FEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f Option B recipe (popover + button + color-picker) into a single form-associated tag for inline form contexts (settings drawer \"source color\" field, swatch-row inline-edit, etc.).",
+          "description": "Compact form-bearing color input — opens a popover-anchored `<color-area-ui>` from an inline swatch button. §302 (v0.5.12, FEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f Option B recipe (popover + button + color-area) into a single form-associated tag for inline form contexts (settings drawer \"source color\" field, swatch-row inline-edit, etc.). Composes `<color-area-ui>` (ADR-0063, gh#1563 — renamed from `<color-picker-ui>`, which is now a deprecated alias); `color-input-ui`'s own tag/name is unaffected.",
           "name": "UIColorInput",
           "tagName": "color-input-ui",
           "superclass": {
@@ -2895,7 +3056,7 @@
                 "text": "string"
               },
               "default": "bottom",
-              "description": "Popover placement relative to the trigger. Default `bottom` centers the color-picker panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger)."
+              "description": "Popover placement relative to the trigger. Default `bottom` centers the color-area panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger)."
             },
             {
               "name": "open",
@@ -2911,7 +3072,7 @@
                 "text": "number"
               },
               "default": "Infinity",
-              "description": "Generation constraint forwarded to the inner `<color-picker-ui>` (v0.5.13 §-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value. Default Infinity (no constraint)."
+              "description": "Generation constraint forwarded to the inner `<color-area-ui>` (v0.5.13 §-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value. Default Infinity (no constraint)."
             },
             {
               "name": "maxL",
@@ -2981,7 +3142,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated input emitting OKLCH color strings; canonical color authoring surface in the AdiaUI token system. Use for color input in design tools or theming UIs; for simple color swatches use <swatch-ui> or <color-input-ui> instead.",
+          "description": "DEPRECATED (ADR-0063, gh#1563, gh#1377 B11) — `-picker` is reserved for the outer, trigger + popover, form-associated composite shape (`calendar-picker-ui` / `date-range-picker-ui` / `datetime-picker-ui` / `time-picker-ui`); `color-picker-ui` was the sole violator, playing `calendar-grid-ui`'s inline-substrate role under a `-picker` name. `<color-picker-ui>` is now a thin `UIColorArea` subclass (see color-picker.class.js) rather than an independent implementation — every prop/event/token is inherited unchanged from `<color-area-ui>`. Existing markup keeps working, but new markup should reach for `<color-area-ui>` directly. See `<color-area-ui>` for the full contract.",
           "name": "UIColorPicker",
           "tagName": "color-picker-ui",
           "superclass": {
@@ -3792,7 +3953,7 @@
                 "text": "string"
               },
               "default": "start",
-              "description": "Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content."
+              "description": "Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-area-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content."
             },
             {
               "name": "items",
@@ -4514,7 +4675,7 @@
           "slots": [
             {
               "name": "default",
-              "description": "The form control — a WIDE control like input-ui, select-ui, textarea-ui, slider-ui, range-ui, calendar-picker-ui, color-picker-ui, upload-ui, otp-input-ui. Auto-id'd for the label's [for] binding. DO NOT wrap small self-labeling widgets here. check-ui, switch-ui, radio-ui, toggle-ui all carry their own [label] attribute that renders inline next to the control — wrapping them in field-ui produces broken layouts (settings-row `justify-self: end` rule pushes the control to the trailing edge, away from the label that field-ui stamps; the widget's own label then renders again on the right, creating a doubled / right-justified affordance). See anti_patterns below for the canonical alternatives."
+              "description": "The form control — a WIDE control like input-ui, select-ui, textarea-ui, slider-ui, range-ui, calendar-picker-ui, color-area-ui, upload-ui, otp-input-ui. Auto-id'd for the label's [for] binding. DO NOT wrap small self-labeling widgets here. check-ui, switch-ui, radio-ui, toggle-ui all carry their own [label] attribute that renders inline next to the control — wrapping them in field-ui produces broken layouts (settings-row `justify-self: end` rule pushes the control to the trailing edge, away from the label that field-ui stamps; the widget's own label then renders again on the right, creating a doubled / right-justified affordance). See anti_patterns below for the canonical alternatives."
             },
             {
               "name": "trailing",
@@ -6153,7 +6314,7 @@
         },
         {
           "kind": "class",
-          "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + subtitle + value.",
+          "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.)",
           "name": "UIMenuItem",
           "tagName": "menu-item-ui",
           "superclass": {
@@ -6180,7 +6341,14 @@
               "type": {
                 "text": "string"
               },
-              "description": "Optional secondary description line rendered under the label."
+              "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.)"
+            },
+            {
+              "name": "description",
+              "type": {
+                "text": "string"
+              },
+              "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`."
             },
             {
               "name": "value",
@@ -6217,7 +6385,7 @@
             },
             {
               "name": "subtitle",
-              "description": "Custom secondary-line content override; falls through to `[subtitle]` prop if not slotted."
+              "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."
             },
             {
               "name": "trailing",
@@ -7382,6 +7550,13 @@
               "type": {
                 "text": "string"
               },
+              "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."
+            },
+            {
+              "name": "edge",
+              "type": {
+                "text": "string"
+              },
               "description": "'Opts a pane into horizontal-sibling chrome: suppresses the default"
             }
           ],