srcdev-nuxt-components 9.4.6 → 9.4.7

package/.vscode/srcdev-component-column-flow-grid.code-snippets

@@ -0,0 +1,39 @@
+{
+  "SRCDEV ColumnFlowGrid Basic": {
+    "description": "Basic ColumnFlowGrid with a few named item slots",
+    "scope": "vue,html",
+    "body": [
+      "<ColumnFlowGrid :item-min-width=\"$1300\" :gap=\"$21.2\">",
+      "  <template #item-1>",
+      "    $3",
+      "  </template>",
+      "  <template #item-2>",
+      "    $4",
+      "  </template>",
+      "</ColumnFlowGrid>"
+    ]
+  },
+  "SRCDEV ColumnFlowGrid Looped": {
+    "description": "ColumnFlowGrid rendering a v-for list via dynamic slot names (no count prop needed)",
+    "scope": "vue,html",
+    "body": [
+      "<ColumnFlowGrid :item-min-width=\"$1280\" :gap=\"$21.6\">",
+      "  <template v-for=\"($3item, $4index) in $5items\" :key=\"$3item.id\" #[`item-${$4index}`]>",
+      "    $6",
+      "  </template>",
+      "</ColumnFlowGrid>"
+    ]
+  },
+  "SRCDEV ColumnFlowGrid CSS Override": {
+    "description": "CSS override scaffold for ColumnFlowGrid tokens",
+    "scope": "css",
+    "body": [
+      ".$1my-page {",
+      "  .column-flow-grid-wrapper {",
+      "    --column-flow-grid-item-border-colour: $2;",
+      "    --column-flow-grid-item-padding: $3;",
+      "  }",
+      "}"
+    ]
+  }
+}

package/.vscode/srcdev-component-entry-animation.code-snippets

@@ -0,0 +1,29 @@
+{
+  "SRCDEV EntryAnimation Basic": {
+    "description": "Basic EntryAnimation wrapper with a default slide-in animation",
+    "scope": "vue,html",
+    "body": [
+      "<EntryAnimation animation-type=\"$1entry-slide-in\">",
+      "  <template #default>",
+      "    $2",
+      "  </template>",
+      "</EntryAnimation>"
+    ]
+  },
+  "SRCDEV EntryAnimation Looped, Skip First": {
+    "description": "EntryAnimation in a v-for loop, skipping the first (above-the-fold) item",
+    "scope": "vue,html",
+    "body": [
+      "<EntryAnimation",
+      "  v-for=\"($1item, $2index) in $3items\"",
+      "  :key=\"$1item.id\"",
+      "  :skip-animation=\"$2index === 0\"",
+      "  animation-type=\"$4entry-slide-in\"",
+      ">",
+      "  <template #default>",
+      "    $5",
+      "  </template>",
+      "</EntryAnimation>"
+    ]
+  }
+}

package/.vscode/srcdev-component-input-text.code-snippets

