srcdev-nuxt-components 9.4.4 → 9.4.5

package/.claude/skills/composable-tooltips-guide.md

@@ -89,6 +89,16 @@ await startGuide()
 | `stopGuide()` | `() => void` | Close any open popovers and stop the guide |
 | `initializePopovers()` | `() => void` | Re-scan the container for `[popover]` elements; call if popovers are added dynamically |
 
+## Example with DisplayTooltip / DisplayTooltipDefined
+
+[`DisplayTooltip`](components/display-tooltip.md) and
+[`DisplayTooltipDefined`](components/display-tooltip-defined.md) already emit the
+`[popover]`/`popovertarget`/`popovertargetaction` markup this composable expects, so no extra
+wiring is needed beyond passing their shared container's ref in. See the `GuidedTour` story in
+`DisplayTooltipDefined.stories.ts` for a full working example — it recreates the old
+`app/pages/ui/tooltips.vue` demo page (removed 2026-08-23 when Storybook became the only demo
+surface), mixing one of each component as guide steps.
+
 ## Notes
 
 - If no trigger button is found for a popover, `togglePopover(true)` is called directly as a fallback — anchor positioning may not apply in this case.

package/.claude/skills/index.md

@@ -63,6 +63,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── composable-analytics.md           — useAnalytics: provider-agnostic trackEvent/page-view tracking (google-analytics only implemented), consent-gated, single call site for setup + firing events
 └── components/
     ├── alert-content-inner.md    — AlertContentInner: shared icon/body/dismiss molecule under AlertContent + AlertMaskedContent; app.config icon map (alertContent.icons + dismissIcon) covers all consumers
+    ├── animated-svg-text.md    — AnimatedSvgText: inline SVG stroke-draw-then-fill animation, text slot, CSS token API
     ├── accordian-core.md       — AccordianCore indexed dynamic slots (accordian-{n}-summary/icon/content), exclusive-open grouping
     ├── eyebrow-text.md         — EyebrowText props, usage patterns, styling
     ├── hero-text.md            — HeroText props, usage patterns, styling
@@ -109,7 +110,12 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── site-header.md            — SiteHeader: PageRow + SkipLinks + ResponsiveHeader composition, #branding/#secondaryNavigation slots, dual styleClassPassthrough hooks
     ├── responsive-header.md      — ResponsiveHeader: overflow-collapsing adaptive nav, measurement-pipeline gotchas (unsized icons, vw font-size drift), full CSS token API
     ├── navigation-items.md       — NavigationItems: internal overflow-panel renderer for ResponsiveHeader, complement-visibility logic, not used standalone
