@adia-ai/web-components 0.8.40 → 0.8.42

package/components/timeline/timeline-item.yaml

@@ -38,26 +38,39 @@ props:
     description: Visual variant (default | accent | success | warning | danger).
     type: string
     default: 'default'
+    enum: [default, accent, success, warning, danger]
   status:
-    description: Lifecycle state (idle | active | completed | error). Pairs with `spinner` on "active" for an in-progress step.
+    description: Lifecycle state (idle | active | completed | error) — the values timeline.css currently styles. Pairs with `spinner` on "active" for an in-progress step.
     type: string
     default: 'idle'
+    enum: [idle, active, completed, error]
   spinner:
     description: Show a spinner instead of the dot/icon while status="active".
     type: boolean
     default: false
 
 slots:
+  label:
+    description: >-
+      Custom primary-line content; falls through to the [text] prop if not
+      slotted. render() only writes into the component-stamped fallback
+      span (gh#1462 adopt-or-stamp guard).
+  time:
+    description: >-
+      Custom timestamp/duration content; falls through to the [duration]
+      or [time] prop if not slotted. render() only writes into the
+      component-stamped fallback span (gh#1462 adopt-or-stamp guard).
   icon:
     description: >-
-      Override the [icon] glyph with a custom slotted element. Use for
-      branded icons, avatars, or non-Phosphor sources. Mutually exclusive
-      with the [icon] attribute.
+      Override the [icon] glyph with a custom slotted element (custom
+      icon-ui, image, avatar). Mutually exclusive with the [icon]
+      attribute — a consumer-authored slot child wins and is never renamed
+      or removed by render() (gh#1462 adopt-or-stamp guard).
   description:
     description: >-
-      Override slot for rich description markup (inline links, code spans,
-      embedded badges). Renders beneath the primary text at body-subtle
-      typography.
+      Custom secondary-line content; falls through to [description] prop
+      if not slotted. render() only writes into the component-stamped
+      fallback span (gh#1462 adopt-or-stamp guard).
 
 keywords:
   - timeline-item
@@ -75,6 +88,8 @@ related:
   - Stepper
 
 a2ui:
+  allowedParents:
+    - Timeline
   rules:
     - rule: 'Child of <timeline-ui> — one chronological event with timestamp + content + optional icon dot.'
       reason: 'Timeline cluster contract.'

package/components/timeline/timeline.a2ui.json

@@ -40,6 +40,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedChildren": [
+      "TimelineItem"
+    ],
     "anti_patterns": [],
     "category": "display",
     "composes": [
@@ -68,6 +71,7 @@
       "timeline"
     ],
     "name": "UITimeline",
+    "parts": {},
     "related": [
       "timeline-item"
     ],

package/components/timeline/timeline.class.js

@@ -104,14 +104,23 @@ export class UITimelineItem extends UIElement {
     this.render();
   }
 
+  // Adopt-or-stamp (gh#1462): a fallback child stamped from a prop is
+  // marked, and render() only ever writes into marked elements — a
+  // consumer-authored slot="label"/"description"/"time"/"icon" child is
+  // adopted as source of truth and never overwritten or removed. Mirrors
+  // action-item-ui/menu-item-ui's stamp-marking (PR #1429).
+  #stampMark(el) { el.dataset.timelineItemStamped = '1'; return el; }
+  #wasStamped(el) { return el?.dataset?.timelineItemStamped === '1'; }
+
   connected() {
-    if (!logicalSlotted(this, 'label').length) {
-      // Author provided just text/time — stamp the default slot structure
-      this.innerHTML = `
-        <span slot="label"></span>
-        <span slot="description"></span>
-        <span slot="time"></span>
-      `;
+    // Each slot's adopt-or-stamp decision is independent per slot key —
+    // an authored label must not suppress the prop-driven description/time
+    // fallbacks (mirrors action-item-ui's per-part stamping, PR #1429).
+    for (const name of ['label', 'description', 'time']) {
+      if (logicalSlotted(this, name).length) continue;
+      const span = this.#stampMark(document.createElement('span'));
+      span.setAttribute('slot', name);
+      this.appendChild(span);
     }
   }
 
@@ -119,20 +128,22 @@ export class UITimelineItem extends UIElement {
     const label = this.querySelector(':scope > [slot="label"]');
     const desc  = this.querySelector(':scope > [slot="description"]');
     const time  = this.querySelector(':scope > [slot="time"]');
-    if (label) label.textContent = this.text;
-    if (desc)  desc.textContent  = this.description;
-    if (time)  time.textContent  = this.duration || this.time;
+    if (this.#wasStamped(label)) label.textContent = this.text;
+    if (this.#wasStamped(desc))  desc.textContent  = this.description;
+    if (this.#wasStamped(time))  time.textContent  = this.duration || this.time;
 
+    const iconEl = this.querySelector(':scope > [slot="icon"]');
     if (this.icon) {
-      let iconEl = this.querySelector(':scope > [slot="icon"]');
-      if (!iconEl) {
-        iconEl = document.createElement('icon-ui');
-        iconEl.setAttribute('slot', 'icon');
-        this.prepend(iconEl);
+      if (iconEl) {
+        if (this.#wasStamped(iconEl)) iconEl.setAttribute('name', this.icon);
+      } else {
+        const el = this.#stampMark(document.createElement('icon-ui'));
+        el.setAttribute('slot', 'icon');
+        el.setAttribute('name', this.icon);
+        this.prepend(el);
       }
-      iconEl.setAttribute('name', this.icon);
-    } else {
-      this.querySelector(':scope > [slot="icon"]')?.remove();
+    } else if (this.#wasStamped(iconEl)) {
+      iconEl.remove();
     }
 
     // Outcomes sub-list + toggle caret

package/components/timeline/timeline.d.ts

@@ -42,12 +42,12 @@ export class UITimelineItem extends UIElement {
   icon: string;
   /** Show a spinner instead of the dot/icon while status="active". */
   spinner: boolean;
-  /** Lifecycle state (idle | active | completed | error). Pairs with `spinner` on "active" for an in-progress step. */
-  status: string;
+  /** Lifecycle state (idle | active | completed | error) — the values timeline.css currently styles. Pairs with `spinner` on "active" for an in-progress step. */
+  status: 'idle' | 'active' | 'completed' | 'error';
   /** Primary step label. */
   text: string;
   /** Absolute timestamp (HH:MM or ISO). */
   time: string;
   /** Visual variant (default | accent | success | warning | danger). */
-  variant: string;
+  variant: 'default' | 'accent' | 'success' | 'warning' | 'danger';
 }

package/components/timeline/timeline.yaml

@@ -46,6 +46,8 @@ requiredIcons:
   - caret-down
   - caret-right
 a2ui:
+  allowedChildren:
+    - TimelineItem
   rules:
     - rule: 'Use for chronological event lists (audit log, activity feed, version history).'
       reason: 'Visual rhythm: line + dot + content per row.'

package/components/toast/toast.a2ui.json

@@ -58,14 +58,20 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
-    "anti_patterns": [],
+    "anti_patterns": [
+      {
+        "fix": "{\"component\": \"Toast\", \"variant\": \"success\", \"text\": \"Saved successfully.\"}\n",
+        "why": "<feed-item-ui> is the underlying imperative-channel item — every\nfeed.yaml/feed-item.yaml a2ui rule says not to place it\ndeclaratively. It is meant to be created via UIFeed.post() (or a\ndeclared <toast-ui>, which forwards into it), never authored\ndirectly in generated markup.\n",
+        "wrong": "{\"component\": \"FeedItem\", \"variant\": \"success\", \"text\": \"Saved successfully.\"}\n"
+      }
+    ],
     "category": "container",
     "composes": [],
     "events": {},
     "examples": [
       {
-        "description": "Column of three toast notification components showing success, warning, and error variants.",
-        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Column\",\n    \"gap\": \"2\",\n    \"children\": [\n      \"t1\",\n      \"t2\",\n      \"t3\"\n    ]\n  },\n  {\n    \"id\": \"t1\",\n    \"component\": \"Toast\",\n    \"variant\": \"success\",\n    \"title\": \"Saved successfully\",\n    \"description\": \"Your changes have been saved.\",\n    \"dismissible\": true\n  },\n  {\n    \"id\": \"t2\",\n    \"component\": \"Toast\",\n    \"variant\": \"warning\",\n    \"title\": \"Storage almost full\",\n    \"description\": \"You are using 90% of your available storage.\",\n    \"dismissible\": true\n  },\n  {\n    \"id\": \"t3\",\n    \"component\": \"Toast\",\n    \"variant\": \"error\",\n    \"title\": \"Upload failed\",\n    \"description\": \"The file could not be uploaded. Please try again.\",\n    \"dismissible\": true\n  }\n]",
+        "description": "Column of three toast notification components showing success, warning, and danger variants.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Column\",\n    \"gap\": \"2\",\n    \"children\": [\n      \"t1\",\n      \"t2\",\n      \"t3\"\n    ]\n  },\n  {\n    \"id\": \"t1\",\n    \"component\": \"Toast\",\n    \"variant\": \"success\",\n    \"text\": \"Saved successfully. Your changes have been saved.\"\n  },\n  {\n    \"id\": \"t2\",\n    \"component\": \"Toast\",\n    \"variant\": \"warning\",\n    \"text\": \"Storage almost full — you are using 90% of your available storage.\"\n  },\n  {\n    \"id\": \"t3\",\n    \"component\": \"Toast\",\n    \"variant\": \"danger\",\n    \"text\": \"Upload failed. The file could not be uploaded. Please try again.\",\n    \"duration\": 0\n  }\n]",
         "name": "toast-notification"
       }
     ],
@@ -84,6 +90,7 @@
       "alert"
     ],
     "name": "UIToast",
+    "parts": {},
     "related": [
       "Feed",
       "Alert",

package/components/toast/toast.yaml

@@ -85,12 +85,24 @@ a2ui:
       reason: 'Toast pattern.'
     - rule: 'Typically posted into <feed-ui> via UIFeed.post(...); for inline persistent alerts use <alert-ui> instead.'
       reason: 'Posting model + surface boundary.'
-    - rule: 'Variant maps to severity (info, success, warn, error); same tokens as <alert-ui>.'
+    - rule: 'Variant maps to severity (info, success, warning, danger); same tokens as <alert-ui>.'
       reason: 'Visual consistency.'
-anti_patterns: []
+    - rule: 'Taught default for generated transient notifications — author `Toast` declaratively. It safely dissolves into `<feed-ui>` on connect (SPEC-FEED-CHANNEL-001 Phase 4; see toast.class.js), forwarding only `text`, `duration`, and `position` — not full parity with `UIFeed.post()`, which also accepts `heading`, `icon`, `dismissible`, and `action`, and defaults `variant` to `default` where Toast defaults to `info`. For those extra fields, call `UIFeed.post()` directly (imperative) instead of authoring `Toast`. Do not author `FeedItem` directly either way — <feed-ui>/<feed-item-ui>''s own a2ui rules say not to place it declaratively; that pair is the imperative channel Toast forwards into, not itself a generation target.'
+      reason: 'Taught-default ruling (#1363 C6 / #1375): Toast is the sanctioned declarative surface for the fields it forwards; Feed is the underlying imperative/programmatic channel and the only path to its richer fields.'
+anti_patterns:
+  - wrong: |
+      {"component": "FeedItem", "variant": "success", "text": "Saved successfully."}
+    why: |
+      <feed-item-ui> is the underlying imperative-channel item — every
+      feed.yaml/feed-item.yaml a2ui rule says not to place it
+      declaratively. It is meant to be created via UIFeed.post() (or a
+      declared <toast-ui>, which forwards into it), never authored
+      directly in generated markup.
+    fix: |
+      {"component": "Toast", "variant": "success", "text": "Saved successfully."}
 examples:
   - name: toast-notification
-    description: Column of three toast notification components showing success, warning, and error variants.
+    description: Column of three toast notification components showing success, warning, and danger variants.
     a2ui: >-
       [
         {
@@ -107,25 +119,20 @@ examples:
           "id": "t1",
           "component": "Toast",
           "variant": "success",
-          "title": "Saved successfully",
-          "description": "Your changes have been saved.",
-          "dismissible": true
+          "text": "Saved successfully. Your changes have been saved."
         },
         {
           "id": "t2",
           "component": "Toast",
           "variant": "warning",
-          "title": "Storage almost full",
-          "description": "You are using 90% of your available storage.",
-          "dismissible": true
+          "text": "Storage almost full — you are using 90% of your available storage."
         },
         {
           "id": "t3",
           "component": "Toast",
-          "variant": "error",
-          "title": "Upload failed",
-          "description": "The file could not be uploaded. Please try again.",
-          "dismissible": true
+          "variant": "danger",
+          "text": "Upload failed. The file could not be uploaded. Please try again.",
+          "duration": 0
         }
       ]
 keywords:

package/components/toc/toc.a2ui.json

@@ -81,6 +81,7 @@
       "heading-nav"
     ],
     "name": "UITableOfContents",
+    "parts": {},
     "related": [
       "aside",
       "nav",

package/components/toggle-group/toggle-group.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ToggleGroup.json",
   "title": "ToggleGroup",
-  "description": "Multi-select button group (unlike <segmented-ui> which is single-select). Hosts <toggle-option-ui> children, each independently toggleable; emits change events with the active value set. Use for filter chips or feature flag clusters; for single-select option groups use <segmented-ui> instead.",
+  "description": "DEPRECATED (gh#1369) — use <segmented-ui multiple> + <segment-ui> instead. Multi-select button group (unlike <segmented-ui> which is single-select by default). Hosts <toggle-option-ui> children, each independently toggleable; emits change events with the active value set.",
   "type": "object",
   "allOf": [
     {
@@ -17,7 +17,7 @@
       "const": "ToggleGroup"
     },
     "single": {
-      "description": "When true, restrict to one active option (single-select).",
+      "description": "When true, restrict to one active option (single-select) — clicking the already-selected option again CLEARS it (empty value), unlike a native radiogroup. Migration (gh#1369): [single]=true maps to plain <segmented-ui> (no [multiple]) — note segmented-ui's single-select never clears on re-click, it's standard radiogroup semantics; the default (false, multi-select) maps to <segmented-ui multiple>.",
       "type": "boolean",
       "default": false
     },
@@ -32,6 +32,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedChildren": [
+      "ToggleOption"
+    ],
     "anti_patterns": [],
     "category": "navigation",
     "composes": [],
@@ -60,6 +63,7 @@
       "group"
     ],
     "name": "UIToggleGroup",
+    "parts": {},
     "related": [
       "ToggleOption",
       "Segmented",
@@ -76,7 +80,7 @@
         "name": "idle"
       }
     ],
-    "status": "stable",
+    "status": "deprecated",
     "synonyms": {
       "toggle-group": [
         "segmented-control",

package/components/toggle-group/toggle-group.class.js

@@ -12,13 +12,17 @@
  */
 
 /**
+ * DEPRECATED (gh#1369, #1363 C1, ADR-0057) — use <segmented-ui multiple> +
+ * <segment-ui> instead (same comma-separated value encoding). Kept working
+ * as-is for existing consumers; no behavior change.
+ *
  * <toggle-group-ui value="bold,italic">
  *   <toggle-option-ui value="bold" icon="text-b"></toggle-option-ui>
  *   <toggle-option-ui value="italic" icon="text-italic"></toggle-option-ui>
  *   <toggle-option-ui value="underline" icon="text-underline"></toggle-option-ui>
  * </toggle-group-ui>
  *
- * Multi-select button group (unlike segmented which is single-select).
+ * Multi-select button group (unlike segmented which is single-select by default).
  *
  * Properties:
  *   value  — comma-separated selected values
@@ -50,7 +54,22 @@ export class UIToggleOption extends UIElement {
 
   #stamped = false;
 
+  // gh#1369 (#1363 C1): DEPRECATED — use <segment-ui> inside
+  // <segmented-ui multiple> instead. One-time warn, same pattern as
+  // UIFormElement's #labelWarned (form.js) — informational only, behavior
+  // is unchanged.
+  static #deprecationWarned = false;
+
   connected() {
+    if (!UIToggleOption.#deprecationWarned) {
+      UIToggleOption.#deprecationWarned = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[AdiaUI] <toggle-option-ui> is deprecated — use <segment-ui> ' +
+        'inside <segmented-ui multiple> instead (gh#1369, #1363 C1). ' +
+        'Kept working as-is; no behavior change.',
+      );
+    }
     this.setAttribute('role', 'button');
     this.setAttribute('tabindex', '0');
   }
@@ -87,11 +106,31 @@ export class UIToggleGroup extends UIElement {
 
   #bound = false;
 
+  // gh#1369 (#1363 C1): DEPRECATED — use <segmented-ui multiple> instead.
+  static #deprecationWarned = false;
+
   get #valueSet() {
     return new Set(this.value ? this.value.split(',').map(v => v.trim()).filter(Boolean) : []);
   }
 
   connected() {
+    if (!UIToggleGroup.#deprecationWarned) {
+      UIToggleGroup.#deprecationWarned = true;
+      // #deprecationWarned is a one-shot PER CLASS (not per instance,
+      // matching UIFormElement's #labelWarned pattern) — the message can't
+      // branch on THIS instance's [single] alone without misleading a page
+      // that mixes single and non-single toggle-groups, so it states both
+      // mappings instead (gh#1369 review).
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[AdiaUI] <toggle-group-ui> is deprecated (gh#1369, #1363 C1) — ' +
+        'migrate to <segmented-ui multiple> + <segment-ui> (multi-select, ' +
+        'the default) or plain <segmented-ui> with no [multiple] (when ' +
+        '[single] is set — note single-select never clears on re-click, ' +
+        'unlike [single]\'s clear-on-reclick). Same comma-separated value ' +
+        'encoding either way. Kept working as-is; no behavior change.',
+      );
+    }
     if (!this.#bound) {
       this.#bound = true;
       this.addEventListener('click', this.#onClick);

package/components/toggle-group/toggle-group.css

@@ -1,4 +1,9 @@
-/* Safari 17.x bug: `:scope:not(...):hover` (Flavor A) and `:scope[selected]`
+/* DEPRECATED (gh#1369, #1363 C1, ADR-0057): <toggle-group-ui>/
+   <toggle-option-ui> are superseded by <segmented-ui multiple> +
+   <segment-ui> (segment.css owns the equivalent [multiple]-mode styling).
+   This file is kept as-is for existing consumers — no behavior change.
+
+   Safari 17.x bug: `:scope:not(...):hover` (Flavor A) and `:scope[selected]`
    (Flavor B — attribute-removal restyle) both fail inside `@scope`.
    Selectors moved out. The @scope is `(toggle-option-ui)` — NOT
    `(toggle-group-ui)` — so the moved-out selectors target

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

@@ -1,5 +1,5 @@
 /**
- * `<toggle-group-ui>` — Multi-select button group (unlike <segmented-ui> which is single-select). Hosts <toggle-option-ui> children, each independently toggleable; emits change events with the active value set. Use for filter chips or feature flag clusters; for single-select option groups use <segmented-ui> instead.
+ * `<toggle-group-ui>` — DEPRECATED (gh#1369) — use <segmented-ui multiple> + <segment-ui> instead. Multi-select button group (unlike <segmented-ui> which is single-select by default). Hosts <toggle-option-ui> children, each independently toggleable; emits change events with the active value set.
  *
  * @see https://ui-kit.exe.xyz/site/components/toggle-group
  *
@@ -20,7 +20,7 @@ export interface ToggleGroupChangeEventDetail {
 export type ToggleGroupChangeEvent = CustomEvent<ToggleGroupChangeEventDetail>;
 
 export class UIToggleGroup extends UIElement {
-  /** When true, restrict to one active option (single-select). */
+  /** When true, restrict to one active option (single-select) — clicking the already-selected option again CLEARS it (empty value), unlike a native radiogroup. Migration (gh#1369): [single]=true maps to plain <segmented-ui> (no [multiple]) — note segmented-ui's single-select never clears on re-click, it's standard radiogroup semantics; the default (false, multi-select) maps to <segmented-ui multiple>. */
   single: boolean;
   /** Comma-separated selected values */
   value: string;

package/components/toggle-group/toggle-group.yaml

@@ -5,22 +5,29 @@
 # onto <segment-ui>'s declared, reflected `[selected]` prop (see
 # toggle-option.yaml). This container sets that prop, keeping `value` as the
 # single source of truth.
+#
+# DEPRECATED (gh#1369, #1363 C1, ADR-0057): superseded by
+# <segmented-ui multiple> + <segment-ui> — same comma-separated value
+# encoding, same corpus/catalog presence. Kept working as-is (no behavior
+# change, one-time console.warn on connect); status: deprecated per the
+# yaml deprecation contract rather than a literal JS-level delegation —
+# see PR body "Rejected alternatives" for why.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIToggleGroup
 tag: toggle-group-ui
-status: stable
+status: deprecated
 component: ToggleGroup
 category: navigation
 version: 1
 description: >-
-  Multi-select button group (unlike <segmented-ui> which is
-  single-select). Hosts <toggle-option-ui> children, each independently
-  toggleable; emits change events with the active value set. Use for
-  filter chips or feature flag clusters; for single-select option groups
-  use <segmented-ui> instead.
+  DEPRECATED (gh#1369) — use <segmented-ui multiple> + <segment-ui>
+  instead. Multi-select button group (unlike <segmented-ui> which is
+  single-select by default). Hosts <toggle-option-ui> children, each
+  independently toggleable; emits change events with the active value
+  set.
 props:
   single:
-    description: When true, restrict to one active option (single-select).
+    description: "When true, restrict to one active option (single-select) — clicking the already-selected option again CLEARS it (empty value), unlike a native radiogroup. Migration (gh#1369): [single]=true maps to plain <segmented-ui> (no [multiple]) — note segmented-ui's single-select never clears on re-click, it's standard radiogroup semantics; the default (false, multi-select) maps to <segmented-ui multiple>."
     type: boolean
     default: false
     reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
@@ -78,15 +85,17 @@ tokens:
   --toggle-option-selected-fg:
     description: Text color when selected
 a2ui:
+  allowedChildren:
+    - ToggleOption
   rules:
+    - rule: 'DEPRECATED (gh#1369, #1363 C1) — generate <segmented-ui multiple> + <segment-ui> children instead when [single] is false/absent (the default, multi-select). When [single] is true, generate plain <segmented-ui> (no [multiple]) instead — single-select toggle-group maps to segmented''s own single-select mode, not the multiple axis; note segmented-ui single-select never clears on re-click (toggle-group[single] does). Same comma-separated value encoding either way; toggle-group is kept working for existing consumers but should not appear in new generated output.'
+      reason: 'Deprecation redirect — this is the primary rule for this component now.'
     - rule: 'Multi-select button cluster — hosts <toggle-option-ui> children, each independently toggleable.'
-      reason: 'Multi-select cluster contract.'
-    - rule: 'Different from <segmented-ui> (single-select) — toggle-group emits a SET of active values.'
-      reason: 'Selection model distinction.'
+      reason: 'Multi-select cluster contract (legacy).'
     - rule: 'Use for filter chips, multi-flag toggles, day-of-week pickers; for binary on/off use <switch-ui>.'
-      reason: 'Capacity guidance.'
+      reason: 'Capacity guidance (legacy).'
     - rule: 'Sets the child <toggle-option-ui>''s declared [selected] prop to reflect the group value (ADR-0056) — do not author [selected] directly in generated markup; author the group''s value instead.'
-      reason: 'Parent-managed declared state — group value stays the single source of truth.'
+      reason: 'Parent-managed declared state — group value stays the single source of truth (legacy).'
 anti_patterns: []
 examples:
   - name: basic-toggle-group

package/components/toggle-group/toggle-option.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ToggleOption.json",
   "title": "ToggleOption",
-  "description": "Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.",
+  "description": "DEPRECATED (gh#1369) — use `<segment-ui>` inside `<segmented-ui multiple>` instead. Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.",
   "type": "object",
   "allOf": [
     {
@@ -47,8 +47,11 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "ToggleGroup"
+    ],
     "anti_patterns": [],
-    "category": "forms",
+    "category": "form",
     "composes": [],
     "events": {},
     "examples": [],
@@ -59,6 +62,7 @@
       "segmented-option"
     ],
     "name": "UIToggleOption",
+    "parts": {},
     "related": [
       "ToggleGroup",
       "Segment",
@@ -66,7 +70,7 @@
     ],
     "slots": {},
     "states": [],
-    "status": "stable",
+    "status": "deprecated",
     "synonyms": {
       "toggle-option": [
         "toggle-segment",

package/components/toggle-group/toggle-option.yaml

@@ -6,17 +6,21 @@
 #
 # ADR-0056 (gh#1303): `selected` converges onto <segment-ui>'s declared,
 # parent-managed, reflected-prop convention.
+#
+# DEPRECATED (gh#1369, #1363 C1, ADR-0057): superseded by <segment-ui>
+# (used as a child of <segmented-ui multiple>). Kept working as-is; see
+# toggle-group.yaml's header for the deprecation rationale.
 
 # Child component of <toggle-group-ui>. Surface only inside that parent.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIToggleOption
 tag: toggle-option-ui
-status: stable
+status: deprecated
 component: ToggleOption
-category: forms
+category: form
 version: 1
 description: |-
-  Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.
+  DEPRECATED (gh#1369) — use `<segment-ui>` inside `<segmented-ui multiple>` instead. Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.
 
 props:
   value:
@@ -60,10 +64,12 @@ related:
   - Radio
 
 a2ui:
+  allowedParents:
+    - ToggleGroup
   rules:
+    - rule: 'DEPRECATED (gh#1369, #1363 C1) — generate <segment-ui> instead, as a child of <segmented-ui multiple> (or plain <segmented-ui>, no [multiple], if the parent toggle-group had [single] — see toggle-group.yaml). toggle-option is kept working for existing consumers but should not appear in new generated output.'
+      reason: 'Deprecation redirect — this is the primary rule for this component now.'
     - rule: 'Child of <toggle-group-ui> — one independently-toggleable button in a multi-select cluster.'
-      reason: 'Multi-select cluster contract.'
-    - rule: 'Different from <segment-ui> (which is single-select inside <segmented-ui>).'
-      reason: 'Selection model boundary.'
+      reason: 'Multi-select cluster contract (legacy).'
     - rule: 'Selected state exposed via its own declared [selected] reflected prop, set by the parent <toggle-group-ui> (ADR-0056) — mirrors <segment-ui>''s convention. Do not set [selected] directly; drive the group''s value instead.'
-      reason: 'Parent-managed declared state — group value stays the single source of truth.'
+      reason: 'Parent-managed declared state — group value stays the single source of truth (legacy).'

package/components/toggle-scheme/toggle-scheme.a2ui.json

@@ -121,7 +121,7 @@
   "unevaluatedProperties": false,
   "x-adiaui": {
     "anti_patterns": [],
-    "category": "control",
+    "category": "action",
     "composes": [
       "button-ui"
     ],
@@ -158,6 +158,7 @@
       "sun"
     ],
     "name": "UIToggleScheme",
+    "parts": {},
     "related": [
       "Button",
       "Switch"

package/components/toggle-scheme/toggle-scheme.yaml

@@ -4,7 +4,7 @@ name: UIToggleScheme
 tag: toggle-scheme-ui
 status: stable
 component: ToggleScheme
-category: control
+category: action
 version: 1
 description: >-
   Icon-button primitive that toggles `color-scheme` between light and dark on

package/components/toolbar/toolbar-group.a2ui.json

@@ -34,6 +34,7 @@
       "toolbar-cluster"
     ],
     "name": "UIToolbarGroup",
+    "parts": {},
     "related": [
       "Toolbar",
       "Button",

package/components/toolbar/toolbar.a2ui.json

@@ -67,6 +67,7 @@
       "actions"
     ],
     "name": "UIToolbar",
+    "parts": {},
     "related": [
       "button",
       "divider"

package/components/toolbar/toolbar.class.js

@@ -263,6 +263,9 @@ export class UIToolbar extends UIElement {
 
   #queueReflow() {
     if (this.#reflowQueued) return;
+    // No rAF (SSR shim — gh#1436's render sweep) → no layout to measure
+    // overflow against; every item stays inline and the client reflows.
+    if (typeof requestAnimationFrame !== 'function') return;
     this.#reflowQueued = true;
     this.#reflowRaf = requestAnimationFrame(() => {
       this.#reflowRaf = null;

package/components/tooltip/tooltip.a2ui.json

@@ -95,6 +95,7 @@
       "popover"
     ],
     "name": "UITooltip",
+    "parts": {},
     "related": [
       "button"
     ],