@@ -0,0 +1,107 @@
+{
+  "SRCDEV InputTextCore Basic": {
+    "description": "Basic InputTextCore native input (no label/error wrapper)",
+    "scope": "vue,html",
+    "body": [
+      "<InputTextCore",
+      "  id=\"$1fieldId\"",
+      "  name=\"$2fieldName\"",
+      "  v-model=\"$3fieldValue\"",
+      "  type=\"$4text\"",
+      "  placeholder=\"$5Enter value...\"",
+      "/>"
+    ]
+  },
+  "SRCDEV InputTextCore Date with min/max": {
+    "description": "InputTextCore date input constrained to a min/max range (e.g. no dates in the past)",
+    "scope": "vue,html",
+    "body": [
+      "<InputTextCore",
+      "  id=\"$1appointment-date\"",
+      "  name=\"$2appointmentDate\"",
+      "  v-model=\"$3appointmentDate\"",
+      "  type=\"date\"",
+      "  :min=\"new Date().toISOString().split('T')[0]\"",
+      "  max=\"$42027-12-31\"",
+      "/>"
+    ]
+  },
+  "SRCDEV InputTextWithLabel Basic": {
+    "description": "InputTextWithLabel: labelled text field with error/description support",
+    "scope": "vue,html",
+    "body": [
+      "<InputTextWithLabel",
+      "  v-model=\"$1fieldValue\"",
+      "  id=\"$2fieldId\"",
+      "  name=\"$3fieldName\"",
+      "  type=\"$4text\"",
+      "  label=\"$5Field label\"",
+      "  :error-message=\"$6errors.fieldName\"",
+      "  :field-has-error=\"!!$6errors.fieldName\"",
+      "/>"
+    ]
+  },
+  "SRCDEV InputTextWithLabel Date with min/max": {
+    "description": "InputTextWithLabel date field constrained to a min/max range",
+    "scope": "vue,html",
+    "body": [
+      "<InputTextWithLabel",
+      "  v-model=\"$1appointmentDate\"",
+      "  id=\"$2appointment-date\"",
+      "  name=\"$2appointmentDate\"",
+      "  type=\"date\"",
+      "  label=\"$3Appointment date\"",
+      "  :min=\"new Date().toISOString().split('T')[0]\"",
+      "  max=\"$42027-12-31\"",
+      "  :error-message=\"$5errors.appointmentDate\"",
+      "  :field-has-error=\"!!$5errors.appointmentDate\"",
+      "/>"
+    ]
+  },
+  "SRCDEV InputPasswordWithLabel": {
+    "description": "InputPasswordWithLabel with show/hide toggle",
+    "scope": "vue,html",
+    "body": [
+      "<InputPasswordWithLabel",
+      "  v-model=\"$1password\"",
+      "  name=\"$2password\"",
+      "  label=\"$3Password\"",
+      "  :error-message=\"$4errors.password\"",
+      "  :field-has-error=\"!!$4errors.password\"",
+      "/>"
+    ]
+  },
+  "SRCDEV InputTextAsNumberWithLabel": {
+    "description": "InputTextAsNumberWithLabel numeric stepper with min/max/step",
+    "scope": "vue,html",
+    "body": [
+      "<InputTextAsNumberWithLabel",
+      "  v-model=\"$1quantity\"",
+      "  name=\"$2quantity\"",
+      "  label=\"$3Quantity\"",
+      "  :min=\"$41\"",
+      "  :max=\"$599\"",
+      "  :step=\"$61\"",
+      "  :error-message=\"$7errors.quantity\"",
+      "  :field-has-error=\"!!$7errors.quantity\"",
+      ">",
+      "  <template #left>−</template>",
+      "  <template #right>+</template>",
+      "</InputTextAsNumberWithLabel>"
+    ]
+  },
+  "SRCDEV InputText CSS Override": {
+    "description": "CSS override scaffold for InputTextCore tokens",
+    "scope": "css",
+    "body": [
+      ".$1my-page {",
+      "  .input-text-wrapper {",
+      "    --input-text-surface: $2;",
+      "    --input-text-border: $3;",
+      "    --input-text-border-focus: $4;",
+      "    --input-text-color: $5;",
+      "  }",
+      "}"
+    ]
+  }
+}

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/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/canvas-switcher/stories/CanvasSwitcher.stories.ts

@@ -37,17 +37,18 @@ export default {
   },
 } as Meta<typeof CanvasSwitcher>;
 
+// `args` is Storybook's own reactive object — bind to it directly (`args.x`) rather than
+// destructuring it into local variables/refs, which would snapshot the values once at setup()
+// and stop reflecting later Controls-panel changes.
 const Template: StoryFn<CanvasSwitcherStoryArgs> = (args) => ({
   components: { CanvasSwitcher },
   setup() {
-    const { canvasName, ...otherArgs } = args;
-    const selected = ref(canvasName);
-    return { selected, args: otherArgs };
+    return { args };
   },
   template: `
     <div>
-      <CanvasSwitcher v-model:canvas-name="selected" v-bind="args" />
-      <p style="margin-top: 1.6rem;">Selected: {{ selected }}</p>
+      <CanvasSwitcher v-model:canvas-name="args.canvasName" v-bind="args" />
+      <p style="margin-top: 1.6rem;">Selected: {{ args.canvasName }}</p>
     </div>
   `,
 });
