srcdev-nuxt-components 9.0.3 → 9.0.5

package/.claude/skills/testing-add-playwright.md

@@ -0,0 +1,167 @@
+# Adding a Playwright Visual Test
+
+## Overview
+
+Playwright tests run pixel-level screenshot comparisons against a running Storybook instance.
+Each test navigates to a story URL, locates the component element, and asserts it matches
+a stored PNG baseline.
+
+## Prerequisites
+
+Storybook must be running before Playwright tests can execute. Use `npm run storybook:serve`
+(build + serve static) for stable baselines, or `npm run storybook` (dev server) for quick
+iteration.
+
+## File location
+
+```url
+app/components/<component-folder>/playwright/<component-name>.playwright.ts
+```
+
+## Standard structure
+
+```ts
+import { test, expect, type Page } from "@playwright/test";
+
+// --- Config ---
+const STORYBOOK_URL = "http://127.0.0.1:6006";
+const STORY_BASE = "category-subcategory-componentname"; // see derivation below
+const ELEMENT_TIMEOUT = 15_000;
+
+// --- Helpers ---
+const getStoryUrl = (story: string, args: Record<string, string> = {}): string => {
+  const argsParam = Object.entries(args)
+    .map(([k, v]) => `${k}:${v}`)
+    .join(";");
+  const url = `${STORYBOOK_URL}/?path=/story/${STORY_BASE}--${story}`;
+  return argsParam ? `${url}&args=${argsParam}` : url;
+};
+
+const getElement = async (page: Page, story: string, args: Record<string, string> = {}) => {
+  await page.goto(getStoryUrl(story, args), { waitUntil: "load" });
+  const frame = page.frameLocator("#storybook-preview-iframe");
+  await frame.locator("#storybook-root > *").waitFor({ state: "visible", timeout: ELEMENT_TIMEOUT });
+  const el = frame.locator(".component-name");
+  await el.waitFor({ state: "visible", timeout: ELEMENT_TIMEOUT });
+  return el;
+};
+
+// -------------------------
+// Baseline (default story, default args)
+// -------------------------
+test.describe("ComponentName — baseline", () => {
+  test("default matches snapshot", async ({ page }) => {
+    const el = await getElement(page, "default");
+    await expect(el).toHaveScreenshot("default.png");
+  });
+});
+
+// -------------------------
+// Prop variants (one describe per prop, iterate values)
+// -------------------------
+const VARIANTS = ["primary", "secondary", "tertiary"] as const;
+
+test.describe("ComponentName — variants", () => {
+  for (const variant of VARIANTS) {
+    test(`variant-${variant}`, async ({ page }) => {
+      const el = await getElement(page, "default", { variant });
+      await expect(el).toHaveScreenshot(`variant-${variant}.png`);
+    });
+  }
+});
+
+// -------------------------
+// State snapshots (named stories or arg overrides)
+// -------------------------
+test.describe("ComponentName — states", () => {
+  test("with-error", async ({ page }) => {
+    const el = await getElement(page, "default", { fieldHasError: "true" });
+    await expect(el).toHaveScreenshot("state-error.png");
+  });
+});
+
+// -------------------------
+// Cross-variant combinations (meaningful pairs only)
+// -------------------------
+test.describe("ComponentName — combinations", () => {
+  const combinations: Array<{ story: string; args: Record<string, string>; name: string }> = [
+    { story: "default", args: { variant: "secondary", theme: "error" }, name: "secondary-error" },
+  ];
+
+  for (const { story, args, name } of combinations) {
+    test(name, async ({ page }) => {
+      const el = await getElement(page, story, args);
+      await expect(el).toHaveScreenshot(`combo-${name}.png`);
+    });
+  }
+});
+```
+
+## Deriving the STORY_BASE slug
+
+Take the story `title` from the `.stories.ts` file, lowercase everything, remove spaces,
+and replace `/` with `-`:
+
+| Story `title`                                     | `STORY_BASE`                                    |
+| ------------------------------------------------- | ----------------------------------------------- |
+| `"Atoms/Text Blocks/HeroText"`                    | `atoms-text-blocks-herotext`                    |
+| `"Components/Forms/Input Button/InputButtonCore"` | `components-forms-input-button-inputbuttoncore` |
+
+The full story URL pattern is:
+
+```url
+http://127.0.0.1:6006/?path=/story/<STORY_BASE>--<story-export-name>
+```
+
+Story export names are lowercased and hyphenated: `Default` → `default`,
+`WithError` → `with-error`.
+
+## Locating the element
+
+Prefer a semantic locator (role) when available, otherwise use the component's root class:
+
+```ts
+// By role (preferred for interactive elements)
+const el = frame.getByRole("button");
+
+// By class (preferred for display/layout components)
+const el = frame.locator(".component-name");
+
+// By test id (if set on the component)
+const el = frame.getByTestId("component-name");
+```
+
+Always `await el.waitFor({ state: "visible", timeout })` before asserting.
+
+## Screenshot naming conventions
+
+| Scenario                  | File name pattern                          |
+| ------------------------- | ------------------------------------------ |
+| Default story, no args    | `default.png`                              |
+| Single prop variant       | `variant-secondary.png`, `theme-error.png` |
+| State override            | `state-readonly.png`, `state-pending.png`  |
+| Named story baseline      | `<story-name>.png`                         |
+| Cross-variant combination | `combo-secondary-error.png`                |
+
+## Running tests
+
+```bash
+# Requires Storybook running at http://127.0.0.1:6006
+npm run playwright
+
+# Update baselines after an intentional visual change
+npm run playwright:update
+
+# View the HTML test report
+npx playwright show-report
+```
+
+## Notes
+
+- Baselines are stored per browser (Chromium, Firefox, WebKit) — expect three PNG files per
+  `toHaveScreenshot()` call.
+- Use `waitUntil: "load"` on `page.goto` for consistency — the iframe needs to fully render.
+- Keep combinations focused on pairs that meaningfully interact visually. Don't exhaustively
+  cross every prop — that creates a large, brittle baseline set.
+- Comment out stories in the `STORIES` array rather than deleting them if they're temporarily
+  broken, so intent is preserved.

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

