srcdev-nuxt-components 9.4.4 → 9.4.6

package/app/components/01.atoms/animations/marquee-scroller/tests/MarqueeScroller.spec.ts

@@ -0,0 +1,315 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { nextTick } from "vue";
+import MarqueeScroller from "../MarqueeScroller.vue";
+
+const stubMatchMedia = (prefersReducedMotion: boolean) => {
+  vi.stubGlobal(
+    "matchMedia",
+    vi.fn().mockReturnValue({
+      matches: prefersReducedMotion,
+      addEventListener: vi.fn(),
+    })
+  );
+};
+
+// jsdom reports 0 for offsetWidth/scrollWidth — stub them per-element by class so
+// updateRepeatCount() sees realistic container/content dimensions.
+const originalOffsetWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "offsetWidth");
+const originalScrollWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "scrollWidth");
+
+const stubDimensions = ({ containerWidth, groupScrollWidth }: { containerWidth: number; groupScrollWidth: number }) => {
+  Object.defineProperty(HTMLElement.prototype, "offsetWidth", {
+    configurable: true,
+    get() {
+      return this.classList.contains("marquee-scroller") ? containerWidth : 0;
+    },
+  });
+  Object.defineProperty(HTMLElement.prototype, "scrollWidth", {
+    configurable: true,
+    get() {
+      return this.classList.contains("marquee-group") ? groupScrollWidth : 0;
+    },
+  });
+};
+
+const restoreDimensions = () => {
+  if (originalOffsetWidth) Object.defineProperty(HTMLElement.prototype, "offsetWidth", originalOffsetWidth);
+  if (originalScrollWidth) Object.defineProperty(HTMLElement.prototype, "scrollWidth", originalScrollWidth);
+};
+
+const marqueeData = [
+  { id: 1, content: "logo-a" },
+  { id: 2, content: "logo-b" },
+];
+
+describe("MarqueeScroller", () => {
+  beforeEach(() => {
+    stubMatchMedia(false);
+  });
+
+  afterEach(() => {
+    restoreDimensions();
+  });
+
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders after mount (displayComponent flips true in onMounted)", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.find(".marquee-scroller").exists()).toBe(true);
+  });
+
+  // ─── Snapshots ───────────────────────────────────────────────────────────
+
+  it("renders correct HTML structure (default props)", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders correct HTML structure (all props set)", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: {
+        animationRuntime: "20s",
+        reverse: true,
+        marqueeData,
+        itemConfig: { width: "80px", height: "80px", gap: "24px" },
+        ariaLabel: "Client logos",
+        ariaDescription: "Custom instructions",
+        showControls: true,
+      },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  // ─── marqueeData / slots ─────────────────────────────────────────────────
+
+  it("renders each marqueeData item twice (main track + duplicate for looping)", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { marqueeData },
+      slots: {
+        "1": "<span class='logo-a'>A</span>",
+        "2": "<span class='logo-b'>B</span>",
+      },
+    });
+    expect(wrapper.findAll(".logo-a")).toHaveLength(2);
+    expect(wrapper.findAll(".logo-b")).toHaveLength(2);
+  });
+
+  it("renders no items when marqueeData is empty", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.findAll(".item")).toHaveLength(0);
+  });
+
+  // ─── reverse ─────────────────────────────────────────────────────────────
+
+  it("does not apply the reverse class by default", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.classes()).not.toContain("reverse");
+  });
+
+  it("applies the reverse class when reverse is true", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { reverse: true },
+    });
+    expect(wrapper.classes()).toContain("reverse");
+  });
+
+  // ─── Accessibility attributes ────────────────────────────────────────────
+
+  it("defaults aria-label to 'Scrolling content'", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.attributes("aria-label")).toBe("Scrolling content");
+  });
+
+  it("uses a custom ariaLabel when provided", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { ariaLabel: "Client logos" },
+    });
+    expect(wrapper.attributes("aria-label")).toBe("Client logos");
+  });
+
+  it("uses default screen-reader instructions when ariaDescription is not set", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.find(".sr-only").text()).toContain("Use spacebar to pause or play");
+  });
+
+  it("uses a custom ariaDescription when provided", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { ariaDescription: "Custom instructions" },
+    });
+    expect(wrapper.find(".sr-only").text()).toBe("Custom instructions");
+  });
+
+  it("sets aria-live to off while playing", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.attributes("aria-live")).toBe("off");
+  });
+
+  // ─── Controls ────────────────────────────────────────────────────────────
+
+  it("does not render the control button by default", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.find(".control-btn").exists()).toBe(false);
+  });
+
+  it("renders the control button when showControls is true", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { showControls: true },
+    });
+    expect(wrapper.find(".control-btn").exists()).toBe(true);
+  });
+
+  it("toggles paused state and aria-live when the control button is clicked", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { showControls: true },
+    });
+    await wrapper.find(".control-btn").trigger("click");
+    expect(wrapper.classes()).toContain("paused");
+    expect(wrapper.attributes("aria-live")).toBe("polite");
+    expect(wrapper.find(".control-btn").attributes("aria-label")).toBe("Play animation");
+  });
+
+  // ─── Control button icon / label customisation ──────────────────────────
+
+  it("renders the default play icon while playing", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { showControls: true },
+    });
+    expect(wrapper.find(".control-btn").html()).toContain("mdi:pause");
+  });
+
+  it("renders the default play icon once paused", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { showControls: true },
+    });
+    await wrapper.find(".control-btn").trigger("click");
+    expect(wrapper.find(".control-btn").html()).toContain("mdi:play");
+  });
+
+  it("renders a custom playIcon/pauseIcon", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { showControls: true, playIcon: "mdi:play-circle", pauseIcon: "mdi:pause-circle" },
+    });
+    expect(wrapper.find(".control-btn").html()).toContain("mdi:pause-circle");
+    await wrapper.find(".control-btn").trigger("click");
+    expect(wrapper.find(".control-btn").html()).toContain("mdi:play-circle");
+  });
+
+  it("uses custom playLabel/pauseLabel for the control button's aria-label", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { showControls: true, playLabel: "Reproduire", pauseLabel: "Suspendre" },
+    });
+    expect(wrapper.find(".control-btn").attributes("aria-label")).toBe("Suspendre");
+    await wrapper.find(".control-btn").trigger("click");
+    expect(wrapper.find(".control-btn").attributes("aria-label")).toBe("Reproduire");
+  });
+
+  it("replaces the toggle icon via the toggle-icon slot", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { showControls: true },
+      slots: { "toggle-icon": "<span class='custom-icon'>custom</span>" },
+    });
+    expect(wrapper.find(".custom-icon").exists()).toBe(true);
+  });
+
+  it("passes isPaused to the toggle-icon slot", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { showControls: true },
+      slots: { "toggle-icon": "<template #toggle-icon=\"{ isPaused }\"><span class='state'>{{ isPaused }}</span></template>" },
+    });
+    expect(wrapper.find(".state").text()).toBe("false");
+    await wrapper.find(".control-btn").trigger("click");
+    expect(wrapper.find(".state").text()).toBe("true");
+  });
+
+  // ─── Keyboard interaction ────────────────────────────────────────────────
+
+  it("toggles pause on spacebar keydown", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    await wrapper.trigger("keydown", { key: " " });
+    expect(wrapper.classes()).toContain("paused");
+    await wrapper.trigger("keydown", { key: " " });
+    expect(wrapper.classes()).not.toContain("paused");
+  });
+
+  it("does not react to arrow keys (no manual-stepping behaviour is implemented)", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    await wrapper.trigger("keydown", { key: "ArrowLeft" });
+    await wrapper.trigger("keydown", { key: "ArrowRight" });
+    expect(wrapper.classes()).not.toContain("paused");
+  });
+
+  // ─── Focus / blur ────────────────────────────────────────────────────────
+
+  it("pauses on focus when respectReducedMotion is true (default)", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    await wrapper.trigger("focus");
+    expect(wrapper.classes()).toContain("paused");
+  });
+
+  it("resumes on blur when the user does not prefer reduced motion", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller);
+    await wrapper.trigger("focus");
+    await wrapper.trigger("blur");
+    expect(wrapper.classes()).not.toContain("paused");
+  });
+
+  it("does not pause on focus when respectReducedMotion is false", async () => {
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { respectReducedMotion: false },
+    });
+    await wrapper.trigger("focus");
+    expect(wrapper.classes()).not.toContain("paused");
+  });
+
+  // ─── Reduced motion ──────────────────────────────────────────────────────
+
+  it("auto-pauses and applies reduced-motion class when the user prefers reduced motion", async () => {
+    stubMatchMedia(true);
+    const wrapper = await mountSuspended(MarqueeScroller);
+    expect(wrapper.classes()).toContain("paused");
+    expect(wrapper.classes()).toContain("reduced-motion");
+  });
+
+  it("does not check matchMedia when respectReducedMotion is false", async () => {
+    stubMatchMedia(false);
+    const matchMediaSpy = vi.fn(() => ({ matches: false, addEventListener: vi.fn() }));
+    vi.stubGlobal("matchMedia", matchMediaSpy);
+    await mountSuspended(MarqueeScroller, {
+      props: { respectReducedMotion: false },
+    });
+    expect(matchMediaSpy).not.toHaveBeenCalled();
+  });
+
+  // ─── Repeating marqueeData to fill a wide container ─────────────────────
+
+  it("repeats marqueeData enough times so one group's width covers a wide container", async () => {
+    stubDimensions({ containerWidth: 500, groupScrollWidth: 100 });
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { marqueeData },
+      slots: { "1": "<span class='logo-a'></span>", "2": "<span class='logo-b'></span>" },
+    });
+    await nextTick();
+    await nextTick();
+    // needs ceil(500/100) = 5 copies of the 2-item data per group
+    expect(wrapper.findAll(".logo-a")).toHaveLength(10);
+    expect(wrapper.findAll(".logo-b")).toHaveLength(10);
+  });
+
+  it("does not add extra copies when a single copy already covers the container", async () => {
+    stubDimensions({ containerWidth: 50, groupScrollWidth: 200 });
+    const wrapper = await mountSuspended(MarqueeScroller, {
+      props: { marqueeData },
+      slots: { "1": "<span class='logo-a'></span>", "2": "<span class='logo-b'></span>" },
+    });
+    await nextTick();
+    await nextTick();
+    expect(wrapper.findAll(".logo-a")).toHaveLength(2);
+    expect(wrapper.findAll(".logo-b")).toHaveLength(2);
+  });
+});

