srcdev-nuxt-components 9.0.15 → 9.0.17

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

@@ -174,6 +174,66 @@ template: `
 This keeps the ID wiring self-contained inside the component — the parent story just
 consumes what the slot exposes, rather than generating its own ID.
 
+### Extra controls that are not component props
+
+Use when you want a Storybook control that sets something other than a component prop — e.g. a CSS custom property toggle.
+
+`Meta<typeof Component>` is strict: its `argTypes`/`args` keys must match the component's actual props. Adding extras causes a TypeScript error. The fix is a `StoryArgs` type that covers both:
+
+```ts
+import { computed } from "vue"; // ← must be explicit in .ts files (not auto-imported)
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import ComponentName from "../ComponentName.vue";
+
+type StoryArgs = {
+  // mirror the component props you want controls for
+  tag?: "div" | "section";
+  // plus any extras
+  headerBackground?: string;
+};
+
+const meta: Meta<StoryArgs> = {  // ← StoryArgs, not typeof ComponentName
+  title: "...",
+  component: ComponentName,
+  argTypes: {
+    headerBackground: { control: "color", description: "Sets --my-header-bg" },
+  },
+  args: { headerBackground: "" },
+};
+
+export default meta;
+type Story = StoryObj<typeof ComponentName>; // ← still strict for individual stories
+```
+
+Strip extra args before `v-bind` using a `useStorySetup` helper in `setup()`:
+
+```ts
+function useStorySetup(args: StoryArgs) {
+  const bgStyles = computed(() => ({
+    ...(args.headerBackground ? { "--my-header-bg": args.headerBackground } : {}),
+  }));
+  const componentArgs = computed(() => {
+    const { headerBackground: _h, ...rest } = args;
+    return rest;
+  });
+  return { bgStyles, componentArgs };
+}
+
+export const Default: Story = {
+  render: (args: StoryArgs) => ({
+    components: { ComponentName },
+    setup() { return useStorySetup(args); },
+    template: `<ComponentName v-bind="componentArgs" :style="bgStyles" />`,
+  }),
+};
+```
+
+Key points:
+
+- `computed` is **not** auto-imported in `.ts` story files — import it explicitly from `"vue"`.
+- Extra args must be stripped before `v-bind` — spreading unknown keys onto a component makes them unknown HTML attributes.
+- CSS custom properties set via `:style` on the component root are picked up by `var()` in the component's scoped CSS.
+
 ## Notes
 
 - Use `table: { category: "..." }` in `argTypes` when a component has many props — it groups

package/.claude/skills/testing-add-unit-test.md

@@ -165,6 +165,34 @@ it("exposes headingId via scoped slot", async () => {
 - Always `afterEach(() => wrapper?.unmount())` to prevent test leaks.
 - Use a `createWrapper` helper to keep individual tests short.
 - Include at least one snapshot test per meaningful visual state.
+- `nextTick` is **not** auto-imported in test files — always import it explicitly: `import { nextTick } from "vue"`.
+
+## Fake timers
+
+`vitest.setup.ts` calls `vi.useFakeTimers()` globally and resets in `afterEach`. **Never** call `vi.useFakeTimers()`, `vi.useRealTimers()`, or `vi.runAllTimers()` inside a test file — it conflicts with the global setup and can cause infinite loops or bleed between tests.
+
+Use `vi.advanceTimersByTime(ms)` to move time forward by a specific amount. Avoid `vi.runAllTimers()` — it fires all queued timers including any that re-queue themselves, which loops infinitely.
+
+```ts
+// ✅
+vi.advanceTimersByTime(500);
+await nextTick();
+
+// ❌ — can loop infinitely if a timer re-queues itself
+vi.runAllTimers();
+```
+
+## Hyphenated prop attributes in tests
+
+When a component uses a hyphenated Vue prop like `:tab-index` or `:aria-label`, Vue renders it as the literal hyphenated DOM attribute. Assert with the hyphenated form — not the camelCase equivalent:
+
+```ts
+// ✅ — prop :tab-index renders as the DOM attribute "tab-index"
+expect(wrapper.find(".el").attributes("tab-index")).toBe("2");
+
+// ❌ — "tabindex" won't match
+expect(wrapper.find(".el").attributes("tabindex")).toBe("2");
+```
 
 ## Snapshot testing
 
@@ -195,6 +223,34 @@ const style = (el.element as HTMLElement).style;
 expect(style.getPropertyValue("--custom-prop")).toBe("expected-value");
 ```
 