@@ -0,0 +1,185 @@
+# Adding a Unit Test
+
+## Overview
+
+Unit tests use Vitest with `mountSuspended` from `@nuxt/test-utils`. They verify props,
+slots, classes, ARIA attributes, and computed internals. Snapshot tests catch unintended
+HTML structure changes.
+
+## File location
+
+```url
+app/components/<component-folder>/tests/<ComponentName>.spec.ts
+```
+
+## Standard structure
+
+```ts
+import { describe, it, expect, afterEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ComponentName from "../ComponentName.vue";
+
+// --- Types (for accessing vm internals) ---
+interface ComponentNameInstance {
+  computedProp: string;
+}
+
+// --- Helper ---
+const createWrapper = async (props: Record<string, unknown> = {}, slots: Record<string, string> = {}) => {
+  return mountSuspended(ComponentName, {
+    props: { requiredProp: "default", ...props },
+    slots,
+  });
+};
+
+describe("ComponentName", () => {
+  let wrapper: Awaited<ReturnType<typeof createWrapper>>;
+
+  afterEach(() => {
+    wrapper?.unmount();
+  });
+
+  // -------------------------
+  // Snapshots
+  // -------------------------
+  describe("Snapshots", () => {
+    it("default", async () => {
+      wrapper = await createWrapper();
+      expect(wrapper.html()).toMatchSnapshot();
+    });
+
+    it("variant-a", async () => {
+      wrapper = await createWrapper({ variant: "a" });
+      expect(wrapper.html()).toMatchSnapshot();
+    });
+  });
+
+  // -------------------------
+  // Rendering
+  // -------------------------
+  describe("Rendering", () => {
+    it("mounts without error", async () => {
+      wrapper = await createWrapper();
+      expect(wrapper.vm).toBeTruthy();
+    });
+
+    it("renders expected element", async () => {
+      wrapper = await createWrapper();
+      expect(wrapper.find(".component-name").exists()).toBe(true);
+    });
+  });
+
+  // -------------------------
+  // Props
+  // -------------------------
+  describe("Props", () => {
+    it("applies variant class", async () => {
+      wrapper = await createWrapper({ variant: "secondary" });
+      expect(wrapper.find(".component-name").classes()).toContain("secondary");
+    });
+
+    it("applies styleClassPassthrough", async () => {
+      wrapper = await createWrapper({ styleClassPassthrough: ["extra"] });
+      expect(wrapper.find(".component-name").classes()).toContain("extra");
+    });
+
+    it("applies data-theme attribute", async () => {
+      wrapper = await createWrapper({ theme: "secondary" });
+      expect(wrapper.find(".component-name").attributes("data-theme")).toBe("secondary");
+    });
+  });
+
+  // -------------------------
+  // Accessibility
+  // -------------------------
+  describe("Accessibility", () => {
+    it("has correct aria attribute by default", async () => {
+      wrapper = await createWrapper();
+      expect(wrapper.find(".component-name").attributes("aria-label")).toBeDefined();
+    });
+  });
+
+  // -------------------------
+  // Slots
+  // -------------------------
+  describe("Slots", () => {
+    it("renders default slot content", async () => {
+      wrapper = await createWrapper({}, { default: "<span>Content</span>" });
+      expect(wrapper.find("span").exists()).toBe(true);
+    });
+  });
+
+  // -------------------------
+  // Computed properties
+  // -------------------------
+  describe("Computed properties", () => {
+    it("computedProp returns expected value", async () => {
+      wrapper = await createWrapper({ someProp: "value" });
+      expect((wrapper.vm as unknown as ComponentNameInstance).computedProp).toBe("expected");
+    });
+  });
+});
+```
+
+## Key rules
+
+- Always `mountSuspended` — never `mount` or `shallowMount` from `@vue/test-utils` directly.
+- 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.
+
+## Snapshot testing
+
+```ts
+expect(wrapper.html()).toMatchSnapshot();
+```
+
+- Run `npm run test:update` after **intentional** component changes to regenerate snapshots.
+- Never update snapshots to fix a failing test without first verifying the change is intentional.
+- Snapshot files are committed alongside tests.
+
+## Accessing component internals (vm)
+
+```ts
+interface ComponentInstance {
+  computedProp: string;
+  refElement: HTMLElement | null;
+}
+const vm = wrapper.vm as unknown as ComponentInstance;
+expect(vm.computedProp).toBe("expected");
+```
+
+## Testing CSS custom properties
+
+```ts
+const el = wrapper.find(".component-name");
+const style = (el.element as HTMLElement).style;
+expect(style.getPropertyValue("--custom-prop")).toBe("expected-value");
+```
+
+## Mocking browser APIs
+
+Mock before the `describe` block if the component uses ResizeObserver, IntersectionObserver, etc.:
+
+```ts
+const mockResizeObserver = vi.fn(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn(),
+}));
+vi.stubGlobal("ResizeObserver", mockResizeObserver);
+```
+
+## Describe section conventions
+
+Use these section names consistently so tests are easy to scan:
+
+| Section               | What it covers                                 |
+| --------------------- | ---------------------------------------------- |
+| `Snapshots`           | `toMatchSnapshot()` per visual state           |
+| `Rendering`           | mounts, expected elements exist                |
+| `Props`               | each prop produces the right class/attr/output |
+| `Accessibility`       | ARIA attributes, sr-only, roles                |
+| `Slots`               | named and default slots render correctly       |
+| `Computed properties` | `wrapper.vm` internals via interface cast      |
+| `Reactivity`          | state changes update the DOM as expected       |