@@ -60,14 +61,12 @@ PreviewWidthDemo.args = {};
 PreviewWidthDemo.render = (args) => ({
   components: { CanvasSwitcher },
   setup() {
-    const { canvasName } = args;
-    const selected = ref(canvasName);
-    return { selected };
+    return { args };
   },
   template: `
     <div>
-      <CanvasSwitcher v-model:canvas-name="selected" />
-      <div :class="selected" style="border: 1px dashed currentColor; margin-top: 1.6rem; padding: 1.6rem;">
+      <CanvasSwitcher v-model:canvas-name="args.canvasName" />
+      <div :class="args.canvasName" 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/content-wrappers/docs-pages/stories/ContentDocs.stories.ts

@@ -1,4 +1,5 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { computed } from "vue";
 import ContentDocs from "../ContentDocs.vue";
 import type { DocsNavItem } from "~/types/components";
 
@@ -86,19 +87,19 @@ export default {
 
 // ─── Stories ─────────────────────────────────────────────────────────────────
 
+// `args` is Storybook's own reactive object — bind to it directly (`args.x`) rather than
+// destructuring it into local variables/refs, which would snapshot the values once at setup()
+// and stop reflecting later Controls-panel changes.
 const Template: StoryFn<ContentDocsStoryArgs> = (args) => ({
   components: { ContentDocs },
   setup() {
-    const { activeNavItem, activePageNavItem, ...rest } = args;
-    const activeNav = ref(activeNavItem);
-    const activePageNav = ref(activePageNavItem);
-    return { args: rest, activeNav, activePageNav };
+    return { args };
   },
   template: `
     <ContentDocs
       v-bind="args"
-      v-model:active-nav-item="activeNav"
-      v-model:active-page-nav-item="activePageNav"
+      v-model:active-nav-item="args.activeNavItem"
+      v-model:active-page-nav-item="args.activePageNavItem"
     >
       <template #docsContent>
         <h3 style="margin-top:0">Docs Content</h3>
@@ -140,10 +141,8 @@ CustomLabels.args = {
 export const IconAtEnd: StoryFn<ContentDocsStoryArgs> = (args) => ({
   components: { ContentDocs },
   setup() {
-    const { activeNavItem, activePageNavItem, ...rest } = args;
-    const activeNav = ref(activeNavItem);
-    const activePageNav = ref(activePageNavItem);
-    return { args: { ...rest, styleClassPassthrough: ["icon-at-end-demo"] }, activeNav, activePageNav };
+    const componentArgs = computed(() => ({ ...args, styleClassPassthrough: ["icon-at-end-demo"] }));
+    return { args, componentArgs };
   },
   template: `
     <div>
@@ -154,9 +153,9 @@ export const IconAtEnd: StoryFn<ContentDocsStoryArgs> = (args) => ({
         }
       </style>
       <ContentDocs
-        v-bind="args"
-        v-model:active-nav-item="activeNav"
-        v-model:active-page-nav-item="activePageNav"
+        v-bind="componentArgs"
+        v-model:active-nav-item="args.activeNavItem"
+        v-model:active-page-nav-item="args.activePageNavItem"
       >
         <template #docsContent>
           <h3 style="margin-top:0">Docs Content</h3>

package/app/components/01.atoms/grids/column-flow-grid/CONSUMER-STYLING.md

@@ -0,0 +1,33 @@
+# ColumnFlowGrid — Consumer Styling Guide
+
+## Public token API
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--column-flow-grid-item-border-colour` | `var(--theme-border)` | Outline colour around each item |
+| `--column-flow-grid-item-padding` | `1.2rem` | Inner padding of each item |
+
+Column width and gap are controlled via props (`item-min-width`, `gap`, `unit`), not CSS custom
+properties — they drive the CSS column layout directly and need JS-computed values, so they aren't
+part of the public token API. See `.claude/skills/components/column-flow-grid.md`.
+
+---
+
+## Global theming — app-level CSS file
+
+```css
+:where(html) {
+  --column-flow-grid-item-border-colour: var(--rose-05);
+  --column-flow-grid-item-padding: 1.6rem;
+}
+```
+
+---
+
+## Per-instance overrides
+
+```vue
+<ColumnFlowGrid style="--column-flow-grid-item-border-colour: var(--gold-04);">
+  ...
+</ColumnFlowGrid>
+```

package/app/components/01.atoms/grids/column-flow-grid/ColumnFlowGrid.vue

@@ -0,0 +1,55 @@
+<template>
+  <component
+    :is="tag"
+    class="column-flow-grid-wrapper"
+    :class="[elementClasses]"
+    :style="`--_column-flow-grid-gap: ${gap}${unit}; --_item-min-width: ${itemMinWidth}px`"
+  >
+    <div v-for="(_, name) in $slots" :key="name" class="column-flow-grid-item">
+      <slot :name="name"></slot>
+    </div>
+  </component>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  tag?: "div" | "section" | "article" | "main";
+  itemMinWidth?: number;
+  gap?: number;
+  unit?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  itemMinWidth: 300,
+  gap: 1.2,
+  unit: "rem",
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .column-flow-grid-wrapper {
+    columns: auto var(--_item-min-width);
+    column-gap: var(--_column-flow-grid-gap);
+
+    .column-flow-grid-item {
+      break-inside: avoid;
+      outline: 0.1rem solid var(--column-flow-grid-item-border-colour, var(--theme-border));
+      padding: var(--column-flow-grid-item-padding, 1.2rem);
+      margin-block-end: var(--_column-flow-grid-gap);
+    }
+  }
+}
+</style>