package/app/components/01.atoms/animations/marquee-scroller/tests/__snapshots__/MarqueeScroller.spec.ts.snap

@@ -0,0 +1,28 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`MarqueeScroller > renders correct HTML structure (all props set) 1`] = `
+"<div class="marquee-scroller reverse" role="region" aria-label="Client logos" aria-live="off" tabindex="0">
+  <div class="sr-only">Custom instructions</div><button class="control-btn" aria-label="Pause animation" type="button"><span class="iconify i-mdi:pause" aria-hidden="true"></span></button>
+  <div class="marquee-track" aria-hidden="true">
+    <div class="marquee-group">
+      <div class="item"></div>
+      <div class="item"></div>
+    </div>
+    <div class="marquee-group" aria-hidden="true">
+      <div class="item"></div>
+      <div class="item"></div>
+    </div>
+  </div>
+</div>"
+`;
+
+exports[`MarqueeScroller > renders correct HTML structure (default props) 1`] = `
+"<div class="marquee-scroller" role="region" aria-label="Scrolling content" aria-live="off" tabindex="0">
+  <div class="sr-only">Use spacebar to pause or play the animation.</div>
+  <!--v-if-->
+  <div class="marquee-track" aria-hidden="true">
+    <div class="marquee-group"></div>
+    <div class="marquee-group" aria-hidden="true"></div>
+  </div>
+</div>"
+`;