package/.claude/skills/theming-override-default.md

@@ -0,0 +1,238 @@
+# Override the Default Theme in a Consuming App
+
+## Overview
+
+The layer ships a default blue theme. This skill covers how to replace it with your own colour palette in a consuming Nuxt app — including adding a new colour scale and remapping all semantic tokens for light and dark modes.
+
+## Prerequisites
+
+- Consuming app has `srcdev-nuxt-components` installed as a Nuxt layer
+- The consuming app has its own CSS entry point (e.g. `app/assets/styles/main.css`) registered in `nuxt.config.ts` via `css: [...]`
+
+## Steps
+
+### 1. Create the colour scale file
+
+Create `app/assets/styles/setup/02.colours/_gold.css` (or your colour name).
+
+Colours use the `oklch` colour space. The scale runs from `00` (lightest) to `10` (darkest) — `00` is optional and only needed if you require a near-white tint.
+
+```css
+:where(html) {
+  --gold-00: oklch(98% 0.01 85);
+  --gold-01: oklch(94% 0.04 85);
+  --gold-02: oklch(88% 0.09 85);
+  --gold-03: oklch(80% 0.14 85);
+  --gold-04: oklch(72% 0.18 85);
+  --gold-05: oklch(64% 0.20 85);
+  --gold-06: oklch(56% 0.19 85);
+  --gold-07: oklch(48% 0.17 85);
+  --gold-08: oklch(40% 0.15 85);
+  --gold-09: oklch(32% 0.12 85);
+  --gold-10: oklch(25% 0.09 85);
+}
+```
+
+Adjust the hue angle (third value) to taste — `85` is a warm gold. Use an oklch colour picker to preview the scale.
+
+### 2. Create the colours index
+
+Create `app/assets/styles/setup/02.colours/index.css` and import your scale:
+
+```css
+@import "./_gold";
+```
+
+### 3. Create the light theme override
+
+Create `app/assets/styles/setup/03.theming/default/_light.css`.
+
+This file uses `:where(html)` and maps semantic tokens to your colour scale. Copy the full token list from the layer and replace `--blue-*` references with `--gold-*`:
+
+```css
+:where(html) {
+  /* Color scale */
+  --colour-theme-1: var(--gold-01);
+  --colour-theme-2: var(--gold-02);
+  --colour-theme-3: var(--gold-03);
+  --colour-theme-4: var(--gold-04);
+  --colour-theme-5: var(--gold-05);
+  --colour-theme-6: var(--gold-06);
+  --colour-theme-7: var(--gold-07);
+  --colour-theme-8: var(--gold-08);
+  --colour-theme-9: var(--gold-09);
+  --colour-theme-10: var(--gold-10);
+
+  /* Body */
+  --page-bg: var(--slate-00);
+  --colour-text-default: var(--slate-09);
+  --colour-text-accent: var(--gold-09);
+  --colour-text-eyebrow: var(--gold-09);
+
+  /* Links */
+  --colour-link-default: var(--gold-10);
+  --colour-link-hover: var(--gold-09);
+
+  /* Form inputs */
+  --theme-input-surface: var(--slate-00);
+  --theme-input-surface-hover: var(--slate-01);
+  --theme-input-border: var(--gold-06);
+  --theme-input-border-hover: var(--gold-05);
+  --theme-input-border-focus: var(--gold-04);
+  --theme-input-outline: transparent;
+  --theme-input-outline-focus: var(--gold-04);
+  --theme-input-visible-outline: var(--gold-10);
+  --theme-focus-visible-shadow: 0 0 0 2px var(--gold-02);
+  --theme-input-placeholder: var(--slate-05);
+  --theme-input-text-color-normal: var(--slate-09);
+
+  /* Checkbox / radio */
+  --theme-checkbox-symbol-color: var(--gold-08);
+  --theme-checkbox-symbol-surface: var(--theme-input-surface);
+  --theme-checkbox-decorator-color: var(--gold-09);
+
+  /* Toggle */
+  --theme-toggle-symbol-color-default: var(--gold-00);
+  --theme-toggle-symbol-color-checked: var(--gold-08);
+
+  /* Buttons — primary */
+  --theme-button-primary-surface: var(--gold-09);
+  --theme-button-primary-surface-hover: var(--gold-08);
+  --theme-button-primary-surface-active: var(--gold-07);
+  --theme-button-primary-border: var(--gold-09);
+  --theme-button-primary-border-active: var(--gold-09);
+  --theme-button-primary-outline: var(--gold-01);
+  --theme-button-primary-outline-active: var(--gold-07);
+  --theme-button-primary-text: var(--gold-00);
+  --theme-button-primary-text-hover: var(--gold-00);
+
+  /* Buttons — secondary */
+  --theme-button-secondary-surface: transparent;
+  --theme-button-secondary-surface-hover: var(--gold-01);
+  --theme-button-secondary-surface-active: var(--gold-01);
+  --theme-button-secondary-border: var(--gold-09);
+  --theme-button-secondary-border-active: var(--gold-09);
+  --theme-button-secondary-outline: var(--gold-09);
+  --theme-button-secondary-outline-active: var(--gold-09);
+  --theme-button-secondary-text: var(--gold-09);
+  --theme-button-secondary-text-hover: var(--gold-09);
+
+  /* Buttons — tertiary */
+  --theme-button-tertiary-surface: var(--slate-01);
+  --theme-button-tertiary-text: var(--gold-09);
+  --theme-button-tertiary-border-active: var(--gold-09);
+  --theme-button-tertiary-outline-active: var(--gold-09);
+}
+```
+
+### 4. Create the dark theme override
+
+Create `app/assets/styles/setup/03.theming/default/_dark.css`.
+
+Selector is `:where(html.dark)`. Dark mode typically inverts the scale direction — light values for text/borders, dark values for backgrounds:
+
+```css
+:where(html.dark) {
+  /* Color scale */
+  --colour-theme-1: var(--gold-01);
+  --colour-theme-2: var(--gold-02);
+  --colour-theme-3: var(--gold-03);
+  --colour-theme-4: var(--gold-04);
+  --colour-theme-5: var(--gold-05);
+  --colour-theme-6: var(--gold-06);
+  --colour-theme-7: var(--gold-07);
+  --colour-theme-8: var(--gold-08);
+  --colour-theme-9: var(--gold-09);
+  --colour-theme-10: var(--gold-10);
+
+  /* Body */
+  --page-bg: var(--slate-08);
+  --colour-text-default: var(--slate-01);
+  --colour-text-accent: var(--gold-05);
+  --colour-text-eyebrow: var(--gold-05);
+
+  /* Links */
+  --colour-link-default: var(--gold-03);
+  --colour-link-hover: var(--gold-04);
+
+  /* Form inputs */
+  --theme-input-surface: var(--slate-10);
+  --theme-input-surface-hover: var(--slate-09);
+  --theme-input-border: var(--gold-06);
+  --theme-input-border-hover: var(--gold-05);
+  --theme-input-border-focus: var(--gold-04);
+  --theme-input-outline: var(--gold-06);
+  --theme-input-outline-focus: var(--gold-04);
+  --theme-input-visible-outline: var(--gold-04);
+  --theme-focus-visible-shadow: 0 0 0 2px var(--gold-02);
+  --theme-input-placeholder: var(--slate-04);
+  --theme-input-text-color-normal: var(--slate-01);
+
+  /* Checkbox / radio */
+  --theme-checkbox-symbol-surface: var(--theme-input-surface);
+  --theme-checkbox-symbol-color: var(--gold-02);
+  --theme-checkbox-decorator-color: var(--gold-02);
+
+  /* Buttons — primary */
+  --theme-button-primary-border: var(--gold-07);
+  --theme-button-primary-border-active: var(--gold-07);
+  --theme-button-primary-text: var(--gold-00);
+  --theme-button-primary-text-hover: var(--gold-00);
+
+  /* Buttons — secondary */
+  --theme-button-secondary-surface: var(--gold-01);
+  --theme-button-secondary-border-active: var(--gold-01);
+  --theme-button-secondary-text: var(--gold-09);
+
+  /* Buttons — tertiary */
+  --theme-button-tertiary-surface: transparent;
+  --theme-button-tertiary-text: var(--gold-01);
+  --theme-button-tertiary-border-active: var(--gold-01);
+  --theme-button-tertiary-outline-active: var(--gold-09);
+}
+```
+
+### 5. Create the theming index
+
+Create `app/assets/styles/setup/03.theming/default/index.css`:
+
+```css
+@import "./_light";
+@import "./_dark";
+```
+
+### 6. Create the setup index
+
+Create `app/assets/styles/setup/index.css` that imports colours then theming (order matters — colours must be defined before theming references them):
+
+```css
+@import "./02.colours/";
+@import "./03.theming/default/";
+```
+
+### 7. Wire up the CSS entry point
+
+In your consuming app's `app/assets/styles/main.css` (or equivalent), import your setup after the layer's styles are applied:
+
+```css
+@import "./setup/";
+```
+
+Then register it in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  extends: "srcdev-nuxt-components",
+  css: ["~/assets/styles/main.css"],
+});
+```
+
+The consuming app's CSS loads after the layer's, so your token overrides win via the cascade.
+
+## Notes
+
+- The `--slate-*` scale comes from the layer and does not need to be redefined — keep all neutral/background tokens pointing at `--slate-*`.
+- Only redefine tokens that change. You do not need to copy tokens that stay identical between layer and your override.
+- Dark mode is triggered by the `dark` class on `<html>`. The layer handles toggling this via `data-color-scheme` and the colour scheme store.
+- If you need additional component-specific tokens (e.g. `--stepper-list-*`, `--glass-panel-*`), add them to `_light.css` and `_dark.css` following the same pattern.
+- Use an oklch colour picker (e.g. oklch.com) to build and preview your scale before committing values.

package/README.md

@@ -20,6 +20,26 @@ defineNuxtConfig({
 });
 ```
 
