srcdev-nuxt-components 9.6.9 → 9.6.11

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.",
+    },
+  },
+};

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

@@ -0,0 +1,202 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { defineComponent, ref } from "vue";
+import SegmentedControl from "../SegmentedControl.vue";
+import type { IFormMultipleOptions } from "~/types/forms/types.forms";
+
+const buildOptions = (): IFormMultipleOptions => ({
+  data: [
+    { id: "system", name: "scheme", value: "system", label: "System", icon: "radix-icons:gear" },
+    { id: "light", name: "scheme", value: "light", label: "Light", icon: "radix-icons:sun" },
+    { id: "dark", name: "scheme", value: "dark", label: "Dark", icon: "radix-icons:moon" },
+  ],
+  total: 3,
+  skip: 0,
+  limit: 3,
+});
+
+const mounted: { unmount: () => void }[] = [];
+
+const mountSwitch = async (props: Record<string, unknown> = {}) => {
+  const wrapper = await mountSuspended(SegmentedControl, {
+    props: {
+      modelValue: "system",
+      fieldData: buildOptions(),
+      ...props,
+    },
+  });
+  mounted.push(wrapper);
+  return wrapper;
+};
+
+interface SegmentedControlInstance {
+  selectedOptionIndex: number;
+  markerIndex: number;
+  optionCount: number;
+}
+
+const inputs = (wrapper: Awaited<ReturnType<typeof mountSwitch>>) => wrapper.findAll("input.segmented-control-option-input");
+const optionLabels = (wrapper: Awaited<ReturnType<typeof mountSwitch>>) => wrapper.findAll("label.segmented-control-option");
+
+describe("SegmentedControl", () => {
+  afterEach(() => {
+    mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+    vi.restoreAllMocks();
+  });
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSwitch();
+    expect(wrapper.vm).toBeTruthy();
+    expect(wrapper.find(".segmented-control").exists()).toBe(true);
+  });
+
+  it("renders one radio per option with its value and the shared name", async () => {
+    const wrapper = await mountSwitch({ name: "colour-scheme" });
+    expect(inputs(wrapper)).toHaveLength(3);
+    expect(inputs(wrapper).map((i) => (i.element as HTMLInputElement).value)).toEqual(["system", "light", "dark"]);
+    inputs(wrapper).forEach((i) => {
+      expect(i.attributes("type")).toBe("radio");
+      expect(i.attributes("name")).toBe("colour-scheme");
+    });
+  });
+
+  it("builds ids from useId, not from option data", async () => {
+    const wrapper = await mountSwitch();
+    const ids = inputs(wrapper).map((i) => i.attributes("id"));
+    expect(ids).not.toContain("system");
+    expect(new Set(ids).size).toBe(3);
+    expect(optionLabels(wrapper).map((l) => l.attributes("for"))).toEqual(ids);
+  });
+
+  it("gives two instances separate radio groups and ids", async () => {
+    const Host = defineComponent({
+      components: { SegmentedControl },
+      setup() {
+        return { first: ref("system"), second: ref("dark"), options: ref(buildOptions()) };
+      },
+      template: `
+        <div>
+          <SegmentedControl v-model="first" v-model:field-data="options" />
+          <SegmentedControl v-model="second" v-model:field-data="options" />
+        </div>
+      `,
+    });
+    const wrapper = await mountSuspended(Host);
+    mounted.push(wrapper);
+    const all = wrapper.findAll("input.segmented-control-option-input");
+    const names = new Set(all.map((i) => i.attributes("name")));
+    const ids = new Set(all.map((i) => i.attributes("id")));
+    expect(names.size).toBe(2);
+    expect(ids.size).toBe(6);
+  });
+
+  it("renders the label text for screen readers", async () => {
+    const wrapper = await mountSwitch();
+    expect(wrapper.findAll(".segmented-control-option .sr-only").map((s) => s.text())).toEqual([
+      "System",
+      "Light",
+      "Dark",
+    ]);
+  });
+
+  it("exposes the options as a radiogroup", async () => {
+    const wrapper = await mountSwitch();
+    const group = wrapper.find(".segmented-control-options");
+    expect(group.attributes("role")).toBe("radiogroup");
+    expect(group.attributes("aria-label")).toBeUndefined();
+  });
+
+  it("applies ariaLabel to the radiogroup", async () => {
+    const wrapper = await mountSwitch({ ariaLabel: "Colour scheme" });
+    expect(wrapper.find(".segmented-control-options").attributes("aria-label")).toBe("Colour scheme");
+  });
+
+  it("hides the decorative marker from assistive tech", async () => {
+    const wrapper = await mountSwitch();
+    expect(wrapper.find(".segmented-control-marker-layer").attributes("aria-hidden")).toBe("true");
+  });
+
+  it("checks the radio matching modelValue", async () => {
+    const wrapper = await mountSwitch({ modelValue: "light" });
+    const checked = inputs(wrapper).map((i) => (i.element as HTMLInputElement).checked);
+    expect(checked).toEqual([false, true, false]);
+  });
+
+  it("emits update:modelValue when another option is chosen", async () => {
+    const wrapper = await mountSwitch();
+    await inputs(wrapper)[2]!.setValue(true);
+    expect(wrapper.emitted("update:modelValue")?.[0]).toEqual(["dark"]);
+  });
+
+  it("marks only the selected option with data-checked and exposes its value", async () => {
+    const wrapper = await mountSwitch({ modelValue: "dark" });
+    expect(optionLabels(wrapper).map((l) => l.attributes("data-checked"))).toEqual([undefined, undefined, ""]);
+    expect(optionLabels(wrapper).map((l) => l.attributes("data-value"))).toEqual(["system", "light", "dark"]);
+
+    await wrapper.setProps({ modelValue: "light" });
+    expect(optionLabels(wrapper).map((l) => l.attributes("data-checked"))).toEqual([undefined, "", undefined]);
+  });
+
+  it("does not use collision-prone bare class names", async () => {
+    const wrapper = await mountSwitch();
+    for (const name of [".option-group", ".option-icon", ".option-input", ".selected-option-marker", ".active", ".show"]) {
+      expect(wrapper.find(name).exists()).toBe(false);
+    }
+  });
+
+  it("omits the icon when an option has none", async () => {
+    const options = buildOptions();
+    delete options.data[1]!.icon;
+    const wrapper = await mountSwitch({ fieldData: options });
+    expect(wrapper.findAll(".segmented-control-option-icon")).toHaveLength(2);
+    expect(inputs(wrapper)).toHaveLength(3);
+  });
+
+  it("marks icons as decorative", async () => {
+    const wrapper = await mountSwitch();
+    wrapper.findAll(".segmented-control-option-icon").forEach((icon) => {
+      expect(icon.attributes("aria-hidden")).toBe("true");
+    });
+  });
+
+  it("tracks the selected index and hides the marker for an unknown value", async () => {
+    const wrapper = await mountSwitch({ modelValue: "dark" });
+    const vm = wrapper.vm as unknown as SegmentedControlInstance;
+    const root = () => wrapper.find(".segmented-control");
+    expect(vm.selectedOptionIndex).toBe(2);
+    expect(vm.markerIndex).toBe(2);
+    expect(root().attributes("data-has-selection")).toBe("");
+
+    await wrapper.setProps({ modelValue: "unknown" });
+    expect(vm.selectedOptionIndex).toBe(-1);
+    expect(vm.markerIndex).toBe(0);
+    expect(root().attributes("data-has-selection")).toBeUndefined();
+  });
+
+  it("sizes the grid from the option count, never below one column", async () => {
+    const four = buildOptions();
+    four.data.push({ id: "auto", name: "scheme", value: "auto", label: "Auto", icon: "radix-icons:gear" });
+    const wrapper = await mountSwitch({ fieldData: four });
+    expect((wrapper.vm as unknown as SegmentedControlInstance).optionCount).toBe(4);
+
+    const empty = await mountSwitch({ fieldData: { data: [], total: 0, skip: 0, limit: 0 } });
+    expect((empty.vm as unknown as SegmentedControlInstance).optionCount).toBe(1);
+    expect(empty.findAll("input")).toHaveLength(0);
+  });
+
+  it("applies the theme as data-theme", async () => {
+    const wrapper = await mountSwitch({ theme: "success" });
+    expect(wrapper.find(".segmented-control").attributes("data-theme")).toBe("success");
+  });
+
+  it("applies styleClassPassthrough classes to the root and reacts to changes", async () => {
+    const wrapper = await mountSwitch({ styleClassPassthrough: ["small", "extra"] });
+    const root = () => wrapper.find(".segmented-control");
+    expect(root().classes()).toContain("small");
+    expect(root().classes()).toContain("extra");
+
+    await wrapper.setProps({ styleClassPassthrough: ["other"] });
+    expect(root().classes()).toContain("other");
+    expect(root().classes()).not.toContain("small");
+  });
+});

