srcdev-nuxt-components 9.4.5 → 9.4.7

package/.vscode/srcdev-component-marquee-scroller.code-snippets

@@ -0,0 +1,93 @@
+{
+  "SRCDEV MarqueeScroller Basic": {
+    "description": "MarqueeScroller — infinite horizontal logo/badge scroller with per-item slots",
+    "scope": "vue,html",
+    "body": [
+      "<MarqueeScroller",
+      "  :marquee-data=\"[",
+      "    { id: 1, content: '$1logo-a' },",
+      "    { id: 2, content: '$2logo-b' },",
+      "  ]\"",
+      "  :item-config=\"{ width: '${3:120px}', height: '${4:60px}', gap: '${5:24px}' }\"",
+      ">",
+      "  <template #1>",
+      "    $6",
+      "  </template>",
+      "  <template #2>",
+      "    $7",
+      "  </template>",
+      "</MarqueeScroller>"
+    ]
+  },
+  "SRCDEV MarqueeScroller With Controls": {
+    "description": "MarqueeScroller with the visible pause/play control button (WCAG 2.2.2)",
+    "scope": "vue,html",
+    "body": [
+      "<MarqueeScroller",
+      "  :marquee-data=\"$1items\"",
+      "  show-controls",
+      "  aria-label=\"$2Scrolling client logos\"",
+      ">",
+      "  <template v-for=\"item in $1items\" #[item.id] :key=\"item.id\">",
+      "    $3",
+      "  </template>",
+      "</MarqueeScroller>"
+    ]
+  },
+  "SRCDEV MarqueeScroller Custom Control Icon/Copy": {
+    "description": "MarqueeScroller control button with custom icons and localised aria-labels",
+    "scope": "vue,html",
+    "body": [
+      "<MarqueeScroller",
+      "  :marquee-data=\"$1items\"",
+      "  show-controls",
+      "  play-icon=\"${2:mdi:play-circle}\"",
+      "  pause-icon=\"${3:mdi:pause-circle}\"",
+      "  play-label=\"${4:Play}\"",
+      "  pause-label=\"${5:Pause}\"",
+      ">",
+      "  <template v-for=\"item in $1items\" #[item.id] :key=\"item.id\">",
+      "    $6",
+      "  </template>",
+      "</MarqueeScroller>"
+    ]
+  },
+  "SRCDEV MarqueeScroller Custom Toggle Icon Slot": {
+    "description": "MarqueeScroller with the toggle-icon slot fully replacing the control button's icon",
+    "scope": "vue,html",
+    "body": [
+      "<MarqueeScroller :marquee-data=\"$1items\" show-controls>",
+      "  <template #toggle-icon=\"{ isPaused }\">",
+      "    $2",
+      "  </template>",
+      "</MarqueeScroller>"
+    ]
+  },
+  "SRCDEV MarqueeScroller CSS Override": {
+    "description": "CSS override scaffold for MarqueeScroller — scope to a page or section class",
+    "scope": "css",
+    "body": [
+      ".$1my-page {",
+      "  .marquee-scroller {",
+      "    --marquee-scroller-fade-width: ;",
+      "    --marquee-scroller-focus-outline-width: ;",
+      "    --marquee-scroller-focus-outline-offset: ;",
+      "    --marquee-scroller-item-border-colour: ;",
+      "    --marquee-scroller-item-border-width: ;",
+      "    --marquee-scroller-item-border-radius: ;",
+      "    --marquee-scroller-item-transition-duration: ;",
+      "    --marquee-scroller-group-hover-filter: ;",
+      "    --marquee-scroller-item-hover-filter: ;",
+      "    --marquee-scroller-control-offset: ;",
+      "    --marquee-scroller-control-background-colour: ;",
+      "    --marquee-scroller-control-background-colour-hover: ;",
+      "    --marquee-scroller-control-text-colour: ;",
+      "    --marquee-scroller-control-border-radius: ;",
+      "    --marquee-scroller-control-border-width: ;",
+      "    --marquee-scroller-control-padding: ;",
+      "    --marquee-scroller-control-font-size: ;",
+      "  }",
+      "}"
+    ]
+  }
+}

