@adia-ai/web-components 0.6.18 → 0.6.19

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # 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)

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,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.",

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/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.19",
   "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",