srcdev-nuxt-components 9.0.4 → 9.0.6

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "mcp__ide__getDiagnostics",
+      "WebFetch(domain:drafts.csswg.org)",
+      "Bash(grep '\"\"typescript\"\"' package.json)",
+      "Bash(grep '\"\"@vue/language-server\\\\|@volar\\\\|vue-tsc\"\"' package.json)",
+      "Bash(npx nuxi prepare)"
+    ]
+  }
+}

package/.claude/skills/components/eyebrow-text.md

@@ -0,0 +1,83 @@
+# EyebrowText Component
+
+## Overview
+
+`EyebrowText` renders a short uppercase label — typically used above a heading to provide context or categorisation. It outputs a single string with configurable tag, size, and colour via CSS custom properties.
+
+## Before Adding to a Page
+
+Always ask the user for the following before placing the component:
+
+1. **`textContent`** — what is the label text? (passed as-is — do not pre-uppercase)
+2. **`fontSize`** — which size? (`large` | `medium` | `small`) — default is `medium`
+3. **`tag`** — does it need to be inline? If yes, use `span`. Otherwise `p` or `div` (default).
+4. **`styleClassPassthrough`** — any extra classes to add? (layout, spacing, custom styling hooks)
+
+Do not assume placeholder text or default content.
+
+## Props
+
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| `textContent` | `string` | — | yes |
+| `tag` | `"p" \| "div" \| "span"` | `"div"` | no |
+| `fontSize` | `"large" \| "medium" \| "small"` | `"medium"` | no |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | no |
+
+## Basic Usage
+
+```vue
+<EyebrowText textContent="Interior Design" />
+```
+
+## With Tag and Size
+
+Use `tag="p"` for semantic paragraph context, or `tag="span"` when inline. Choose `fontSize` to match surrounding hierarchy.
+
+```vue
+<EyebrowText
+  tag="p"
+  fontSize="small"
+  textContent="Featured Collection"
+/>
+```
+
+## Paired with HeroText
+
+EyebrowText is commonly placed directly above a `HeroText` heading:
+
+```vue
+<EyebrowText tag="p" textContent="Our Services" />
+<HeroText
+  tag="h2"
+  :textContent="[
+    { text: 'Crafted with', styleClass: 'normal' },
+    { text: 'Care', styleClass: 'accent' },
+  ]"
+/>
+```
+
+## Font Size Scale
+
+| Value | CSS variable |
+|-------|-------------|
+| `large` | `--eyebrow-text-large` |
+| `medium` | `--eyebrow-text-medium` |
+| `small` | `--eyebrow-text-small` |
+
+Define these CSS custom properties in your consuming app to control sizes.
+
+## Styling
+
+Key CSS custom properties:
+
+- `--colour-text-eyebrow` — text colour (defaults to an accent/muted tone)
+
+Text is always `text-transform: uppercase` — do not pass pre-uppercased strings, as this makes content harder to edit and search.
+
+Override via `styleClassPassthrough` or a parent HOC `<style>` block targeting `.eyebrow-text`.
+
+## Notes
+
+- Component is auto-imported in Nuxt — no import needed.
+- `tag` defaults to `"div"` which is block-level. Use `"span"` when the eyebrow must be inline within a flow of text.

package/.claude/skills/components/hero-text.md