package/.vscode/srcdev-component-masonry-grid.code-snippets

@@ -0,0 +1,51 @@
+{
+  "SRCDEV MasonryGrid Basic": {
+    "description": "Basic MasonryGrid with a few named item slots",
+    "scope": "vue,html",
+    "body": [
+      "<MasonryGrid :item-min-width=\"$1300\" :gap=\"$212\">",
+      "  <template #item-1>",
+      "    $3",
+      "  </template>",
+      "  <template #item-2>",
+      "    $4",
+      "  </template>",
+      "</MasonryGrid>"
+    ]
+  },
+  "SRCDEV MasonryGrid Looped": {
+    "description": "MasonryGrid rendering a v-for list via dynamic slot names (no count prop needed)",
+    "scope": "vue,html",
+    "body": [
+      "<MasonryGrid :item-min-width=\"$1280\" :gap=\"$216\">",
+      "  <template v-for=\"($3item, $4index) in $5items\" :key=\"$3item.id\" #[`item-${$4index}`]>",
+      "    $6",
+      "  </template>",
+      "</MasonryGrid>"
+    ]
+  },
+  "SRCDEV MasonryGrid Fixed Width Centered": {
+    "description": "MasonryGrid with fixed-width tiles centered in the wrapper",
+    "scope": "vue,html",
+    "body": [
+      "<MasonryGrid :fixed-width=\"true\" justify=\"center\" :item-min-width=\"$1240\" :gap=\"$212\">",
+      "  <template v-for=\"($3item, $4index) in $5items\" :key=\"$3item.id\" #[`item-${$4index}`]>",
+      "    $6",
+      "  </template>",
+      "</MasonryGrid>"
+    ]
+  },
+  "SRCDEV MasonryGrid CSS Override": {
+    "description": "CSS override scaffold for MasonryGrid tokens",
+    "scope": "css",
+    "body": [
+      ".$1my-page {",
+      "  .masonry-grid-wrapper {",
+      "    --masonry-grid-item-border-colour: $2;",
+      "    --masonry-grid-item-padding: $3;",
+      "    --masonry-grid-transition-duration: $4;",
+      "  }",
+      "}"
+    ]
+  }
+}

package/.vscode/srcdev-component-pop-over.code-snippets

@@ -0,0 +1,44 @@
+{
+  "SRCDEV PopOver Basic": {
+    "description": "PopOver — generic anchor-positioned disclosure panel",
+    "scope": "vue,html",
+    "body": [
+      "<PopOver>",
+      "  <template #trigger>",
+      "    <span>$1</span>",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$0</p>",
+      "  </template>",
+      "</PopOver>"
+    ]
+  },
+  "SRCDEV PopOver Placement": {
+    "description": "PopOver with an explicit placement",
+    "scope": "vue,html",
+    "body": [
+      "<PopOver placement=\"${1|top,right,bottom,left|}\">",
+      "  <template #trigger>",
+      "    <span>$2</span>",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$0</p>",
+      "  </template>",
+      "</PopOver>"
+    ]
+  },
+  "SRCDEV PopOver Icon Trigger": {
+    "description": "PopOver with an icon-only trigger and localised labels",
+    "scope": "vue,html",
+    "body": [
+      "<PopOver trigger-aria-label=\"${1:Show more}\" popover-aria-label=\"${2:More information}\">",
+      "  <template #trigger>",
+      "    <Icon name=\"${3:lucide:info}\" aria-hidden=\"true\" />",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$0</p>",
+      "  </template>",
+      "</PopOver>"
+    ]
+  }
+}

package/.vscode/srcdev-component-responsive-header.code-snippets

@@ -15,6 +15,18 @@
       "</ResponsiveHeader>"
     ]
   },