package/app/components/01.atoms/canvas-switcher/CONSUMER-STYLING.md

@@ -0,0 +1,27 @@
+# CanvasSwitcher — Consumer Styling
+
+CanvasSwitcher renders its buttons via `InputButtonCore` (`variant="tertiary"`, icon-only) — see
+that component's own `CONSUMER-STYLING.md` for the button surface/hover/focus tokens it inherits.
+CanvasSwitcher itself exposes the following public tokens:
+
+| Token | Default | Applies to |
+|---|---|---|
+| `--canvas-switcher-gap` | `2rem` | Gap between the switcher's own children (currently just the list) |
+| `--canvas-switcher-item-gap` | `1rem` | Gap between each button in the list |
+| `--canvas-switcher-icon-size` | `2.4rem` | Width/height of each icon |
+| `--canvas-switcher-icon-colour` | `light-dark(var(--slate-10), var(--slate-02))` | Icon colour, resting state |
+| `--canvas-switcher-icon-colour-current` | `light-dark(var(--green-10), var(--green-04))` | Icon colour when that button's canvas is selected (`aria-pressed="true"`) |
+
+## Class passthrough
+
+`styleClassPassthrough` (string or string[]) is applied to the root `.canvas-switcher` element via
+`useStyleClassPassthrough()`.
+
+## Canvas-size utility classes
+
+`.mobileCanvas`, `.tabletCanvas`, `.laptopCanvas`, `.desktopCanvas`, `.fullWidthCanvas` are also
+declared in this component's stylesheet (not scoped to `.canvas-switcher`) so a consumer can apply
+the same `MediaCanvas` value returned by `v-model:canvas-name` directly as a class on a preview
+wrapper to constrain its width — see `LayoutGridA`/`LayoutGridB` stories for the pattern. These are
+plain global utility classes, not overridable via a CSS custom property; import `CanvasSwitcher`
+(or otherwise ensure its styles are bundled) wherever you rely on them.

