srcdev-nuxt-components 9.4.9 → 9.4.11

package/app/components/02.molecules/display-theme-switch/DisplayThemeSwitch.vue

@@ -0,0 +1,102 @@
+<template>
+  <ClientOnly>
+    <TripleToggleSwitchCore
+      v-model="colorModeVal"
+      v-model:field-data="sampleFieldData"
+      :style-class-passthrough="[`colour-scheme-select`, elementClasses]"
+    />
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import type { IFormMultipleOptions } from "~/types/forms/types.forms";
+interface Props {
+  styleClassPassthrough?: string | string[];
+  systemLabel?: string;
+  lightLabel?: string;
+  darkLabel?: string;
+  systemIcon?: string;
+  lightIcon?: string;
+  darkIcon?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  styleClassPassthrough: () => [],
+  systemLabel: "System",
+  lightLabel: "Light",
+  darkLabel: "Dark",
+  systemIcon: "material-symbols:night-sight-auto-sharp",
+  lightIcon: "radix-icons:sun",
+  darkIcon: "radix-icons:moon",
+});
+
+const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+const sampleFieldData = computed<IFormMultipleOptions>(() => ({
+  data: [
+    {
+      id: "system",
+      name: "colorModeVal",
+      value: "system",
+      label: props.systemLabel,
+      icon: props.systemIcon,
+    },
+    {
+      id: "light",
+      name: "colorModeVal",
+      value: "light",
+      label: props.lightLabel,
+      icon: props.lightIcon,
+    },
+    {
+      id: "dark",
+      name: "colorModeVal",
+      value: "dark",
+      label: props.darkLabel,
+      icon: props.darkIcon,
+    },
+  ],
+  total: 3,
+  skip: 0,
+  limit: 3,
+}));
+
+const { colourScheme, setColourScheme } = useSettingsStore();
+
+const colorModeVal = ref(colourScheme);
+watch(colorModeVal, (val) => {
+  setColourScheme(val);
+});
+</script>
+
+<style lang="css">
+@layer components {
+.colour-scheme-select {
+  /* Everything DisplayThemeSwitch used to redeclare here beyond sizing (wrapper background/border/
+     focus ring, marker border, option border/outline/focus/hover, option-icon colours, and the
+     system/light/dark marker gradients) was a byte-for-byte duplicate of TripleToggleSwitchCore's
+     own defaults for the exact same selectors — a no-op at best, and for the ones that bypassed
+     TripleToggleSwitchCore's public --triple-toggle-switch-* tokens with a hardcoded literal
+     (background-color, border, focus outline, marker border, option border/hover/focus, icon
+     colour) an active bug: a consumer setting e.g. --triple-toggle-switch-surface globally would
+     have been silently overridden back to the hardcoded default by this block's higher
+     specificity. Removed 2026-09-20 — TripleToggleSwitchCore already owns all of that. Only the
+     genuine "small" sizing variant remains, now driving TripleToggleSwitchCore's own public
+     sizing tokens instead of reaching into its private --_form-* and --_scheme-icon-font-size
+     locals directly (see TripleToggleSwitchCore's CONSUMER-STYLING.md). */
+  &.triple-toggle-switch {
+    --triple-toggle-switch-gap: 0.4rem;
+    --triple-toggle-switch-padding: 0.4rem;
+    --triple-toggle-switch-option-padding: 0.4rem;
+    --triple-toggle-switch-icon-size: 2rem;
+
+    &.small {
+      --triple-toggle-switch-gap: 0.2rem;
+      --triple-toggle-switch-padding: 0.2rem;
+      --triple-toggle-switch-option-padding: 0.2rem;
+      --triple-toggle-switch-icon-size: 1.6rem;
+    }
+  }
+}
+}
+</style>

package/app/components/02.molecules/display-theme-switch/stories/DisplayThemeSwitch.stories.ts