+  "SRCDEV ResponsiveHeader Localised Nav Labels": {
+    "description": "ResponsiveHeader with localised aria-labels on the main/secondary nav landmarks and overflow menu",
+    "scope": "vue,html",
+    "body": [
+      "<ResponsiveHeader",
+      "  :responsive-nav-links=\"$1responsiveNavLinks\"",
+      "  main-nav-aria-label=\"${2:Main navigation}\"",
+      "  secondary-nav-aria-label=\"${3:Secondary navigation}\"",
+      "  overflow-menu-aria-label=\"${4:Overflow navigation menu}\"",
+      "/>"
+    ]
+  },
   "SRCDEV ResponsiveHeader Nav Data (with dropdown)": {
     "description": "responsiveNavLinks data with a dropdown group",
     "scope": "typescript,vue",

package/.vscode/srcdev-component-site-header.code-snippets

@@ -30,6 +30,23 @@
       "</SiteHeader>"
     ]
   },
+  "SRCDEV SiteHeader Localised Nav Labels": {
+    "description": "SiteHeader with localised aria-labels on all its nav landmarks (home, main, secondary, overflow)",
+    "scope": "vue,html",
+    "body": [
+      "<SiteHeader",
+      "  :responsive-nav-links=\"$1responsiveNavLinks\"",
+      "  home-nav-aria-label=\"${2:Home Navigation}\"",
+      "  main-nav-aria-label=\"${3:Main navigation}\"",
+      "  secondary-nav-aria-label=\"${4:Secondary navigation}\"",
+      "  overflow-menu-aria-label=\"${5:Overflow navigation menu}\"",
+      ">",
+      "  <template #branding>",
+      "    <NuxtLink to=\"/\" class=\"home-link\">$6Brand</NuxtLink>",
+      "  </template>",
+      "</SiteHeader>"
+    ]
+  },
   "SRCDEV SiteHeader Nav Data (flat)": {
     "description": "Simple flat responsiveNavLinks data with no dropdowns, for a few-page site",
     "scope": "typescript,vue",

package/.vscode/srcdev-component-site-navigation.code-snippets

@@ -0,0 +1,30 @@
+{
+  "SRCDEV SiteNavigation Basic": {
+    "description": "SiteNavigation horizontal nav with sliding active/hover indicator",
+    "scope": "vue,html",
+    "body": [
+      "<SiteNavigation :nav-item-data=\"$1navData\" nav-align=\"${2:left}\" />"
+    ]
+  },
+  "SRCDEV SiteNavigation Localised": {
+    "description": "SiteNavigation with a localised aria-label",
+    "scope": "vue,html",
+    "body": [
+      "<SiteNavigation :nav-item-data=\"$1navData\" aria-label=\"${2:Site navigation}\" />"
+    ]
+  },
+  "SRCDEV SiteNavigation Nav Data Script": {
+    "description": "navItemData for SiteNavigation",
+    "scope": "typescript,vue",
+    "body": [
+      "import type { NavItemData } from \"srcdev-nuxt-components\";",
+      "",
+      "const $1navData: NavItemData = {",
+      "  main: [",
+      "    { text: \"$2Home\", href: \"$3/\" },",
+      "    { text: \"$4About\", href: \"$5/about\" },",
+      "  ],",
+      "};"
+    ]
+  }
+}

package/.vscode/srcdev-component-slider-gallery.code-snippets

@@ -0,0 +1,38 @@
+{
+  "SRCDEV SliderGallery Basic": {
+    "description": "SliderGallery full-screen image slider with thumbnails and prev/next arrows",
+    "scope": "vue,html",
+    "body": [
+      "<SliderGallery v-model:gallery-data=\"$1galleryData\" />"
+    ]
+  },
+  "SRCDEV SliderGallery Localised": {
+    "description": "SliderGallery with localised loading/CTA/arrow copy",
+    "scope": "vue,html",
+    "body": [
+      "<SliderGallery",
+      "  v-model:gallery-data=\"$1galleryData\"",
+      "  loading-text=\"${2:Loading gallery...}\"",
+      "  see-more-text=\"${3:SEE MORE}\"",
+      "  prev-aria-label=\"${4:Previous image}\"",
+      "  next-aria-label=\"${5:Next image}\"",
+      "/>"
+    ]
+  },
+  "SRCDEV SliderGallery Data Script": {
+    "description": "galleryData ref for SliderGallery",
+    "scope": "typescript,vue",
+    "body": [
+      "import type { IGalleryData } from \"srcdev-nuxt-components\";",
+      "",
+      "const $1galleryData = ref<IGalleryData[]>([",
+      "  {",
+      "    src: \"$2/images/slide-1.jpg\",",
+      "    alt: \"$3\",",
+      "    title: \"$4\",",
+      "    textBrightness: \"${5:light}\",",
+      "  },",
+      "]);"
+    ]
+  }
+}

package/.vscode/srcdev-component-tab-navigation.code-snippets

@@ -0,0 +1,30 @@
+{
+  "SRCDEV TabNavigation Basic": {
+    "description": "TabNavigation with route/hash links",
+    "scope": "vue,html",
+    "body": [
+      "<TabNavigation :nav-item-data=\"$1navData\" nav-align=\"${2:center}\" />"
+    ]
+  },
+  "SRCDEV TabNavigation Localised": {
+    "description": "TabNavigation with a localised aria-label",
+    "scope": "vue,html",
+    "body": [
+      "<TabNavigation :nav-item-data=\"$1navData\" aria-label=\"${2:Site navigation}\" />"
+    ]
+  },
+  "SRCDEV TabNavigation Nav Data Script": {
+    "description": "navItemData for TabNavigation",
+    "scope": "typescript,vue",
+    "body": [
+      "import type { NavItemData } from \"srcdev-nuxt-components\";",
+      "",
+      "const $1navData: NavItemData = {",
+      "  main: [",
+      "    { text: \"$2Home\", href: \"$3/\" },",
+      "    { text: \"$4Overview\", href: \"$5#overview\" },",
+      "  ],",
+      "};"
+    ]
+  }
+}

package/app/components/01.atoms/animations/entry/EntryAnimation.vue

@@ -8,15 +8,21 @@
 interface Props {
   tag?: "div" | "section" | "article" | "aside";
   animationType?: "entry-slide-in" | "entry-zoom-reveal" | "entry-exit-blur";
+  /** Renders as a plain element with no animation class — e.g. the first item in a looped list
+   * that's already above the fold, where an entry animation would just delay visible content. */
+  skipAnimation?: boolean;
   styleClassPassthrough?: string | string[];
 }
 const props = withDefaults(defineProps<Props>(), {
   tag: "div",
   animationType: "entry-slide-in",
+  skipAnimation: false,
   styleClassPassthrough: () => [],
 });
 
 const { elementClasses, updateElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
-updateElementClasses(props.animationType);
+if (!props.skipAnimation) {
+  updateElementClasses(props.animationType);
+}
 </script>

package/app/components/01.atoms/animations/entry/stories/EntryAnimation.stories.ts

@@ -17,6 +17,12 @@ const meta: Meta<typeof EntryAnimation> = {
       description: "Type of entry animation",
       defaultValue: "entry-slide-in",
     },
+    skipAnimation: {
+      control: { type: "boolean" },
+      description:
+        "Render as a plain element with no animation class — e.g. the first item in a looped list that's already above the fold",
+      defaultValue: false,
+    },
     styleClassPassthrough: {
       control: { type: "text" },
       description: "Additional classes for styling",
@@ -72,3 +78,44 @@ export const EntryExitBlur: StoryObj<typeof EntryAnimation> = {
   },
   render: EntrySlideIn.render,
 };
+
+export const SkippedInALoop: StoryObj<typeof EntryAnimation> = {
+  name: "Skip first item (looped list, above the fold)",
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The common `v-for` case: the first item is already above the fold, so animating it in " +
+          "would just delay content the visitor can already see. Pass `skip-animation` for that one " +
+          "item instead of swapping the whole component out for a plain tag.",
+      },
+    },
+  },
+  render: () => ({
+    components: { EntryAnimation },
+    setup() {
+      const items = [0, 1, 2];
+      return { items };
+    },
+    template: `
+      <div style="padding-block: 400px; background-color: green; margin-bottom: 1000px;">
+        <label style="display: block; font-weight: bold; margin-bottom: 1rem; color: #fff;">
+          Item 0 renders immediately (skip-animation) — scroll to see items 1 and 2 animate in
+        </label>
+        <div
+          v-for="index in items"
+          :key="index"
+          style="margin-bottom: 2rem;"
+        >
+          <EntryAnimation :skip-animation="index === 0" animation-type="entry-slide-in">
+            <template #default>
+              <div style="padding: 2rem; background: #f0f0f0; border-radius: 8px;">
+                Item {{ index }} {{ index === 0 ? '(skipped)' : '(animated)' }}
+              </div>
+            </template>
+          </EntryAnimation>
+        </div>
+      </div>
+    `,
+  }),
+};