package/app/components/01.atoms/canvas-switcher/CanvasSwitcher.vue

@@ -0,0 +1,111 @@
+<template>
+  <div class="canvas-switcher" :class="[elementClasses]">
+    <ul class="canvas-switcher-list">
+      <li v-for="option in canvasOptions" :key="option.value">
+        <InputButtonCore
+          type="button"
+          variant="tertiary"
+          class="canvas-switcher-button"
+          :button-text="option.label"
+          :aria-pressed="canvasName === option.value"
+          @click="updateCanvas(option.value)"
+        >
+          <template #iconOnly>
+            <Icon :name="option.icon" class="icon"></Icon>
+          </template>
+        </InputButtonCore>
+      </li>
+    </ul>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { MediaCanvas } from "~/types/components";
+
+interface CanvasOption {
+  value: MediaCanvas;
+  label: string;
+  icon: string;
+}
+
+interface Props {
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  styleClassPassthrough: () => [],
+});
+
+const canvasName = defineModel<MediaCanvas>("canvasName");
+
+const canvasOptions: CanvasOption[] = [
+  { value: "mobileCanvas", label: "Mobile", icon: "ic:baseline-phone-iphone" },
+  { value: "tabletCanvas", label: "Tablet", icon: "ic:baseline-tablet-mac" },
+  { value: "laptopCanvas", label: "Laptop", icon: "ic:baseline-laptop-mac" },
+  { value: "desktopCanvas", label: "Desktop", icon: "ic:outline-desktop-mac" },
+  { value: "fullWidthCanvas", label: "Full width", icon: "pixelarticons:viewport-wide" },
+];
+
+const updateCanvas = (setCanvas: MediaCanvas) => {
+  canvasName.value = setCanvas;
+};
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .canvas-switcher {
+    display: flex;
+    align-items: center;
+    gap: var(--canvas-switcher-gap, 2rem);
+  }
+
+  .canvas-switcher-list {
+    display: flex;
+    align-items: center;
+    gap: var(--canvas-switcher-item-gap, 1rem);
+    list-style-type: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  .canvas-switcher-button.input-button-core {
+    color: var(--canvas-switcher-icon-colour, light-dark(var(--slate-10), var(--slate-02)));
+
+    &[aria-pressed="true"] {
+      color: var(--canvas-switcher-icon-colour-current, light-dark(var(--green-10), var(--green-04)));
+    }
+
+    .icon {
+      width: var(--canvas-switcher-icon-size, 2.4rem);
+      height: var(--canvas-switcher-icon-size, 2.4rem);
+    }
+  }
+
+  /* Canvas-size utility classes — applied by a consumer to a preview wrapper to constrain
+     it to the width matching a MediaCanvas value. Not scoped to .canvas-switcher itself. */
+  .mobileCanvas {
+    max-width: 41.2rem;
+  }
+  .tabletCanvas {
+    max-width: 76.8rem;
+  }
+  .laptopCanvas {
+    max-width: 106.4rem;
+  }
+  .desktopCanvas {
+    max-width: 128rem;
+  }
+  .fullWidthCanvas {
+    max-width: unset;
+  }
+}
+</style>

