srcdev-nuxt-components 9.4.9 → 9.4.11

package/README.md

@@ -123,7 +123,7 @@ A formula declared on every potential theme host (`html`, `[data-theme]`, `[data
 computes the scale from the two params:
 
 ```css
---colour-theme-6: oklch(56% calc(var(--theme-chroma) * 1.00) var(--theme-hue)); /* peak chroma */
+--colour-theme-6: oklch(56% calc(var(--theme-chroma) * 1) var(--theme-hue)); /* peak chroma */
 --colour-theme-0: oklch(98% calc(var(--theme-chroma) * 0.045) var(--theme-hue)); /* near-white */
 --colour-theme-10: oklch(25% calc(var(--theme-chroma) * 0.64) var(--theme-hue)); /* near-black */
 ```
@@ -138,7 +138,7 @@ re-evaluates locally so each themed element gets its own full palette without af
 ### Built-in named palettes
 
 | Name   | Hue | Used for                                          |
-|--------|-----|---------------------------------------------------|
+| ------ | --- | ------------------------------------------------- |
 | blue   | 255 | Default (page-level)                              |
 | red    | 30  | Error / `data-theme="error"`                      |
 | green  | 157 | Success / `data-theme="success"`                  |
@@ -163,7 +163,7 @@ the cascade automatically:
 // ramps.config.mjs
 export const ramps = {
   // New palette — adds --gold-00..10 and --palette-gold-* vars
-  gold: { hue: 85, chroma: 0.20 },
+  gold: { hue: 85, chroma: 0.2 },
 
   // Override a built-in — replaces the layer's --blue-00..10 with your values
   // blue: { hue: 240, chroma: 0.18 },
@@ -218,11 +218,11 @@ In your `app/assets/styles/setup/02.colours/index.css` (create if it doesn't exi
 ```css
 /* app/assets/styles/setup/03.theming/_default.css */
 :where(html) {
-  --theme-hue:    var(--palette-gold-hue);
+  --theme-hue: var(--palette-gold-hue);
   --theme-chroma: var(--palette-gold-chroma);
 
   /* Page-level tokens — readable named steps, not raw oklch */
-  --colour-text-accent:  light-dark(var(--gold-09), var(--gold-04));
+  --colour-text-accent: light-dark(var(--gold-09), var(--gold-04));
   --colour-text-eyebrow: light-dark(var(--gold-09), var(--gold-04));
 }
 ```
@@ -244,7 +244,7 @@ And in `app/assets/styles/main.css`:
 ### Hue quick reference
 
 | Range   | Colour         |
-|---------|----------------|
+| ------- | -------------- |
 | 0–30    | Red / pink     |
 | 30–70   | Orange / amber |
 | 70–100  | Yellow / gold  |
@@ -265,12 +265,12 @@ npm run check:ramps      # CI: fail if generated CSS is out of date
 
 ### Further reading
 
-| Guide | Location |
-|-------|----------|
-| Full ramp architecture, formula details, hue drift | `.claude/skills/theming-colour-ramps.md` |
-| Full palette swap for a consumer app | `.claude/skills/theming-override-default.md` |
+| Guide                                                   | Location                                     |
+| ------------------------------------------------------- | -------------------------------------------- |
+| Full ramp architecture, formula details, hue drift      | `.claude/skills/theming-colour-ramps.md`     |
+| Full palette swap for a consumer app                    | `.claude/skills/theming-override-default.md` |
 | Partial token override (palette shift, buttons, inputs) | `.claude/skills/theming-partial-override.md` |
-| Disable light/dark mode support | `.claude/skills/colour-scheme-disable.md` |
+| Disable light/dark mode support                         | `.claude/skills/colour-scheme-disable.md`    |
 
 Skills are available in your project after running `npm run setup:claude`.
 
@@ -330,15 +330,19 @@ The `.vscode` directory contains Visual Studio Code configuration files to ensur
   - **CSS Development**: `willofindie.vscode-cssvar` - CSS custom property IntelliSense
   - **Testing**: `vitest.explorer` - Vitest test runner integration
   - **Markdown**: `davidanson.vscode-markdownlint` - Markdown linting
-  - **Productivity**: `jkjustjoshing.vscode-text-pastry`, `formulahendry.auto-rename-tag`
+  - **Productivity**: `jkjustjoshing.vscode-text-pastry`, `formulahendry.auto-rename-tag`, `nixon.env-cmd-file-syntax`
+  - **AI-assisted development**: `anthropic.claude-code`
 
 ### Code Snippets
 
-The `.vscode` directory includes comprehensive code snippets for rapid component development:
+Every component ships a matching `.vscode/srcdev-component-{name}.code-snippets` file — one per
+component, kept up to date as part of this project's component migration workflow (see
+`CLAUDE.md`). Consumer apps get all of them copied into their own `.vscode/` folder automatically
+via the `postinstall` setup described above; there's nothing to configure manually.
 
 ## Contact Form — Resend Setup
 
-The contact form at `/ui/contact-section` sends enquiries via [Resend](https://resend.com).
+The `ContactSection` component (see it in Storybook under **Molecules/ContactSection**) sends enquiries via [Resend](https://resend.com).
 No extra packages are required — the server route calls the Resend REST API directly.
 
 ### 1. Create a Resend account
@@ -490,26 +494,3 @@ Fonts are served instead from local files in `.storybook/public/_fonts/`, declar
 | Playfair Display | woff2  | `.storybook/public/_fonts/playfair-display/` |
 
 To add a new font, see [.claude/skills/storybook-add-font.md](.claude/skills/storybook-add-font.md).
-
-#### Core Components
-
-- **`srcdev-nuxt3-component-boilerplate.code-snippets`** - Base component template with prop validation
-- **`srcdev-nuxt3-page-layout.code-snippets`** - Page layout scaffolding
-- **`srcdev-nuxt3-pinia-store-setup.code-snippets`** - Pinia store configuration
-
-#### UI Components
-
-- **`srcdev-nuxt3-accordian-component.code-snippets`** - Accordion component templates
-- **`srcdev-nuxt3-carousel-basic-component.code-snippets`** - Basic carousel implementation
-- **`srcdev-nuxt3-carousel-flip-component.code-snippets`** - Flip carousel variant
-- **`srcdev-nuxt3-container-glow-component.code-snippets`** - Container with glow effects
-- **`srcdev-nuxt3-dialog-component.code-snippets`** - Modal dialog templates
-- **`srcdev-nuxt3-display-banner-component.code-snippets`** - Display banner component
-- **`srcdev-nuxt3-display-details-component.code-snippets`** - Collapsible details component
-- **`srcdev-nuxt3-display-prompt-component.code-snippets`** - Alert/notification prompts
-- **`srcdev-nuxt3-expanding-panel-component.code-snippets`** - Expandable panel component
-- **`srcdev-nuxt3-layout-row.code-snippets`** - Layout row component
-- **`srcdev-nuxt3-responsive-header-component.code-snippets`** - Responsive navigation header
-- **`srcdev-nuxt3-tabs-component.code-snippets`** - Tab component system
-
-Each snippet provides both HTML template usage examples and TypeScript setup code, enabling developers to quickly implement components with proper typing and configuration.

package/app/components/{alert-mask → 01.atoms/alert-mask}/AlertMaskCore.vue

@@ -1,6 +1,6 @@
 <template>
   <div class="alert-mask-core" :class="[elementClasses]">
-    <svg class="alert-mask-decorator" :style="{ '--alertHeight': svgHeight + 'px' }" xmlns="http://www.w3.org/2000/svg">
+    <svg class="alert-mask-decorator" :style="{ '--_height': svgHeight + 'px' }" xmlns="http://www.w3.org/2000/svg">
       <defs>
         <mask id="borderMask" maskUnits="userSpaceOnUse">
           <path :d="outerPath" fill="white" />
@@ -15,10 +15,10 @@
     <div
       class="alert-mask-content"
       :style="{
-        '--insetInlineStart': (props.config?.borderLeft ?? 0) + 'px',
-        '--insetInlineEnd': (props.config?.borderRight ?? 0) + 'px',
-        '--insetBlockStart': (props.config?.borderTop ?? 0) + 'px',
-        '--insetBlockEnd': (props.config?.borderBottom ?? 0) + 'px',
+        '--_inset-inline-start': (props.config?.borderLeft ?? 0) + 'px',
+        '--_inset-inline-end': (props.config?.borderRight ?? 0) + 'px',
+        '--_inset-block-start': (props.config?.borderTop ?? 0) + 'px',
+        '--_inset-block-end': (props.config?.borderBottom ?? 0) + 'px',
       }"
     >
       <div ref="alertContentRef" class="alert-mask-content-slot">
@@ -31,15 +31,14 @@
 <script setup lang="ts">
 import type { AlertMaskConfig } from "~/types/components";
 
-const props = defineProps({
-  config: {
-    type: Object as PropType<AlertMaskConfig>,
-    default: () => ({}),
-  },
-  styleClassPassthrough: {
-    type: [String, Array] as PropType<string | string[]>,
-    default: () => [],
-  },
+interface Props {
+  config?: AlertMaskConfig;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  config: () => ({}),
+  styleClassPassthrough: () => [],
 });
 
 const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
@@ -136,13 +135,13 @@ const innerPath = computed(() => {
   .alert-mask-decorator {
     grid-area: mask;
     width: 100%;
-    height: var(--alertHeight);
+    height: var(--_height);
   }
 
   .alert-mask-content {
     grid-area: mask;
-    margin-block: var(--insetBlockStart) var(--insetBlockEnd);
-    margin-inline: var(--insetInlineStart) var(--insetInlineEnd);
+    margin-block: var(--_inset-block-start) var(--_inset-block-end);
+    margin-inline: var(--_inset-inline-start) var(--_inset-inline-end);
   }
 }
 }

package/app/components/01.atoms/alert-mask/CONSUMER-STYLING.md

@@ -0,0 +1,46 @@
+# AlertMaskCore — Consumer Styling Guide
+
+## No public CSS token API
+
+`AlertMaskCore` draws its border/background via an SVG `<mask>` whose path geometry is computed
+from measured content dimensions, so it can't expose colour/radius/thickness as CSS custom
+properties the way most components do — a `var()` can't be interpolated into an SVG path or
+resized reactively the way a `fill` attribute can. Instead, the override surface is the `config`
+prop (`AlertMaskConfig`):
+
+```vue
+<AlertMaskCore
+  :config="{
+    backgroundColour: '#1a1a1a',
+    borderColour: 'var(--theme-accent)',
+    radiusLeft: 8,
+    radiusRight: 4,
+    borderLeft: 6,
+    borderTop: 1,
+    borderRight: 1,
+    borderBottom: 1,
+  }"
+>
+  <p>Alert content</p>
+</AlertMaskCore>
+```
+
+All fields are optional and fall back to `backgroundColour: "rgba(0,0,0,0.25)"`,
+`borderColour: "var(--orange-08)"`, `radiusLeft`/`radiusRight: 12`, `borderLeft`/`borderTop`/
+`borderRight`/`borderBottom: 8`.
+
+## Class passthrough
+
+Use `styleClassPassthrough` to add classes to the root `.alert-mask-core` element for layout
+purposes (positioning, sizing) — it doesn't affect the mask's own colours or geometry, which stay
+governed by `config`.
+
+```vue
+<AlertMaskCore style-class-passthrough="my-alert-mask">...</AlertMaskCore>
+```
+
+## Internal (non-overridable) custom properties
+
+`--_height`, `--_inset-inline-start`, `--_inset-inline-end`, `--_inset-block-start`, and
+`--_inset-block-end` are set inline from measured content size and `config` border widths. They're
+private implementation plumbing, not a consumer override surface — use `config` instead.

package/app/components/01.atoms/alert-mask/stories/AlertMaskCore.stories.ts

@@ -0,0 +1,79 @@
+import AlertMaskCore from "../AlertMaskCore.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof AlertMaskCore> = {
+  title: "Atoms/AlertMaskCore",
+  component: AlertMaskCore,
+  argTypes: {
+    config: {
+      control: "object",
+      description:
+        "Border/background colour and geometry: backgroundColour, borderColour, radiusLeft, radiusRight, borderLeft, borderTop, borderRight, borderBottom",
+      table: { category: "Basic" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Draws a border/background mask around slotted content via an SVG path, sized to the measured content. Colour and geometry are set via the `config` prop, not CSS tokens — see CONSUMER-STYLING.md.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof AlertMaskCore>;
+
+export const Default: Story = {
+  args: {
+    config: {},
+  },
+  render: (args) => ({
+    components: { AlertMaskCore },
+    setup() {
+      return { args };
+    },
+    template: `
+      <AlertMaskCore v-bind="args">
+        <p style="margin: 0; padding: 1.6rem; color: white;">Default alert mask content</p>
+      </AlertMaskCore>
+    `,
+  }),
+};
+
+export const CustomConfig: Story = {
+  args: {
+    config: {
+      backgroundColour: "rgba(0, 0, 0, 0.3)",
+      borderColour: "var(--theme-accent)",
+      radiusLeft: 8,
+      radiusRight: 4,
+      borderLeft: 6,
+      borderTop: 1,
+      borderRight: 1,
+      borderBottom: 1,
+    },
+  },
+  render: (args) => ({
+    components: { AlertMaskCore },
+    setup() {
+      return { args };
+    },
+    template: `
+      <AlertMaskCore v-bind="args">
+        <p style="margin: 0; padding: 1.6rem; color: white;">Custom accent-bar config, matching AlertMaskedContent's default shape</p>
+      </AlertMaskCore>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "The accent-bar shape used by AlertMaskedContent: thick left radius/border, thin elsewhere.",
+      },
+    },
+  },
+};

