srcdev-nuxt-components 9.6.9 → 9.6.11

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

@@ -1,99 +0,0 @@
-# TripleToggleSwitch — Consumer Styling Guide
-
-> **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 |
-|---|---|---|
-| `--triple-toggle-switch-surface` | `var(--theme-input-surface)` | Wrapper background |
-| `--triple-toggle-switch-border` | `var(--theme-border)` | Wrapper border colour |
-| `--triple-toggle-switch-ring-focus` | `var(--theme-ring)` | Wrapper outline colour while a radio has `:focus-visible` |
-| `--triple-toggle-switch-padding` | `0.6rem` | Wrapper padding |
-| `--triple-toggle-switch-gap` | `1rem` | Gap between the three options (also drives the marker's position) |
-
-### Selected-option marker
-
-| Token | Default | Controls |
-|---|---|---|
-| `--triple-toggle-switch-marker-surface` | `var(--theme-input-surface)` | Marker background when the selected value isn't `system`/`light`/`dark` |
-| `--triple-toggle-switch-marker-border` | `var(--slate-10)` | Marker border colour |
-| `--triple-toggle-switch-marker-gradient-system` | green `radial-gradient(...)` | Marker `background-image` when `system` is selected |
-| `--triple-toggle-switch-marker-gradient-light` | red/orange `radial-gradient(...)` | Marker `background-image` when `light` is selected |
-| `--triple-toggle-switch-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 |
-|---|---|---|
-| `--triple-toggle-switch-option-padding` | `0.5rem` | Padding inside each option circle |
-| `--triple-toggle-switch-icon-size` | `2rem` | Icon `font-size` (and the hidden radio's hit area) |
-| `--triple-toggle-switch-option-border` | `#00000025` | Each option's resting border colour |
-| `--triple-toggle-switch-option-border-hover` | `var(--slate-10)` | Option outline colour on icon hover |
-| `--triple-toggle-switch-option-ring-focus` | `var(--theme-ring)` | Option outline colour on `:focus-visible` |
-| `--triple-toggle-switch-option-icon-color` | `var(--slate-10)` | Icon colour, resting |
-| `--triple-toggle-switch-option-icon-color-active` | `var(--slate-00)` | Icon colour, selected |
-
-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 used twice,
-fed by the public gap/icon-size tokens) and `--_select-scheme-group-background-color`/
-`--_select-scheme-group-background-image` (swapped per selected value).
-
-## 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 `--triple-toggle-switch-marker-surface` instead.
-- **Option icon classes**: each `.option-icon` carries the option's `id` as a class (e.g.
-  `.option-icon.light`) plus `.active` when selected.
-- **Marker**: `.selected-option-marker` gains `.show` roughly 250ms after mount (it's positioned
-  from a measured option width, so it stays hidden until measured).
-- **Theme**: `data-theme` on the root, from the `theme` prop.
-- **Inner classes**: `.triple-toggle-switch-wrapper`, `.selected-option-marker-wrapper`,
-  `.selected-option-marker`, `.option-group-wrapper` (the `role="radiogroup"`), `.option-group`
-  (each `<label>`), `.option-icon`, `.option-input`.
-
-## 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) {
-  --triple-toggle-switch-surface: var(--rose-09);
-  --triple-toggle-switch-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
-(`--triple-toggle-switch-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, `TripleToggleSwitch` re-declares nothing.
-
-## Class passthrough
-
-`style-class-passthrough` adds classes to the root `.triple-toggle-switch` element, alongside
-`data-theme`. `DisplayThemeSwitch` uses it for its `colour-scheme-select` and `small` classes.

package/app/components/05.forms/triple-toggle-switch/TripleToggleSwitch.vue

@@ -1,251 +0,0 @@
-<template>
-  <div class="triple-toggle-switch" :class="[elementClasses]" :data-theme="theme">
-    <div class="triple-toggle-switch-wrapper">
-      <div class="selected-option-marker-wrapper">
-        <div class="selected-option-marker" :class="[{ show: showMarker }]"></div>
-      </div>
-      <div class="option-group-wrapper" role="radiogroup" :aria-label="ariaLabel || undefined">
-        <label
-          v-for="option in fieldData.data"
-          :key="option.id"
-          ref="optionGroup"
-          :for="option.id"
-          class="option-group"
-        >
-          <span class="sr-only">{{ option.label }}</span>
-          <Icon
-            v-if="option.icon"
-            :name="option.icon"
-            class="option-icon"
-            :class="[option.id, { active: modelValue === option.value }]"
-          />
-          <input
-            :id="option.id"
-            v-model="modelValue"
-            type="radio"
-            :name="name"
-            class="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: "triple-toggle-switch",
-  ariaLabel: "",
-  theme: "default",
-  stepAnimationDuration: "250ms",
-  styleClassPassthrough: () => [],
-});
-
-const modelValue = defineModel<string | number | boolean>({ required: true });
-const fieldData = defineModel<IFormMultipleOptions>("fieldData", { required: true });
-
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
-
-const { stepAnimationDuration } = toRefs(props);
-
-const optionGroupRefs = useTemplateRef<HTMLLabelElement[]>("optionGroup");
-
-const iconWidth = ref("0px");
-const showMarker = ref(false);
-
-const selectedOptionIndex = computed(() => {
-  if (!fieldData.value?.data) return 0;
-  const index = fieldData.value.data.findIndex((option) => option.value === modelValue.value);
-  return Math.max(0, index);
-});
-
-const setupDefaults = async () => {
-  await nextTick();
-
-  const firstOption = optionGroupRefs.value?.[0];
-  if (firstOption) {
-    iconWidth.value = `${firstOption.getBoundingClientRect().width}px`;
-  }
-
-  await new Promise((resolve) => {
-    requestAnimationFrame(() => {
-      setTimeout(resolve, 250);
-    });
-  });
-
-  showMarker.value = true;
-};
-
-onMounted(() => {
-  setupDefaults();
-});
-</script>
-
-<style lang="css">
-@layer components {
-  .triple-toggle-switch {
-    --_form-items-gap: var(--triple-toggle-switch-gap, 1rem);
-    --_select-scheme-group-background-color: var(--triple-toggle-switch-marker-surface, var(--theme-input-surface));
-    --_select-scheme-group-background-image: none;
-    --_scheme-icon-font-size: var(--triple-toggle-switch-icon-size, 2rem);
-
-    &:has(input[value="system"]:checked) {
-      --_select-scheme-group-background-color: transparent;
-      --_select-scheme-group-background-image: var(
-        --triple-toggle-switch-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(
-        --triple-toggle-switch-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(
-        --triple-toggle-switch-marker-gradient-dark,
-        radial-gradient(circle, rgb(50, 20, 25) 0%, rgb(0, 0, 0) 27%, rgb(100, 100, 100) 100%)
-      );
-    }
-
-    .triple-toggle-switch-wrapper {
-      display: inline-grid;
-      grid-template-areas: "select-stack";
-      width: fit-content;
-
-      background-color: var(--triple-toggle-switch-surface, var(--theme-input-surface));
-      border: var(--form-element-border-width) solid var(--triple-toggle-switch-border, var(--theme-border));
-      outline: var(--form-element-outline-width) solid transparent;
-      border-radius: 100vw;
-      padding: var(--triple-toggle-switch-padding, 0.6rem);
-
-      transition: all var(--theme-form-transition-duration) ease-in-out;
-
-      &:has(input:focus-visible) {
-        outline: var(--form-element-outline-width) solid var(--triple-toggle-switch-ring-focus, var(--theme-ring));
-        outline-offset: 0.2rem;
-      }
-
-      .selected-option-marker-wrapper {
-        grid-area: select-stack;
-        z-index: 1;
-        display: flex;
-        align-items: center;
-        position: relative;
-
-        .selected-option-marker {
-          aspect-ratio: 1;
-          width: v-bind(iconWidth);
-          transition: all 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(--triple-toggle-switch-marker-border, var(--slate-10));
-          border-radius: 50%;
-
-          position: absolute;
-          left: calc(
-            v-bind(selectedOptionIndex) * v-bind(iconWidth) + (var(--_form-items-gap) * v-bind(selectedOptionIndex))
-          );
-
-          opacity: 0;
-
-          &.show {
-            opacity: 1;
-          }
-
-          @media (prefers-reduced-motion: reduce) {
-            transition: none;
-          }
-        }
-      }
-
-      .option-group-wrapper {
-        display: grid;
-        grid-area: select-stack;
-        grid-template-columns: repeat(3, 1fr);
-        align-items: center;
-        width: fit-content;
-        z-index: 2;
-        gap: var(--_form-items-gap);
-        position: relative;
-
-        .option-group {
-          display: grid;
-          grid-template-areas: "icon-stack";
-          place-items: center;
-          background: transparent;
-          border: var(--form-element-border-width) solid var(--triple-toggle-switch-option-border, #00000025);
-          outline: var(--form-element-outline-width) solid transparent;
-          border-radius: 50%;
-          padding: var(--triple-toggle-switch-option-padding, 0.5rem);
-          overflow: hidden;
-
-          transition: all calc(var(--theme-form-transition-duration) / 3);
-
-          &:has(.option-icon:hover) {
-            outline: var(--form-element-outline-width) solid
-              var(--triple-toggle-switch-option-border-hover, var(--slate-10));
-          }
-
-          &:has(input:focus-visible) {
-            outline: var(--form-element-outline-width) solid
-              var(--triple-toggle-switch-option-ring-focus, var(--theme-ring));
-            outline-offset: 0.2rem;
-          }
-
-          .option-icon {
-            grid-area: icon-stack;
-            display: block;
-            font-size: var(--_scheme-icon-font-size);
-            width: 1em;
-            height: 1em;
-            color: var(--triple-toggle-switch-option-icon-color, var(--slate-10));
-            transition: color calc(v-bind(stepAnimationDuration) / 2) ease-in-out;
-
-            &.active {
-              color: var(--triple-toggle-switch-option-icon-color-active, var(--slate-00));
-              transition-delay: calc(v-bind(stepAnimationDuration) / 2);
-            }
-
-            @media (prefers-reduced-motion: reduce) {
-              transition: none;
-            }
-
-            &:hover {
-              cursor: pointer;
-            }
-          }
-
-          .option-input {
-            grid-area: icon-stack;
-            appearance: none;
-            opacity: 0;
-            width: var(--_scheme-icon-font-size);
-            height: var(--_scheme-icon-font-size);
-
-            &:hover {
-              cursor: pointer;
-            }
-          }
-        }
-      }
-    }
-  }
-}
-</style>

package/app/components/05.forms/triple-toggle-switch/stories/TripleToggleSwitch.stories.ts

@@ -1,104 +0,0 @@
-import type { Meta, StoryFn } from "@nuxtjs/storybook";
-import { ref } from "vue";
-import StorybookComponent from "../TripleToggleSwitch.vue";
-import type { IFormMultipleOptions } from "~/types/forms/types.forms.d";
-
-interface TripleToggleSwitchStoryArgs {
-  name: string;
-  ariaLabel: string;
-  stepAnimationDuration: string;
-}
-
-// TripleToggleSwitch keys its marker gradients off three option *values*: "system", "light",
-// "dark" (see CONSUMER-STYLING.md). This story uses exactly those values so each gradient fires;
-// any other value falls back to --triple-toggle-switch-marker-surface. DisplayThemeSwitch is the
-// real-world consumer and adds the useSettingsStore wiring on top.
-export default {
-  title: "Components/Forms/Triple Toggle Switch/TripleToggleSwitch",
-  component: StorybookComponent,
-  argTypes: {
-    name: { control: "text", 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: "colour-scheme",
-    ariaLabel: "Colour scheme",
-    stepAnimationDuration: "250ms",
-  },
-} as Meta<TripleToggleSwitchStoryArgs>;
-
-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<TripleToggleSwitchStoryArgs> = (args) => ({
-  components: { StorybookComponent },
-  setup() {
-    const modelValue = ref("system");
-    const fieldData = ref<IFormMultipleOptions>(buildOptions());
-    return { args, modelValue, fieldData };
-  },
-  template: `
-    <div style="margin: 36px;">
-      <StorybookComponent
-        v-model="modelValue"
-        v-model:field-data="fieldData"
-        :name="args.name"
-        :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({});
-
-const CustomTokensTemplate: StoryFn<TripleToggleSwitchStoryArgs> = (args) => ({
-  components: { StorybookComponent },
-  setup() {
-    const modelValue = ref("light");
-    const fieldData = ref<IFormMultipleOptions>(buildOptions());
-    return { args, modelValue, fieldData };
-  },
-  template: `
-    <div
-      style="
-        margin: 36px;
-        --triple-toggle-switch-gap: 0.4rem;
-        --triple-toggle-switch-padding: 0.4rem;
-        --triple-toggle-switch-icon-size: 1.6rem;
-        --triple-toggle-switch-marker-gradient-system: linear-gradient(135deg, #0ea5e9, #6366f1);
-        --triple-toggle-switch-marker-gradient-light: linear-gradient(135deg, #facc15, #f97316);
-        --triple-toggle-switch-marker-gradient-dark: linear-gradient(135deg, #1e293b, #475569);
-      "
-    >
-      <StorybookComponent
-        v-model="modelValue"
-        v-model:field-data="fieldData"
-        :name="args.name"
-        :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({});

package/app/components/05.forms/triple-toggle-switch/tests/TripleToggleSwitch.spec.ts

@@ -1,138 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { mountSuspended } from "@nuxt/test-utils/runtime";
-import { nextTick } from "vue";
-import TripleToggleSwitch from "../TripleToggleSwitch.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 mountSwitch = (props: Record<string, unknown> = {}) =>
-  mountSuspended(TripleToggleSwitch, {
-    props: {
-      modelValue: "system",
-      fieldData: buildOptions(),
-      ...props,
-    },
-  });
-
-interface TripleToggleSwitchInstance {
-  selectedOptionIndex: number;
-}
-
-describe("TripleToggleSwitch", () => {
-  it("mounts without error", async () => {
-    const wrapper = await mountSwitch();
-    expect(wrapper.vm).toBeTruthy();
-    expect(wrapper.find(".triple-toggle-switch").exists()).toBe(true);
-  });
-
-  it("renders one radio per option with matching id, value and shared name", async () => {
-    const wrapper = await mountSwitch({ name: "colour-scheme" });
-    const inputs = wrapper.findAll("input.option-input");
-    expect(inputs).toHaveLength(3);
-    expect(inputs.map((i) => i.attributes("id"))).toEqual(["system", "light", "dark"]);
-    expect(inputs.map((i) => (i.element as HTMLInputElement).value)).toEqual(["system", "light", "dark"]);
-    inputs.forEach((i) => {
-      expect(i.attributes("type")).toBe("radio");
-      expect(i.attributes("name")).toBe("colour-scheme");
-    });
-  });
-
-  it("uses the default name when none is passed", async () => {
-    const wrapper = await mountSwitch();
-    expect(wrapper.find("input.option-input").attributes("name")).toBe("triple-toggle-switch");
-  });
-
-  it("links each label to its radio and renders the label text for screen readers", async () => {
-    const wrapper = await mountSwitch();
-    const labels = wrapper.findAll("label.option-group");
-    expect(labels.map((l) => l.attributes("for"))).toEqual(["system", "light", "dark"]);
-    expect(wrapper.findAll(".option-group .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(".option-group-wrapper");
-    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(".option-group-wrapper").attributes("aria-label")).toBe("Colour scheme");
-  });
-
-  it("checks the radio matching modelValue", async () => {
-    const wrapper = await mountSwitch({ modelValue: "light" });
-    const checked = wrapper.findAll("input.option-input").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 wrapper.findAll("input.option-input")[2]!.setValue(true);
-    expect(wrapper.emitted("update:modelValue")?.[0]).toEqual(["dark"]);
-  });
-
-  it("marks only the selected option's icon as active", async () => {
-    const wrapper = await mountSwitch({ modelValue: "dark" });
-    const icons = wrapper.findAll(".option-icon");
-    expect(icons).toHaveLength(3);
-    expect(icons.map((i) => i.classes().includes("active"))).toEqual([false, false, true]);
-    expect(icons[0]!.classes()).toContain("system");
-  });
-
-  it("updates the active icon when modelValue changes", async () => {
-    const wrapper = await mountSwitch();
-    await wrapper.setProps({ modelValue: "light" });
-    const icons = wrapper.findAll(".option-icon");
-    expect(icons[1]!.classes()).toContain("active");
-    expect(icons[0]!.classes()).not.toContain("active");
-  });
-
-  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(".option-icon")).toHaveLength(2);
-  });
-
-  it("computes the selected option index, falling back to 0 for an unknown value", async () => {
-    const wrapper = await mountSwitch({ modelValue: "dark" });
-    const vm = wrapper.vm as unknown as TripleToggleSwitchInstance;
-    expect(vm.selectedOptionIndex).toBe(2);
-    await wrapper.setProps({ modelValue: "unknown" });
-    expect(vm.selectedOptionIndex).toBe(0);
-  });
-
-  it("shows the marker only after the mount delay", async () => {
-    const wrapper = await mountSwitch();
-    const marker = wrapper.find(".selected-option-marker");
-    expect(marker.classes()).not.toContain("show");
-    vi.advanceTimersByTime(300);
-    await nextTick();
-    await nextTick();
-    expect(wrapper.find(".selected-option-marker").classes()).toContain("show");
-  });
-
-  it("applies the theme as data-theme", async () => {
-    const wrapper = await mountSwitch({ theme: "success" });
-    expect(wrapper.find(".triple-toggle-switch").attributes("data-theme")).toBe("success");
-  });
-
-  it("applies styleClassPassthrough classes to the root", async () => {
-    const wrapper = await mountSwitch({ styleClassPassthrough: ["small", "extra"] });
-    const root = wrapper.find(".triple-toggle-switch");
-    expect(root.classes()).toContain("small");
-    expect(root.classes()).toContain("extra");
-  });
-});