package/app/components/01.atoms/canvas-switcher/stories/CanvasSwitcher.stories.ts

@@ -0,0 +1,75 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import CanvasSwitcher from "../CanvasSwitcher.vue";
+import type { MediaCanvas } from "~/types/components";
+
+interface CanvasSwitcherStoryArgs {
+  canvasName: MediaCanvas | undefined;
+  styleClassPassthrough: string[];
+}
+
+export default {
+  title: "Atoms/CanvasSwitcher",
+  component: CanvasSwitcher,
+  argTypes: {
+    canvasName: {
+      control: { type: "select" },
+      options: ["mobileCanvas", "tabletCanvas", "laptopCanvas", "desktopCanvas", "fullWidthCanvas"],
+      description: "Bound via v-model:canvas-name — the currently selected MediaCanvas value",
+      table: { category: "Model" },
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Additional CSS classes applied to the root element",
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    canvasName: "desktopCanvas",
+    styleClassPassthrough: [],
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "An icon button group for switching between MediaCanvas preview widths (mobile/tablet/laptop/desktop/full width). Also declares the `.mobileCanvas`/`.tabletCanvas`/etc. utility classes a consumer can apply to a preview wrapper to constrain it to the matching width — see LayoutGridA/LayoutGridB stories.",
+      },
+    },
+  },
+} as Meta<typeof CanvasSwitcher>;
+
+const Template: StoryFn<CanvasSwitcherStoryArgs> = (args) => ({
+  components: { CanvasSwitcher },
+  setup() {
+    const { canvasName, ...otherArgs } = args;
+    const selected = ref(canvasName);
+    return { selected, args: otherArgs };
+  },
+  template: `
+    <div>
+      <CanvasSwitcher v-model:canvas-name="selected" v-bind="args" />
+      <p style="margin-top: 1.6rem;">Selected: {{ selected }}</p>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+Default.args = {};
+
+export const PreviewWidthDemo = Template.bind({});
+PreviewWidthDemo.args = {};
+PreviewWidthDemo.render = (args) => ({
+  components: { CanvasSwitcher },
+  setup() {
+    const { canvasName } = args;
+    const selected = ref(canvasName);
+    return { selected };
+  },
+  template: `
+    <div>
+      <CanvasSwitcher v-model:canvas-name="selected" />
+      <div :class="selected" style="border: 1px dashed currentColor; margin-top: 1.6rem; padding: 1.6rem;">
+        This box is constrained by the selected canvas's utility class.
+      </div>
+    </div>
+  `,
+});

package/app/components/01.atoms/canvas-switcher/tests/CanvasSwitcher.spec.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import CanvasSwitcher from "../CanvasSwitcher.vue";
+
+describe("CanvasSwitcher", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(CanvasSwitcher);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders one button per canvas option", async () => {
+    const wrapper = await mountSuspended(CanvasSwitcher);
+    expect(wrapper.findAll("button").length).toBe(5);
+  });
+
+  it("gives each button an accessible name", async () => {
+    const wrapper = await mountSuspended(CanvasSwitcher);
+    const labels = wrapper.findAll("button").map((button) => button.text());
+    expect(labels).toEqual(["Mobile", "Tablet", "Laptop", "Desktop", "Full width"]);
+  });
+
+  it("marks no button as pressed when canvasName is unset", async () => {
+    const wrapper = await mountSuspended(CanvasSwitcher);
+    const pressed = wrapper.findAll('button[aria-pressed="true"]');
+    expect(pressed.length).toBe(0);
+  });
+
+  it("marks the matching button as pressed via the canvasName model", async () => {
+    const wrapper = await mountSuspended(CanvasSwitcher, {
+      props: { canvasName: "tabletCanvas" },
+    });
+    const buttons = wrapper.findAll("button");
+    expect(buttons[1]?.attributes("aria-pressed")).toBe("true");
+    expect(buttons[0]?.attributes("aria-pressed")).toBe("false");
+  });
+
+  it("updates the canvasName model when a button is clicked", async () => {
+    const wrapper = await mountSuspended(CanvasSwitcher, {
+      props: { canvasName: "mobileCanvas" },
+    });
+    await wrapper.findAll("button")[3]?.trigger("click");
+    expect(wrapper.emitted("update:canvasName")?.[0]).toEqual(["desktopCanvas"]);
+  });
+
+  it("applies a single styleClassPassthrough string", async () => {
+    const wrapper = await mountSuspended(CanvasSwitcher, { props: { styleClassPassthrough: "custom-class" } });
+    expect(wrapper.classes()).toContain("custom-class");
+  });
+
+  it("applies multiple styleClassPassthrough classes from an array", async () => {
+    const wrapper = await mountSuspended(CanvasSwitcher, {
+      props: { styleClassPassthrough: ["class-a", "class-b"] },
+    });
+    expect(wrapper.classes()).toContain("class-a");
+    expect(wrapper.classes()).toContain("class-b");
+  });
+
+  it("updates classes when styleClassPassthrough prop changes", async () => {
+    const wrapper = await mountSuspended(CanvasSwitcher, {
+      props: { styleClassPassthrough: ["original"] },
+    });
+    expect(wrapper.classes()).toContain("original");
+    await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+    expect(wrapper.classes()).not.toContain("original");
+    expect(wrapper.classes()).toContain("updated");
+  });
+});

package/app/components/01.atoms/clipped-panel/CONSUMER-STYLING.md

@@ -0,0 +1,39 @@
+# ClippedPanel — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--clipped-panel-background-colour` | `light-dark(hsl(0, 0%, 96%), hsl(0, 0%, 12%))` | Panel background |
+| `--clipped-panel-outline-colour` | `light-dark(hsl(0, 29%, 3%), hsl(0, 0%, 92%))` | Outline colour, and the panel's text/icon colour (`color`) |
+| `--clipped-panel-outline-width` | `1px` | Outline width |
+
+```css
+.my-page {
+  --clipped-panel-background-colour: #fef3e7;
+  --clipped-panel-outline-colour: #b5651d;
+  --clipped-panel-outline-width: 2px;
+}
+```
+
+Or scope to a single instance via `styleClassPassthrough`:
+
+```vue
+<ClippedPanel variant="square" style-class-passthrough="promo-panel">...</ClippedPanel>
+```
+
+```css
+.promo-panel {
+  --clipped-panel-background-colour: #fef3e7;
+}
+```
+
+## Shapes are fixed-size, not tokenised
+
+Each `variant`'s notched/cutout shape is drawn with `clip-path: path("...")` using literal pixel
+coordinates (`square`/`circle-cutout` at 200×200px, `rectangle` at 300×200px). CSS custom
+properties cannot be interpolated into a `path()` string, so the shape geometry itself — corner
+radii, notch size, overall dimensions — is **not** overridable via tokens or `width`/`height`
+overrides. Changing `width` on the element stretches the box without moving the clip-path
+coordinates, which will misalign the shape. If a different size or geometry is needed, that
+requires a new variant with its own `path()` string, not a CSS override.