srcdev-nuxt-components 9.6.10 → 9.6.12

package/app/components/05.forms/patterns/stories/MigratedFieldsForm.stories.ts

@@ -12,7 +12,7 @@ import ToggleSwitchField from "../../toggle-switch/ToggleSwitchField.vue";
 import MultipleCheckboxes from "../../input-checkbox/MultipleCheckboxes.vue";
 import SingleCheckbox from "../../input-checkbox/SingleCheckbox.vue";
 import MultipleRadiobuttons from "../../input-radio/MultipleRadiobuttons.vue";
-import TripleToggleSwitch from "../../triple-toggle-switch/TripleToggleSwitch.vue";
+import SegmentedControl from "../../segmented-control/SegmentedControl.vue";
 import InputButton from "../../input-button/InputButton.vue";
 import FormField from "../../form-field/FormField.vue";
 import FormWrapper from "../../form-wrapper/FormWrapper.vue";
@@ -31,7 +31,7 @@ interface MigratedFieldsFormStoryArgs {
 //   InputTextAsNumberField, InputRangeField (InputRange), InputNumberField
 //   (InputNumber), InputOtpField (InputOtp), InputTextareaField (InputTextarea), InputSelectField
 //   (InputSelect), ToggleSwitchField, stacked and inline (ToggleSwitch),
-//   MultipleCheckboxes, SingleCheckbox, MultipleRadiobuttons, TripleToggleSwitch ("Theme
+//   MultipleCheckboxes, SingleCheckbox, MultipleRadiobuttons, SegmentedControl ("Theme
 //   preference": no Field wrapper or error state, so it sits under a plain caption).
 // - Rendered inside other fields: FormWrapper (wraps the form), FormField (wraps every field),
 //   FormFieldset (checkbox/radio groups), InputLabel, InputDescription (the "Full name" and
@@ -71,7 +71,7 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
     MultipleCheckboxes,
     SingleCheckbox,
     MultipleRadiobuttons,
-    TripleToggleSwitch,
+    SegmentedControl,
     InputButton,
     FormField,
     FormWrapper,
@@ -418,7 +418,7 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
           <FormField width="wide" :has-gutter="false">
             <div style="display: grid; gap: 0.8rem; justify-items: start;">
               <span>Theme preference</span>
-              <TripleToggleSwitch
+              <SegmentedControl
                 v-model="state.themePreference"
                 v-model:field-data="themeOptions"
                 name="themePreference"

package/app/components/05.forms/pending-effect/CONSUMER-STYLING.md

@@ -8,8 +8,12 @@ directly: `InputButton` renders it when `has-pending-effect` is set, and it anim
 <InputButton button-text="Save" has-pending-effect :is-pending="saving" />
 ```
 
-The CSS keys off the host button's classes: `.pending-effect` (added by `has-pending-effect`),
-`.is-pending`, and `.icon-only`. The SVG itself is `.pending-effect-container`.
+The CSS keys off the host button's state attributes: `.input-button[data-pending-effect]` (added by
+`has-pending-effect`), `[data-pending]`, and `[data-icon-only]`. The SVG itself is
+`.pending-effect-container`.
+
+> **Changed 2026-10-17**: these were the classes `.pending-effect`, `.is-pending` and `.icon-only`
+> until `InputButton` moved its state to `data-*` attributes.
 
 The line sits outside the button's edge, so nothing around it may clip overflow. `InputButton`
 sets `overflow: visible` on itself when `has-pending-effect` is on, but an ancestor with
@@ -50,7 +54,7 @@ positioning maths) and `--_offset` (the resolved `--pending-effect-offset`).
 ## Reduced motion
 
 Under `prefers-reduced-motion: reduce` the effect stays hidden. The host button still gets
-`pointer-events: none` while `.is-pending` is set, from this component's CSS, so it can't be
+`pointer-events: none` while `[data-pending]` is set, from this component's CSS, so it can't be
 clicked twice.
 
 ---

package/app/components/05.forms/pending-effect/PendingEffect.vue

@@ -34,7 +34,7 @@ watch(
 
 <style lang="css">
 @layer components {
-  .pending-effect {
+  .input-button[data-pending-effect] {
     position: relative;
 
     .pending-effect-container {
@@ -72,14 +72,14 @@ watch(
       }
     }
 
-    &.icon-only .pending-effect-container {
+    &[data-icon-only] .pending-effect-container {
       .pending-effect-blur,
       .pending-effect-line {
         rx: var(--pending-effect-border-radius-icon-only, 100vw);
       }
     }
 
-    &.is-pending {
+    &[data-pending] {
       pointer-events: none;
       cursor: wait;
 

package/app/components/05.forms/pending-effect/tests/PendingEffect.spec.ts

@@ -54,7 +54,7 @@ describe("PendingEffect", () => {
         props: { buttonText: "Save", hasPendingEffect: true },
       });
       expect(withEffect.find(".pending-effect-container").exists()).toBe(true);
-      expect(withEffect.find("button").classes()).toContain("pending-effect");
+      expect(withEffect.find("button").attributes("data-pending-effect")).toBe("");
     });
 
     it("passes the button theme through", async () => {

package/app/components/05.forms/segmented-control/CONSUMER-STYLING.md

@@ -0,0 +1,125 @@
+# SegmentedControl — Consumer Styling Guide
+
+> **Renamed 2026-10-17**: `TripleToggleSwitch` → `SegmentedControl`, since it handles any number
+> of options. Every class and token changed prefix: `.triple-toggle-switch*` → `.segmented-control*`
+> and `--triple-toggle-switch-*` → `--segmented-control-*`, with the rest of each name unchanged.
+>
+> **Renamed 2026-09-27**: `TripleToggleSwitchCore` → `TripleToggleSwitch`. The root class was
+> already `.triple-toggle-switch`, and no token names changed.
+
+## Public token API
+
+Colour tokens fall back to the shared `--theme-*` tokens every other themed component uses, so
+leave them unset to follow the site theme. See `theming-component-token-pattern.md`.
+
+### Wrapper
+
+| Token | Default | Controls |
+|---|---|---|
+| `--segmented-control-surface` | `var(--theme-input-surface)` | Wrapper background |
+| `--segmented-control-border` | `var(--theme-border)` | Wrapper border colour |
+| `--segmented-control-border-hover` | the resolved border | 1px wrapper outline colour on hover |
+| `--segmented-control-shadow` | `var(--form-element-shadow-colour, var(--colour-theme-2))` | Resting shadow ring outside the border (on the wrapper). Width is the global `--form-element-shadow-width` (`0.2rem`; `0` removes it) |
+| `--segmented-control-ring-focus` | `var(--theme-ring)` | Wrapper outline colour while a radio has `:focus-visible` |
+| `--segmented-control-padding` | `0.6rem` | Wrapper padding |
+| `--segmented-control-gap` | `1rem` | Gap between the options (also drives the marker's position) |
+
+### Selected-option marker
+
+| Token | Default | Controls |
+|---|---|---|
+| `--segmented-control-marker-surface` | `var(--theme-surface)` | Marker background when the selected value isn't `system`/`light`/`dark` |
+| `--segmented-control-marker-border` | `var(--theme-text)` | Marker border colour |
+| `--segmented-control-marker-gradient-system` | green `radial-gradient(...)` | Marker `background-image` when `system` is selected |
+| `--segmented-control-marker-gradient-light` | red/orange `radial-gradient(...)` | Marker `background-image` when `light` is selected |
+| `--segmented-control-marker-gradient-dark` | black/grey `radial-gradient(...)` | Marker `background-image` when `dark` is selected |
+
+> **Changed 2026-09-27**: the three marker gradients were hardcoded literals with no override hook.
+> They're now public tokens; the defaults are unchanged. Any `<image>` value works
+> (`linear-gradient(...)`, `url(...)`, `none`).
+
+### Options
+
+| Token | Default | Controls |
+|---|---|---|
+| `--segmented-control-option-padding` | `0.5rem` | Padding inside each option circle |
+| `--segmented-control-icon-size` | `2rem` | Icon `font-size` (and the hidden radio's hit area) |
+| `--segmented-control-option-border` | `#00000025` | Each option's resting border colour |
+| `--segmented-control-option-border-hover` | `var(--theme-text)` | Option outline colour on hover |
+| `--segmented-control-option-ring-focus` | `var(--theme-ring)` | Option outline colour on `:focus-visible` |
+| `--segmented-control-option-icon-color` | `var(--theme-text)` | Icon colour, resting |
+| `--segmented-control-option-icon-color-active` | `var(--theme-on-surface)` | Icon colour, selected |
+
+> **Changed 2026-10-17**: the marker surface defaulted to `--theme-input-surface` (white) while
+> the selected icon defaulted to white too, so any value other than `system`/`light`/`dark` showed
+> a white icon on a white marker. The marker now defaults to `--theme-surface` and the icons to
+> `--theme-text`/`--theme-on-surface`, replacing the raw `--slate-10`/`--slate-00` palette tokens
+> (close to the same colours on the default theme).
+
+Also read (shared, not component-specific): `--form-element-border-width`,
+`--form-element-outline-width`, `--theme-form-transition-duration`. See
+`theming-form-geometry-tokens.md`.
+
+Private tokens (not public API): `--_form-items-gap`, `--_scheme-icon-font-size` (each read in
+several places, fed by the public gap/icon-size tokens) and `--_select-scheme-group-background-color`/
+`--_select-scheme-group-background-image` (swapped per selected value).
+
+> **Changed 2026-10-17**: bordered controls carry a light shadow ring (`box-shadow`, theme step 2,
+> so red when invalid), and hover draws a 1px outline in the border colour with no offset, over the
+> ring's inner edge. Hover used to draw a 2px outline at a 2px offset in the focus colour. Focus is
+> unchanged and sits just outside the ring.
+
+## State hooks
+
+- **Selected value**: the marker gradients key off `:has(input[value="system" | "light" | "dark"]:checked)`
+  on the root. These three values are hardcoded, a legacy of the one real consumer
+  (`DisplayThemeSwitch`). Any other value shows `--segmented-control-marker-surface` instead.
+- **Each option** (`.segmented-control-option`, the `<label>`) carries `data-value` (the
+  option's value) and `data-checked` when selected. Target one with
+  `.segmented-control-option[data-value="light"]`.
+- **Root** has `data-has-selection` when the value matches an option; without it the marker is
+  hidden.
+- **Theme**: `data-theme` on the root, from the `theme` prop.
+- **Inner classes**: `.segmented-control-wrapper`, `.segmented-control-marker-layer`,
+  `.segmented-control-marker`, `.segmented-control-options` (the `role="radiogroup"`),
+  `.segmented-control-option`, `.segmented-control-option-icon`,
+  `.segmented-control-option-input`.
+
+> **Changed 2026-10-17**: the inner classes were generic (`.selected-option-marker-wrapper`,
+> `.selected-option-marker`, `.option-group-wrapper`, `.option-group`, `.option-icon`,
+> `.option-input`) and collided with consumer CSS. State moved too: `.option-icon.active` →
+> `.segmented-control-option[data-checked]`, `.option-icon.light` (the option id as a class)
+> → `.segmented-control-option[data-value="light"]`, and `.selected-option-marker.show` is gone:
+> the marker is positioned in CSS from the first paint, no measuring.
+
+## Motion
+
+The marker slides between options over the `stepAnimationDuration` prop (default `250ms`). Under
+`prefers-reduced-motion: reduce` the slide transition is removed and the marker jumps.
+
+## Global theming
+
+```css
+:where(html) {
+  --segmented-control-surface: var(--rose-09);
+  --segmented-control-option-ring-focus: var(--rose-04);
+}
+```
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the
+component need `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** when used through `DisplayThemeSwitch`, that wrapper re-declares the four sizing tokens
+(`--segmented-control-gap`, `-padding`, `-option-padding`, `-icon-size`) on the root element, so
+setting them on an ancestor has no effect there. Set them on the component itself (via
+`style` or a passthrough class) instead. Used directly, `SegmentedControl` re-declares nothing.
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `.segmented-control` element, alongside
+`data-theme`. `DisplayThemeSwitch` uses it for its `colour-scheme-select` and `small` classes.

package/app/components/05.forms/segmented-control/SegmentedControl.vue

@@ -0,0 +1,231 @@
+<template>
+  <div
+    class="segmented-control"
+    :class="elementClasses"
+    :data-theme="theme"
+    :data-has-selection="hasSelection ? '' : undefined"
+  >
+    <div class="segmented-control-wrapper">
+      <div class="segmented-control-marker-layer" aria-hidden="true">
+        <div class="segmented-control-marker"></div>
+      </div>
+      <div class="segmented-control-options" role="radiogroup" :aria-label="ariaLabel || undefined">
+        <label
+          v-for="(option, index) in options"
+          :key="option.id ?? index"
+          :for="`${uid}-${index}`"
+          class="segmented-control-option"
+          :data-value="option.value"
+          :data-checked="modelValue === option.value ? '' : undefined"
+        >
+          <span class="sr-only">{{ option.label }}</span>
+          <Icon v-if="option.icon" :name="option.icon" class="segmented-control-option-icon" aria-hidden="true" />
+          <input
+            :id="`${uid}-${index}`"
+            v-model="modelValue"
+            type="radio"
+            :name="groupName"
+            class="segmented-control-option-input"
+            :value="option.value"
+          />
+        </label>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { FormUiTheme, IFormMultipleOptions } from "~/types/forms/types.forms";
+
+interface Props {
+  name?: string;
+  ariaLabel?: string;
+  theme?: FormUiTheme;
+  stepAnimationDuration?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  name: undefined,
+  ariaLabel: "",
+  theme: "default",
+  stepAnimationDuration: "250ms",
+  styleClassPassthrough: () => [],
+});
+
+const modelValue = defineModel<string | number | boolean>({ required: true });
+const fieldData = defineModel<IFormMultipleOptions>("fieldData", { required: true });
+
+const uid = useId();
+const groupName = computed(() => props.name || `segmented-control-${uid}`);
+
+const options = computed(() => fieldData.value?.data ?? []);
+const optionCount = computed(() => Math.max(1, options.value.length));
+const selectedOptionIndex = computed(() => options.value.findIndex((option) => option.value === modelValue.value));
+const hasSelection = computed(() => selectedOptionIndex.value >= 0);
+const markerIndex = computed(() => Math.max(0, selectedOptionIndex.value));
+
+const { stepAnimationDuration } = toRefs(props);
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .segmented-control {
+    --_form-items-gap: var(--segmented-control-gap, 1rem);
+    --_select-scheme-group-background-color: var(--segmented-control-marker-surface, var(--theme-surface));
+    --_select-scheme-group-background-image: none;
+    --_scheme-icon-font-size: var(--segmented-control-icon-size, 2rem);
+
+    &:has(input[value="system"]:checked) {
+      --_select-scheme-group-background-color: transparent;
+      --_select-scheme-group-background-image: var(
+        --segmented-control-marker-gradient-system,
+        radial-gradient(circle, rgb(66, 180, 58) 0%, rgb(17, 199, 0) 27%, rgb(8, 117, 3) 100%)
+      );
+    }
+
+    &:has(input[value="light"]:checked) {
+      --_select-scheme-group-background-color: transparent;
+      --_select-scheme-group-background-image: var(
+        --segmented-control-marker-gradient-light,
+        radial-gradient(circle, rgba(180, 58, 91, 1) 0%, rgba(253, 29, 29, 1) 27%, rgba(252, 176, 69, 1) 100%)
+      );
+    }
+
+    &:has(input[value="dark"]:checked) {
+      --_select-scheme-group-background-color: transparent;
+      --_select-scheme-group-background-image: var(
+        --segmented-control-marker-gradient-dark,
+        radial-gradient(circle, rgb(50, 20, 25) 0%, rgb(0, 0, 0) 27%, rgb(100, 100, 100) 100%)
+      );
+    }
+
+    .segmented-control-wrapper {
+      display: inline-grid;
+      grid-template-areas: "select-stack";
+      width: fit-content;
+      max-inline-size: 100%;
+
+      background-color: var(--segmented-control-surface, var(--theme-input-surface));
+      border: var(--form-element-border-width) solid var(--segmented-control-border, var(--theme-border));
+      outline: var(--form-element-outline-width) solid transparent;
+      box-shadow: 0 0 0 var(--form-element-shadow-width)
+        var(--segmented-control-shadow, var(--form-element-shadow-colour, var(--colour-theme-2)));
+      border-radius: 100vw;
+      padding: var(--segmented-control-padding, 0.6rem);
+
+      transition: all var(--theme-form-transition-duration) ease-in-out;
+
+      &:hover {
+        outline-color: var(--segmented-control-border-hover, var(--segmented-control-border, var(--theme-border)));
+      }
+
+      &:has(input:focus-visible) {
+        outline: var(--form-element-outline-width) solid var(--segmented-control-ring-focus, var(--theme-ring));
+        outline-offset: 0.2rem;
+      }
+
+      & .segmented-control-marker-layer,
+      & .segmented-control-options {
+        grid-area: select-stack;
+        display: grid;
+        grid-template-columns: repeat(v-bind(optionCount), minmax(0, 1fr));
+        gap: var(--_form-items-gap);
+      }
+
+      & .segmented-control-marker-layer {
+        z-index: 1;
+
+        .segmented-control-marker {
+          grid-column: 1;
+          position: relative;
+          inset-inline-start: calc(v-bind(markerIndex) * (100% + var(--_form-items-gap)));
+          transition: inset-inline-start v-bind(stepAnimationDuration) ease-in-out;
+          background-color: var(--_select-scheme-group-background-color);
+          background-image: var(--_select-scheme-group-background-image);
+          border: var(--form-element-border-width) solid var(--segmented-control-marker-border, var(--theme-text));
+          border-radius: 50%;
+          opacity: 0;
+
+          @media (prefers-reduced-motion: reduce) {
+            transition: none;
+          }
+        }
+      }
+
+      & .segmented-control-options {
+        z-index: 2;
+        align-items: center;
+
+        .segmented-control-option {
+          display: grid;
+          grid-template-areas: "icon-stack";
+          place-items: center;
+          min-inline-size: 0;
+          background: transparent;
+          border: var(--form-element-border-width) solid var(--segmented-control-option-border, #00000025);
+          outline: var(--form-element-outline-width) solid transparent;
+          border-radius: 50%;
+          padding: var(--segmented-control-option-padding, 0.5rem);
+          overflow: hidden;
+          cursor: pointer;
+
+          transition: all calc(var(--theme-form-transition-duration) / 3);
+
+          &:hover {
+            outline-color: var(--segmented-control-option-border-hover, var(--theme-text));
+          }
+
+          &:has(input:focus-visible) {
+            outline: var(--form-element-outline-width) solid
+              var(--segmented-control-option-ring-focus, var(--theme-ring));
+            outline-offset: 0.2rem;
+          }
+
+          .segmented-control-option-icon {
+            grid-area: icon-stack;
+            display: block;
+            font-size: var(--_scheme-icon-font-size);
+            width: 1em;
+            height: 1em;
+            color: var(--segmented-control-option-icon-color, var(--theme-text));
+            transition: color calc(v-bind(stepAnimationDuration) / 2) ease-in-out;
+
+            @media (prefers-reduced-motion: reduce) {
+              transition: none;
+            }
+          }
+
+          &[data-checked] .segmented-control-option-icon {
+            color: var(--segmented-control-option-icon-color-active, var(--theme-on-surface));
+            transition-delay: calc(v-bind(stepAnimationDuration) / 2);
+          }
+
+          .segmented-control-option-input {
+            grid-area: icon-stack;
+            appearance: none;
+            margin: 0;
+            opacity: 0;
+            width: var(--_scheme-icon-font-size);
+            height: var(--_scheme-icon-font-size);
+            cursor: pointer;
+          }
+        }
+      }
+    }
+
+    &[data-has-selection] .segmented-control-wrapper .segmented-control-marker {
+      opacity: 1;
+    }
+  }
+}
+</style>

package/app/components/05.forms/segmented-control/stories/SegmentedControl.stories.ts

@@ -0,0 +1,215 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { ref } from "vue";
+import StorybookComponent from "../SegmentedControl.vue";
+import CanvasSwitcher from "../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
+import type { IFormMultipleOptions } from "~/types/forms/types.forms.d";
+import type { MediaCanvas } from "~/types/components";
+
+interface SegmentedControlStoryArgs {
+  name: string;
+  ariaLabel: string;
+  stepAnimationDuration: string;
+}
+
+// The marker gradients key off three option values: "system", "light", "dark" (see
+// CONSUMER-STYLING.md). Any other value falls back to --segmented-control-marker-surface.
+export default {
+  title: "Components/Forms/Segmented Control/SegmentedControl",
+  component: StorybookComponent,
+  argTypes: {
+    name: {
+      control: "text",
+      description: "Radio group name. Leave empty for a unique generated name",
+      table: { category: "Basic" },
+    },
+    ariaLabel: {
+      control: "text",
+      description: "Accessible name for the radiogroup",
+      table: { category: "Accessibility" },
+    },
+    stepAnimationDuration: {
+      control: "text",
+      description: "CSS transition duration for the marker sliding between options",
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    name: "",
+    ariaLabel: "Colour scheme",
+    stepAnimationDuration: "250ms",
+  },
+  decorators: [
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "fullWidthCanvas");
+        return { canvasName };
+      },
+      template: `
+        <div style="padding: 1.2rem 1.6rem; border-block-end: 1px solid currentColor;">
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </div>
+        <div :class="canvasName" style="margin-inline: auto; padding: 2rem; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "A segmented radio group drawn as icons in a pill, with a marker that slides to the selected option. `v-model` is the selected value and `v-model:field-data` the options (`data[]` of `value`, `label`, `icon`); labels are screen-reader text. `aria-label` names the group, `name` defaults to a unique generated name, and `step-animation-duration` sets the slide. The values `system`, `light` and `dark` get their own marker gradients. [DisplayThemeSwitch](?path=/story/molecules-displaythemeswitch--default) wraps it as a colour-scheme switch.",
+      },
+    },
+  },
+} as Meta<SegmentedControlStoryArgs>;
+
+// Links in the canvas open in the Storybook manager (target="_top"), not inside the preview iframe.
+const storyNoteStyle = "margin: 0 0 1.6rem; font-size: 1.4rem;";
+const themeSwitchNote = `
+  <p style="${storyNoteStyle}">
+    Wired to the site's colour scheme with labels, icons and a small size in the
+    <a href="/?path=/story/molecules-displaythemeswitch--default" target="_top">DisplayThemeSwitch</a> story.
+  </p>
+`;
+
+const buildOptions = (): IFormMultipleOptions => ({
+  data: [
+    { id: "system", name: "colour-scheme", value: "system", label: "System", icon: "material-symbols:night-sight-auto-sharp" },
+    { id: "light", name: "colour-scheme", value: "light", label: "Light", icon: "radix-icons:sun" },
+    { id: "dark", name: "colour-scheme", value: "dark", label: "Dark", icon: "radix-icons:moon" },
+  ],
+  total: 3,
+  skip: 0,
+  limit: 3,
+});
+
+const Template: StoryFn<SegmentedControlStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const modelValue = ref("system");
+    const fieldData = ref<IFormMultipleOptions>(buildOptions());
+    return { args, modelValue, fieldData };
+  },
+  template: `
+    <div>
+      ${themeSwitchNote}
+      <StorybookComponent
+        v-model="modelValue"
+        v-model:field-data="fieldData"
+        :name="args.name || undefined"
+        :aria-label="args.ariaLabel"
+        :step-animation-duration="args.stepAnimationDuration"
+      />
+      <div style="margin-top: 1.6rem; font-size: 1.4rem;">Current value: {{ modelValue }}</div>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+Default.parameters = {
+  docs: { description: { story: "The three colour-scheme values, each with its own marker gradient." } },
+};
+
+const CustomTokensTemplate: StoryFn<SegmentedControlStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const modelValue = ref("light");
+    const fieldData = ref<IFormMultipleOptions>(buildOptions());
+    return { args, modelValue, fieldData };
+  },
+  template: `
+    <div
+      style="
+        --segmented-control-gap: 0.4rem;
+        --segmented-control-padding: 0.4rem;
+        --segmented-control-icon-size: 1.6rem;
+        --segmented-control-marker-gradient-system: linear-gradient(135deg, #0ea5e9, #6366f1);
+        --segmented-control-marker-gradient-light: linear-gradient(135deg, #facc15, #f97316);
+        --segmented-control-marker-gradient-dark: linear-gradient(135deg, #1e293b, #475569);
+      "
+    >
+      <StorybookComponent
+        v-model="modelValue"
+        v-model:field-data="fieldData"
+        :name="args.name || undefined"
+        :aria-label="args.ariaLabel"
+        :step-animation-duration="args.stepAnimationDuration"
+      />
+      <div style="margin-top: 1.6rem; font-size: 1.4rem;">Current value: {{ modelValue }}</div>
+    </div>
+  `,
+});
+
+export const CustomTokens = CustomTokensTemplate.bind({});
+CustomTokens.parameters = {
+  docs: {
+    description: { story: "Smaller sizing and custom marker gradients, set as tokens on a wrapper." },
+  },
+};
+
+const stressOptions = (): IFormMultipleOptions => ({
+  data: [
+    { id: "a", name: "stress", value: "first", label: "Erste Option mit einer sehr langen Beschreibung für Bildschirmleser", icon: "radix-icons:sun" },
+    { id: "a", name: "stress", value: "second", label: "<b>not bold</b>", icon: "radix-icons:moon" },
+    { id: "c", name: "stress", value: "third", label: "خيار ثالث" },
+    { id: "d", name: "stress", value: "fourth", label: "🎉", icon: "material-symbols:night-sight-auto-sharp" },
+    { id: "e", name: "stress", value: "fifth", label: "x", icon: "radix-icons:gear" },
+  ],
+  total: 5,
+  skip: 0,
+  limit: 5,
+});
+
+const StressTemplate: StoryFn<SegmentedControlStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const fiveValue = ref("second");
+    const fiveOptions = ref<IFormMultipleOptions>(stressOptions());
+    const unknownValue = ref("not-an-option");
+    const unknownOptions = ref<IFormMultipleOptions>(buildOptions());
+    const singleValue = ref("only");
+    const singleOptions = ref<IFormMultipleOptions>({
+      data: [{ id: "only", name: "single", value: "only", label: "Only option", icon: "radix-icons:sun" }],
+      total: 1,
+      skip: 0,
+      limit: 1,
+    });
+    return { args, fiveValue, fiveOptions, unknownValue, unknownOptions, singleValue, singleOptions };
+  },
+  template: `
+    <div style="display: grid; gap: 2.4rem; justify-items: start;">
+      <div>
+        <p style="margin: 0 0 0.8rem; font-size: 1.4rem;">Five options, one without an icon, a duplicate id in the data</p>
+        <StorybookComponent v-model="fiveValue" v-model:field-data="fiveOptions" :aria-label="args.ariaLabel" :step-animation-duration="args.stepAnimationDuration" />
+        <div style="margin-top: 0.8rem; font-size: 1.4rem;">Current value: {{ fiveValue }}</div>
+      </div>
+      <div>
+        <p style="margin: 0 0 0.8rem; font-size: 1.4rem;">Value that matches no option (no marker)</p>
+        <StorybookComponent v-model="unknownValue" v-model:field-data="unknownOptions" :aria-label="args.ariaLabel" :step-animation-duration="args.stepAnimationDuration" />
+      </div>
+      <div>
+        <p style="margin: 0 0 0.8rem; font-size: 1.4rem;">A single option</p>
+        <StorybookComponent v-model="singleValue" v-model:field-data="singleOptions" :aria-label="args.ariaLabel" :step-animation-duration="args.stepAnimationDuration" />
+      </div>
+      <div dir="rtl">
+        <p style="margin: 0 0 0.8rem; font-size: 1.4rem;">Right-to-left</p>
+        <StorybookComponent v-model="fiveValue" v-model:field-data="fiveOptions" :aria-label="args.ariaLabel" :step-animation-duration="args.stepAnimationDuration" />
+      </div>
+    </div>
+  `,
+});
+
+export const StressTest = StressTemplate.bind({});
+StressTest.storyName = "Stress Test (Worst-Case Data)";
+StressTest.parameters = {
+  initialCanvas: "mobileCanvas",
+  docs: {
+    description: {
+      story:
+        "Five options (one with no icon, two sharing a data id, long, HTML-like, right-to-left and emoji labels as screen-reader text), a value that matches no option, a single option, and the five-option group in a right-to-left container. Check at every canvas width: the marker lines up with the selected option and slides the right way in RTL, the pill shrinks inside the dashed outline rather than overflowing, no marker shows for the unknown value, and clicking any option in either five-option group selects it in both (they share one model) without the two groups interfering.",
+    },
+  },
+};