@@ -0,0 +1,110 @@
+# HeroText Component
+
+## Overview
+
+`HeroText` renders a styled heading with support for mixed text styling (normal/accent segments), configurable font size, layout axis, and an optional icon. It uses Playfair Display font with italic variation for accent segments.
+
+## Before Adding to a Page
+
+Always ask the user for the following before placing the component:
+
+1. **`tag`** — what heading level? (`h1` | `h2` | `h3` | `h4` | `h5` | `h6`)
+2. **Text segments** — for each segment, what is the text and should it be `normal` (default) or `accent` (italic, `--colour-text-accent` colour)?
+3. **`axis`** — should segments sit inline (`horizontal`, default) or stack in a column (`vertical`)?
+4. **`fontSize`** — which size? (`display` | `title` | `heading` | `subheading` | `label`) — default is `title`
+5. **`styleClassPassthrough`** — any extra classes to add? (layout, spacing, custom styling hooks)
+
+Do not assume placeholder text or default content.
+
+## Props
+
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| `tag` | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"` | — | yes |
+| `textContent` | `TextConfig[]` | — | yes |
+| `id` | `string` | `undefined` | no |
+| `axis` | `"horizontal" \| "vertical"` | `"horizontal"` | no |
+| `fontSize` | `"display" \| "title" \| "heading" \| "subheading" \| "label"` | `"title"` | no |
+| `icon` | `string` | `undefined` | no |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | no |
+
+### TextConfig
+
+```ts
+interface TextConfig {
+  text: string;
+  styleClass?: "normal" | "accent";
+}
+```
+
+- `"normal"` — default unstyled text
+- `"accent"` — italic, coloured with `--colour-text-accent`
+
+## Basic Usage
+
+```vue
+<HeroText
+  tag="h1"
+  :textContent="[
+    { text: 'Designing', styleClass: 'normal' },
+    { text: 'Artistry', styleClass: 'accent' },
+    { text: 'at Home', styleClass: 'normal' },
+  ]"
+/>
+```
+
+## With Icon
+
+`icon` accepts any icon name from `@nuxt/icon` (e.g. Iconify identifiers).
+
+```vue
+<HeroText
+  tag="h2"
+  icon="lucide:sparkles"
+  fontSize="heading"
+  :textContent="[{ text: 'Featured', styleClass: 'accent' }]"
+/>
+```
+
+## Vertical Axis
+
+Use `axis="vertical"` to stack text segments in a column instead of a row.
+
+```vue
+<HeroText
+  tag="h1"
+  axis="vertical"
+  fontSize="display"
+  :textContent="[
+    { text: 'Modern', styleClass: 'normal' },
+    { text: 'Living', styleClass: 'accent' },
+  ]"
+/>
+```
+
+## Font Size Scale
+
+| Value | CSS variable |
+|-------|-------------|
+| `display` | `--hero-text-display` |
+| `title` | `--hero-text-title` |
+| `heading` | `--hero-text-heading` |
+| `subheading` | `--hero-text-subheading` |
+| `label` | `--hero-text-label` |
+
+Define these CSS custom properties in your consuming app to control sizes.
+
+## Styling
+
+Override via `styleClassPassthrough` or a parent HOC `<style>` block targeting `.hero-text`.
+
+Key CSS custom properties:
+
+- `--colour-text-accent` — colour applied to `.accent` spans and the icon
+- `--hero-text-{scale}` — font size per scale value
+
+## Notes
+
+- Text segments are trimmed and a trailing space is automatically appended between segments in horizontal axis — do not manually pad `text` values.
+- The icon is sized to match the font size. At `subheading` scale it is explicitly capped at `0.75 * --hero-text-subheading`.
+- Component is auto-imported in Nuxt — no import needed.

package/.claude/skills/components/link-text.md