+**`v-bind()` in CSS — root component only.** Vue's `v-bind(propName)` in a component's `<style>` block sets `--v-bind-propName` on that component's root element in JSDOM. This only works when the component under test **is** the root wrapper. When the component is rendered as a **child** inside a parent, JSDOM does not apply those inline styles — `getPropertyValue` returns `""`.
+
+```ts
+// ❌ Won't work — StepperList is a child; JSDOM doesn't apply its v-bind() styles
+const list = wrapper.find(".stepper-list");
+expect((list.element as HTMLElement).style.getPropertyValue("--v-bind-indicatorSize")).toBe("4rem");
+
+// ✅ Use findComponent + props() to test prop pass-through to a child component
+expect(wrapper.findComponent(StepperList).props("indicatorSize")).toBe("4rem");
+```
+
+## Testing prop pass-through to child components
+
+When a parent component forwards a prop to a child, use `findComponent` + `.props()` rather than inspecting the DOM:
+
+```ts
+import ChildComponent from "../../child/ChildComponent.vue";
+
+it("passes myProp to ChildComponent", async () => {
+  const wrapper = await mountSuspended(ParentComponent, {
+    props: { myProp: "value" },
+  });
+  expect(wrapper.findComponent(ChildComponent).props("myProp")).toBe("value");
+});
+```
+
+Import the child component directly in the test file — it is not auto-imported there.
+
 ## Mocking browser APIs
 
 Mock before the `describe` block if the component uses ResizeObserver, IntersectionObserver, etc.:

package/app/assets/styles/setup/01.config/index.css

@@ -1,3 +1,2 @@
 @import "./_normalise";
-@import "./_basic-resets";
 @import "./_head";

package/app/assets/styles/setup/03.theming/default/_dark.css

@@ -78,8 +78,8 @@
   /* ===========================================
      ANCHOR LINK VARIABLES
      =========================================== */
-  --colour-link-default: var(--blue-10);
-  --colour-link-hover: var(--blue-09);
+  --colour-link-default: var(--blue-02);
+  --colour-link-hover: var(--blue-03);
 
   /* ===========================================
      FORM INPUT VARIABLES

package/app/assets/styles/setup/04.elements/forms/02.typography.css

@@ -13,6 +13,7 @@
   --button-font-size: 1.6rem; /* 16px */
   --button-line-height: 1.4;
   --button-font-weight: 600;
+  --button-text-transform: none;
 
   /* Description */
   --field-description-font-size: 1.3rem;

package/app/assets/styles/setup/05.typography/02.utility-classes/_font-classes-page-link.css

@@ -1,5 +1,5 @@
 .page-link-large {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-6);
   font-weight: 400;
   font-variation-settings: "wght" 400;
@@ -8,7 +8,7 @@
 }
 
 .page-link-large-semibold {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-6);
   font-weight: 600;
   font-variation-settings: "wght" 600;
@@ -17,7 +17,7 @@
 }
 
 .page-link-medium {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-5);
   font-weight: 400;
   font-variation-settings: "wght" 400;
@@ -26,7 +26,7 @@
 }
 
 .page-link-medium-semibold {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-5);
   font-weight: 600;
   font-variation-settings: "wght" 600;
@@ -35,7 +35,7 @@
 }
 
 .page-link-normal {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-4);
   font-weight: 400;
   font-variation-settings: "wght" 400;
@@ -44,7 +44,7 @@
 }
 
 .page-link-normal-semibold {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-4);
   font-weight: 600;
   font-variation-settings: "wght" 600;
@@ -53,7 +53,7 @@
 }
 
 .page-link-small {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-3);
   font-weight: 400;
   font-variation-settings: "wght" 400;