package/app/components/01.atoms/animations/entry/tests/EntryAnimation.spec.ts

@@ -0,0 +1,57 @@
+// https://nuxt.com/docs/getting-started/testing#unit-testing
+import type { VueWrapper } from "@vue/test-utils";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ComponentUnderTest from "../EntryAnimation.vue";
+
+let wrapper: VueWrapper<InstanceType<typeof ComponentUnderTest>>;
+const wrapperFactory = (propsData = {}, slotsData = {}) => {
+  return mountSuspended(ComponentUnderTest, {
+    attachTo: document.body,
+    props: propsData,
+    slots: {
+      default: () => "Content",
+      ...slotsData,
+    },
+  });
+};
+
+describe("EntryAnimation", () => {
+  it("mounts without error", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders the given tag", async () => {
+    wrapper = await wrapperFactory({ tag: "section" });
+    expect(wrapper.element.tagName).toBe("SECTION");
+  });
+
+  it("applies the default animation class", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.classes()).toContain("entry-slide-in");
+  });
+
+  it("applies the requested animationType class", async () => {
+    wrapper = await wrapperFactory({ animationType: "entry-zoom-reveal" });
+    expect(wrapper.classes()).toContain("entry-zoom-reveal");
+    expect(wrapper.classes()).not.toContain("entry-slide-in");
+  });
+
+  it("applies no animation class when skipAnimation is true", async () => {
+    wrapper = await wrapperFactory({ skipAnimation: true });
+    expect(wrapper.classes()).not.toContain("entry-slide-in");
+    expect(wrapper.classes()).not.toContain("entry-zoom-reveal");
+    expect(wrapper.classes()).not.toContain("entry-exit-blur");
+  });
+
+  it("still applies styleClassPassthrough classes when skipAnimation is true", async () => {
+    wrapper = await wrapperFactory({ skipAnimation: true, styleClassPassthrough: ["custom-class"] });
+    expect(wrapper.classes()).toContain("custom-class");
+    expect(wrapper.classes()).not.toContain("entry-slide-in");
+  });
+
+  it("renders slot content", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.text()).toContain("Content");
+  });
+});