@@ -0,0 +1,101 @@
+# LinkText Component
+
+## Overview
+
+`LinkText` renders a `NuxtLink` styled as a standalone text link, with optional left and/or right icon slots. Icons are vertically centred with the label text. Intended as a CTA-style link — distinct from `InputButtonCore` (which is a button/link hybrid with button styling).
+
+## Props
+
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| `to` | `string` | — | yes |
+| `linkText` | `string` | — | yes |
+| `external` | `boolean` | `false` | no |
+| `target` | `string` | `undefined` | no |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | no |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `left` | Icon rendered before the label |
+| `right` | Icon rendered after the label |
+
+Both slots are optional. If neither is provided, no icon wrapper elements are rendered.
+
+## Basic Usage
+
+```vue
+<LinkText to="/about" linkText="About Us" />
+```
+
+## With Left Icon (back/previous pattern)
+
+```vue
+<LinkText to="/blog" linkText="Back to Blog">
+  <template #left>
+    <Icon name="lucide:arrow-left" />
+  </template>
+</LinkText>
+```
+
+## With Right Icon (forward/more pattern)
+
+```vue
+<LinkText to="/services" linkText="Learn More">
+  <template #right>
+    <Icon name="lucide:arrow-right" />
+  </template>
+</LinkText>
+```
+
+## Both Icons
+
+```vue
+<LinkText to="/collection" linkText="Explore">
+  <template #left>
+    <Icon name="lucide:sparkles" />
+  </template>
+  <template #right>
+    <Icon name="lucide:arrow-right" />
+  </template>
+</LinkText>
+```
+
+## External Link
+
+```vue
+<LinkText
+  to="https://example.com"
+  linkText="Visit Site"
+  :external="true"
+  target="_blank"
+>
+  <template #right>
+    <Icon name="lucide:external-link" />
+  </template>
+</LinkText>
+```
+
+## Styling
+
+Key CSS custom properties — define these in your consuming app to control appearance:
+
+| Property | Default | Purpose |
+|----------|---------|---------|
+| `--link-text-colour` | `currentColor` | Link text/icon colour |
+| `--link-text-colour-hover` | `currentColor` | Colour on hover/focus |
+| `--link-text-gap` | `0.4em` | Gap between icon and label |
+| `--link-text-font-size` | `inherit` | Font size |
+| `--link-text-decoration` | `underline` | Text decoration |
+| `--link-text-decoration-hover` | `none` | Text decoration on hover |
+| `--link-text-underline-offset` | `0.2em` | Underline offset |
+
+Override via `styleClassPassthrough` or a parent HOC `<style>` block targeting `.link-text`.
+
+## Notes
+
+- Component is auto-imported in Nuxt — no import needed.
+- NuxtLink handles both internal (`/path`) and external (`https://...`) URLs automatically. Only set `external: true` if you need to force external handling on an internal-looking path.
+- The label is always rendered inside `.link-text__label` — target this class if you need to style the text independently of the icons.
+- DOM order is always: left icon → label → right icon.

package/.claude/skills/index.md

@@ -0,0 +1,54 @@
+# Skills
+
+Step-by-step guides for repeatable development tasks in this project.
+
+## For consuming apps
+
+Copy skills into your project with:
+
+```bash
+cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components
+```
+
+Skills land in `.claude/skills/srcdev-nuxt-components/` — safe to re-run without overwriting your own skills.
+
+## Structure
+
+Each skill is a single markdown file named `<area>-<task>.md`.
+
+```
+.claude/skills/
+├── index.md                    — this file
+├── storybook-add-story.md      — create a Storybook story for a component
+├── storybook-add-font.md       — add a new font to Storybook
+├── testing-add-unit-test.md    — create a Vitest unit test with snapshots
+├── testing-add-playwright.md   — create a Playwright visual regression test
+├── theming-override-default.md — override the default theme with a custom colour scale
+└── components/
+    ├── eyebrow-text.md         — EyebrowText props, usage patterns, styling
+    ├── hero-text.md            — HeroText props, usage patterns, styling
+    └── link-text.md            — LinkText props, slots, usage patterns, styling
+```
+
+## Skill file template
+
+```md
+# <Title>
+
+## Overview
+Brief description of what this skill does and why it exists.
+
+## Prerequisites
+What needs to be in place before starting (optional section).
+
+## Steps
+
+### 1. <Step name>
+...
+
+### 2. <Step name>
+...
+
+## Notes
+Edge cases, gotchas, or links to related files (optional section).
+```

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

