@adia-ai/web-components 0.6.17 → 0.6.19

package/CHANGELOG.md

@@ -1,5 +1,145 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.19] — 2026-05-21
+
+### Fixed — `drawer-ui` `innerHTML`-on-host orphaned the internal `<dialog>` (FEEDBACK-30)
+
+- Setting `.innerHTML` on a mounted `<drawer-ui>` wiped the stamped
+  `<dialog>` part; `#dialogRef` (bound once in `connected()`) was left
+  detached, so `#syncDialog()` called `showModal()` on a detached node and
+  the drawer silently never reopened. `render()` now re-binds `#dialogRef`
+  + its listeners when `ensure('dialog')` re-stamps; `#syncDialog()` guards
+  `dialog.isConnected`; a failed `showModal()` surfaces a `console.error`.
+  `drawer.yaml` gains an `anti_patterns` entry for the innerHTML trap.
+
+### Added — `drawer-ui` `opened` event (FEEDBACK-27)
+
+- `<drawer-ui>` now dispatches a bubbling `opened` event after the open
+  transition completes (mirrors `close`). Lets tests + consumers await full
+  interactivity instead of `waitForTimeout` heuristics. `drawer.yaml`
+  `events:` documents it.
+
+### Added — `chart-ui` `.data` shape docs + wrong-shape warning (FEEDBACK-24)
+
+- `chart.yaml` now documents the `data` prop: an array of plain objects
+  keyed by the `x`/`y` attributes — not the Chart.js `{labels, datasets}`
+  envelope. Setting `.data` to a non-array (the common envelope mistake)
+  emits a one-shot `console.warn` instead of silently rendering blank.
+  (`x` and `y` were already documented props — the ticket's Finding 2
+  claim otherwise was inaccurate.)
+
+### Added — `segmented-ui` non-`<segment-ui>`-child warning (FEEDBACK-23)
+
+- `<segmented-ui>` emits a one-shot `console.warn` when a direct child is
+  not a `<segment-ui>` (a bare `<segment>` renders text but gets no sliding
+  indicator, `role`, or `aria-checked`). `segmented.yaml` `description` +
+  `slots` now document the `<segment-ui>` child contract.
+
+### Changed — `UIElement.ensure()` part-wipe invariant (FEEDBACK-31)
+
+- `UIElement.ensure()` (`core/element.js`) marks stamped structural parts
+  with `_uiPart = true` and its doc comment states the invariant: call
+  `ensure()` from `render()`, never cache a part reference once in
+  `connected()` — a host `innerHTML` wipe detaches it.
+
+### Added — `types` condition on CSS subpath exports (FEEDBACK-26)
+
+- `@adia-ai/web-components/css` and the per-component `.css` subpath exports
+  now carry a `types` condition (`css-module.d.ts` stub), so TypeScript
+  under `moduleResolution: bundler` no longer raises TS2882 on CSS
+  side-effect imports.
+
+### Docs — no-`.js`-suffix import rule (FEEDBACK-22)
+
+- `USAGE.md` notes that component subpath imports use the directory name
+  (`…/components/button`), never the explicit file (`…/button/button.js`) —
+  the `exports` wildcard rejects the suffixed form under Vite 8.
+
+## [0.6.18] — 2026-05-21
+
+### Added — `[data-scheme]` attribute on `toggle-scheme-ui` (FB-14)
+
+- **`toggle-scheme-ui` now writes the `[data-scheme]` attribute** on the target
+  element alongside the existing `color-scheme` inline style. `styles/themes.css`
+  selects on `[data-scheme="light|dark|system"]`; consumer CSS patterned after
+  it never fired because the component wrote only the inline style.
+  `#writeTarget()` sets the attribute, `#clearTargetOverride()` removes it —
+  paired with the style so the two never diverge. Non-breaking: consumers
+  relying on the `color-scheme` style alone are unaffected. (~6 LOC `class.js`.)
+
+### Added — `button-ui` text/icon symbol-duplication warning (FB-15)
+
+- **`button-ui` emits a one-shot `console.warn`** when `text=` begins with a
+  symbol that `icon=` already renders — e.g. `text="+ New Item" icon="plus"`
+  renders a doubled `+`. Covers the high-frequency `plus` / `minus` / `x` /
+  `check` / `arrow-*` collisions. Warning-only (WeakSet-guarded, GC-friendly);
+  the button still renders and `text=` is never mutated. `button.yaml` gains the
+  matching `anti_patterns` entry so A2UI validators flag it at generation time.
+  (~36 LOC `class.js` + `button.yaml` + a2ui regen.)
+
+### Added — Loading state as first-class citizen (FB-12 P2)
+
+- **`stat-ui loading` prop.** New `loading: Boolean` (reflect: true). When set,
+  the value + change slots render `<skeleton-ui>` shimmer placeholders and the
+  host gets `aria-busy="true"`. Label and icon are preserved as static
+  metadata. Toggle off when data arrives — slot textContent setters restore
+  cleanly. `composes:` now includes `skeleton-ui`. (~28 LOC `stat.js` + 9 LOC
+  `stat.yaml` + a2ui chunk regen.)
+- **`table-ui` skeleton rows.** `loading=true` now renders N ghost
+  `[data-skeleton-row]` rows (N = `paginate` capped at 8, else 5) instead of
+  the legacy `<progress-ui>` overlay. Header + columns stay intact so layout
+  is preserved while data fetches. Cell widths cycle 60/80/70/50/90% so rows
+  read as natural data. Host gets `aria-busy="true"`. `composes:` now
+  includes `skeleton-ui`. Fixes yaml-vs-impl drift: the yaml description
+  always promised "skeleton rows" since the initial cut; the impl only
+  shipped the overlay. (~42 LOC `class.js` rewrite of `#renderOverlays` +
+  CSS rewrite of the `:scope[loading] [data-body]` rule.)
+
+### Added — `text-ui` overlay attributes (FB-10)
+
+- **`size` / `color` / `weight` / `text-align` props on `text-ui`.** Pre-v0.6.18
+  the skill documented an overlay API (`<text-ui color="subtle" size="sm"
+  weight="semibold" text-align="center">`) but the substrate ignored those
+  attributes — they were valid HTML but no-op CSS. v0.6.18 implements them
+  as `:scope[attr="value"]` rules that override the `--text-*` CSS vars set
+  by `[variant]`. Enums:
+  - `size` — `sm | md | lg` → `--a-body-sm | --a-body-md | --a-body-lg`
+  - `color` — `default | subtle | strong | accent | danger | success | warning`
+  - `weight` — `regular | medium | semibold | bold`
+  - `text-align` — `start | center | end | justify` (sets `text-align` directly;
+    only takes effect when text-ui is block-like)
+  Permissive: unknown values are no-ops (variant default wins). Substrate now
+  matches the skill's already-documented intent.
+
+### Tests
+
+- 9 new tests in `stat.test.js` (FB-12 P2 #1 coverage).
+- 9 new tests in `table.test.js` (FB-12 P2 #3 coverage; uses RAF-based settle
+  helper because table-ui renders via `requestAnimationFrame`, not microtasks).
+- 18 new tests in `text.test.js` for the overlay attributes (attribute
+  reflection × 18 values + CSS rule presence × 18 + 3 enum-vs-CSS
+  consistency checks + permissive-fallback smoke).
+- **Total: 99/99 passing** (text 82 + stat 9 + table 9 — the existing text
+  variant tests still pass alongside the new overlay tests).
+
+### Deferred (see `outbox/FEEDBACK-12--...--followup.md`)
+
+- **`chart-ui` `loading` prop (FB-12 P2 #2)** — design decision upstream.
+  `chart.examples.html` documents intentional "compose loading wrappers"
+  pattern; pivoting in a patch cut would silently lock in a direction.
+- **`skeleton-ui` `variant` reconcile (FB-12 P3)** — two valid dispositions
+  (purge a2ui corpus refs / implement prop) need maintainer signoff.
+
+### No-op (FB-11 P3 substrate)
+
+- Verified that `import { UIFeed } from '@adia-ai/web-components/components/feed/class'`
+  resolves correctly via the existing `./components/*/class` exports pattern.
+  No package.json change needed. The original ticket flagged
+  `/components/feed/feed.js` as failing — confirmed (Node exports wildcards
+  can't substitute `*` across multiple path segments) but the `/class`
+  shorthand is the canonical path and works today. Skill v2.11.0 documents
+  this.
+
 ## [0.6.17] — 2026-05-21
 
 ### Maintenance

package/USAGE.md

@@ -49,6 +49,12 @@ import '@adia-ai/web-components/components/button';
 import '@adia-ai/web-components/components/button.css';
 ```
 
+> **No `.js` suffix on component subpaths.** Import the directory name —
+> `…/components/button`, never `…/components/button/button.js`. The
+> `exports` wildcard matches only the directory form; appending the
+> explicit filename fails to resolve under Vite 8 (rolldown). The on-disk
+> filename is irrelevant to the subpath specifier.
+
 Subpath exports also available:
 
 ```js

package/components/button/button.a2ui.json

@@ -96,7 +96,14 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
-    "anti_patterns": [],
+    "anti_patterns": [
+      {
+        "description": "Beginning text= with a symbol that icon= already renders. icon=\"plus\" paints a Phosphor \"+\" glyph; text=\"+ New Item\" then renders the literal \"+\" too, so the symbol appears twice ([+ icon] [+ New Item]).",
+        "right": "<button-ui text=\"New Claim\" icon=\"plus\" variant=\"primary\"></button-ui>\n",
+        "rule": "Do not repeat the icon's glyph in text=. The icon provides the symbol; text= carries only the words. Applies to plus / minus / x / check / arrow icons.",
+        "wrong": "<button-ui text=\"+ New Claim\" icon=\"plus\" variant=\"primary\"></button-ui>\n"
+      }
+    ],
     "category": "action",
     "composes": [
       "icon-ui"

package/components/button/button.yaml

@@ -140,7 +140,19 @@ tokens:
     description: Inherited multiplier for padding
 a2ui:
   rules: []
-anti_patterns: []
+anti_patterns:
+  - description: >-
+      Beginning text= with a symbol that icon= already renders. icon="plus"
+      paints a Phosphor "+" glyph; text="+ New Item" then renders the literal
+      "+" too, so the symbol appears twice ([+ icon] [+ New Item]).
+    wrong: |
+      <button-ui text="+ New Claim" icon="plus" variant="primary"></button-ui>
+    right: |
+      <button-ui text="New Claim" icon="plus" variant="primary"></button-ui>
+    rule: >-
+      Do not repeat the icon's glyph in text=. The icon provides the symbol;
+      text= carries only the words. Applies to plus / minus / x / check /
+      arrow icons.
 examples: []
 keywords: []
 synonyms: {}

package/components/button/class.js

@@ -16,6 +16,19 @@
 import { UIElement, signal, html } from '../../core/element.js';
 import { getIcon } from '../../core/icons.js';
 
+// FEEDBACK-15: highest-frequency icon ⇄ text-prefix collisions. When an
+// author writes e.g. text="+ New Item" icon="plus", the Phosphor glyph and
+// the literal symbol both render — a doubled "+". Map is intentionally a
+// curated high-frequency set, not exhaustive; the warning is non-breaking.
+const ICON_TEXT_PREFIXES = {
+  plus:          ['+', '＋'],
+  minus:         ['-', '−', '–'],
+  x:             ['×', 'x ', 'X '],
+  check:         ['✓', '✔'],
+  'arrow-right': ['→', '>'],
+  'arrow-left':  ['←', '<'],
+};
+
 export class UIButton extends UIElement {
   static properties = {
     text:     { type: String,  default: '', reflect: true },
@@ -57,6 +70,26 @@ export class UIButton extends UIElement {
       }
     }
 
+    // FEEDBACK-15: warn when text= begins with a symbol that icon= already
+    // renders (e.g. text="+ New Claim" icon="plus" → a doubled "+"). One-shot
+    // per element via WeakSet; warning-only — the button still renders. The
+    // text value is never mutated (text="+1" with no icon is a valid label).
+    if (this.icon && this.text) {
+      const prefixes = ICON_TEXT_PREFIXES[this.icon];
+      if (prefixes && prefixes.some((p) => this.text.startsWith(p))) {
+        if (!UIButton.#dupSymbolWarned.has(this)) {
+          UIButton.#dupSymbolWarned.add(this);
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[button-ui] text="${this.text}" begins with a symbol that ` +
+            `icon="${this.icon}" already renders — the glyph appears twice. ` +
+            `Drop the leading symbol from text= (the icon provides it).`,
+            this,
+          );
+        }
+      }
+    }
+
     // §184 (v0.5.5, FEEDBACK-08 §8): icon-only a11y warning + title→aria-label
     // auto-derive. Two complementary mechanisms (consumer chooses):
     //   (a) When [title="Undo"] is set on an icon-only button without an
@@ -97,6 +130,9 @@ export class UIButton extends UIElement {
   // is gone the entry is collected.
   static #a11yWarned = new WeakSet();
 
+  // FEEDBACK-15: one-shot set for the text/icon symbol-duplication warning.
+  static #dupSymbolWarned = new WeakSet();
+
   #onClick = (e) => {
     if (this.disabled) { e.stopPropagation(); return; }
     if (this.type === 'submit') {

package/components/chart/chart.a2ui.json

@@ -65,6 +65,11 @@
     "component": {
       "const": "Chart"
     },
+    "data": {
+      "description": "JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x=\"month\" y=\"revenue\">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data=\"[…]\"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute.",
+      "type": "array",
+      "default": []
+    },
     "format": {
       "description": "Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default \"$\"); `percent` multiplies × 100 and adds a % suffix.",
       "type": "string",

package/components/chart/chart.d.ts

@@ -24,6 +24,8 @@ export class UIChart extends UIElement {
   aspect: 'std' | 'wide' | 'square' | 'tall';
   /** Color scheme */
   color: 'accent' | 'success' | 'warning' | 'danger' | 'info';
+  /** JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x="month" y="revenue">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data="[…]"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute. */
+  data: unknown[];
   /** Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default "$"); `percent` multiplies × 100 and adds a % suffix. */
   format: 'abbr' | 'decimal' | 'currency' | 'percent';
   /** DEPRECATED (OD-CHART-02). Place chart titles in an enclosing card-ui's `<header><span slot="heading">...</span></header>` instead. Still honored for back-compat; emits a one-shot console.warn per instance when set. Used as the chart's `aria-label` when no explicit label is provided. */

package/components/chart/chart.yaml

@@ -122,6 +122,19 @@ props:
     description: Y-axis key(s), comma-separated for multi-series
     type: string
     default: ""
+  data:
+    description: >-
+      JS property (set programmatically — `el.data = [...]`). An array of
+      plain objects; each object's keys are named by the `x` and `y`
+      attributes — e.g. `<chart-ui x="month" y="revenue">` consumes
+      `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The
+      Chart.js `{labels, datasets}` envelope is NOT chart-ui's API —
+      passing it (or any non-array value) renders an empty chart. May also
+      be supplied declaratively as a JSON-array `data="[…]"` attribute,
+      hydrated once at connect. Custom accessor on the element class, not a
+      reflected attribute.
+    type: array
+    default: []
 events:
   chart-hover:
     description: >-

package/components/chart/class.js

@@ -231,6 +231,7 @@ export class UIChart extends UIElement {
   static template = () => null;
 
   #data = [];
+  #shapeWarned = false;  // FEEDBACK-24: one-shot wrong-.data-shape warning
   #resizeObs = null;
   #resizeRaf = null;
   #lastW = 0;
@@ -250,6 +251,18 @@ export class UIChart extends UIElement {
   }
 
   set data(arr) {
+    // FEEDBACK-24: a non-array — typically the Chart.js `{labels, datasets}`
+    // envelope — is silently coerced to [] below, producing a blank chart
+    // with no diagnostic. Warn once per element.
+    if (!Array.isArray(arr) && !this.#shapeWarned) {
+      this.#shapeWarned = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[chart-ui] .data must be an array of plain objects — received ` +
+        `${arr === null ? 'null' : typeof arr}. The {labels, datasets} ` +
+        `envelope is the Chart.js API, not the chart-ui API. See chart.yaml.`,
+      );
+    }
     this.#data = Array.isArray(arr) ? arr : [];
     this.#warnIfOverBudget();
     this.#renderChart();

package/components/drawer/class.js

@@ -39,7 +39,8 @@
  *   drawer.show() · drawer.hide() · drawer.open = true|false
  *
  * Events:
- *   close — fired after the drawer finishes closing
+ *   close  — fired after the drawer finishes closing
+ *   opened — fired after the drawer finishes its open transition
  */
 
 import { UIElement } from '../../core/element.js';
@@ -49,6 +50,7 @@ export class UIDrawer extends UIElement {
   #closing = false;
   #previousFocus = null;
   #closeTimer = null;
+  #openTimer = null;
   #dialogRef = null;
   // §156 (v0.5.3): track the reason the drawer closed so the dispatched
   // `close` CustomEvent carries `detail.reason`. Set at each entry point
@@ -161,6 +163,10 @@ export class UIDrawer extends UIElement {
       clearTimeout(this.#closeTimer);
       this.#closeTimer = null;
     }
+    if (this.#openTimer != null) {
+      clearTimeout(this.#openTimer);
+      this.#openTimer = null;
+    }
     this.#bound = false;
     this.#dialogRef = null;
   }
@@ -213,6 +219,27 @@ export class UIDrawer extends UIElement {
   render() {
     const dialog = this.ensure('dialog');
 
+    // §FB-30 (P0): render() is the single source of truth for the dialog
+    // binding. When a consumer sets `drawer.innerHTML` on a mounted drawer
+    // the internal <dialog> is wiped; ensure('dialog') re-stamps a fresh
+    // one, but #dialogRef (set once in connected()) still points at the
+    // detached old dialog. Re-bind the cancel/close/click listeners onto
+    // the new dialog so #syncDialog() never calls showModal() on a
+    // detached node. On first render after mount `dialog` already equals
+    // #dialogRef (set in connected()), so the listeners are NOT
+    // double-added. Per FEEDBACK-30.
+    if (dialog !== this.#dialogRef) {
+      if (this.#dialogRef) {
+        this.#dialogRef.removeEventListener('cancel', this.#onDialogCancel);
+        this.#dialogRef.removeEventListener('close', this.#onDialogClose);
+        this.#dialogRef.removeEventListener('click', this.#onDialogClick);
+      }
+      this.#dialogRef = dialog;
+      dialog.addEventListener('cancel', this.#onDialogCancel);
+      dialog.addEventListener('close', this.#onDialogClose);
+      dialog.addEventListener('click', this.#onDialogClick);
+    }
+
     if (this.text) {
       dialog.setAttribute('aria-label', this.text);
       this.setAttribute('aria-label', this.text);
@@ -289,10 +316,23 @@ export class UIDrawer extends UIElement {
   #syncDialog() {
     const dialog = this.#dialogRef;
     if (!dialog) return;
+    // §FB-30 (P0): guard against a detached dialog. If a consumer wiped
+    // the host's children via innerHTML between render() passes, #dialogRef
+    // could momentarily point at a node outside the document — showModal()
+    // on a detached <dialog> throws InvalidStateError. Per FEEDBACK-30.
+    if (!dialog.isConnected) return;
     if (this.open && !dialog.open) {
       this.#closing = false;
       this.#previousFocus = document.activeElement;
-      dialog.showModal();
+      // §FB-30 (P0): wrap showModal() so a detached-dialog InvalidStateError
+      // surfaces synchronously instead of being swallowed by the effect
+      // runner and rethrown as an unhandled microtask rejection. Per
+      // FEEDBACK-30.
+      try {
+        dialog.showModal();
+      } catch (e) {
+        console.error('[drawer-ui] showModal() failed — dialog may be detached:', e);
+      }
       // Synchronous reflow instead of rAF — Safari throttles
       // requestAnimationFrame when a top-layer dialog is open, sometimes
       // delaying [data-open] (and the slide-in transition) by tens of
@@ -300,6 +340,17 @@ export class UIDrawer extends UIElement {
       // synchronous frame. See docs/BROWSER-COMPAT.md §3a (Flavor C).
       void dialog.offsetHeight;
       dialog.setAttribute('data-open', '');
+      // §FB-27 (P2): emit `opened` after the slide-in transition completes
+      // so Playwright (and any consumer waiting for "drawer fully open and
+      // interactive") can listen for it instead of guessing with
+      // waitForTimeout. Mirrors #closeTimer — cleared in #animateClose and
+      // disconnected() so a rapid close→open never fires a stale `opened`.
+      // Per FEEDBACK-27.
+      if (this.#openTimer != null) clearTimeout(this.#openTimer);
+      this.#openTimer = setTimeout(() => {
+        this.#openTimer = null;
+        this.dispatchEvent(new CustomEvent('opened', { bubbles: true }));
+      }, this.#getDuration());
     } else if (!this.open && dialog.open && !this.#closing) {
       this.#animateClose(dialog);
     }
@@ -307,6 +358,13 @@ export class UIDrawer extends UIElement {
 
   #animateClose(dialog) {
     this.#closing = true;
+    // §FB-27 (P2): a close cancels any pending `opened` — clear the open
+    // timer so a rapid open→close never fires a stale `opened` event after
+    // the drawer is already sliding out. Per FEEDBACK-27.
+    if (this.#openTimer != null) {
+      clearTimeout(this.#openTimer);
+      this.#openTimer = null;
+    }
     // Set [data-closing] FIRST (carries the transition spec), force a
     // reflow, THEN remove [data-open]. If both attribute changes batch
     // into a single style update, Safari can skip the slide-out animation

package/components/drawer/drawer.a2ui.json

@@ -58,7 +58,14 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
-    "anti_patterns": [],
+    "anti_patterns": [
+      {
+        "description": "Replacing a drawer's children wholesale — `drawer.innerHTML = '…'` — wipes the internal <dialog> part UIDrawer stamps and tracks. render() re-stamps and re-binds the dialog defensively (FEEDBACK-30), but the authored header/section/footer skeleton is still destroyed on every mutation, and any consumer-held reference to a former child is stale.",
+        "right": "<drawer-ui><header>Title</header><section id=\"body\"></section></drawer-ui>\n<!-- mutate a stable inner element, never the component host -->\ndocument.getElementById('body').innerHTML = renderFields(claim);\n",
+        "rule": "Never set .innerHTML on a UIElement component host. Keep <header>/<section>/<footer> as persistent children and mutate the content of a plain inner element instead.",
+        "wrong": "drawer.innerHTML = `<header>${title}</header><section>${body}</section>`;\n"
+      }
+    ],
     "category": "container",
     "composes": [],
     "events": {
@@ -76,6 +83,9 @@
             ]
           }
         }
+      },
+      "opened": {
+        "description": "Fired after the drawer finishes its open transition — scheduled `--drawer-duration` ms after `showModal()` + `[data-open]`. Lets Playwright (and any consumer code waiting for the drawer to be fully open and interactive) listen for an event instead of guessing with a fixed timeout. Cancelled if the drawer closes before the open transition completes, so a rapid close→open never fires a stale `opened`. Added per FEEDBACK-27."
       }
     },
     "examples": [

package/components/drawer/drawer.d.ts

@@ -18,6 +18,7 @@ export interface DrawerCloseEventDetail {
 }
 
 export type DrawerCloseEvent = CustomEvent<DrawerCloseEventDetail>;
+export type DrawerOpenedEvent = CustomEvent<unknown>;
 
 export class UIDrawer extends UIElement {
   /** Controls visibility. When false, backdrop and panel are removed from DOM. */
@@ -37,4 +38,5 @@ export class UIDrawer extends UIElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'close', listener: (ev: DrawerCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'opened', listener: (ev: DrawerOpenedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/drawer/drawer.yaml

@@ -60,6 +60,15 @@ events:
           `'programmatic'` (consumer set `.open = false` from JS).
           Defaults to `'programmatic'` when no event-driven path
           captured a reason. Added v0.5.3 §156 per FEEDBACK-06 §2.
+  opened:
+    description: >-
+      Fired after the drawer finishes its open transition — scheduled
+      `--drawer-duration` ms after `showModal()` + `[data-open]`. Lets
+      Playwright (and any consumer code waiting for the drawer to be fully
+      open and interactive) listen for an event instead of guessing with
+      a fixed timeout. Cancelled if the drawer closes before the open
+      transition completes, so a rapid close→open never fires a stale
+      `opened`. Added per FEEDBACK-27.
 slots:
   backdrop:
     description: Scrim overlay behind the drawer (stamped by the component).
@@ -123,7 +132,23 @@ traits: []
 tokens: {}
 a2ui:
   rules: []
-anti_patterns: []
+anti_patterns:
+  - description: >-
+      Replacing a drawer's children wholesale — `drawer.innerHTML = '…'` —
+      wipes the internal <dialog> part UIDrawer stamps and tracks. render()
+      re-stamps and re-binds the dialog defensively (FEEDBACK-30), but the
+      authored header/section/footer skeleton is still destroyed on every
+      mutation, and any consumer-held reference to a former child is stale.
+    wrong: |
+      drawer.innerHTML = `<header>${title}</header><section>${body}</section>`;
+    right: |
+      <drawer-ui><header>Title</header><section id="body"></section></drawer-ui>
+      <!-- mutate a stable inner element, never the component host -->
+      document.getElementById('body').innerHTML = renderFields(claim);
+    rule: >-
+      Never set .innerHTML on a UIElement component host. Keep
+      <header>/<section>/<footer> as persistent children and mutate the
+      content of a plain inner element instead.
 examples:
   - name: drawer-panel
     description: Card with a trigger button that opens a Drawer side panel containing a form with inputs

package/components/segmented/class.js

@@ -33,6 +33,12 @@ export class UISegmented extends UIFormElement {
 
   static template = () => null;
 
+  // FEEDBACK-23: one-shot per-element warn when a consumer authors a direct
+  // child that isn't <segment-ui> (typically a bare <segment> tag — renders
+  // text but gets no sliding indicator, role, or aria-checked). WeakSet so
+  // the warn never pins the element from GC.
+  static #warnedNonSegment = new WeakSet();
+
   #indicator = null;
   #bound = false;
   #transitionRaf = null;
@@ -97,6 +103,23 @@ export class UISegmented extends UIFormElement {
   }
 
   render() {
+    // FEEDBACK-23: flag a non-<segment-ui> direct child once per element.
+    // Runs before the empty-guard so an all-bare-<segment> group still warns.
+    if (!UISegmented.#warnedNonSegment.has(this)) {
+      const bad = [...this.children].find(
+        (c) => c.tagName !== 'SEGMENT-UI' && !c.hasAttribute('data-indicator'),
+      );
+      if (bad) {
+        UISegmented.#warnedNonSegment.add(this);
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[segmented-ui] child <${bad.tagName.toLowerCase()}> is not ` +
+          `<segment-ui> — bare <segment> tags render text but receive no ` +
+          `sliding indicator or aria-checked state. Use <segment-ui>.`,
+        );
+      }
+    }
+
     const segs = this.#segments;
     if (!segs.length) return;
 

package/components/segmented/segmented.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Segmented.json",
   "title": "Segmented",
-  "description": "<segmented-ui value=\"tab1\">",
+  "description": "Single-select toggle group with an animated sliding indicator. Children must be segment-ui elements.",
   "type": "object",
   "allOf": [
     {
@@ -37,8 +37,8 @@
     },
     "examples": [
       {
-        "description": "Basic Segmented usage",
-        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"comp\"\n    ]\n  },\n  {\n    \"id\": \"comp\",\n    \"component\": \"Segmented\",\n    \"value\": \"\"\n  }\n]",
+        "description": "Segmented control with three segment-ui children for view switching.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"comp\"\n    ]\n  },\n  {\n    \"id\": \"comp\",\n    \"component\": \"Segmented\",\n    \"value\": \"daily\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"daily\",\n    \"text\": \"Daily\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"weekly\",\n    \"text\": \"Weekly\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"monthly\",\n    \"text\": \"Monthly\"\n  }\n]",
         "name": "basic-segmented"
       }
     ],
@@ -54,7 +54,14 @@
     ],
     "name": "UISegmented",
     "related": [],
-    "slots": {},
+    "slots": {
+      "default": {
+        "description": "Child segment-ui elements that form the toggle group. Children MUST be segment-ui — bare segment tags render text but are silently ignored for the sliding indicator and role/aria-checked state."
+      },
+      "indicator": {
+        "description": "Auto-created sliding indicator element prepended on first render."
+      }
+    },
     "states": [
       {
         "description": "Default, ready for interaction.",