-    └── cookie-consent-banner.md  — CookieConsentBanner: fixed non-modal Accept/Reject banner driven by useCookieConsent, message/acceptLabel/rejectLabel slots, CSS token API
+    ├── cookie-consent-banner.md  — CookieConsentBanner: fixed non-modal Accept/Reject banner driven by useCookieConsent, message/acceptLabel/rejectLabel slots, CSS token API
+    ├── display-banner.md         — DisplayBanner: canvas/content stacked overlay banner, conditional slot wrappers, CSS token API
+    ├── deep-expanding-menu.md         — DeepExpandingMenu: anchor-positioned popover nav panels, browser support caveat, CSS token API
+    ├── deep-expanding-menu-classic.md — DeepExpandingMenuClassic: <details>-based fallback nav, click-outside close, CSS token API
+    ├── display-tooltip.md         — DisplayTooltip: anchor-positioned popover trigger, browser support caveat, CSS token API
+    └── display-tooltip-defined.md — DisplayTooltipDefined: structured title/body/action tooltip content with close button, composes DisplayTooltip
 ```
 
 ## Skill file template

package/.claude/skills/storybook-add-story.md

@@ -240,3 +240,33 @@ Key points:
   them in the Storybook controls panel (e.g. `"Model"`, `"Basic"`, `"Validation"`, `"Styling"`, `"Slots"`).
 - Export multiple named stories (`Default`, `WithError`, `Outlined`, etc.) when you want
   Playwright to test distinct visual states via separate story URLs.
+
+## Scroll/animation-driven effects need surrounding chrome, not just the bare component
+
+A story that renders a scroll- or timer-driven component with no other markup often fails to
+show the effect at all — not because the component is broken, but because the demo gives the
+viewer nothing to judge it against. Things that make an animated/scroll-driven effect illegible
+in isolation:
+
+- The effect resolves over a short distance/time relative to the page (e.g. a 100px scroll
+  window on an otherwise-long page) — easy to scroll straight past it.
+- The visual change is a subtle crop/shift on photographic content, where the eye has no
+  reference point to notice a boundary moving.
+- There's no indicator of *where* or *when* the effect completes.
+
+Add scaffolding around the component to fix this, rather than assuming a bigger/slower prop
+value alone solves it:
+
+- A fixed marker (a line, label) at the point in the viewport where the effect's key transition
+  happens (e.g. `position: fixed; top: 0` for a component that resolves when its own top hits
+  the viewport top).
+- A ruled/striped overlay or contrasting background behind the animated content so a boundary
+  (clip edge, wipe line, fade) is visible against it, not just a crop of photo pixels.
+- Short on-page instructions telling the viewer what to do and what to watch for ("scroll
+  slowly — the image clips in over the last 100px before the red line").
+- A second story with an exaggerated prop value (larger distance/duration) purely so the effect
+  is easy to preview without precise scrolling/timing — see `ClipElement`'s `LargeClipDistance`
+  story for the pattern (`.claude/skills/components/clip-element.md`).
+
+This is a documentation-only concern — it doesn't change the component's default props, just
+how the story demonstrates it.

package/.vscode/srcdev-component-animated-svg-text.code-snippets

@@ -0,0 +1,15 @@
+{
+  "SRCDEV AnimatedSvgText": {
+    "description": "AnimatedSvgText — stroke-draw-then-fill animation for inline SVG text/path content",
+    "scope": "vue,html",
+    "body": [
+      "<AnimatedSvgText>",
+      "  <template #text>",
+      "    <svg viewBox=\"0 0 $1600 $2150\">",
+      "      <path d=\"$3\" />",
+      "    </svg>",
+      "  </template>",
+      "</AnimatedSvgText>"
+    ]
+  }
+}

package/.vscode/srcdev-component-canvas-switcher.code-snippets

@@ -0,0 +1,9 @@
+{
+  "SRCDEV CanvasSwitcher": {
+    "description": "CanvasSwitcher — v-model:canvas-name icon button group for MediaCanvas preview widths",
+    "scope": "vue,html",
+    "body": [
+      "<CanvasSwitcher v-model:canvas-name=\"${1:canvasName}\" />"
+    ]
+  }
+}

package/.vscode/srcdev-component-clip-element.code-snippets

@@ -0,0 +1,20 @@
+{
+  "SRCDEV ClipElement Basic": {
+    "description": "ClipElement — scroll-driven clip-path reveal for a single image or block",
+    "scope": "vue,html",
+    "body": [
+      "<ClipElement :max-clip=\"$1100\">",
+      "  <img src=\"$2/images/hero.jpg\" alt=\"$3Hero\" style=\"width: 100%; display: block;\" />",
+      "</ClipElement>"
+    ]
+  },
+  "SRCDEV ClipElement With Passthrough": {
+    "description": "ClipElement with styleClassPassthrough for a custom wrapper class",
+    "scope": "vue,html",
+    "body": [
+      "<ClipElement :max-clip=\"$1150\" style-class-passthrough=\"$2my-clip-wrapper\">",
+      "  $0",
+      "</ClipElement>"
+    ]
+  }
+}

package/.vscode/srcdev-component-clipped-panel.code-snippets

@@ -0,0 +1,23 @@
+{
+  "SRCDEV ClippedPanel Basic": {
+    "description": "ClippedPanel — fixed-size notched/cutout shape panel",
+    "scope": "vue,html",
+    "body": [
+      "<ClippedPanel variant=\"$1square\">",
+      "  $0",
+      "</ClippedPanel>"
+    ]
+  },
+  "SRCDEV ClippedPanel Custom Colours": {
+    "description": "ClippedPanel with background/outline colour overrides",
+    "scope": "vue,html",
+    "body": [
+      "<ClippedPanel",
+      "  variant=\"$1square\"",
+      "  style=\"--clipped-panel-background-colour: $2#fef3e7; --clipped-panel-outline-colour: $3#b5651d;\"",
+      ">",
+      "  $0",
+      "</ClippedPanel>"
+    ]
+  }
+}

package/.vscode/srcdev-component-deep-expanding-menu-classic.code-snippets

@@ -0,0 +1,9 @@
+{
+  "SRCDEV DeepExpandingMenuClassic Basic": {
+    "description": "DeepExpandingMenuClassic — <details>-based fallback nav",
+    "scope": "vue,html",
+    "body": [
+      "<DeepExpandingMenuClassic :nav-links=\"$1navLinks\" />"
+    ]
+  }
+}

package/.vscode/srcdev-component-deep-expanding-menu.code-snippets

@@ -0,0 +1,9 @@
+{
+  "SRCDEV DeepExpandingMenu Basic": {
+    "description": "DeepExpandingMenu — anchor-positioned popover nav panels",
+    "scope": "vue,html",
+    "body": [
+      "<DeepExpandingMenu :nav-links=\"$1navLinks\" />"
+    ]
+  }
+}

package/.vscode/srcdev-component-display-banner.code-snippets

@@ -0,0 +1,30 @@
+{
+  "SRCDEV DisplayBanner Basic": {
+    "description": "DisplayBanner — canvas/content stacked overlay banner",
+    "scope": "vue,html",
+    "body": [
+      "<DisplayBanner>",
+      "  <template #canvas>",
+      "    $1",
+      "  </template>",
+      "  <template #content>",
+      "    $0",
+      "  </template>",
+      "</DisplayBanner>"
+    ]
+  },
+  "SRCDEV DisplayBanner Min Height": {
+    "description": "DisplayBanner with min-height override",
+    "scope": "vue,html",
+    "body": [
+      "<DisplayBanner style=\"--display-banner-min-height: $140rem;\">",
+      "  <template #canvas>",
+      "    $2",
+      "  </template>",
+      "  <template #content>",
+      "    $0",
+      "  </template>",
+      "</DisplayBanner>"
+    ]
+  }
+}

package/.vscode/srcdev-component-display-tooltip-defined.code-snippets

@@ -0,0 +1,14 @@
+{
+  "SRCDEV DisplayTooltipDefined Basic": {
+    "description": "DisplayTooltipDefined — structured title/body/action tooltip",
+    "scope": "vue,html",
+    "body": [
+      "<DisplayTooltipDefined",
+      "  :content-text=\"{",
+      "    tooltipTitle: { tag: 'h4', text: '$1' },",
+      "    tooltipContent: { tag: 'p', text: '$0' },",
+      "  }\"",
+      "/>"
+    ]
+  }
+}

package/.vscode/srcdev-component-display-tooltip.code-snippets

@@ -0,0 +1,27 @@
+{
+  "SRCDEV DisplayTooltip Basic": {
+    "description": "DisplayTooltip — anchor-positioned popover trigger",
+    "scope": "vue,html",
+    "body": [
+      "<DisplayTooltip>",
+      "  <template #tooltipContent>",
+      "    <p>$0</p>",
+      "  </template>",
+      "</DisplayTooltip>"
+    ]
+  },
+  "SRCDEV DisplayTooltip With Trigger Content": {
+    "description": "DisplayTooltip with a triggerContent label",
+    "scope": "vue,html",
+    "body": [
+      "<DisplayTooltip>",
+      "  <template #triggerContent>",
+      "    <span>$1</span>",
+      "  </template>",
+      "  <template #tooltipContent>",
+      "    <p>$0</p>",
+      "  </template>",
+      "</DisplayTooltip>"
+    ]
+  }
+}

package/app/components/01.atoms/animations/animated-svg-text/AnimatedSvgText.vue

@@ -0,0 +1,58 @@
+<template>
+  <div class="animated-svg-text" :class="[elementClasses]">
+    <slot name="text"></slot>
+  </div>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+
+@keyframes animatedSvgText {
+  0% {
+    fill: transparent;
+    stroke-dashoffset: var(--animated-svg-text-stroke-dasharray, 1000);
+    stroke-width: var(--animated-svg-text-stroke-width, 0.3);
+  }
+  70% {
+    fill: transparent;
+    stroke-width: var(--animated-svg-text-stroke-width, 0.3);
+  }
+  100% {
+    fill: var(--animated-svg-text-fill-colour, var(--theme-text));
+    stroke-dashoffset: 0;
+    stroke-width: 0;
+  }
+}
+
+.animated-svg-text {
+  svg path,
+  svg text {
+    stroke: var(--animated-svg-text-stroke-colour, var(--theme-text));
+    stroke-width: var(--animated-svg-text-stroke-width, 0.3);
+    stroke-dasharray: var(--animated-svg-text-stroke-dasharray, 1000);
+    stroke-dashoffset: var(--animated-svg-text-stroke-dasharray, 1000);
+    animation: animatedSvgText var(--animated-svg-text-animation-duration, 2s) linear 1 forwards;
+  }
+}
+
+}
+</style>

package/app/components/01.atoms/animations/animated-svg-text/CONSUMER-STYLING.md

@@ -0,0 +1,34 @@
+# AnimatedSvgText — Consumer Styling
+
+`AnimatedSvgText` has no props of its own beyond `styleClassPassthrough` — the SVG markup is
+provided via the `text` slot, either as `<path>` outlines of the text or a plain SVG `<text>`
+element (both support `stroke`/`fill`/`stroke-dasharray` per the SVG spec). All visual control is
+through public CSS custom properties, consumed directly on `.animated-svg-text svg path, .animated-svg-text svg text`.
+
+## Public tokens
+
+| Property | Default | Description |
+| -------- | ------- | ------------ |
+| `--animated-svg-text-stroke-colour` | `var(--theme-text)` | Stroke colour during the draw-on phase. |
+| `--animated-svg-text-fill-colour` | `var(--theme-text)` | Fill colour once the draw-on animation completes. |
+| `--animated-svg-text-stroke-width` | `0.3` | Stroke width (in the SVG's own coordinate units) during the draw-on phase. |
+| `--animated-svg-text-stroke-dasharray` | `1000` | Dash length used to drive the "draw" effect. Set this to roughly the total path length of your SVG — too small and the stroke completes before covering the full outline; too large and the animation appears to pause at the start. |
+| `--animated-svg-text-animation-duration` | `2s` | Duration of the full draw-fill animation. |
+
+```vue
+<AnimatedSvgText style="--animated-svg-text-stroke-colour: #e63946; --animated-svg-text-animation-duration: 3.5s;">
+  <template #text>
+    <svg viewBox="0 0 400 100"><path d="..." /></svg>
+  </template>
+</AnimatedSvgText>
+```
+
+## Notes
+
+- The animation runs once on mount (`forwards`, `1` iteration) — it does not loop or replay on re-entry.
+- `--animated-svg-text-stroke-dasharray` is the one token worth tuning per SVG: it depends on the
+  total length of the animated content, which varies with font, text length, and the SVG's
+  coordinate scale (`viewBox`). The defaults (`0.3` stroke-width, `1000` dasharray) suit path data
+  traced at a small/normalised coordinate scale — a larger `viewBox` (e.g. plain SVG `<text>` at a
+  large `font-size`) needs a proportionally larger `--animated-svg-text-stroke-width` and
+  `--animated-svg-text-stroke-dasharray`, or the stroke renders too thin/short to see.

package/app/components/01.atoms/animations/animated-svg-text/stories/AnimatedSvgText.stories.ts

@@ -0,0 +1,69 @@
+import AnimatedSvgText from "../AnimatedSvgText.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof AnimatedSvgText> = {
+  title: "Atoms/Animations/AnimatedSvgText",
+  component: AnimatedSvgText,
+  argTypes: {
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Animates inline SVG text outlines with a stroke-draw-then-fill effect on mount. Provide the SVG markup via the `text` slot. Styling is entirely via CSS custom properties — see CONSUMER-STYLING.md.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof AnimatedSvgText>;
+
+const svgSlot = `
+  <svg viewBox="0 0 600 150" xmlns="http://www.w3.org/2000/svg" style="width: 100%; height: auto;">
+    <text x="0" y="110" font-size="120" font-family="sans-serif" font-weight="700" fill="none">Hello</text>
+  </svg>
+`;
+
+// The default tokens (stroke-width 0.3, dasharray 1000) are tuned for path data traced at a
+// small/normalised coordinate scale. This demo's viewBox is much larger, so both stories override
+// stroke-width/dasharray to suit — see CONSUMER-STYLING.md: dasharray should roughly match the
+// total path length of the SVG being animated.
+const demoScaleTokens = "--animated-svg-text-stroke-width: 2; --animated-svg-text-stroke-dasharray: 2200;";
+
+export const Default: Story = {
+  render: () => ({
+    components: { AnimatedSvgText },
+    template: `<AnimatedSvgText style="${demoScaleTokens}"><template #text>${svgSlot}</template></AnimatedSvgText>`,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Default draw-on animation using the theme's text colour for both stroke and fill.",
+      },
+    },
+  },
+};
+
+export const CustomColourAndSpeed: Story = {
+  render: () => ({
+    components: { AnimatedSvgText },
+    template: `
+      <AnimatedSvgText
+        style="${demoScaleTokens} --animated-svg-text-stroke-colour: #e63946; --animated-svg-text-fill-colour: #e63946; --animated-svg-text-animation-duration: 3.5s;"
+      >
+        <template #text>${svgSlot}</template>
+      </AnimatedSvgText>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Overriding `--animated-svg-text-stroke-colour`, `--animated-svg-text-fill-colour`, and slowing the animation via `--animated-svg-text-animation-duration`.",
+      },
+    },
+  },
+};

package/app/components/01.atoms/animations/animated-svg-text/tests/AnimatedSvgText.spec.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import AnimatedSvgText from "../AnimatedSvgText.vue";
+
+describe("AnimatedSvgText", () => {
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      slots: { text: '<svg viewBox="0 0 100 100"><path d="M0 0 L100 100" /></svg>' },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  // ─── Root element ────────────────────────────────────────────────────────
+
+  it("renders a div with the animated-svg-text class", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText);
+    expect(wrapper.element.tagName).toBe("DIV");
+    expect(wrapper.classes()).toContain("animated-svg-text");
+  });
+
+  // ─── Slot ────────────────────────────────────────────────────────────────
+
+  it("renders the text slot content", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      slots: { text: '<svg data-testid="my-svg"><path d="M0 0" /></svg>' },
+    });
+    expect(wrapper.find('[data-testid="my-svg"]').exists()).toBe(true);
+  });
+
+  // ─── styleClassPassthrough ───────────────────────────────────────────────
+
+  it("applies a single styleClassPassthrough string to the root", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      props: { styleClassPassthrough: "hero-svg-text" },
+    });
+    expect(wrapper.classes()).toContain("hero-svg-text");
+  });
+
+  it("applies multiple styleClassPassthrough classes from an array", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      props: { styleClassPassthrough: ["hero-svg-text", "mbe-32"] },
+    });
+    expect(wrapper.classes()).toContain("hero-svg-text");
+    expect(wrapper.classes()).toContain("mbe-32");
+  });
+
+  it("updates classes when styleClassPassthrough prop changes", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      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/animations/animated-svg-text/tests/__snapshots__/AnimatedSvgText.spec.ts.snap

@@ -0,0 +1,7 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`AnimatedSvgText > renders correct HTML structure 1`] = `
+"<div class="animated-svg-text"><svg viewBox="0 0 100 100">
+    <path d="M0 0 L100 100"></path>
+  </svg></div>"
+`;

package/app/components/01.atoms/animations/clip-element/CONSUMER-STYLING.md

@@ -0,0 +1,27 @@
+# ClipElement — Consumer Styling Guide
+
+## No public CSS token API
+
+`ClipElement` has no `--clip-element-*` custom properties. Its only visual output is the
+`clip-path` inset applied to `.clipped-element`, and that value is entirely computed at runtime
+from the `maxClip` prop and the element's scroll position — there is no fixed appearance value a
+consumer would plausibly want to override via CSS.
+
+## Override surface
+
+Use `styleClassPassthrough` to apply your own classes to the root `.clip-element-wrapper`:
+
+```vue
+<ClipElement :max-clip="150" style-class-passthrough="my-clip-wrapper">
+  <img src="/images/hero.jpg" alt="Hero" />
+</ClipElement>
+```
+
+```css
+.my-clip-wrapper {
+  border-radius: 1.6rem;
+}
+```
+
+Style the slotted content directly for anything beyond the clip effect itself (sizing, object-fit,
+borders, etc.) — `ClipElement` does not constrain it.

package/app/components/{clip-element → 01.atoms/animations/clip-element}/ClipElement.vue

@@ -7,18 +7,23 @@
 </template>
 
 <script lang="ts" setup>
-const props = defineProps({
-  maxClip: {
-    type: Number,
-    default: 100,
-  },
-  styleClassPassthrough: {
-    type: [String, Array] as PropType<string | string[]>,
-    default: () => [],
-  },
-})
+interface Props {
+  /** Scroll distance (px) over which the element clips in/out. */
+  maxClip?: number;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  maxClip: 100,
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 
 const container = ref(null)
 const clipElement = ref<HTMLDivElement | null>(null)