@@ -0,0 +1,115 @@
+import DisplayThemeSwitch from "../DisplayThemeSwitch.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof DisplayThemeSwitch> = {
+  title: "Molecules/DisplayThemeSwitch",
+  component: DisplayThemeSwitch,
+  argTypes: {
+    styleClassPassthrough: {
+      control: "object",
+      description: "Extra classes — pass \"small\" for a compact size",
+      table: { category: "Styling" },
+    },
+    systemLabel: {
+      control: "text",
+      description: "Accessible label for the system option",
+      table: { category: "Labels" },
+    },
+    lightLabel: {
+      control: "text",
+      description: "Accessible label for the light option",
+      table: { category: "Labels" },
+    },
+    darkLabel: {
+      control: "text",
+      description: "Accessible label for the dark option",
+      table: { category: "Labels" },
+    },
+    systemIcon: {
+      control: "text",
+      description: "Icon name for the system option",
+      table: { category: "Icons" },
+    },
+    lightIcon: {
+      control: "text",
+      description: "Icon name for the light option",
+      table: { category: "Icons" },
+    },
+    darkIcon: {
+      control: "text",
+      description: "Icon name for the dark option",
+      table: { category: "Icons" },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A system/light/dark theme switch wrapping TripleToggleSwitchCore, wired to useSettingsStore. Colour and sizing are entirely delegated to TripleToggleSwitchCore's public --triple-toggle-switch-* tokens — see CONSUMER-STYLING.md.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DisplayThemeSwitch>;
+
+export const Default: Story = {
+  args: {},
+  render: (args) => ({
+    components: { DisplayThemeSwitch },
+    setup() {
+      return { args };
+    },
+    template: `<DisplayThemeSwitch v-bind="args" />`,
+  }),
+};
+
+export const Small: Story = {
+  args: {
+    styleClassPassthrough: "small",
+  },
+  render: (args) => ({
+    components: { DisplayThemeSwitch },
+    setup() {
+      return { args };
+    },
+    template: `<DisplayThemeSwitch v-bind="args" />`,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Compact sizing for use in a tight header/nav slot.",
+      },
+    },
+  },
+};
+
+export const InNavigation: Story = {
+  args: {
+    styleClassPassthrough: "small",
+  },
+  render: (args) => ({
+    components: { DisplayThemeSwitch },
+    setup() {
+      return { args };
+    },
+    template: `
+      <nav style="display: flex; align-items: center; justify-content: space-between; padding: 1.6rem 2.4rem; background: var(--theme-surface); border-radius: 0.8rem; border: 1px solid var(--theme-border);">
+        <div style="display: flex; align-items: center; gap: 1.6rem;">
+          <span style="font-weight: 600; color: var(--theme-text);">My App</span>
+          <a href="#" style="color: var(--theme-text); text-decoration: none;">Home</a>
+          <a href="#" style="color: var(--theme-text); text-decoration: none;">About</a>
+        </div>
+        <DisplayThemeSwitch v-bind="args" />
+      </nav>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Example of the theme switch integrated into a navigation bar context.",
+      },
+    },
+  },
+};

package/app/components/02.molecules/display-theme-switch/tests/DisplayThemeSwitch.spec.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { mountSuspended, mockNuxtImport } from "@nuxt/test-utils/runtime";
+import { nextTick, ref } from "vue";
+import DisplayThemeSwitch from "../DisplayThemeSwitch.vue";
+
+const { useSettingsStoreMock, setColourSchemeMock } = vi.hoisted(() => ({
+  useSettingsStoreMock: vi.fn(),
+  setColourSchemeMock: vi.fn(),
+}));
+
+mockNuxtImport("useSettingsStore", () => useSettingsStoreMock);
+
+describe("DisplayThemeSwitch", () => {
+  beforeEach(() => {
+    setColourSchemeMock.mockClear();
+    useSettingsStoreMock.mockReturnValue({
+      colourScheme: ref("system"),
+      setColourScheme: setColourSchemeMock,
+    });
+  });
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(DisplayThemeSwitch);
+    await nextTick();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders TripleToggleSwitchCore with the colour-scheme-select class", async () => {
+    const wrapper = await mountSuspended(DisplayThemeSwitch);
+    await nextTick();
+    expect(wrapper.find(".colour-scheme-select").exists()).toBe(true);
+    expect(wrapper.find(".triple-toggle-switch").exists()).toBe(true);
+  });
+
+  it("renders default option labels", async () => {
+    const wrapper = await mountSuspended(DisplayThemeSwitch);
+    await nextTick();
+    const labels = wrapper.findAll(".option-group .sr-only").map((el) => el.text());
+    expect(labels).toEqual(["System", "Light", "Dark"]);
+  });
+
+  it("renders custom option labels via props", async () => {
+    const wrapper = await mountSuspended(DisplayThemeSwitch, {
+      props: {
+        systemLabel: "Auto",
+        lightLabel: "Day",
+        darkLabel: "Night",
+      },
+    });
+    await nextTick();
+    const labels = wrapper.findAll(".option-group .sr-only").map((el) => el.text());
+    expect(labels).toEqual(["Auto", "Day", "Night"]);
+  });
+
+  it("applies custom option icons via props", async () => {
+    const wrapper = await mountSuspended(DisplayThemeSwitch, {
+      props: {
+        systemIcon: "custom:system",
+        lightIcon: "custom:light",
+        darkIcon: "custom:dark",
+      },
+    });
+    await nextTick();
+    const icons = wrapper.findAll(".option-icon").map((el) => el.attributes("class"));
+    expect(icons.some((c) => c?.includes("system"))).toBe(true);
+  });
+
+  it("applies the small class via styleClassPassthrough", async () => {
+    const wrapper = await mountSuspended(DisplayThemeSwitch, {
+      props: { styleClassPassthrough: "small" },
+    });
+    await nextTick();
+    expect(wrapper.find(".triple-toggle-switch").classes()).toContain("small");
+  });
+
+  it("calls setColourScheme when the selected option changes", async () => {
+    const wrapper = await mountSuspended(DisplayThemeSwitch);
+    await nextTick();
+
+    const lightInput = wrapper.findAll("input.option-input")[1];
+    await lightInput?.setValue(true);
+    await nextTick();
+
+    expect(setColourSchemeMock).toHaveBeenCalledWith("light");
+  });
+});

package/app/components/02.molecules/navigation/deep-expanding-menu/CONSUMER-STYLING.md

@@ -7,7 +7,7 @@
 | `--deep-expanding-menu-gap` | `2.4rem` | Gap between top-level items |
 | `--deep-expanding-menu-link-border-width` | `0.2rem` | Bottom border width on links and group toggles |
 | `--deep-expanding-menu-link-padding-block` | `0.8rem` | Vertical padding on links and group toggles |
-| `--deep-expanding-menu-link-border-colour-hover` | `light-dark(var(--blue-10), var(--slate-00))` | Bottom border colour on hover/focus |
+| `--deep-expanding-menu-link-border-colour-hover` | `var(--blue-10)` | Bottom border colour on hover/focus |
 | `--deep-expanding-menu-icon-size` | `1.2rem` | Caret icon size |
 | `--deep-expanding-menu-panel-width` | `min(100%, 50vw)` | Popover panel width |
 | `--deep-expanding-menu-panel-background-colour` | `white` | Popover panel background |

package/app/components/02.molecules/navigation/deep-expanding-menu/DeepExpandingMenu.vue

@@ -92,7 +92,7 @@ watch(
             cursor: pointer;
             border-color: var(
               --deep-expanding-menu-link-border-colour-hover,
-              light-dark(var(--blue-10), var(--slate-00))
+              var(--blue-10)
             );
           }
         }

package/app/components/02.molecules/navigation/deep-expanding-menu-classic/CONSUMER-STYLING.md

@@ -8,7 +8,7 @@
 | `--deep-expanding-menu-classic-item-gap` | `2.4rem` | Gap between top-level items |
 | `--deep-expanding-menu-classic-link-border-width` | `0.2rem` | Bottom border width on links and group toggles |
 | `--deep-expanding-menu-classic-link-padding-block` | `0.8rem` | Vertical padding on links and group toggles |
-| `--deep-expanding-menu-classic-link-border-colour-hover` | `light-dark(var(--blue-10), var(--slate-00))` | Bottom border colour on hover/focus |
+| `--deep-expanding-menu-classic-link-border-colour-hover` | `var(--blue-10)` | Bottom border colour on hover/focus |
 | `--deep-expanding-menu-classic-icon-size` | `1.2rem` | Caret icon size |
 | `--deep-expanding-menu-classic-panel-offset-top` | `4rem` | Panel offset from the toggle |
 | `--deep-expanding-menu-classic-panel-width` | `20rem` | Panel width below the `768px` breakpoint |

package/app/components/02.molecules/navigation/deep-expanding-menu-classic/DeepExpandingMenuClassic.vue

@@ -89,7 +89,7 @@ onMounted(() => {
             cursor: pointer;
             border-color: var(
               --deep-expanding-menu-classic-link-border-colour-hover,
-              light-dark(var(--blue-10), var(--slate-00))
+              var(--blue-10)
             );
           }
         }

package/app/components/02.molecules/select-menu/CONSUMER-STYLING.md

@@ -0,0 +1,168 @@
+# SelectMenu — Consumer Styling Guide
+
+## Public token API
+
+All `--select-menu-*` tokens are the stable override surface, each falling back to a `--theme-*`
+global token so it matches the rest of the design system out of the box.
+
+### Trigger button
+
+| Token | Default | Controls |
+|---|---|---|
+| `--select-menu-trigger-gap` | `0.8rem` | Gap between icon / label / chevron |
+| `--select-menu-trigger-min-height` | `4.4rem` | Trigger minimum height |
+| `--select-menu-trigger-padding-block` | `0.8rem` | Trigger vertical padding |
+| `--select-menu-trigger-padding-inline` | `1.2rem` | Trigger horizontal padding |
+| `--select-menu-trigger-border-width` | `0.1rem` | Trigger border thickness |
+| `--select-menu-trigger-border` | `var(--theme-border)` | Trigger border colour (rest state) |
+| `--select-menu-trigger-border-focus` | `var(--theme-border-focus)` | Trigger border colour on hover/focus |
+| `--select-menu-trigger-border-radius` | `0.5rem` | Trigger corner rounding |
+| `--select-menu-trigger-surface` | `var(--theme-input-surface)` | Trigger background |
+| `--select-menu-trigger-text-color` | `var(--theme-text)` | Trigger label text colour |
+| `--select-menu-trigger-font-size` | `1.6rem` | Trigger label font size |
+| `--select-menu-trigger-outline-width` | `0.2rem` | Focus-visible outline width (trigger and items) |
+| `--select-menu-trigger-icon-size` | `2rem` | Selected option's icon size in the trigger |
+| `--select-menu-trigger-chevron-size` | `1.6rem` | Chevron icon size |
+
+### Menu popover
+
+| Token | Default | Controls |
+|---|---|---|
+| `--select-menu-block-distance` | `0.4rem` | Gap between trigger bottom and menu top |
+| `--select-menu-popover-border-width` | `0.1rem` | Popover border thickness |
+| `--select-menu-popover-border` | `var(--theme-border)` | Popover border colour |
+| `--select-menu-popover-surface` | `var(--theme-input-surface)` | Popover background |
+| `--select-menu-popover-border-radius` | `0.5rem` | Popover corner rounding |
+| `--select-menu-popover-min-width` | `18rem` | Minimum popover width |
+| `--select-menu-popover-max-height` | `32rem` | Maximum popover height before scrolling |
+| `--select-menu-popover-shadow` | `0 0.4rem 1.6rem rgb(0 0 0 / 12%)` | Popover drop shadow |
+| `--select-menu-transition-duration` | `200ms` | Open/close fade and chevron-rotate duration |
+
+### Options
+
+| Token | Default | Controls |
+|---|---|---|
+| `--select-menu-item-gap` | `0.8rem` | Gap between checkmark / icon / label in a row |
+| `--select-menu-item-padding-block` | `1rem` | Option row vertical padding |
+| `--select-menu-item-padding-inline` | `1.2rem` | Option row horizontal padding |
+| `--select-menu-item-text-color` | `var(--theme-text)` | Option label colour |
+| `--select-menu-item-font-size` | `1.5rem` | Option label font size |
+| `--select-menu-item-surface-hover` | `var(--theme-input-surface-hover)` | Option row background on hover/focus |
+| `--select-menu-item-check-size` | `1.6rem` | Checkmark icon box size |
+| `--select-menu-item-check-color` | `currentcolor` | Checkmark icon colour |
+| `--select-menu-item-icon-size` | `1.8rem` | Per-option icon size |
+
+---
+
+## Global theming — recommended approach
+
+Create `assets/styles/setup/07.components/select-menu.css` in the consuming app and set tokens
+on `:root`. This applies to every `SelectMenu` across the site.
+
+```css
+/* assets/styles/setup/07.components/select-menu.css */
+:root {
+  --select-menu-trigger-border-radius: 999rem;
+  --select-menu-trigger-surface: var(--brand-surface);
+  --select-menu-trigger-border: var(--brand-border);
+
+  --select-menu-popover-surface: var(--brand-surface);
+  --select-menu-popover-border: var(--brand-border);
+  --select-menu-popover-shadow: 0 0.8rem 2.4rem rgba(0, 0, 0, 0.15);
+
+  --select-menu-item-surface-hover: var(--brand-surface-subtle);
+  --select-menu-item-check-color: var(--brand-accent);
+}
+```
+
+---
+
+## Per-instance overrides via styleClassPassthrough
+
+```vue
+<SelectMenu
+  v-model="language"
+  :options="languageOptions"
+  label="Language"
+  :style-class-passthrough="['compact-switcher']"
+/>
+```
+
+```css
+.select-menu.compact-switcher {
+  --select-menu-trigger-min-height: 3.2rem;
+  --select-menu-trigger-padding-inline: 0.8rem;
+  --select-menu-trigger-border-radius: 50%;
+}
+```
+
+---
+
+## Trigger content variants
+
+`showIcon` / `showLabel` / `showChevron` control what renders in the trigger — combine them for
+the three common shapes:
+
+| Variant | Props |
+|---|---|
+| Icon-only (e.g. flag switcher in a tight header) | `:show-label="false" :show-chevron="false"` |
+| Text + chevron (e.g. a category filter with no per-option icons) | `:show-icon="false"` (default `showLabel`/`showChevron`) |
+| Icon + text + chevron (full select) | Defaults — no overrides needed |
+
+---
+
+## Single-select vs multi-select
+
+By default `SelectMenu` is single-select: `v-model` is `string | number | undefined`, the selected
+option shows a checkmark, and picking one closes the popover.
+
+Set `multiple` for a checkbox-per-option multi-select instead: `v-model` becomes
+`(string | number)[]`, every option shows a checkbox (checked/unchecked), and picking an option
+toggles it in the array without closing the popover — so several can be picked in one open/close
+cycle. By default the trigger text stays fixed on `placeholder`/`label` as a static category tag
+(e.g. `"Services required"`) regardless of how many options are checked, since a comma-joined list
+of checked options would grow unpredictably long. Set `showSelectionInTrigger` to opt into that
+comma-joined list instead (falling back to `placeholder`/`label` when nothing is checked). The
+trigger icon is not shown in multi-select mode (`showIcon` has no effect), since there's no single
+selected option to represent.
+
+```vue
+<script setup lang="ts">
+const treatments = ref<string[]>([]);
+const treatmentOptions = [
+  { value: "trim", label: "Trim" },
+  { value: "layers", label: "Layers" },
+  { value: "restyle", label: "Restyle" },
+  { value: "straightening", label: "Straightening" },
+];
+</script>
+
+<template>
+  <SelectMenu v-model="treatments" :options="treatmentOptions" label="Services required" multiple />
+
+  <!-- Trigger updates to "Layers, Restyle" etc. as options are checked -->
+  <SelectMenu
+    v-model="treatments"
+    :options="treatmentOptions"
+    label="Services required"
+    multiple
+    show-selection-in-trigger
+  />
+</template>
+```
+
+For several independent single-select filter categories (rather than one multi-select category),
+place multiple single-select `SelectMenu` instances side by side instead — see the "Filter Bar"
+story.
+
+---
+
+## Notes
+
+- **Popover API + CSS anchor positioning** — same mechanism as `ActionMenu`. Broadly supported
+  (Chrome 114+, Firefox 125+, Safari 17+). No polyfill is included.
+- **Popover left-aligns with the trigger** by default (`left: anchor(left)`), unlike `ActionMenu`
+  which right-aligns — matches native `<select>` dropdown behaviour. Flips above the trigger near
+  the bottom of the viewport (`position-try-fallbacks: flip-block`).
+- **Chevron rotation** is pure CSS via `:has(.select-menu-popover:popover-open)` — no JS state
+  needed for the visual, though `isOpen` is still tracked internally to drive `aria-expanded`.