@@ -62,7 +62,7 @@
 }
 
 .page-link-small-semibold {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-3);
   font-weight: 600;
   font-variation-settings: "wght" 600;
@@ -71,7 +71,7 @@
 }
 
 .page-link-xsmall {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-2);
   font-weight: 400;
   font-variation-settings: "wght" 400;
@@ -80,7 +80,7 @@
 }
 
 .page-link-xsmall-semibold {
-  color: var(--theme-link-default);
+  color: var(--colour-link-default);
   font-size: var(--step-2);
   font-weight: 600;
   font-variation-settings: "wght" 600;
@@ -100,16 +100,16 @@
 .page-link-xsmall-semibold {
   margin: 0;
   &:visited {
-    color: var(--theme-link-default);
+    color: var(--colour-link-default);
   }
 
   &:hover {
-    color: var(--theme-link-hover);
+    color: var(--colour-link-hover);
   }
 
   &:focus-visible {
-    color: var(--theme-link-hover);
-    outline: 2px solid var(--theme-link-default);
+    color: var(--colour-link-hover);
+    outline: 2px solid var(--colour-link-default);
     outline-offset: 3px;
     border-radius: 4px;
   }

package/app/assets/styles/setup/index.css

@@ -1,4 +1,3 @@
-/* @layer reset, colours, theming, form-tokens, typography, a11y, utilities, components; */
 @layer reset, colours, theming, form-tokens, typography, a11y, components, utilities;
 
 @import "./01.config/" layer(reset);

package/app/components/01.atoms/card/CardCore.vue

@@ -0,0 +1,92 @@
+<template>
+  <component
+    :is="tag"
+    class="card-core"
+    :class="[variant, elementClasses, { 'has-dividers': hasDividers }, { 'no-outline': noOutline }]"
+  >
+    <template v-for="(_, name) in $slots" :key="name">
+      <div class="card-row" :class="`card-row-${name}`">
+        <slot :name="name"></slot>
+      </div>
+    </template>
+  </component>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  tag?: "div" | "section" | "article" | "aside" | "main" | "nav";
+  hasDividers?: boolean;
+  noOutline?: boolean;
+  variant?: "solid" | "subtle" | "soft" | "outline";
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  hasDividers: false,
+  noOutline: false,
+  variant: "solid",
+  styleClassPassthrough: () => [],
+});
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .card-core {
+    --_inner-padding: 1rem;
+    --_background-color: white;
+    --_border-color: green;
+    --_border-width: 0.2rem;
+    --_box-shadow-color: transparent;
+
+    display: grid;
+    grid-auto-flow: row;
+    /* gap: 1rem; */
+    border-radius: 0.5rem;
+    overflow: hidden;
+
+    background-color: var(--_background-color, transparent);
+    border: var(--_border-width) solid var(--_border-color, transparent);
+    box-shadow: 0 0 0.4rem var(--_border-width) var(--_box-shadow-color, transparent);
+
+    &.no-outline {
+      --_border-width: 0;
+    }
+
+    &.solid {
+      --_background-color: light-dark(var(--slate-00), var(--slate-10));
+      --_border-color: red;
+    }
+
+    &.subtle {
+      --_background-color: color-mix(in oklab, light-dark(var(--slate-01), var(--slate-08)) 50%, transparent);
+      --_border-color: red;
+    }
+
+    &.soft {
+      --_background-color: color-mix(in oklab, light-dark(var(--slate-01), var(--slate-08)) 20%, transparent);
+      --_box-shadow-color: color-mix(in oklab, light-dark(var(--slate-02), var(--slate-08)) 80%, transparent);
+    }
+
+    &.outline {
+      --_background-color: transparent;
+      --_border-color: green;
+    }
+
+    &.has-dividers {
+      .card-row + .card-row {
+        /* border-top: 0.2rem solid var(--_border-color); */
+        border-top: 0.2rem solid green;
+      }
+    }
+  }
+}
+</style>

package/app/components/01.atoms/card/stories/CardCore.stories.ts