package/app/components/05.forms/toggle-switch/CONSUMER-STYLING.md

@@ -18,6 +18,8 @@ this two-tier shape exists.
 | `--toggle-switch-surface` | `var(--theme-checkbox-symbol-surface)` | Track background (resting) |
 | `--toggle-switch-surface-hover` | `var(--theme-surface-subtle)` | Track background on hover |
 | `--toggle-switch-border` | `var(--theme-border)` | Track border colour |
+| `--toggle-switch-border-hover` | the resolved border | 1px track outline colour on hover |
+| `--toggle-switch-shadow` | `var(--form-element-shadow-colour, var(--colour-theme-2))` | Resting shadow ring outside the border (on the track). Width is the global `--form-element-shadow-width` (`0.2rem`; `0` removes it) |
 | `--toggle-switch-border-focus` | `var(--theme-border-focus)` | Track outline colour on `:focus-visible` |
 | `--toggle-switch-symbol-border` | `var(--theme-text)` | Thumb border colour |
 | `--toggle-switch-symbol-surface-off` | `var(--theme-on-surface)` | Thumb background, off |
@@ -54,6 +56,11 @@ Only set `--toggle-switch-track-width` for a width the formula doesn't produce.
 
 ---
 
+> **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
 
 | Attribute | On | When |

package/app/components/05.forms/toggle-switch/ToggleSwitch.vue

@@ -133,12 +133,14 @@ watch(
         background-color: var(--toggle-switch-surface, var(--theme-checkbox-symbol-surface));
         border: var(--form-element-border-width) solid var(--toggle-switch-border, var(--theme-border));
         outline: var(--form-element-outline-width) solid transparent;
+        box-shadow: 0 0 0 var(--form-element-shadow-width) var(--toggle-switch-shadow, var(--form-element-shadow-colour, var(--colour-theme-2)));
         border-radius: var(--_border-radius);
         width: var(--_track-width);
         padding: calc(var(--input-toggle-wrapper-padding) + var(--input-toggle-symbol-outline-width));
 
         &:hover {
           background-color: var(--toggle-switch-surface-hover, var(--theme-surface-subtle));
+          outline-color: var(--toggle-switch-border-hover, var(--toggle-switch-border, var(--theme-border)));
           cursor: pointer;
         }