@adia-ai/web-components 0.6.18 → 0.6.20

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.20] — 2026-05-21
+
+### Added — `table-ui` `row-click` event (FEEDBACK-35)
+
+- `<table-ui>` now dispatches a bubbling `row-click` event (detail:
+  `{ row, dataIndex }`) once per row click, alongside the existing per-cell
+  `cell-click`. Master-detail / open-flyout wiring no longer has to
+  deduplicate `cell-click` by `dataIndex`. `table.yaml` documents it.
+
+### Changed — `select-ui` honours declarative `<option selected>` (FEEDBACK-36)
+
+- `<select-ui>` now promotes an `<option selected>` child to the initial
+  value when the host carries no `[value]` attribute — matching native
+  `<select>` semantics. Previously the `selected` attribute was silently
+  ignored and the placeholder shown. Guarded on an empty `this.value`, so
+  consumers who set `[value]` explicitly are unaffected.
+
+### Changed — `chart-ui` wrong-`.data`-shape warning shows the correct shape (FEEDBACK-34)
+
+- The one-shot `console.warn` emitted when `.data` is set to a non-array
+  now embeds a minimal correct-shape example
+  (`[{ label: "Jan", value: 100 }, … ]`) instead of only naming the wrong
+  API and pointing at `chart.yaml`.
+
+### Docs — `table.yaml` / `select.yaml` description clarifications (FEEDBACK-35 §2, FEEDBACK-36)
+
+- `components/table/table.yaml` `sort` event: the `key` / `dir` detail
+  descriptions now name the fields explicitly (`key` not `column`, `dir` not
+  `direction`) — closing the guess the bare names invited.
+- `components/select/select.yaml` `value`: documents that a declarative
+  `<option selected>` child sets the initial value when the host `[value]`
+  attribute is absent.
+
+## [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)

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/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,20 @@ 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.\n` +
+        `Correct shape for <chart-ui x="label" y="value">:\n` +
+        `  [{ label: "Jan", value: 100 }, { label: "Feb", value: 200 }]`,
+      );
+    }
     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.",

package/components/segmented/segmented.yaml

@@ -4,7 +4,7 @@ tag: segmented-ui
 component: Segmented
 category: navigation
 version: 1
-description: <segmented-ui value="tab1">
+description: Single-select toggle group with an animated sliding indicator. Children must be segment-ui elements.
 props:
   value:
     description: Value of the currently selected segment.
@@ -13,7 +13,11 @@ props:
 events:
   change:
     description: Fired when the selected segment changes. detail contains { value }.
-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:
 - name: idle
   description: Default, ready for interaction.
@@ -24,10 +28,52 @@ a2ui:
 anti_patterns: []
 examples:
 - name: basic-segmented
-  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: >-
+    [
+      {
+        "id": "root",
+        "component": "Card",
+        "children": [
+          "sec"
+        ]
+      },
+      {
+        "id": "sec",
+        "component": "Section",
+        "children": [
+          "comp"
+        ]
+      },
+      {
+        "id": "comp",
+        "component": "Segmented",
+        "value": "daily",
+        "children": [
+          "s1",
+          "s2",
+          "s3"
+        ]
+      },
+      {
+        "id": "s1",
+        "component": "Segment",
+        "value": "daily",
+        "text": "Daily"
+      },
+      {
+        "id": "s2",
+        "component": "Segment",
+        "value": "weekly",
+        "text": "Weekly"
+      },
+      {
+        "id": "s3",
+        "component": "Segment",
+        "value": "monthly",
+        "text": "Monthly"
+      }
+    ]
 keywords:
 - segmented
 - options

package/components/select/class.js

@@ -212,15 +212,20 @@ export class UISelect extends UIFormElement {
     this.#options = [];
     // §225 (v0.5.9): track unknown-child-tag names so we can warn once per element.
     const unknownTags = new Set();
+    // FEEDBACK-36: capture the value of an <option selected> child so a
+    // declarative initial selection is honoured (native <select> parity).
+    let preSelected;
     for (const child of this.children) {
       if (child.tagName === 'OPTGROUP') {
         const group = { label: child.label || child.getAttribute('label') || '', options: [] };
         for (const opt of child.querySelectorAll('option')) {
           group.options.push({ value: opt.value, label: opt.textContent.trim(), disabled: opt.disabled });
+          if (preSelected === undefined && opt.hasAttribute('selected')) preSelected = opt.value;
         }
         this.#options.push(group);
       } else if (child.tagName === 'OPTION') {
         this.#options.push({ value: child.value, label: child.textContent.trim(), disabled: child.disabled });
+        if (preSelected === undefined && child.hasAttribute('selected')) preSelected = child.value;
       } else if (
         // §225: skip [slot="display"] / [slot="listbox"] / [slot="action"] etc. — these are
         // stamped by the component itself, not consumer-authored options. Anything other
@@ -231,6 +236,10 @@ export class UISelect extends UIFormElement {
       }
     }
     for (const child of [...this.querySelectorAll('option, optgroup')]) child.remove();
+    // FEEDBACK-36: honour <option selected> as the initial value when the host
+    // carries no [value] — matches native <select> semantics. Guarded on an
+    // empty this.value so consumers who set [value] explicitly are unaffected.
+    if (!this.value && preSelected !== undefined) this.value = preSelected;
     // §225 (v0.5.9): warn once per element when consumer authored non-<option> children.
     if (unknownTags.size > 0 && !UISelect.#warnedNonOption.has(this)) {
       UISelect.#warnedNonOption.add(this);

package/components/select/select.a2ui.json

@@ -122,7 +122,7 @@
       "default": "md"
     },
     "value": {
-      "description": "Currently selected option value",
+      "description": "Currently selected option value. With declarative <option> children, a child carrying the native `selected` attribute sets the initial value when this attribute is absent (native <select> parity).",
       "type": "string",
       "default": ""
     },

package/components/select/select.yaml

@@ -111,7 +111,10 @@ props:
     type: boolean
     default: false
   value:
-    description: Currently selected option value
+    description: >-
+      Currently selected option value. With declarative <option> children, a
+      child carrying the native `selected` attribute sets the initial value
+      when this attribute is absent (native <select> parity).
     type: string
     default: ""
 events:

package/components/table/class.js

@@ -47,6 +47,7 @@
  *   page       — { detail: { page } }
  *   resize     — { detail: { key, width } }
  *   cell-click — { detail: { key, row, value, dataIndex } }
+ *   row-click  — { detail: { row, dataIndex } }  — row-level companion to cell-click
  */
 
 import { UIElement } from '../../core/element.js';
@@ -1303,6 +1304,13 @@ export class UITable extends UIElement {
           bubbles: true,
           detail: { key, row: rowData, value, dataIndex },
         }));
+        // FEEDBACK-35: row-click convenience event — fires once per row,
+        // regardless of which cell was hit. detail is a strict subset of
+        // cell-click (no key/value) so it reads as row identity, not a cell.
+        this.dispatchEvent(new CustomEvent('row-click', {
+          bubbles: true,
+          detail: { row: rowData, dataIndex },
+        }));
       }
     }
   };

package/components/table/table.a2ui.json

@@ -144,6 +144,19 @@
           }
         }
       },
+      "row-click": {
+        "description": "Fired once when any cell in a data row is clicked — the row-level companion to cell-click. Use it for master-detail / open-flyout wiring.",
+        "detail": {
+          "dataIndex": {
+            "description": "Row index in the underlying data array.",
+            "type": "number"
+          },
+          "row": {
+            "description": "Row data object.",
+            "type": "object"
+          }
+        }
+      },
       "row-collapse": {
         "description": "Fired when an already-expanded row's chevron is activated (collapses the row). Mirror of row-expand.",
         "detail": {
@@ -183,11 +196,11 @@
         "description": "Fired when sort state changes via header click.",
         "detail": {
           "dir": {
-            "description": "Sort direction — \"asc\" / \"desc\" / null (cleared).",
+            "description": "Sort direction — \"asc\" / \"desc\" / null (cleared). The detail field is `dir` (not `direction`).",
             "type": "string"
           },
           "key": {
-            "description": "Column key being sorted.",
+            "description": "Column key being sorted — the detail field is `key` (not `column`).",
             "type": "string"
           },
           "sortState": {

package/components/table/table.d.ts

@@ -44,6 +44,14 @@ export interface TableResizeEventDetail {
 }
 
 export type TableResizeEvent = CustomEvent<TableResizeEventDetail>;
+export interface TableRowClickEventDetail {
+  /** Row index in the underlying data array. */
+  dataIndex: number;
+  /** Row data object. */
+  row: Record<string, unknown>;
+}
+
+export type TableRowClickEvent = CustomEvent<TableRowClickEventDetail>;
 export interface TableRowCollapseEventDetail {
   /** Row index in the underlying data array. */
   index: number;
@@ -67,9 +75,9 @@ export interface TableSelectEventDetail {
 
 export type TableSelectEvent = CustomEvent<TableSelectEventDetail>;
 export interface TableSortEventDetail {
-  /** Sort direction — "asc" / "desc" / null (cleared). */
+  /** Sort direction — "asc" / "desc" / null (cleared). The detail field is `dir` (not `direction`). */
   dir: string;
-  /** Column key being sorted. */
+  /** Column key being sorted — the detail field is `key` (not `column`). */
   key: string;
   /** Full sort state array (multi-column support). */
   sortState: unknown[];
@@ -110,6 +118,7 @@ export class UITable extends UIElement {
   addEventListener(type: 'filter-change', listener: (ev: TableFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'page', listener: (ev: TablePageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'resize', listener: (ev: TableResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'row-click', listener: (ev: TableRowClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'row-collapse', listener: (ev: TableRowCollapseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'row-expand', listener: (ev: TableRowExpandEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'select', listener: (ev: TableSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/components/table/table.yaml

@@ -91,6 +91,15 @@ events:
       dataIndex:
         type: number
         description: Row index in the underlying data array.
+  row-click:
+    description: Fired once when any cell in a data row is clicked — the row-level companion to cell-click. Use it for master-detail / open-flyout wiring.
+    detail:
+      row:
+        type: object
+        description: Row data object.
+      dataIndex:
+        type: number
+        description: Row index in the underlying data array.
   filter-change:
     description: Fired when an interactive filter row applies / clears. detail.filters is the current filter map.
     detail:
@@ -141,10 +150,10 @@ events:
     detail:
       key:
         type: string
-        description: Column key being sorted.
+        description: Column key being sorted — the detail field is `key` (not `column`).
       dir:
         type: string
-        description: Sort direction — "asc" / "desc" / null (cleared).
+        description: Sort direction — "asc" / "desc" / null (cleared). The detail field is `dir` (not `direction`).
       sortState:
         type: array
         description: Full sort state array (multi-column support).

package/components/textarea/textarea.a2ui.json

@@ -13,9 +13,24 @@
     }
   ],
   "properties": {
+    "required": {
+      "description": "Marks the field as required for form validation. Sets aria-required. Inherited from UIFormElement.",
+      "type": "boolean",
+      "default": false
+    },
     "component": {
       "const": "Textarea"
     },
+    "disabled": {
+      "description": "Disables interaction, removes contenteditable, and dims the control. Inherited from UIFormElement.",
+      "type": "boolean",
+      "default": false
+    },
+    "error": {
+      "description": "Validation error message. Set by constraint validation or manually via setInvalid(). Inherited from UIFormElement.",
+      "type": "string",
+      "default": ""
+    },
     "hint": {
       "description": "Help text displayed below the textarea. Hidden when error is set.",
       "type": "string",
@@ -36,6 +51,11 @@
       "type": "string",
       "default": ""
     },
+    "readonly": {
+      "description": "Prevents editing while keeping the surface focusable. Sets contenteditable=false. Inherited from UIFormElement.",
+      "type": "boolean",
+      "default": false
+    },
     "resize": {
       "description": "Resize behavior of the textarea.",
       "type": "string",
@@ -56,6 +76,11 @@
       "description": "§220 (v0.5.9, FEEDBACK-14 §3). Trailing-debounce on the `input`\nevent in milliseconds. When > 0, value mutates immediately + the UI\nstays responsive, but `input` dispatch is collapsed so only the\nfinal value in the throttle window emits. Useful for expensive\n`input`-driven computation (autosave preview, server-side\nautocomplete, large-doc reflow). `change` fires unthrottled on blur\n/ Enter; any pending `input` flushes before `change` so consumers\nsee input→input→…→input→change ordering. Default 0 preserves\nsynchronous emission.",
       "type": "number",
       "default": 0
+    },
+    "value": {
+      "description": "Current textarea value, synced with the contenteditable text surface. Inherited from UIFormElement.",
+      "type": "string",
+      "default": ""
     }
   },
   "required": [

package/components/textarea/textarea.yaml

@@ -8,6 +8,15 @@ category: layout
 version: 1
 description: Multiline text input. The host IS the interactive surface.
 props:
+  disabled:
+    description: Disables interaction, removes contenteditable, and dims the control. Inherited from UIFormElement.
+    type: boolean
+    default: false
+    reflect: true
+  error:
+    description: Validation error message. Set by constraint validation or manually via setInvalid(). Inherited from UIFormElement.
+    type: string
+    default: ""
   hint:
     description: Help text displayed below the textarea. Hidden when error is set.
     type: string
@@ -24,6 +33,16 @@ props:
     description: Placeholder text shown when textarea is empty.
     type: string
     default: ""
+  readonly:
+    description: Prevents editing while keeping the surface focusable. Sets contenteditable=false. Inherited from UIFormElement.
+    type: boolean
+    default: false
+    reflect: true
+  required:
+    description: Marks the field as required for form validation. Sets aria-required. Inherited from UIFormElement.
+    type: boolean
+    default: false
+    reflect: true
   resize:
     description: Resize behavior of the textarea.
     type: string
@@ -51,6 +70,10 @@ props:
     type: number
     default: 0
     reflect: true
+  value:
+    description: Current textarea value, synced with the contenteditable text surface. Inherited from UIFormElement.
+    type: string
+    default: ""
 events:
   change:
     description: Fired when the textarea loses focus after a value change.

package/core/element.js

@@ -262,6 +262,18 @@ export class UIElement extends HTMLElement {
 
   signal(v) { const s = signal(v); this.#as.push(s); return s; }
 
+  /**
+   * Get-or-create a structural part by slot name. Returns the existing
+   * `[slot="X"]` child when present, otherwise clones the part blueprint
+   * (`static parts`) and appends it. Re-stamped parts carry `_uiPart = true`
+   * so a part wiped by a host `innerHTML` mutation is detectable downstream.
+   *
+   * INVARIANT (FEEDBACK-31) — call `ensure()` from `render()`; never cache
+   * its result once in `connected()`. A consumer that replaces the host's
+   * children (`el.innerHTML = …`) wipes stamped parts; `render()` re-stamps
+   * them, but a reference captured once in `connected()` is left pointing at
+   * detached DOM. Part identity does not survive a host child-list wipe.
+   */
   ensure(slot) {
     for (const ch of this.children) {
       if (ch.getAttribute('slot') === slot) return ch;
@@ -272,6 +284,7 @@ export class UIElement extends HTMLElement {
     const blueprint = this.constructor._pp?.[slot];
     if (!blueprint) return null;
     const el = blueprint.cloneNode(true);
+    el._uiPart = true;
     this.appendChild(el);
     return el;
   }

package/css-module.d.ts

@@ -0,0 +1,6 @@
+// Ambient declaration so TypeScript (moduleResolution: bundler / node16)
+// can resolve CSS side-effect subpath imports — e.g.
+//   import '@adia-ai/web-components/css';
+// without a TS2882 "no type declarations for side-effect import" error.
+// See FEEDBACK-26.
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.6.18",
+  "version": "0.6.20",
   "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",
@@ -13,7 +13,10 @@
       "import": "./index.js",
       "default": "./index.js"
     },
-    "./css": "./index.css",
+    "./css": {
+      "types": "./css-module.d.ts",
+      "default": "./index.css"
+    },
     "./core": {
       "types": "./core/index.d.ts",
       "import": "./core/index.js",
@@ -39,9 +42,18 @@
       "import": "./components/*/class.js",
       "default": "./components/*/class.js"
     },
-    "./components/*.css": "./components/*/*.css",
-    "./components/*/*.css": "./components/*/*.css",
-    "./components/*/css/*.css": "./components/*/css/*.css",
+    "./components/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./components/*/*.css"
+    },
+    "./components/*/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./components/*/*.css"
+    },
+    "./components/*/css/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./components/*/css/*.css"
+    },
     "./styles/*": "./styles/*",
     "./traits": {
       "types": "./traits.d.ts",
@@ -77,6 +89,7 @@
     "index.js",
     "index.css",
     "index.d.ts",
+    "css-module.d.ts",
     "bin/",
     "custom-elements.json",
     "USAGE.md",