@@ -0,0 +1,101 @@
+# Adding a New Font to Storybook
+
+## Overview
+
+`@nuxt/fonts` is disabled in Storybook (via `process.env.STORYBOOK` check in `nuxt.config.ts`).
+Fonts are served instead via `.storybook/fonts.css`, which is imported in `.storybook/preview.ts`.
+Font files live in `.storybook/public/_fonts/` and are served as static assets via `staticDirs: ["./public"]` in `.storybook/main.ts`.
+
+## Steps
+
+### 1. Check what weights/styles exist
+
+`@nuxt/fonts` caches font metadata here after a `nuxt build` or `nuxt dev`:
+
+```url
+node_modules/.cache/nuxt/fonts/meta/bunny/<hash>/bunny/<FontName>-<hash>-data.json
+```
+
+Open the matching JSON file — it lists every available `weight`, `style`, and `src.url`.
+The bunny CDN URL pattern is predictable:
+
+```url
+https://fonts.bunny.net/<font-slug>/files/<font-slug>-<subset>-<weight>-<style>.woff2
+```
+
+Example for Playfair Display latin, 700 normal:
+
+```url
+https://fonts.bunny.net/playfair-display/files/playfair-display-latin-700-normal.woff2
+```
+
+Common subsets: `latin`, `latin-ext`, `cyrillic`, `vietnamese`. For Storybook, `latin` only is sufficient.
+
+### 2. Create the font directory
+
+```url
+.storybook/public/_fonts/<font-slug>/
+```
+
+### 3. Download the font files
+
+Run this from the project root, substituting `<font-slug>` and the weights that actually exist:
+
+```bash
+mkdir -p .storybook/public/_fonts/<font-slug>
+cd .storybook/public/_fonts/<font-slug>
+
+for weight in 400 500 600 700 800 900; do
+  for style in normal italic; do
+    curl -sfLo "<font-slug>-latin-${weight}-${style}.woff2" \
+      "https://fonts.bunny.net/<font-slug>/files/<font-slug>-latin-${weight}-${style}.woff2" \
+      && echo "OK: ${weight} ${style}" || echo "FAIL: ${weight} ${style}"
+  done
+done
+```
+
+`FAIL` results mean that weight/style combination doesn't exist — safe to ignore.
+
+### 4. Add @font-face declarations to `.storybook/fonts.css`
+
+```css
+/* Font Name */
+@font-face {
+  font-family: "Font Name";
+  src: url("/_fonts/<font-slug>/<font-slug>-latin-400-normal.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+/* repeat for each weight/style downloaded */
+```
+
+### 5. Register the font in `nuxt.config.ts`
+
+Add to the `fonts.families` array (used by the Nuxt app, not Storybook):
+
+```ts
+{
+  name: "Font Name",
+  weights: [400, 500, 600, 700, 800, 900],
+  styles: ["normal", "italic"],
+  provider: "bunny",
+},
+```
+
+### 6. Update the font table in `README.md`
+
+Add a row to the Storybook fonts table under `## Storybook > ### Fonts`.
+
+## Notes
+
+**Architecture summary**
+
+| Context   | Font source                                                          |
+| --------- | -------------------------------------------------------------------- |
+| Nuxt app  | `@nuxt/fonts` (bunny CDN → hashed `/_fonts/*.woff2`)                 |
+| Storybook | `.storybook/fonts.css` + static files in `.storybook/public/_fonts/` |
+
+**Poppins exception** — Poppins files use TTF (not woff2) and are stored as
+`.storybook/public/_fonts/poppins/Poppins-<Weight>.ttf`. These came from Google Fonts
+directly, not bunny, so there is no equivalent curl script.

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

