@adia-ai/web-components 0.8.39 → 0.8.41

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

@@ -34,8 +34,14 @@
       "default": false
     },
     "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",
+      "enum": [
+        "idle",
+        "active",
+        "completed",
+        "error"
+      ],
       "default": "idle"
     },
     "text": {
@@ -49,6 +55,13 @@
     "variant": {
       "description": "Visual variant (default | accent | success | warning | danger).",
       "type": "string",
+      "enum": [
+        "default",
+        "accent",
+        "success",
+        "warning",
+        "danger"
+      ],
       "default": "default"
     }
   },
@@ -57,6 +70,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "Timeline"
+    ],
     "anti_patterns": [],
     "category": "feedback",
     "composes": [],
@@ -70,6 +86,7 @@
       "history-row"
     ],
     "name": "UITimelineItem",
+    "parts": {},
     "related": [
       "Timeline",
       "FeedItem",
@@ -77,10 +94,16 @@
     ],
     "slots": {
       "description": {
-        "description": "Override slot for rich description markup (inline links, code spans, embedded badges). Renders beneath the primary text at body-subtle typography."
+        "description": "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)."
       },
       "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."
+        "description": "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)."
+      },
+      "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)."
       }
     },
     "states": [],

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.css

@@ -309,7 +309,7 @@ agent-reasoning-ui timeline-ui:not([orientation="horizontal"]),
     font-weight: var(--timeline-item-label-weight);
     font-size: var(--timeline-item-label-size);
     color: var(--timeline-item-label-fg);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     overflow-wrap: break-word;
     min-width: 0;
   }
@@ -323,7 +323,7 @@ agent-reasoning-ui timeline-ui:not([orientation="horizontal"]),
     grid-row: 2;
     color: var(--timeline-item-desc-fg);
     font-size: var(--timeline-item-desc-size);
-    line-height: 1.5;
+    line-height: var(--a-font-leading-relaxed);
     margin-top: var(--a-space-0-5);
   }
 
@@ -333,7 +333,7 @@ agent-reasoning-ui timeline-ui:not([orientation="horizontal"]),
     color: var(--timeline-item-time-fg);
     font-size: var(--timeline-item-time-size);
     font-variant-numeric: tabular-nums;
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     white-space: nowrap;
     justify-self: end;
   }
@@ -356,7 +356,7 @@ agent-reasoning-ui timeline-ui:not([orientation="horizontal"]),
     gap: var(--a-space-0-5);
     color: var(--timeline-item-outcome-fg);
     font-size: var(--timeline-item-desc-size);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-relaxed);
     animation: tl-fade var(--timeline-item-duration) var(--timeline-item-easing);
   }
 

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/toc/toc.css

@@ -59,7 +59,7 @@
     padding-inline: var(--toc-padding-inline);
     text-decoration: none;
     color: inherit;
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     border-inline-start: 2px solid var(--toc-rule-inactive);
     transition:
       color  var(--a-duration-fast) var(--a-easing),

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
@@ -34,11 +38,8 @@ import { UIElement } from '../../core/element.js';
 // truth. ADR-0056 (gh#1303): the child's current-state surface is the
 // declared, reflected `selected` prop below, converging onto <segment-ui>'s
 // mechanism (yaml → catalog → generative grammar) instead of a private
-// stamp. `toggle-group-ui` also stamps the legacy `data-selected` attribute
-// on the same element in parallel — DEPRECATED, kept only because external
-// CSS may already target it as an undocumented hook; its removal rides the
-// 0.9.0 breaking wave. Don't set `selected` directly on an option; drive
-// the group's `value` instead.
+// stamp. Don't set `selected` directly on an option; drive the group's
+// `value` instead.
 
 export class UIToggleOption extends UIElement {
   static properties = {
@@ -53,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');
   }
@@ -90,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);
@@ -110,13 +146,8 @@ export class UIToggleGroup extends UIElement {
       const isSelected = selected.has(optVal);
       // ADR-0056 (gh#1303): `selected` is the declared, reflected mechanism —
       // converges onto <segment-ui>'s convention (opt's own render() stamps
-      // aria-pressed from it). `data-selected` is stamped alongside it only
-      // as a DEPRECATED parallel hook for pre-existing external CSS; it no
-      // longer drives styling (toggle-group.css) and its removal rides the
-      // 0.9.0 breaking wave.
+      // aria-pressed from it).
       opt.selected = isSelected;
-      if (isSelected) opt.setAttribute('data-selected', '');
-      else opt.removeAttribute('data-selected');
     }
   }
 

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
@@ -10,9 +15,7 @@ toggle-option-ui:not([disabled]):hover {
 }
 
 /* ADR-0056 (gh#1303): converged onto <segment-ui>'s declared, reflected
-   [selected] prop, set by <toggle-group-ui> (toggle-group.class.js). The
-   parent also stamps the legacy `data-selected` attribute in parallel —
-   DEPRECATED, no longer styled here; removal rides the 0.9.0 breaking wave. */
+   [selected] prop, set by <toggle-group-ui> (toggle-group.class.js). */
 toggle-option-ui[selected] {
   --toggle-option-bg: var(--toggle-option-selected-bg);
   --toggle-option-fg: var(--toggle-option-selected-fg);

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;
@@ -41,8 +41,7 @@ export class UIToggleOption extends UIElement {
   /** Whether this option is currently selected. Managed by the parent
 <toggle-group-ui> container (ADR-0056) — don't set directly; the group's
 `value` is the single source of truth. Converges onto <segment-ui>'s
-declared reflected-prop mechanism (was previously a private
-`data-selected` stamp with no declared API surface). */
+declared reflected-prop mechanism. */
   selected: boolean;
   /** Visible label text. */
   text: string;