@adia-ai/web-components 0.8.39 → 0.8.41

package/components/section/section.a2ui.json

@@ -52,6 +52,7 @@
       "section"
     ],
     "name": "UISection",
+    "parts": {},
     "related": [
       "avatar",
       "input",

package/components/segment/segment.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Segment.json",
   "title": "Segment",
-  "description": "Individual segment child of <segmented-ui> — carries the [value],\n[text], optional [icon], and [selected] state for one option in\na horizontal segmented selector. Distinct from <tab-ui> (a view\nswitcher's child) and <option> (native option for <select-ui>).\nUse segment-ui only as a direct child of <segmented-ui>; never\nstandalone.\n",
+  "description": "Individual segment child of <segmented-ui> — carries the [value],\n[text], optional [icon], and [selected] state for one option in\na horizontal segmented selector, single- or multi-select\n(<segmented-ui multiple>, gh#1369). Distinct from <tab-ui> (a view\nswitcher's child) and <option> (native option for <select-ui>).\nUse segment-ui only as a direct child of <segmented-ui>; never\nstandalone.\n",
   "type": "object",
   "allOf": [
     {
@@ -47,6 +47,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "Segmented"
+    ],
     "anti_patterns": [],
     "category": "navigation",
     "composes": [
@@ -56,36 +59,39 @@
     "examples": [
       {
         "description": "Segmented control with 3 segment options for tab-like switching.",
-        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"SegmentedControl\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"text\": \"Overview\",\n    \"active\": true\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"text\": \"Features\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"text\": \"Pricing\"\n  }\n]",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Segmented\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"text\": \"Overview\",\n    \"selected\": true\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"text\": \"Features\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"text\": \"Pricing\"\n  }\n]",
         "name": "segmented-control"
       },
       {
         "description": "Three segments inside a segmented control for view switching.",
-        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"SegmentedControl\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"overview\",\n    \"text\": \"Overview\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"features\",\n    \"text\": \"Features\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"pricing\",\n    \"text\": \"Pricing\"\n  }\n]",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Segmented\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"overview\",\n    \"text\": \"Overview\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"features\",\n    \"text\": \"Features\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"pricing\",\n    \"text\": \"Pricing\"\n  }\n]",
         "name": "basic"
       },
       {
         "description": "Segmented control showing four time-range segments labeled via text attribute.",
-        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"SegmentedControl\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\",\n      \"s4\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"d\",\n    \"text\": \"Daily\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"w\",\n    \"text\": \"Weekly\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"m\",\n    \"text\": \"Monthly\"\n  },\n  {\n    \"id\": \"s4\",\n    \"component\": \"Segment\",\n    \"value\": \"y\",\n    \"text\": \"Yearly\"\n  }\n]",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Segmented\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\",\n      \"s4\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"d\",\n    \"text\": \"Daily\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"w\",\n    \"text\": \"Weekly\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"m\",\n    \"text\": \"Monthly\"\n  },\n  {\n    \"id\": \"s4\",\n    \"component\": \"Segment\",\n    \"value\": \"y\",\n    \"text\": \"Yearly\"\n  }\n]",
         "name": "text"
       },
       {
         "description": "Segmented control with one disabled segment that cannot be selected.",
-        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"SegmentedControl\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"free\",\n    \"text\": \"Free\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"pro\",\n    \"text\": \"Pro\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"enterprise\",\n    \"text\": \"Enterprise\",\n    \"disabled\": true\n  }\n]",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Segmented\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"free\",\n    \"text\": \"Free\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"pro\",\n    \"text\": \"Pro\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"enterprise\",\n    \"text\": \"Enterprise\",\n    \"disabled\": true\n  }\n]",
         "name": "disabled"
       },
       {
         "description": "Segmented control with icon+text segments for view-mode toggles (list, grid, board).",
-        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"SegmentedControl\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"list\",\n    \"text\": \"List\",\n    \"icon\": \"list\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"grid\",\n    \"text\": \"Grid\",\n    \"icon\": \"squares-four\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"board\",\n    \"text\": \"Board\",\n    \"icon\": \"kanban\"\n  }\n]",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Segmented\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"list\",\n    \"text\": \"List\",\n    \"icon\": \"list\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"grid\",\n    \"text\": \"Grid\",\n    \"icon\": \"squares-four\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"board\",\n    \"text\": \"Board\",\n    \"icon\": \"kanban\"\n  }\n]",
         "name": "icons"
       }
     ],
     "keywords": [
-      "segment"
+      "segment",
+      "toggle-option"
     ],
     "name": "UISegment",
+    "parts": {},
     "related": [
-      "segmented-control"
+      "segmented-control",
+      "ToggleOption"
     ],
     "slots": {},
     "states": [
@@ -104,11 +110,16 @@
       "segment": [
         "segment-button",
         "segmented-option",
-        "option-button"
+        "option-button",
+        "toggle-option"
       ]
     },
     "tag": "segment-ui",
-    "tokens": {},
+    "tokens": {
+      "--segment-bg-selected": {
+        "description": "Background color of a selected segment under the parent's [multiple] mode (no sliding indicator in that mode)."
+      }
+    },
     "traits": [],
     "version": 1
   }

package/components/segment/segment.css

@@ -8,6 +8,16 @@ segment-ui[selected] {
   color: var(--segment-fg-selected);
 }
 
+/* [multiple] (gh#1369, #1363 C1): the parent segmented-ui[multiple] never
+   creates a sliding indicator (segmented.class.js render()), so each
+   selected segment paints its own background instead — mirrors the
+   deprecated toggle-option-ui[selected] treatment it replaces. Scoped to
+   the multiple ancestor so single-select's indicator-driven look is
+   unchanged. */
+segmented-ui[multiple] > segment-ui[selected] {
+  background: var(--segment-bg-selected);
+}
+
 @scope (segment-ui) {
   :where(:scope) {
     /* ── Layout ── */
@@ -23,15 +33,21 @@ segment-ui[selected] {
        `line-height: 1` is deliberate, but the label's ::after clips to its
        own line box, so inheriting 1 makes half-leading negative and shears
        descenders (g/j/p/q/y, parentheses) by ~0.93px at the default size —
-       gh#906. Snug (1.3) contains the font's content box at every [size];
-       mirrors --button-label-line-height. */
-    --segment-label-line-height: var(--a-leading-snug);
+       gh#906. Normal (1.35) contains the font's content box at every
+       [size]; mirrors --button-label-line-height. Value-nearest migration
+       from the retired --a-leading-snug (1.3) — ADR-0052. */
+    --segment-label-line-height: var(--a-font-leading-normal);
 
     /* ── Colors ── */
     --segment-fg:              var(--a-ui-text-subtle);
     --segment-fg-hover:        var(--a-ui-text-hover);
     --segment-fg-selected:     var(--a-chrome-dark);
     --segment-fg-disabled:     var(--a-ui-text-disabled);
+    /* [multiple] only — see the moved-out selector above (Safari 17.x bug
+       note at top of file). Same default the deprecated
+       toggle-option-ui[selected] background used, for visual continuity
+       across the merge (gh#1369). */
+    --segment-bg-selected:     var(--md-sys-color-primary-container);
 
     /* ── Transition ── */
     --segment-duration:        var(--a-duration-fast);
@@ -60,7 +76,7 @@ segment-ui[selected] {
     font-family: var(--segment-font-family);
     font-size: var(--segment-font-size);
     font-weight: var(--segment-font-weight);
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     color: var(--segment-fg);
     white-space: nowrap;
     overflow: hidden;

package/components/segment/segment.d.ts

@@ -1,7 +1,8 @@
 /**
  * `<segment-ui>` — Individual segment child of <segmented-ui> — carries the [value],
 [text], optional [icon], and [selected] state for one option in
-a horizontal segmented selector. Distinct from <tab-ui> (a view
+a horizontal segmented selector, single- or multi-select
+(<segmented-ui multiple>, gh#1369). Distinct from <tab-ui> (a view
 switcher's child) and <option> (native option for <select-ui>).
 Use segment-ui only as a direct child of <segmented-ui>; never
 standalone.

package/components/segment/segment.yaml

@@ -10,7 +10,8 @@ version: 1
 description: |
   Individual segment child of <segmented-ui> — carries the [value],
   [text], optional [icon], and [selected] state for one option in
-  a horizontal segmented selector. Distinct from <tab-ui> (a view
+  a horizontal segmented selector, single- or multi-select
+  (<segmented-ui multiple>, gh#1369). Distinct from <tab-ui> (a view
   switcher's child) and <option> (native option for <select-ui>).
   Use segment-ui only as a direct child of <segmented-ui>; never
   standalone.
@@ -51,14 +52,18 @@ states:
     description: Non-interactive; dimmed.
     attribute: disabled
 traits: []
-tokens: {}
+tokens:
+  --segment-bg-selected:
+    description: Background color of a selected segment under the parent's [multiple] mode (no sliding indicator in that mode).
 a2ui:
+  allowedParents:
+    - Segmented
   rules:
-    - rule: 'Child of <segmented-ui> — one selectable option button in a single-select group.'
+    - rule: 'Child of <segmented-ui> — one selectable option button; the parent''s [multiple] axis decides single- or multi-select, segment-ui itself is unchanged either way.'
       reason: 'Cluster contract.'
-    - rule: 'Different from <toggle-option-ui> (which is multi-select inside <toggle-group-ui>).'
-      reason: 'Single vs multi-select sibling distinction.'
-    - rule: 'Selected state managed by parent <segmented-ui> via active attribute; do not set selected directly on segment.'
+    - rule: '<toggle-option-ui> (deprecated, gh#1369) is the same concept — use segment-ui inside <segmented-ui multiple> instead.'
+      reason: 'Deprecation redirect.'
+    - rule: 'Selected state managed by the parent <segmented-ui> — it syncs the selected attribute onto every child whose value is in its own value (single value, or the [multiple] comma-separated set); do not set selected directly on segment.'
       reason: 'Parent owns selection state.'
 anti_patterns: []
 examples:
@@ -68,7 +73,7 @@ examples:
       [
         {
           "id": "root",
-          "component": "SegmentedControl",
+          "component": "Segmented",
           "children": [
             "s1",
             "s2",
@@ -79,7 +84,7 @@ examples:
           "id": "s1",
           "component": "Segment",
           "text": "Overview",
-          "active": true
+          "selected": true
         },
         {
           "id": "s2",
@@ -98,7 +103,7 @@ examples:
       [
         {
           "id": "root",
-          "component": "SegmentedControl",
+          "component": "Segmented",
           "children": [
             "s1",
             "s2",
@@ -130,7 +135,7 @@ examples:
       [
         {
           "id": "root",
-          "component": "SegmentedControl",
+          "component": "Segmented",
           "children": [
             "s1",
             "s2",
@@ -169,7 +174,7 @@ examples:
       [
         {
           "id": "root",
-          "component": "SegmentedControl",
+          "component": "Segmented",
           "children": [
             "s1",
             "s2",
@@ -202,7 +207,7 @@ examples:
       [
         {
           "id": "root",
-          "component": "SegmentedControl",
+          "component": "Segmented",
           "children": [
             "s1",
             "s2",
@@ -233,7 +238,9 @@ examples:
       ]
 keywords:
   - segment
+  - toggle-option
 synonyms:
-  segment: [segment-button, segmented-option, option-button]
+  segment: [segment-button, segmented-option, option-button, toggle-option]
 related:
   - segmented-control
+  - ToggleOption

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": "Single-select toggle group with an animated sliding indicator. Children must be segment-ui elements.",
+  "description": "Toggle group with an animated sliding indicator (single-select) or independently-toggleable segments (multi-select via [multiple]). Children must be segment-ui elements.",
   "type": "object",
   "allOf": [
     {
@@ -14,15 +14,20 @@
   ],
   "properties": {
     "allowEmpty": {
-      "description": "Suppresses the connect-time self-select of the first enabled segment when value is falsy. Without it, an empty value silently selects the first segment; with it, a falsy value renders every segment unselected until a real value arrives — for path-bound consumers whose bound value can be a genuine empty state.",
+      "description": "Suppresses the connect-time self-select of the first enabled segment when value is falsy. Without it, an empty value silently selects the first segment; with it, a falsy value renders every segment unselected until a real value arrives — for path-bound consumers whose bound value can be a genuine empty state. No effect under [multiple] — multi-select never self-selects (empty value already means \"nothing chosen\").",
       "type": "boolean",
       "default": false
     },
     "component": {
       "const": "Segmented"
     },
+    "multiple": {
+      "description": "Enables multi-select — value becomes a comma-separated set, the sliding indicator is suppressed (each selected segment carries its own background instead), and Space/Enter toggles a focused segment instead of arrow-move selecting it. Positive polarity, matching select-ui[multiple]. Absorbs the role of the deprecated <toggle-group-ui> + <toggle-option-ui> pair (gh#1369, #1363 C1). Unlike <toggle-group-ui single>, re-clicking an already-selected segment does NOT clear the selection — segmented-ui's single-select is standard radiogroup semantics (always exactly one selected once a value is set).",
+      "type": "boolean",
+      "default": false
+    },
     "value": {
-      "description": "Value of the currently selected segment.",
+      "description": "Value of the currently selected segment. Under [multiple], a comma-separated set of selected values (same encoding as select-ui[multiple]).",
       "type": "string",
       "default": ""
     }
@@ -32,6 +37,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedChildren": [
+      "Segment"
+    ],
     "anti_patterns": [],
     "category": "navigation",
     "composes": [],
@@ -45,6 +53,11 @@
         "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"
+      },
+      {
+        "description": "Multi-select segmented control (gh#1369) for filter chips — [multiple] set, value is a comma-separated set of active segments.",
+        "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    \"multiple\": true,\n    \"value\": \"bold,italic\",\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"Segment\",\n    \"value\": \"bold\",\n    \"text\": \"Bold\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"Segment\",\n    \"value\": \"italic\",\n    \"text\": \"Italic\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"Segment\",\n    \"value\": \"underline\",\n    \"text\": \"Underline\"\n  }\n]",
+        "name": "multi-select-filter-chips"
       }
     ],
     "keywords": [
@@ -55,21 +68,27 @@
       "switch",
       "tab",
       "tabs",
-      "button-group"
+      "button-group",
+      "filter",
+      "multi-select",
+      "filter-chips"
     ],
     "name": "UISegmented",
+    "parts": {
+      "indicator": {
+        "description": "Auto-created sliding indicator element prepended on first render — template-owned anatomy part, not a light-DOM insertion point (gh#1454). Lazily created once via an internal-field guard, never adopted from a consumer-authored element."
+      }
+    },
     "related": [
       "Segment",
       "ToggleGroup",
+      "ToggleOption",
       "Tabs",
       "Radio"
     ],
     "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": [
@@ -85,6 +104,16 @@
         "button",
         "segmented"
       ],
+      "filter": [
+        "segmented",
+        "toggle-group",
+        "filter-chips"
+      ],
+      "multi-select": [
+        "segmented",
+        "toggle-group",
+        "select"
+      ],
       "options": [
         "settings",
         "radio",

package/components/segmented/segmented.class.js

@@ -18,8 +18,19 @@
  *   <segment-ui value="tab3" text="Tab 3"></segment-ui>
  * </segmented-ui>
  *
- * Mutually exclusive toggle group with animated indicator pill.
- * Indicator uses CSS transform (GPU-accelerated).
+ * Mutually exclusive (single-select) toggle group with animated indicator
+ * pill. Indicator uses CSS transform (GPU-accelerated).
+ *
+ * <segmented-ui multiple value="bold,italic">
+ *   <segment-ui value="bold" text="B"></segment-ui>
+ *   <segment-ui value="italic" text="I"></segment-ui>
+ * </segmented-ui>
+ *
+ * [multiple] (gh#1369, #1363 C1): multi-select mode — `value` is a
+ * comma-separated set, no sliding indicator (each selected segment carries
+ * its own background instead), Space/Enter toggles instead of arrow-move.
+ * Absorbs <toggle-group-ui>/<toggle-option-ui>'s role, which are deprecated
+ * in favor of this axis.
  */
 
 import { UIFormElement } from '../../core/form.js';
@@ -28,6 +39,13 @@ import '../segment/segment.js';
 export class UISegmented extends UIFormElement {
   static properties = {
     ...UIFormElement.properties,
+    // gh#1369 (#1363 C1): multi-select axis, positive polarity matching
+    // <select-ui multiple> — not toggle-group's inverted `single`. Under
+    // [multiple], `value` becomes a comma-separated set (same encoding
+    // toggle-group-ui and select-ui[multiple] already use); the sliding
+    // indicator is suppressed and each selected segment carries its own
+    // background instead (segment.css).
+    multiple: { type: Boolean, default: false, reflect: true },
     value: { type: String, default: '', reflect: true },
     // gh#693: absent (default false) preserves the original self-select
     // behavior below. A path-bound consumer whose bound value can be a
@@ -55,7 +73,7 @@ export class UISegmented extends UIFormElement {
 
   connected() {
     super.connected();
-    this.setAttribute('role', 'radiogroup');
+    this.setAttribute('role', this.multiple ? 'group' : 'radiogroup');
 
     if (!this.#bound) {
       this.#bound = true;
@@ -65,8 +83,10 @@ export class UISegmented extends UIFormElement {
 
     // Default to first segment if no value — unless allow-empty opts out
     // (a falsy path-bound value must render as truly empty, not silently
-    // pick one, gh#693).
-    if (!this.value && !this.allowEmpty) {
+    // pick one, gh#693). Multi-select never self-selects: an empty
+    // [multiple] value legitimately means "nothing chosen yet", the same
+    // default toggle-group-ui always had.
+    if (!this.multiple && !this.value && !this.allowEmpty) {
       const first = this.querySelector('segment-ui:not([disabled])');
       if (first) this.value = first.value || first.getAttribute('value') || '';
     }
@@ -112,7 +132,19 @@ export class UISegmented extends UIFormElement {
     return this.#segments.filter(s => !s.disabled);
   }
 
+  // [multiple] value encoding — comma-separated, matching toggle-group-ui
+  // and select-ui[multiple] (gh#1369).
+  get #valueSet() {
+    return new Set(this.value ? this.value.split(',').map(v => v.trim()).filter(Boolean) : []);
+  }
+
   render() {
+    // gh#1369 review: connected() only sets the host role ONCE — if
+    // `multiple` flips after connect, that one-shot value goes stale while
+    // children's roles (below) already update reactively every render.
+    // Keep the host role synchronized here too, every render.
+    this.setAttribute('role', this.multiple ? 'group' : 'radiogroup');
+
     // 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)) {
@@ -137,11 +169,14 @@ export class UISegmented extends UIFormElement {
     const segs = this.#segments;
     if (!segs.length) return;
 
-    // Sync selection state
+    // Sync selection state — [multiple] checks Set membership (comma-
+    // separated value), single-select checks direct string equality.
+    const selectedSet = this.multiple ? this.#valueSet : null;
     let anyActive = false;
     for (const seg of segs) {
       const segVal = seg.value || seg.getAttribute('value') || '';
-      const isActive = segVal === this.value;
+      const isActive = this.multiple ? selectedSet.has(segVal) : segVal === this.value;
+      seg.setAttribute('role', this.multiple ? 'checkbox' : 'radio');
       if (isActive) {
         seg.setAttribute('selected', '');
         anyActive = true;
@@ -152,6 +187,8 @@ export class UISegmented extends UIFormElement {
     }
     // allow-empty's "nothing selected" state must still be keyboard
     // reachable — mirrors list-ui's roving-tabindex fallback (list.class.js).
+    // [multiple] can legitimately have nothing selected at all times, same
+    // fallback applies.
     if (!anyActive) {
       const firstEnabled = segs.find((s) => !s.disabled);
       firstEnabled?.setAttribute('tabindex', '0');
@@ -159,10 +196,33 @@ export class UISegmented extends UIFormElement {
 
     if (this.label) this.setAttribute('aria-label', this.label);
 
+    // Sliding indicator is a single-select-only affordance — exactly one
+    // pill can slide to exactly one position. [multiple] relies on each
+    // segment's own [selected] background instead (segment.css).
+    // #updateIndicator itself guards on `this.multiple` (gh#1369 review) —
+    // call it unconditionally so this is the one call site, same as every
+    // other caller (ResizeObserver, document.fonts.ready).
     this.#updateIndicator(segs);
   }
 
   #updateIndicator(segs) {
+    // gh#1369 review: render() only skips this call in [multiple] mode —
+    // the ResizeObserver (connected()) and document.fonts.ready callbacks
+    // call #updateIndicator directly and asynchronously, bypassing that
+    // guard entirely. Without a guard HERE, a multiple-mode instance with
+    // exactly one segment selected (this.value has no comma, so it can
+    // exactly match a segment's own value) can grow a spurious sliding
+    // indicator after a late resize or font-load event. Guard the method
+    // itself so every call site — sync or async — is covered.
+    if (this.multiple) {
+      for (const stale of this.querySelectorAll(':scope > [data-indicator]')) {
+        stale.remove();
+      }
+      this.#indicator = null;
+      this.removeAttribute('data-indicator-ready');
+      return;
+    }
+
     const selectedIdx = segs.findIndex(s => (s.value || s.getAttribute('value') || '') === this.value);
 
     if (selectedIdx < 0) {
@@ -205,7 +265,18 @@ export class UISegmented extends UIFormElement {
 
   #select(seg) {
     if (seg.disabled) return;
-    this.value = seg.value;
+    const segVal = seg.value || seg.getAttribute('value') || '';
+
+    if (this.multiple) {
+      if (!segVal) return;
+      const selected = this.#valueSet;
+      if (selected.has(segVal)) selected.delete(segVal);
+      else selected.add(segVal);
+      this.value = [...selected].join(',');
+    } else {
+      this.value = segVal;
+    }
+
     this.syncValue();
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   }
@@ -215,26 +286,46 @@ export class UISegmented extends UIFormElement {
     if (seg && this.contains(seg)) this.#select(seg);
   };
 
+  // Shared roving-focus navigation — Home/End/Arrow keys move focus among
+  // enabled segments. Selection semantics diverge below: single-select is
+  // a radiogroup (arrow-move selects, native radio behavior); [multiple]
+  // is a checkbox toolbar (arrow-move only focuses, Space/Enter toggles).
+  #nextFocusTarget(current, key) {
+    const segs = this.#enabledSegments;
+    const idx = segs.indexOf(current);
+    if (idx < 0) return null; // current isn't an enabled segment — nothing to do
+    switch (key) {
+      case 'ArrowRight': case 'ArrowDown':
+        return segs[idx < segs.length - 1 ? idx + 1 : 0];
+      case 'ArrowLeft': case 'ArrowUp':
+        return segs[idx > 0 ? idx - 1 : segs.length - 1];
+      case 'Home': return segs[0];
+      case 'End': return segs[segs.length - 1];
+      default: return null; // key not handled
+    }
+  }
+
   #handleKeydown = (e) => {
     const target = e.target;
     if (target.tagName !== 'SEGMENT-UI') return;
-    const segs = this.#enabledSegments;
-    const idx = segs.indexOf(target);
-    if (idx < 0) return;
 
-    let next;
-    switch (e.key) {
-      case 'ArrowRight': case 'ArrowDown':
-        next = idx < segs.length - 1 ? idx + 1 : 0; break;
-      case 'ArrowLeft': case 'ArrowUp':
-        next = idx > 0 ? idx - 1 : segs.length - 1; break;
-      case 'Home': next = 0; break;
-      case 'End': next = segs.length - 1; break;
-      default: return;
+    if (this.multiple) {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        this.#select(target);
+        return;
+      }
+      const next = this.#nextFocusTarget(target, e.key);
+      if (!next) return;
+      e.preventDefault();
+      next.focus();
+      return;
     }
 
+    const next = this.#nextFocusTarget(target, e.key);
+    if (!next) return;
     e.preventDefault();
-    segs[next].focus();
-    this.#select(segs[next]);
+    next.focus();
+    this.#select(next);
   };
 }

package/components/segmented/segmented.css

@@ -68,6 +68,9 @@
     display: none;
   }
 
+  /* [multiple] never sets data-indicator-ready (segmented.class.js render())
+     — the indicator span is never created/prepended in multi-select mode,
+     so it stays display:none via the rule above. */
   :scope[data-indicator-ready] > [data-indicator] {
     display: block;
     position: absolute;

package/components/segmented/segmented.d.ts

@@ -12,8 +12,10 @@ export interface SegmentedChangeEventDetail<V extends string = string> {
 export type SegmentedChangeEvent<V extends string = string> = CustomEvent<SegmentedChangeEventDetail<V>>;
 
 export class UISegmented extends UIFormElement {
-  /** Selected segment's value. */
+  /** Selected segment's value. Under `multiple`, a comma-separated set. */
   value: string;
+  /** Enables multi-select — comma-separated `value`, no sliding indicator, Space/Enter toggles (gh#1369). */
+  multiple: boolean;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,