+## Claude Code Skills
+
+This package ships Claude Code skills — reference docs for components and development tasks — in the `.claude/` directory.
+
+To make them available in your project, add this script to your `package.json`:
+
+```json
+"setup:claude": "cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components"
+```
+
+Then run it after install:
+
+```bash
+npm run setup:claude
+```
+
+Skills are copied into `.claude/skills/srcdev-nuxt-components/` so they never conflict with or overwrite skills your own project defines. Re-running the script after a package update is safe.
+
+---
+
 ## Known Dev Server Warnings
 
 ### `[request error] [GET] http://localhost:3000/_nuxt/` (404)

package/app/components/01.atoms/text-blocks/link-text/LinkText.vue

@@ -0,0 +1,66 @@
+<template>
+  <NuxtLink class="link-text" :class="elementClasses" :to="to" :external="external" :target="target">
+    <span v-if="hasLeftSlot" class="link-text__icon link-text__icon--left">
+      <slot name="left"></slot>
+    </span>
+    <span class="link-text__label">{{ linkText }}</span>
+    <span v-if="hasRightSlot" class="link-text__icon link-text__icon--right">
+      <slot name="right"></slot>
+    </span>
+  </NuxtLink>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  to: string;
+  linkText: string;
+  external?: boolean;
+  target?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  external: false,
+  target: undefined,
+  styleClassPassthrough: () => [],
+});
+
+const slots = useSlots();
+const hasLeftSlot = computed(() => Boolean(slots.left));
+const hasRightSlot = computed(() => Boolean(slots.right));
+
+const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+</script>
+
+<style lang="css">
+@layer components {
+  .link-text {
+    display: inline-grid;
+    grid-auto-flow: column;
+    align-items: center;
+    gap: var(--link-text-gap, 0.4em);
+    color: var(--link-text-colour, currentColor);
+    font-size: var(--link-text-font-size, inherit);
+    text-decoration: var(--link-text-decoration, underline);
+    text-underline-offset: var(--link-text-underline-offset, 0.2em);
+    transition: color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease);
+
+    &:hover,
+    &:focus-visible {
+      color: var(--link-text-colour-hover, currentColor);
+      text-decoration: var(--link-text-decoration-hover, none);
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--link-text-colour, currentColor);
+      outline-offset: 3px;
+      border-radius: 2px;
+    }
+
+    .link-text__icon {
+      display: flex;
+      align-items: center;
+    }
+  }
+}
+</style>