package/app/components/01.atoms/animations/marquee-scroller/CONSUMER-STYLING.md

@@ -0,0 +1,94 @@
+# MarqueeScroller — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--marquee-scroller-fade-width` | `10%` | Width of the transparent fade at each edge of the track (`mask-image`) |
+| `--marquee-scroller-focus-outline-width` | `2px` | Outline width on the root region and the control button when keyboard-focused (colour is `--theme-ring`) |
+| `--marquee-scroller-focus-outline-offset` | `2px` | Outline offset on the same two focus states |
+| `--marquee-scroller-group-hover-filter` | `grayscale(1)` | Filter applied to every item when the pointer hovers anywhere over the scroller |
+| `--marquee-scroller-item-hover-filter` | `grayscale(0)` | Filter applied to a single item when it is individually hovered (overrides the group filter for that item) |
+| `--marquee-scroller-item-transition-duration` | `0.5s` | Transition duration for the item hover filter change |
+| `--marquee-scroller-item-border-width` | `1px` | Item border width |
+| `--marquee-scroller-item-border-colour` | `light-dark(var(--slate-10), var(--slate-00))` | Item border colour |
+| `--marquee-scroller-item-border-radius` | `4px` | Item border radius |
+| `--marquee-scroller-control-offset` | `8px` | Distance of the pause/play button from the top and end edges |
+| `--marquee-scroller-control-background-colour` | `rgba(0, 0, 0, 0.7)` | Pause/play button background |
+| `--marquee-scroller-control-background-colour-hover` | `rgba(0, 0, 0, 0.9)` | Pause/play button background on hover |
+| `--marquee-scroller-control-text-colour` | `white` | Pause/play button icon colour |
+| `--marquee-scroller-control-border-radius` | `4px` | Pause/play button border radius |
+| `--marquee-scroller-control-padding` | `8px` | Pause/play button padding |
+| `--marquee-scroller-control-font-size` | `14px` | Pause/play button icon font size |
+| `--marquee-scroller-control-transition-duration` | `0.2s` | Pause/play button background-colour transition duration |
+| `--marquee-scroller-control-border-width` | `1px` | Pause/play button border width in forced-colors/high-contrast mode (`prefers-contrast: high`). The border colour itself stays the system `ButtonText` keyword — see note below. |
+
+```css
+.my-page {
+  --marquee-scroller-item-border-colour: #b5651d;
+  --marquee-scroller-control-background-colour: #1a1a1a;
+  --marquee-scroller-fade-width: 20%;
+}
+```
+
+## High-contrast mode colours are not tokenised
+
+Under `prefers-contrast: high`, the control button switches to the system colour keywords
+`ButtonFace`/`ButtonText` rather than the component's own background/text tokens. These aren't
+exposed as overridable tokens on purpose — they're meant to track the user's OS-level high-contrast
+theme, which a component-level override would defeat. Only the border *width* in that mode is a
+token (`--marquee-scroller-control-border-width`), since it's a plain dimension with no such
+constraint.
+
+## Item size and spacing are prop-driven, not tokens
+
+Item `width`/`height`/`gap` and the animation duration are set via the `itemConfig` and
+`animationRuntime` props (not CSS custom properties), since they also drive the component's own
+layout math (`aspect-ratio`, track width). Override those through props:
+
+```vue
+<MarqueeScroller
+  :item-config="{ width: '80px', height: '80px', gap: '24px' }"
+  animation-runtime="60s"
+/>
+```
+
+## Item content via slots
+
+Each entry in `marqueeData` (`{ id, content }`) renders a slot named after its `id`. Provide the
+markup for each item via that dynamically-named slot:
+
+```vue
+<MarqueeScroller :marquee-data="[{ id: 1, content: 'logo-a' }, { id: 2, content: 'logo-b' }]">
+  <template #1>
+    <img src="/logos/a.svg" alt="Logo A" />
+  </template>
+  <template #2>
+    <img src="/logos/b.svg" alt="Logo B" />
+  </template>
+</MarqueeScroller>
+```
+
+## Control button icon and copy
+
+The pause/play button's icon and its `aria-label` copy are all overridable — see `playIcon`/
+`pauseIcon`/`playLabel`/`pauseLabel` props, or the `toggle-icon` slot for a fully custom icon
+(scoped with `isPaused`):
+
+```vue
+<MarqueeScroller
+  show-controls
+  play-icon="mdi:play-circle"
+  pause-icon="mdi:pause-circle"
+  play-label="Reproduire"
+  pause-label="Suspendre"
+/>
+```
+
+```vue
+<MarqueeScroller show-controls>
+  <template #toggle-icon="{ isPaused }">
+    <Icon :name="isPaused ? 'lucide:play' : 'lucide:pause'" />
+  </template>
+</MarqueeScroller>
+```