@adia-ai/web-components 0.5.8 → 0.5.10

package/components/list/list.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/list
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.
@@ -38,3 +38,12 @@ export class UIList extends UIElement {
   ): void;
   addEventListener(type: 'selection-change', listener: (ev: ListSelectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
+
+export class UIListItem extends UIElement {
+  /** Secondary line below the primary text. Subtle color. */
+  description: string;
+  /** Optional leading icon name (Phosphor). */
+  icon: string;
+  /** Primary text. Renders as semibold inline body. */
+  text: string;
+}

package/components/menu/menu-divider.a2ui.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/MenuDivider.json",
+  "title": "MenuDivider",
+  "description": "Visual separator between groups of `<menu-item-ui>` rows. Renders as a horizontal rule with role=\"separator\".",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "MenuDivider"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "navigation",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIMenuDivider",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "menu-divider-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/menu/menu-divider.yaml

@@ -0,0 +1,15 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §228 (v0.5.9): authored to close the §229 baseline class-export-undeclared
+# drift for UIMenuDivider. Ships as a sibling class in menu/class.js +
+# is registered alongside UIMenu + UIMenuItem.
+
+# Child component of <menu-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIMenuDivider
+tag: menu-divider-ui
+component: MenuDivider
+category: navigation
+version: 1
+description: |-
+  Visual separator between groups of `<menu-item-ui>` rows. Renders as a horizontal rule with role="separator".

package/components/menu/menu-item.a2ui.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/MenuItem.json",
+  "title": "MenuItem",
+  "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + value.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "MenuItem"
+    },
+    "disabled": {
+      "description": "Disabled state — blocks pointer + keyboard activation.",
+      "type": "boolean",
+      "default": false
+    },
+    "icon": {
+      "description": "Optional leading Phosphor icon name.",
+      "type": "string",
+      "default": ""
+    },
+    "text": {
+      "description": "Item label text.",
+      "type": "string",
+      "default": ""
+    },
+    "value": {
+      "description": "Stable identifier emitted via the parent menu's `select` event.",
+      "type": "string",
+      "default": ""
+    },
+    "variant": {
+      "description": "Semantic variant.",
+      "type": "string",
+      "enum": [
+        "default",
+        "danger"
+      ],
+      "default": "default"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "navigation",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIMenuItem",
+    "related": [],
+    "slots": {
+      "icon": {
+        "description": "Custom leading element override; falls through to `[icon]` prop if not slotted."
+      },
+      "text": {
+        "description": "Custom label content; falls through to `[text]` prop if not slotted."
+      }
+    },
+    "states": [],
+    "synonyms": {},
+    "tag": "menu-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/menu/menu-item.yaml

@@ -0,0 +1,45 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §228 (v0.5.9): authored to close the §229 baseline class-export-undeclared
+# drift for UIMenuItem. The item ships as a sibling class in menu/class.js
+# + is registered alongside UIMenu + UIMenuDivider.
+
+# Child component of <menu-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIMenuItem
+tag: menu-item-ui
+component: MenuItem
+category: navigation
+version: 1
+description: |-
+  Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + value.
+
+props:
+  icon:
+    description: Optional leading Phosphor icon name.
+    type: string
+    default: ""
+  text:
+    description: Item label text.
+    type: string
+    default: ""
+  value:
+    description: Stable identifier emitted via the parent menu's `select` event.
+    type: string
+    default: ""
+  variant:
+    description: Semantic variant.
+    type: string
+    default: default
+    enum:
+      - default
+      - danger
+  disabled:
+    description: Disabled state — blocks pointer + keyboard activation.
+    type: boolean
+    default: false
+slots:
+  icon:
+    description: Custom leading element override; falls through to `[icon]` prop if not slotted.
+  text:
+    description: Custom label content; falls through to `[text]` prop if not slotted.

package/components/menu/menu.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/menu
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.
@@ -36,3 +36,19 @@ export class UIMenu extends UIElement {
   ): void;
   addEventListener(type: 'action', listener: (ev: MenuActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
+
+export class UIMenuDivider extends UIElement {
+}
+
+export class UIMenuItem extends UIElement {
+  /** Disabled state — blocks pointer + keyboard activation. */
+  disabled: boolean;
+  /** Optional leading Phosphor icon name. */
+  icon: string;
+  /** Item label text. */
+  text: string;
+  /** Stable identifier emitted via the parent menu's `select` event. */
+  value: string;
+  /** Semantic variant. */
+  variant: 'default' | 'danger';
+}

package/components/modal/modal.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/modal
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/nav/nav.css

@@ -17,7 +17,7 @@
     /* Primary-variant collapse */
     --nav-width:           auto;
     --nav-width-collapsed: 48px;
-    --nav-duration: var(--a-duration-base, 200ms);
+    --nav-duration: var(--a-duration);  /* §230-bundle (v0.5.9): canonical mid-tier duration (250ms). Was orphaned --a-duration-base. */
     --nav-easing:   var(--a-easing, ease);
 
     /* Group-heading kicker */

package/components/nav/nav.d.ts

@@ -12,7 +12,7 @@ and a [heading] kicker rendered via CSS.
  * @see https://ui-kit.exe.xyz/site/components/nav
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/nav-group/nav-group.d.ts

@@ -12,7 +12,7 @@ when [collapsible] (default true).
  * @see https://ui-kit.exe.xyz/site/components/nav-group
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/nav-item/nav-item.d.ts

@@ -12,7 +12,7 @@ bubbles a `nav-select` event.
  * @see https://ui-kit.exe.xyz/site/components/nav-item
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/noodles/noodles.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/noodles
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/page/page.d.ts

@@ -10,7 +10,7 @@ primitives (`<header-ui>`, `<section-ui>`, `<footer-ui>`); the page's
  * @see https://ui-kit.exe.xyz/site/components/page
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/pagination/pagination.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/pagination
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/pane/pane.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/pane
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/pipeline-status/pipeline-status.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/pipeline-status
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/popover/popover.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/popover
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/progress/progress.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/progress
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/progress-row/progress-row.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/progress-row
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/range/range.css

@@ -13,7 +13,7 @@ range-ui:not([disabled]) [slot="field"]:hover [data-layer="fill"] {
     --range-fill-bg-hover:   var(--a-ui-bg-hover);
     --range-fill-bg-active:  var(--a-ui-bg-active);
     --range-fill-bg-disabled: var(--a-canvas-muted);
-    --range-fill-fg:         var(--a-ui-fg);
+    --range-fill-fg:         var(--a-fg);
     --range-fill-fg-disabled: var(--a-ui-text-disabled);
     --range-fill-label-fg:   var(--a-ui-text-subtle);
     --range-border:          var(--a-ui-border);

package/components/rating/rating.d.ts

@@ -23,6 +23,14 @@ export class UIRating extends UIFormElement {
   /** Allow half-step values (0.5, 1.5, …). */
   allowHalf: boolean;
   size: 'sm' | 'md' | 'lg';
+  /**
+   * §247 (v0.5.10, FB-26 §1): visual treatment family. `star` (default) /
+   * `heart` / `thumbs` swap the rendered icon set + selected-state color.
+   * Yaml-declared `enum` was not previously typed in `.d.ts`; consumers
+   * authoring `el.variant = 'heart'` got TS2339 despite the runtime
+   * accepting the value.
+   */
+  variant: 'star' | 'heart' | 'thumbs';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/richtext/richtext.a2ui.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://adiaui.dev/a2ui/v0_9/components/Richtext.json",
-  "title": "Richtext",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/RichText.json",
+  "title": "RichText",
   "description": "Renders markdown to styled HTML.",
   "type": "object",
   "allOf": [
@@ -14,7 +14,7 @@
   ],
   "properties": {
     "component": {
-      "const": "Richtext"
+      "const": "RichText"
     },
     "markdown": {
       "description": "Component property: markdown.",
@@ -61,7 +61,7 @@
     "keywords": [
       "richtext"
     ],
-    "name": "UIRichtext",
+    "name": "UIRichText",
     "related": [],
     "slots": {
       "default": {

package/components/richtext/richtext.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/richtext
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.
@@ -12,7 +12,7 @@
 
 import { UIElement } from '../../core/element.js';
 
-export class UIRichtext extends UIElement {
+export class UIRichText extends UIElement {
   /** Component property: markdown. */
   markdown: string;
   /** Source URL (image, iframe, etc.). */

package/components/richtext/richtext.yaml

@@ -1,7 +1,7 @@
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
-name: UIRichtext
+name: UIRichText
 tag: richtext-ui
-component: Richtext
+component: RichText
 category: forms
 version: 1
 description: Renders markdown to styled HTML.

package/components/row/row.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/row
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/segment/segment.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/segment
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/select/class.js

@@ -26,6 +26,14 @@ export class UISelect extends UIFormElement {
   // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
   static requiredIcons = ['caret-up-down'];
 
+  // §225 (v0.5.9, FEEDBACK-10 §3): once-per-element console.warn dedup when
+  // consumer authors children that aren't native <option>/<optgroup>. The
+  // common authoring mistake is reaching for <select-option> (mirroring the
+  // <*-ui> naming convention), which #parseOptions silently ignores. Matches
+  // v0.5.5 §184 §8 button-ui safety-net + v0.5.7 §201 color-picker WeakSet
+  // pattern. WeakSet so the warn doesn't pin the element from GC.
+  static #warnedNonOption = new WeakSet();
+
   static properties = {
     ...UIFormElement.properties,
     placeholder: { type: String,  default: 'Select...', reflect: true },
@@ -201,6 +209,8 @@ export class UISelect extends UIFormElement {
   /** Parse <option> and <optgroup> children into internal model. */
   #parseOptions() {
     this.#options = [];
+    // §225 (v0.5.9): track unknown-child-tag names so we can warn once per element.
+    const unknownTags = new Set();
     for (const child of this.children) {
       if (child.tagName === 'OPTGROUP') {
         const group = { label: child.label || child.getAttribute('label') || '', options: [] };
@@ -210,9 +220,27 @@ export class UISelect extends UIFormElement {
         this.#options.push(group);
       } else if (child.tagName === 'OPTION') {
         this.#options.push({ value: child.value, label: child.textContent.trim(), disabled: child.disabled });
+      } else if (
+        // §225: skip [slot="display"] / [slot="listbox"] / [slot="action"] etc. — these are
+        // stamped by the component itself, not consumer-authored options. Anything other
+        // than a slot-bearing child OR <option>/<optgroup> is a likely authoring mistake.
+        !child.hasAttribute('slot')
+      ) {
+        unknownTags.add(child.tagName.toLowerCase());
       }
     }
     for (const child of [...this.querySelectorAll('option, optgroup')]) child.remove();
+    // §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);
+      // eslint-disable-next-line no-console
+      console.warn(
+        `<select-ui>: ignoring unrecognized child element(s) [${[...unknownTags].join(', ')}]. ` +
+        `Consumer-authored children must be native <option> or <optgroup>, NOT <select-option> ` +
+        `or other <*-ui> shapes. Or set element.options = [...] programmatically. ` +
+        `(Once-per-element warn; see select.yaml usage: for details.)`,
+      );
+    }
   }
 
   set options(list) {

package/components/select/select.css

@@ -314,7 +314,7 @@ select-ui[divider] [role="group"] + [role="group"] {
 select-ui > [slot="hint"] {
   display: block;
   margin-top: var(--select-hint-mt, var(--a-space-1));
-  font-size: var(--select-hint-size, var(--a-fine-size));
+  font-size: var(--select-hint-size, var(--a-ui-xs));
   color: var(--select-hint-fg, var(--a-fg-muted));
   line-height: var(--select-hint-lh, 1.4);
 }

package/components/select/select.d.ts

@@ -42,6 +42,20 @@ export class UISelect extends UIFormElement {
   divider: boolean;
   /** §207 (v0.5.7): hint text below the field, wired to aria-describedby. */
   hint: string;
+  /**
+   * §247 (v0.5.10, FB-26 §1): visual variant. `default` = canonical chrome
+   * (border + bg); `outline` = bordered transparent; `ghost` = inline
+   * (no border); `soft` = subtle background tint. Mirrors `<input-ui>`
+   * variant family.
+   */
+  variant: 'default' | 'outline' | 'ghost' | 'soft';
+  /**
+   * §247 (v0.5.10, FB-26 §1): universal `[size]` attribute system —
+   * `xs` / `sm` / `md` (default) / `lg` / `xl`. Sets `--a-size` token
+   * locally; cascades to child icons / labels via the size-cascade pattern
+   * documented in USAGE.md §221a.
+   */
+  size: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 
   /**
    * Dynamic option list. Setting `.options = [...]` stamps option elements at

package/components/select/select.yaml

@@ -117,6 +117,34 @@ props:
 events:
   change:
     description: Fired when selected value changes
+usage: |-
+  §225 (v0.5.9) — Consumer-authored children must be native `<option>` or
+  `<optgroup>`. The `#parseOptions()` walker reads only those two tag names;
+  other shapes (including hypothetical `<select-option>` mirroring the `<*-ui>`
+  convention) are silently ignored. v0.5.9 adds a once-per-element
+  `console.warn` to surface the authoring mistake at runtime.
+
+  Two canonical paths:
+
+  ```html
+  <!-- Path 1: native option children -->
+  <select-ui name="role" label="Role">
+    <option value="user">User</option>
+    <option value="admin">Admin</option>
+    <optgroup label="Special">
+      <option value="ghost">Ghost</option>
+    </optgroup>
+  </select-ui>
+
+  <!-- Path 2: programmatic .options property -->
+  <select-ui id="role" name="role" label="Role"></select-ui>
+  <script>
+    document.getElementById('role').options = [
+      { value: 'user', label: 'User' },
+      { value: 'admin', label: 'Admin' },
+    ];
+  </script>
+  ```
 slots:
   label:
     description: Label element above the trigger

package/components/skeleton/skeleton.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/skeleton
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.