package/app/components/{alert-mask → 01.atoms/alert-mask}/tests/AlertMaskCore.spec.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import AlertMaskCore from "../AlertMaskCore.vue";
-import type { AlertMaskConfig } from "../../../types/components/alert-mask-core.d";
+import type { AlertMaskConfig } from "../../../../types/components/alert-mask-core.d";
 
 // Type interface for AlertMaskCore component instance
 interface AlertMaskCoreInstance {
@@ -193,10 +193,10 @@ describe("AlertMaskCore", () => {
     const contentEl = wrapper.find(".alert-mask-content");
     const style = (contentEl.element as HTMLElement).style;
 
-    expect(style.getPropertyValue("--insetInlineStart")).toBe("15px");
-    expect(style.getPropertyValue("--insetBlockStart")).toBe("20px");
-    expect(style.getPropertyValue("--insetInlineEnd")).toBe("25px");
-    expect(style.getPropertyValue("--insetBlockEnd")).toBe("30px");
+    expect(style.getPropertyValue("--_inset-inline-start")).toBe("15px");
+    expect(style.getPropertyValue("--_inset-block-start")).toBe("20px");
+    expect(style.getPropertyValue("--_inset-inline-end")).toBe("25px");
+    expect(style.getPropertyValue("--_inset-block-end")).toBe("30px");
   });
 
   it("handles zero border values correctly", async () => {
@@ -214,10 +214,10 @@ describe("AlertMaskCore", () => {
     const contentEl = wrapper.find(".alert-mask-content");
     const style = (contentEl.element as HTMLElement).style;
 
-    expect(style.getPropertyValue("--insetInlineStart")).toBe("0px");
-    expect(style.getPropertyValue("--insetBlockStart")).toBe("0px");
-    expect(style.getPropertyValue("--insetInlineEnd")).toBe("0px");
-    expect(style.getPropertyValue("--insetBlockEnd")).toBe("0px");
+    expect(style.getPropertyValue("--_inset-inline-start")).toBe("0px");
+    expect(style.getPropertyValue("--_inset-block-start")).toBe("0px");
+    expect(style.getPropertyValue("--_inset-inline-end")).toBe("0px");
+    expect(style.getPropertyValue("--_inset-block-end")).toBe("0px");
   });
 
   it("sets up ResizeObserver on mount", async () => {
@@ -271,7 +271,7 @@ describe("AlertMaskCore", () => {
 
     const svg = wrapper.find(".alert-mask-decorator");
     const style = (svg.element as HTMLElement).style;
-    expect(style.getPropertyValue("--alertHeight")).toBe("150px");
+    expect(style.getPropertyValue("--_height")).toBe("150px");
   });
 
   it("handles empty configuration object", async () => {

package/app/components/01.atoms/animations/container-glow/CONSUMER-STYLING.md

@@ -0,0 +1,86 @@
+# ContainerGlow — Consumer Styling Guide
+
+## Public CSS custom properties
+
+These are static, per-card visual tokens — override them with a `style` attribute or from a
+consuming page's own stylesheet:
+
+| Token | Default | Description |
+|---|---|---|
+| `--container-glow-background` | `white` | Card background colour. |
+| `--container-glow-padding` | `2rem` | Card inner padding. |
+| `--container-glow-aspect-ratio` | `330 / 400` | Card aspect ratio. |
+| `--container-glow-border-radius` | `12px` | Card and glow-effect corner radius (shared by the card and every glow layer). |
+| `--container-glow-min-width` | `280px` | Card minimum width. |
+| `--container-glow-max-width` | `280px` | Card maximum width. |
+| `--container-glow-content-gap` | `0.25rem` | Gap between a card's own slotted children. |
+| `--container-glow-highlight-colour` | `hsl(280 10% 50% / 1)` | Tint of the thin proximity-tracking ring drawn under the coloured glow. |
+| `--container-glow-brightness` | `1.5` | Brightness multiplier applied to the coloured glow layer. |
+| `--container-glow-transition-duration` | `1s` | Fade duration when the glow's opacity changes (also disabled under `prefers-reduced-motion: reduce`). |
+| `--container-glow-gradient` | 5-stop conic rainbow gradient | The glow's colour gradient. Override with any valid `background` value (a `conic-gradient(...)`, a flat colour, etc). |
+
+```vue
+<ContainerGlow
+  style="--container-glow-background: #111; --container-glow-border-radius: 4px; --container-glow-gradient: conic-gradient(from 180deg, #22d3ee, #a855f7, #22d3ee);"
+>
+  <template #cta>
+    <p>Custom-coloured glow card</p>
+  </template>
+</ContainerGlow>
+```
+
+## The `config` prop (layout and interaction behaviour)
+
+Proximity distance, glow spread/blur, wrapper gap, wrapper direction, and the inactive-state
+opacity are **not** CSS tokens — they're computed per-pointer-move in JavaScript and applied as
+private custom properties, so they're driven entirely by the `config` prop instead
+(`ContainerGlowConfig`, importable from `srcdev-nuxt-components`):
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `proximity` | `number` | `40` | Pointer distance (px) at which a card starts glowing. |
+| `spread` | `number` | `80` | Angular spread of the glow (degrees). |
+| `blur` | `number` | `20` | Blur applied to the glow layer (px). |
+| `gap` | `number` | `32` | Gap between cards in the wrapper (px). |
+| `vertical` | `boolean` | `false` | Stack cards vertically instead of horizontally. |
+| `inactiveOpacity` | `number` | `0` | Glow opacity when the pointer isn't nearby. |
+
+All fields are optional — pass only the ones you want to change:
+
+```vue
+<ContainerGlow :config="{ blur: 40, vertical: true }">
+  <template #one><p>Card one</p></template>
+  <template #two><p>Card two</p></template>
+</ContainerGlow>
+```
+
+## Named dynamic slots
+
+Each named slot renders as one glow card — the consumer controls the slot names, there's no
+`itemCount`-style prop:
+
+```vue
+<ContainerGlow>
+  <template #pricing><p>Starter</p></template>
+  <template #featured><p>Pro</p></template>
+</ContainerGlow>
+```
+
+## Motion
+
+The glow's opacity fade (`--container-glow-transition-duration`) is disabled under
+`prefers-reduced-motion: reduce`, so proximity changes are instant rather than animated.
+
+## Class passthrough
+
+Use `styleClassPassthrough` to add classes to the root `.container-glow-wrapper` element.
+
+```vue
+<ContainerGlow style-class-passthrough="my-container-glow">...</ContainerGlow>
+```
+
+## Internal (non-overridable) custom properties
+
+`--_start`, `--_opacity-active`, `--_gap`, `--_blur`, `--_spread`, `--_direction`, and `--_gradient`
+are internal plumbing driven by pointer events and the `config` prop — use `config` (for
+gap/blur/spread/direction/opacity) or the public tokens above (for colour/geometry) instead.