@@ -0,0 +1,164 @@
+# Adding a Storybook Story
+
+## Overview
+
+Stories live alongside the component in a `stories/` subfolder and are the source for both
+manual visual review and Playwright visual regression tests.
+
+## File location
+
+```url
+app/components/<component-folder>/stories/<ComponentName>.stories.ts
+```
+
+## Two patterns
+
+### Simple component — `StoryObj`
+
+Use when the component has no v-model and one representative story is enough.
+
+```ts
+import ComponentName from "../ComponentName.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof ComponentName> = {
+  title: "Category/Subcategory/ComponentName",
+  component: ComponentName,
+  argTypes: {
+    propName: {
+      control: { type: "select" },
+      options: ["a", "b", "c"],
+      description: "What this prop does",
+    },
+    booleanProp: {
+      control: "boolean",
+      description: "What this prop does",
+    },
+    textProp: {
+      control: "text",
+      description: "What this prop does",
+    },
+    objectProp: {
+      control: "object",
+      description: "What this prop does",
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ComponentName>;
+
+export const Default: Story = {
+  args: {
+    propName: "a",
+    booleanProp: false,
+    textProp: "Hello",
+    objectProp: [],
+  },
+  render: (args) => ({
+    components: { ComponentName },
+    setup() {
+      return { args };
+    },
+    template: `<ComponentName v-bind="args" />`,
+  }),
+};
+```
+
+### Component with v-model or slots — `StoryFn` with Template
+
+Use when the component has `v-model`, reactive state, or named slots that need toggling.
+
+```ts
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import StorybookComponent from "../ComponentName.vue";
+
+interface ComponentStoryArgs {
+  modelValue: string;
+  propName: string;
+  useSlot: boolean;
+  slotContent: string;
+}
+
+export default {
+  title: "Category/Subcategory/ComponentName",
+  component: StorybookComponent,
+  argTypes: {
+    modelValue: {
+      control: "text",
+      description: "The bound value",
+      table: { category: "Model" },
+    },
+    propName: {
+      control: { type: "select" },
+      options: ["a", "b"],
+      description: "What this prop does",
+      table: { category: "Basic" },
+    },
+    useSlot: {
+      control: "boolean",
+      description: "Toggle named slot",
+      table: { category: "Slots" },
+    },
+    slotContent: {
+      control: "text",
+      description: "Content for the slot",
+      table: { category: "Slots" },
+    },
+  },
+  args: {
+    modelValue: "",
+    propName: "a",
+    useSlot: false,
+    slotContent: "Slot text",
+  },
+} as Meta<typeof StorybookComponent>;
+
+const Template: StoryFn<ComponentStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const { modelValue, ...otherArgs } = args;
+    const inputValue = ref(modelValue);
+    return { inputValue, args: otherArgs, useSlot: args.useSlot, slotContent: args.slotContent };
+  },
+  template: `
+    <StorybookComponent v-model="inputValue" v-bind="args">
+      <template v-if="useSlot" #slotName>{{ slotContent }}</template>
+    </StorybookComponent>
+  `,
+});
+
+export const Default = Template.bind({});
+Default.args = {};
+
+export const WithSlot = Template.bind({});
+WithSlot.args = { useSlot: true, slotContent: "Custom content" };
+```
+
+## Title format
+
+`"Category/Subcategory/ComponentName"` — this becomes the Storybook sidebar path and the
+Playwright `STORY_BASE` slug. The slug is derived by lowercasing and replacing spaces and
+`/` with `-`:
+
+| Title                                         | STORY_BASE slug                             |
+| --------------------------------------------- | ------------------------------------------- |
+| `"Atoms/Text Blocks/HeroText"`                | `atoms-text-blocks-herotext`                |
+| `"Components/Forms/Input Text/InputTextCore"` | `components-forms-input-text-inputtextcore` |
+
+## argTypes control types
+
+| Prop type      | `control`                        |
+| -------------- | -------------------------------- |
+| String         | `"text"`                         |
+| Boolean        | `"boolean"`                      |
+| Number         | `{ type: "number", min, max }`   |
+| Enum / union   | `{ type: "select" }` + `options` |
+| Array / object | `"object"`                       |
+
+## Notes
+
+- Use `table: { category: "..." }` in `argTypes` when a component has many props — it groups
+  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.