@@ -0,0 +1,132 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import StorybookComponent from "../CardCore.vue";
+
+interface CardCoreArgs {
+  tag: "div" | "section" | "article" | "aside" | "main" | "nav";
+  variant: "solid" | "subtle" | "soft" | "outline";
+  hasDividers: boolean;
+  noOutline: boolean;
+  styleClassPassthrough: string[];
+}
+
+export default {
+  title: "Atoms/Card/Card Core Dynamic",
+  component: StorybookComponent,
+  argTypes: {
+    tag: {
+      control: { type: "select" },
+      options: ["div", "section", "article", "aside", "main", "nav"],
+      description: "HTML tag to render",
+      table: { category: "Semantic" },
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["solid", "subtle", "soft", "outline"],
+      description: "Visual style variant",
+      table: { category: "Appearance" },
+    },
+    hasDividers: {
+      control: { type: "boolean" },
+      description: "Add dividers between slot sections",
+      table: { category: "Appearance" },
+    },
+    noOutline: {
+      control: { type: "boolean" },
+      description: "Remove border outline",
+      table: { category: "Appearance" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  args: {
+    tag: "div",
+    variant: "solid",
+    hasDividers: false,
+    noOutline: false,
+    styleClassPassthrough: [],
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A dynamic display card that renders whatever named slots are provided. Any number of slots can be passed and each is wrapped in its own div.",
+      },
+    },
+  },
+} as Meta<CardCoreArgs>;
+
+const Template: StoryFn<CardCoreArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    return { args };
+  },
+  template: `
+    <div style="padding: 40px; max-width: 480px;">
+      <StorybookComponent
+        :tag="args.tag"
+        :variant="args.variant"
+        :has-dividers="args.hasDividers"
+        :no-outline="args.noOutline"
+        :style-class-passthrough="args.styleClassPassthrough"
+      >
+        <template #header>
+          <div style="padding: 1.6rem; border-bottom: 1px solid transparent;">
+            <p style="margin: 0; font-size: 1.2rem; text-transform: uppercase; letter-spacing: 0.08em; opacity: 0.6;">Category</p>
+            <h2 style="margin: 0.4rem 0 0; font-size: 2rem; font-weight: 600;">Card Title</h2>
+          </div>
+        </template>
+        <template #media>
+          <div style="aspect-ratio: 16/9; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); display: flex; align-items: center; justify-content: center; color: white; font-size: 1.4rem;">
+            Media Slot
+          </div>
+        </template>
+        <template #body>
+          <div style="padding: 1.6rem;">
+            <p style="margin: 0; line-height: 1.6; opacity: 0.8;">
+              This is the body content. It can contain any markup — paragraphs, lists, or other components.
+            </p>
+          </div>
+        </template>
+        <template #footer>
+          <div style="padding: 1.2rem 1.6rem; display: flex; gap: 0.8rem; justify-content: flex-end;">
+            <button style="padding: 0.8rem 1.6rem; border-radius: 0.4rem; border: 1px solid currentColor; background: transparent; cursor: pointer; opacity: 0.7;">Cancel</button>
+            <button style="padding: 0.8rem 1.6rem; border-radius: 0.4rem; border: none; background: #667eea; color: white; cursor: pointer;">Confirm</button>
+          </div>
+        </template>
+      </StorybookComponent>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+Default.args = {};
+
+export const Subtle = Template.bind({});
+Subtle.args = { variant: "subtle" };
+
+export const Soft = Template.bind({});
+Soft.args = { variant: "soft" };
+
+export const Outline = Template.bind({});
+Outline.args = { variant: "outline" };
+
+export const WithDividers = Template.bind({});
+WithDividers.args = { hasDividers: true };
+WithDividers.parameters = {
+  docs: {
+    description: {
+      story: "Adds visual dividers between each slot section.",
+    },
+  },
+};
+
+export const NoOutline = Template.bind({});
+NoOutline.args = { noOutline: true };
+NoOutline.parameters = {
+  docs: {
+    description: {
+      story: "Card without a border or box shadow.",
+    },
+  },
+};