srcdev-nuxt-components 9.1.50 → 9.1.52

package/.claude/settings.json

@@ -1,33 +1,14 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npx vitest run app/components/01.atoms/content-wrappers/layout-grid/tests/LayoutGrid.spec.ts)",
-      "Bash(npx vitest run app/components/01.atoms/content-wrappers/layout-grid/tests/LayoutGrid.spec.ts --update-snapshots)",
-      "Bash(npx vitest run app/components/01.atoms/content-wrappers/layout-grid/tests/LayoutGrid.spec.ts -u)",
-      "Bash(npx vitest run app/components/01.atoms/content-wrappers/content-width/tests/ContentWidth.spec.ts)",
-      "Bash(node -e \":*)",
-      "Bash(git add app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/LayoutGridByCols.vue app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/tests/LayoutGridByCols.spec.ts app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/tests/__snapshots__/LayoutGridByCols.spec.ts.snap app/pages/forms/examples/buttons/index.vue app/pages/forms/examples/material/checkbox-radio-panels.vue app/pages/forms/examples/material/text-fields.vue)",
-      "Bash(git commit:*)",
-      "Bash(npx vitest run app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-width/tests/LayoutGridByWidth.spec.ts)",
-      "Bash(npx vitest run app/components/01.atoms/card/tests/CardCore.spec.ts)",
-      "Bash(npx vitest run app/components/image-galleries/slider-gallery/tests/SliderGallery.spec.ts)",
-      "Bash(npx vitest run)",
-      "Bash(git mv:*)",
-      "Bash(npx tsc:*)",
-      "Bash(npx vitest:*)",
-      "Bash(git show:*)",
-      "Edit(/.claude/skills/components/**)",
-      "Bash(npx nuxi:*)",
-      "Bash(npx vue-tsc:*)",
-      "Bash(npm install:*)",
-      "Bash(npm run:*)",
-      "Bash(git add:*)",
-      "Bash(gh release:*)",
-      "Bash(node -e ':*)",
-      "Bash(git ls-tree *)",
-      "Bash(node -p \"require\\('./package.json'\\).version\")",
-      "Bash(git status *)",
-      "Bash(xargs ls -1)"
+      "Bash(grep -v \"^+\\\\s*$\\\\|^-\\\\s*$\")",
+      "Bash(python3 -c \"import json,sys; p=json.load\\(sys.stdin\\); print\\('main:', p.get\\('main'\\)\\); exp=p.get\\('exports',{}\\).get\\('.',{}\\); print\\('exports .:', exp\\)\")",
+      "Bash(node -e \"const p = require\\('/Users/simoncornforth/websites/nuxt-components/.output/server/node_modules/vue/package.json'\\); console.log\\(JSON.stringify\\(p.exports, null, 2\\)\\)\")",
+      "Bash(node .output/server/index.mjs)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:3000/)",
+      "Bash(kill %1)",
+      "Bash(xargs kill -9)",
+      "Edit(/.claude/skills/components/**)"
     ]
   }
 }

package/.claude/settings.local.json

@@ -1,66 +1,38 @@
 {
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "grep -q '/Users/' .claude/settings.json 2>/dev/null && { echo 'settings.json contains absolute paths — move them to settings.local.json' >&2; exit 1; } || exit 0"
-          }
-        ]
-      }
-    ]
-  },
   "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)",
+      "mcp__ide__getDiagnostics",
+      "Bash(npm run:*)",
+      "Bash(npm install:*)",
+      "Bash(npm audit *)",
+      "Bash(npm ls *)",
+      "Bash(npx vitest:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx vue-tsc:*)",
+      "Bash(npx nuxi:*)",
+      "Bash(git add:*)",
+      "Bash(git mv:*)",
+      "Bash(git show:*)",
+      "Bash(git status *)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git ls-tree *)",
+      "Bash(git commit:*)",
+      "Bash(gh release:*)",
+      "Edit(/.claude/skills/components/**)",
+      "Bash(git -C /Users/simoncornforth/websites/nuxt-components *)",
       "Bash(ls -la /Users/simoncornforth/websites/luxury-locs-by-natasha-nuxt3/.env*)",
-      "Bash(node -e \"const t = require\\('/Users/simoncornforth/websites/nuxt-components/node_modules/pinia-plugin-persistedstate'\\); console.log\\(Object.keys\\(t\\)\\)\")",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components log --oneline -5)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 16ac4ef --stat)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components log --oneline -8)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 5597a15 --stat)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 5597a15 -- \"*.vue\" \"*.css\")",
-      "Bash(ls /Users/simoncornforth/websites/nuxt-components/*.md)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components status)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components add .claude/skills/components/services-section.md .claude/skills/components/services-section-grid.md .claude/skills/index.md app/components/03.organisms/services/services-grids/ServicesSectionGrid.vue app/components/03.organisms/services/services-section/ServicesSection.vue app/components/03.organisms/services/services-card/stories/ app/components/03.organisms/services/services-card/tests/ app/components/03.organisms/services/services-grids/stories/ app/components/03.organisms/services/services-grids/tests/ app/components/03.organisms/services/services-section/stories/ app/components/03.organisms/services/services-section/tests/)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components commit -m ':*)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components log --oneline v9.1.22..HEAD)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components log --oneline c401cea..HEAD)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 3058d63 --stat)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 0f99d7a --stat)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff app/components/parallax/SectionParallax.vue)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff HEAD app/components/parallax/SectionParallax.vue)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff --cached)",
-      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/components/02.molecules/samaritan-prompt)",
-      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/composables/tests/useCancellableTimer app/components/02.molecules/samaritan-prompt/tests/SamaritanPromptMixed)",
-      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/components/02.molecules/samaritan-prompt/tests/SamaritanPromptMixed)",
-      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/composables/tests/useCancellableTimer)",
-      "Bash(SRCDEV_STANDALONE=true npm run test:run -- --reporter=verbose)",
-      "Bash(cp /Users/simoncornforth/websites/nuxt-components/.claude/skills/components/data-grid.md /Users/simoncornforth/websites/nuxt-components/.claude/skills/components/auto-grid.md)",
-      "Bash(rm /Users/simoncornforth/websites/nuxt-components/.claude/skills/components/data-grid.md)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components log --oneline -10)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components log 5a80426..HEAD --oneline)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 71c276e --stat)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show a1e1641 --stat)"
+      "Bash(ls /Users/simoncornforth/websites/nuxt-components/*.md)"
     ],
     "additionalDirectories": [
-      "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/content-wrappers/content-width",
       "/Users/simoncornforth/websites/nuxt-components/.claude/skills",
       "/Users/simoncornforth/websites/nuxt-components/.claude/skills/components",
-      "/Users/simoncornforth/websites/nuxt-components/app/components/02.molecules/navigation/site-navigation/tests",
-      "/Users/simoncornforth/websites/luxury-locs-by-natasha-nuxt3/app/pages",
-      "/Users/simoncornforth/websites/nuxt-components/app/assets/styles/extends-layer",
       "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms",
-      "/private/tmp",
-      "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/banner-video",
-      "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/page-row"
+      "/Users/simoncornforth/websites/nuxt-components/app/assets/styles/extends-layer",
+      "/Users/simoncornforth/websites/luxury-locs-by-natasha-nuxt3/app/pages",
+      "/private/tmp"
     ]
   }
 }

package/.claude/skills/components/action-menu.md

@@ -0,0 +1,141 @@
+# ActionMenu
+
+## Overview
+
+`ActionMenu` is a trigger-and-popover component that shows a compact ellipsis button (`lucide:ellipsis`).
+Clicking it opens an anchored menu list populated via indexed dynamic slots (`item-{n}`). Each slot
+should contain a single `ActionMenuItemCore` — either a `<button>` (for actions) or a link (for
+navigation). The popover API and CSS anchor positioning handle positioning and dismiss behaviour
+natively; no JavaScript click-outside logic is needed.
+
+**Location**: `app/components/02.molecules/action-menu/`
+
+---
+
+## Components
+
+### ActionMenu
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `itemCount` | `number` | `0` | Number of `item-{n}` slots to render. |
+| `label` | `string` | `"Open actions menu"` | Used as `aria-label` on the trigger and `aria-label` on the menu list. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the root `<div>`. |
+
+**Slots**
+
+| Slot | When used |
+|---|---|
+| `item-{n}` | One per item, where `n` is 0-indexed up to `itemCount - 1`. Should contain one `ActionMenuItemCore`. |
+
+---
+
+### ActionMenuItemCore
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | — | **Required.** Visible text for the row. |
+| `href` | `string` | `undefined` | If set, renders as `<a>` (external) or `NuxtLink` (internal `/…` path). Omit for a `<button>`. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the root element. |
+
+**Slots**
+
+| Slot | Content |
+|---|---|
+| `#icon` | Optional left icon (e.g. `<Icon name="lucide:pencil" />`). Wrapped in `aria-hidden` span. |
+
+**Emits**
+
+| Event | Payload | Notes |
+|---|---|---|
+| `click` | `MouseEvent` | Fired on every click regardless of whether the item is a button or link. |
+
+**Notes on routing**
+- Internal paths (`/…`) resolve to `<NuxtLink>` via `resolveComponent`.
+- External URLs or relative paths without a leading `/` render as plain `<a>`.
+- `type="button"` is set automatically on `<button>` elements to prevent accidental form submission.
+
+---
+
+## Basic usage
+
+```vue
+<ActionMenu :item-count="3" label="Row actions">
+  <template #item-0>
+    <ActionMenuItemCore label="Edit" @click="handleEdit">
+      <template #icon><Icon name="lucide:pencil" /></template>
+    </ActionMenuItemCore>
+  </template>
+  <template #item-1>
+    <ActionMenuItemCore label="View detail" href="/records/123">
+      <template #icon><Icon name="lucide:eye" /></template>
+    </ActionMenuItemCore>
+  </template>
+  <template #item-2>
+    <ActionMenuItemCore label="Delete" @click="handleDelete">
+      <template #icon><Icon name="lucide:trash-2" /></template>
+    </ActionMenuItemCore>
+  </template>
+</ActionMenu>
+```
+
+---
+
+## Link vs button items
+
+| Scenario | Use |
+|---|---|
+| Triggers a JS handler (delete, share, copy…) | Omit `href` — renders as `<button>` |
+| Navigates to an internal Nuxt route | `href="/path"` — renders as `<NuxtLink>` |
+| Navigates to an external URL | `href="https://…"` — renders as `<a>` |
+
+---
+
+## CSS token API
+
+See `CONSUMER-STYLING.md` in the component folder for the full token reference and override
+examples. Prefer global CSS for action menus — they appear site-wide in tables, cards, and lists.
+
+Quick reference:
+
+```css
+/* assets/styles/setup/07.components/action-menu.css */
+:root {
+  --action-menu-block-distance: 0.6rem;
+  --action-menu-trigger-border-radius: 0.4rem;
+  --action-menu-trigger-surface-hover: var(--brand-surface-subtle);
+  --action-menu-trigger-icon-color: var(--brand-text-muted);
+
+  --action-menu-popover-background: var(--brand-surface);
+  --action-menu-popover-border: 0.1rem solid var(--brand-border);
+  --action-menu-popover-border-radius: 0.6rem;
+
+  --action-menu-item-surface-hover: var(--brand-surface-subtle);
+  --action-menu-item-text-color: var(--brand-text);
+}
+```
+
+---
+
+## Notes
+
+- **Popover API + CSS anchor positioning** — the menu uses `popover` attribute and `position-anchor`.
+  Both are broadly supported (Chrome 114+, Firefox 125+, Safari 17+). No polyfill is included.
+- **Auto-close** — clicking any `<li>` row fires `hidePopover()` on the menu. The `ActionMenuItemCore`
+  emitting `click` triggers normally before the menu closes.
+- **Focus management** — on open the `toggle` event fires `handleToggle`, which moves focus to the
+  first `[role="menuitem"]` inside the popover.
+- **Keyboard navigation `currentIndex === -1` guard** — `handleKeydown` computes the current
+  position via `items.indexOf(document.activeElement)`. When focus is outside the menu this returns
+  `-1`. Always guard explicitly before applying wrap-around math: `ArrowDown` should focus
+  `items[0]`; `ArrowUp` should focus `items[items.length - 1]`. Without the guard, the modulo
+  formula gives `items[n-2]` for `ArrowUp` — the second-to-last item instead of the last.
+- **Right-aligned by default** — the menu's right edge aligns with the trigger's right edge
+  (`right: anchor(right)`). Flips above the trigger near the bottom of the viewport
+  (`position-try-fallbacks: flip-block`).
+- **`anchorName` format** — internally generated as `--action-menu-anchor-{id}` (a valid CSS
+  `<dashed-ident>`). Set via a CSS custom property on the root element so both the trigger's
+  `anchor-name` and the popover's `position-anchor` can reference the same value.
+- **Dynamic slots stability** — `item-{n}` slots enforce that only `ActionMenuItemCore` content
+  enters the list; arbitrary HTML inside the popover is not supported and will break the ARIA
+  `menu` / `menuitem` pattern.

package/.claude/skills/components/stepper-list.md

@@ -94,7 +94,7 @@ Counter bubbles are rendered automatically via CSS — no `#indicator-*` slots n
 </StepperList>
 ```
 
-Custom indicator SVGs should use the `indicator-icon` class — it applies `color: var(--stepper-list-icon)` and sizes the icon to match `indicatorSize`.
+Custom indicator SVGs should use the `indicator-icon` class — it applies `color: var(--stepper-list-icon-color)` and sizes the icon to match `indicatorSize`.
 
 ### Mixed — custom icons for completed steps, counters for pending
 
@@ -146,21 +146,44 @@ Custom indicator SVGs should use the `indicator-icon` class — it applies `colo
 
 ## CSS custom properties
 
-Override these in your consuming component or theme to restyle the indicators and connectors:
-
-| Property | Used by |
-|----------|---------|
-| `--stepper-list-counter-disc-background` | Disc variant counter bubble background |
-| `--stepper-list-counter-disc-text` | Disc variant counter number colour |
-| `--stepper-list-counter-disc-border` | Disc variant counter border colour |
-| `--stepper-list-counter-circle-background` | Circle variant counter bubble background |
-| `--stepper-list-counter-circle-text` | Circle variant counter number colour |
-| `--stepper-list-counter-circle-border` | Circle variant counter border colour |
-| `--stepper-list-counter-square-background` | Square variant counter bubble background |
-| `--stepper-list-counter-square-text` | Square variant counter number colour |
-| `--stepper-list-counter-square-border` | Square variant counter border colour |
-| `--stepper-list-connector-color` | Connector line colour (defaults to `currentColor`) |
-| `--stepper-list-icon` | Icon colour for custom `indicator-icon` SVGs |
+All `--stepper-list-*` tokens are the stable consumer override surface. See
+[CONSUMER-STYLING.md](../../../app/components/02.molecules/stepper-list/CONSUMER-STYLING.md)
+for full examples (global theming, page-scoped, and per-instance overrides).
+
+### Layout & sizing
+
+| Token | Default | Controls |
+|---|---|---|
+| `--stepper-list-padding-block` | `1.2rem` | Vertical padding for each list item |
+| `--stepper-list-gap` | `2.2rem` | Horizontal gap between indicator and content |
+| `--stepper-list-counter-size` | prop `indicatorSize` (`3rem`) | Counter bubble / icon width and height |
+| `--stepper-list-counter-font-size` | `1.4rem` | Counter number font size |
+| `--stepper-list-counter-font-weight` | `600` | Counter number font weight |
+| `--stepper-list-connector-width` | `0.2rem` | Connector line thickness |
+
+### Colours
+
+| Token | Default | Controls |
+|---|---|---|
+| `--stepper-list-connector-color` | `currentColor` | Connector line colour |
+| `--stepper-list-icon-color` | `currentColor` | Icon colour for custom `indicator-icon` elements |
+
+### Per-variant tokens
+
+| Token | Default | Controls |
+|---|---|---|
+| `--stepper-list-counter-circle-background` | `transparent` | Circle bubble fill |
+| `--stepper-list-counter-circle-text` | `currentColor` | Circle counter number colour |
+| `--stepper-list-counter-circle-border` | `currentColor` | Circle bubble border colour |
+| `--stepper-list-counter-circle-border-radius` | `100vw` | Circle bubble corner rounding |
+| `--stepper-list-counter-disc-background` | `transparent` | Disc bubble fill |
+| `--stepper-list-counter-disc-text` | `currentColor` | Disc counter number colour |
+| `--stepper-list-counter-disc-border` | `transparent` | Disc bubble border colour |
+| `--stepper-list-counter-disc-border-radius` | `100vw` | Disc bubble corner rounding |
+| `--stepper-list-counter-square-background` | `transparent` | Square bubble fill |
+| `--stepper-list-counter-square-text` | `currentColor` | Square counter number colour |
+| `--stepper-list-counter-square-border` | `transparent` | Square bubble border colour |
+| `--stepper-list-counter-square-border-radius` | `0.25rem` | Square bubble corner rounding |
 
 ---
 
@@ -192,23 +215,34 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
    ─────────────────────────────────────────────────────────────────── */
 .stepper-list {
   &.my-stepper {
+    /* Layout & sizing */
+    /* --stepper-list-padding-block: 1.2rem; */
+    /* --stepper-list-gap: 2.2rem; */
+    /* --stepper-list-counter-size: 3rem; */
+    /* --stepper-list-counter-font-size: 1.4rem; */
+    /* --stepper-list-counter-font-weight: 600; */
+    /* --stepper-list-connector-width: 0.2rem; */
+
     /* Counter bubble — disc variant */
     /* --stepper-list-counter-disc-background: var(--brand-primary); */
     /* --stepper-list-counter-disc-text: white; */
     /* --stepper-list-counter-disc-border: transparent; */
+    /* --stepper-list-counter-disc-border-radius: 100vw; */
 
     /* Counter bubble — circle variant */
     /* --stepper-list-counter-circle-background: transparent; */
     /* --stepper-list-counter-circle-text: var(--brand-primary); */
     /* --stepper-list-counter-circle-border: var(--brand-primary); */
+    /* --stepper-list-counter-circle-border-radius: 100vw; */
 
     /* Counter bubble — square variant */
     /* --stepper-list-counter-square-background: var(--brand-primary); */
     /* --stepper-list-counter-square-text: white; */
     /* --stepper-list-counter-square-border: transparent; */
+    /* --stepper-list-counter-square-border-radius: 0.25rem; */
 
     /* Custom indicator icon colour */
-    /* --stepper-list-icon: var(--brand-primary); */
+    /* --stepper-list-icon-color: var(--brand-primary); */
 
     /* Connector line */
     /* --stepper-list-connector-color: var(--brand-primary); */
@@ -223,5 +257,5 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 
 - Always keep `itemCount` in sync with the number of `#item-*` slots you provide — mismatches will render empty `<li>` rows.
 - Slot names are **zero-indexed** — `#item-0` not `#item-1`.
-- The `indicator-icon` class is defined inside the component CSS and sizes the SVG to `var(--_counter-size)` (driven by `indicatorSize`). Always add it to custom SVGs.
+- The `indicator-icon` class is defined inside the component CSS and sizes the SVG to `var(--_counter-size)` (driven by `indicatorSize` or `--stepper-list-counter-size`). Always add it to custom SVGs.
 - Auto-imported in Nuxt — no manual import needed.

package/.claude/skills/css-nesting-conventions.md

@@ -0,0 +1,121 @@
+# CSS Nesting Conventions
+
+## Overview
+
+This project uses **native CSS nesting** (W3C CSS Nesting spec), not Sass/SCSS. They look similar but behave differently in one important way: native CSS does not support BEM-style `&` concatenation for child element selectors.
+
+## The key rule
+
+> `&` must be followed by a combinator (space, `>`, `~`, `+`) or a selector starting with `.`, `#`, `:`, `[`, or `*`. It **cannot** be followed by a bare identifier or `__` prefix.
+
+## ❌ What NOT to do — Sass-style BEM concatenation
+
+```css
+/* Sass/SCSS — does NOT work in native CSS */
+.demo-controls {
+  padding: 1.6rem;
+
+  &__heading {        /* ← Invalid native CSS — esbuild converts to :is(__heading) */
+    font-size: 1.1rem;
+  }
+
+  &__fields {         /* ← Invalid native CSS */
+    display: flex;
+  }
+}
+```
+
+**Why it silently fails**: esbuild converts `&__heading` to `:is(__heading)`, which tries to match an HTML element named `__heading`. No such element exists, so the styles are never applied. There's no error — just missing styles.
+
+The build will show this warning:
+```
+▲ [WARNING] Cannot use type selector "__heading" directly after nesting selector "&" [css-syntax-error]
+  CSS nesting syntax does not allow the "&" selector to come before a type selector.
+```
+
+## ✅ Correct patterns
+
+### Nested descendant (preferred for BEM child elements)
+
+```css
+.demo-controls {
+  padding: 1.6rem;
+
+  & .demo-controls__heading {   /* space + full class name */
+    font-size: 1.1rem;
+  }
+
+  & .demo-controls__fields {
+    display: flex;
+  }
+}
+```
+
+### Flat top-level rules (also valid — avoids repetition for deeply nested structures)
+
+```css
+.demo-controls {
+  padding: 1.6rem;
+}
+
+.demo-controls__heading {
+  font-size: 1.1rem;
+}
+
+.demo-controls__fields {
+  display: flex;
+}
+```
+
+### Same-element modifier (this IS valid)
+
+```css
+/* & followed by a class — matches the same element that also has this class */
+.button {
+  background: blue;
+
+  &.button--large {   /* ← valid: & immediately followed by . */
+    padding: 2rem;
+  }
+
+  &:hover {           /* ← valid: & immediately followed by : */
+    background: darkblue;
+  }
+
+  &[disabled] {       /* ← valid: & immediately followed by [ */
+    opacity: 0.5;
+  }
+}
+```
+
+### Pseudo-elements and pseudo-classes
+
+```css
+.component {
+  &::before { content: ""; }    /* ✅ valid */
+  &::after  { content: ""; }    /* ✅ valid */
+  &:focus   { outline: auto; }  /* ✅ valid */
+  &:not(.active) { opacity: 0.5; }  /* ✅ valid */
+}
+```
+
+### Media / container queries inside a rule
+
+```css
+.component {
+  grid-template-columns: 1fr;
+
+  @media (width >= 768px) {
+    grid-template-columns: 1fr 2fr;  /* ✅ valid — query wraps the property */
+  }
+}
+```
+
+## Spot-check during review
+
+If you see `&__` or `&-` in a `.vue` `<style lang="css">` block, it's Sass syntax and will not work. Convert it to `& .full-class-name` or lift it to a top-level rule.
+
+## Related
+
+- `CLAUDE.md` → Styling Methodology section
+- `css-grid-max-width-gutters.md` — example of correct native nesting in a grid utility

package/.claude/skills/index.md

@@ -33,6 +33,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── component-dynamic-slots.md        — named dynamic slots ($slots iteration) vs indexed dynamic slots (itemCount pattern)
 ├── component-local-style-override.md — styleClassPassthrough + scoped style block for per-usage visual customisation
 ├── component-prop-driven-container-layout.md — vary CSS grid layout inside @container queries using data-* attribute selectors
+├── css-nesting-conventions.md                — native CSS nesting rules: why &__child Sass BEM concatenation silently breaks, correct patterns
 ├── css-grid-max-width-gutters.md             — cap a centre grid column width by growing gutters, with start/center alignment variants
 ├── css-animation-utilities.md                — scroll-driven animation utility classes: scroller-x (carousel), entry-zoom-reveal, entry-slide-in, entry-exit-blur, auto-rotate
 ├── component-aria-landmark.md        — useAriaLabelledById composable: aria-labelledby for section/main/article/aside tags
@@ -44,6 +45,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── new-app-scaffold.md               — scaffold a new Nuxt consumer app extending this layer (package.json, nuxt.config, app structure, CLAUDE.md)
 ├── qa-panel.md                       — collapsible dev-only panel for toggling component props live on a page (demo pages and consuming apps)
 ├── release-notes.md                  — produce release notes as a fenced markdown block from git log
+├── pull-request-description.md       — produce a PR description as a fenced markdown block from git diff vs main
 ├── composable-canonical-url.md       — useCanonicalUrl: set <link rel="canonical"> from runtimeConfig.public.canonicalHost; layout setup, node types
 ├── composable-whatsapp.md            — useWhatsApp: open pre-filled wa.me link from form payload; runtime config, security, usage
 ├── composable-zod-validation.md      — useZodValidation: schema-driven form validation, error binding, submit flow, API error push
@@ -82,6 +84,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── auto-grid.md            — AutoGrid: auto-fit responsive grid, $slots iteration, --auto-grid-min-col-size/gap tokens, semantic tag + aria
     ├── display-avatar.md       — DisplayAvatar: circular avatar with image/initials fallback, size variants, chip badge, icon slot, styleClassPassthrough
     ├── card-core.md            — CardCore: generic card container, dynamic named slots as rows, 4 variants, blurred backdrop layer, full CSS token API
+    ├── action-menu.md          — ActionMenu + ActionMenuItemCore: ellipsis trigger + anchored popover menu, indexed item-{n} slots, link/button items, full CSS token API
     ├── display-dialog.md       — DisplayDialog: native <dialog> overlay, 5 variants (dialog/modal/confirm/alert/fullscreen), useDialogControls integration, CSS token API
     ├── display-chip.md         — DisplayChip: status indicator chip overlay, CSS trig positioning, circle/square shapes, status colours, icon/label content
     ├── display-pill.md         — DisplayPill: pill/badge label with icon slot, 6 variants, 3 sizes, reversible order, full CSS token API for border/outline/colour

package/.claude/skills/pull-request-description.md

@@ -0,0 +1,48 @@
+# Pull Request Description
+
+## Overview
+
+When asked to create a pull request description, produce a fenced markdown code block (` ```markdown `) so the content can be copied and pasted directly into GitHub's PR body field without formatting being stripped.
+
+## Steps
+
+### 1. Identify the base branch
+
+Run `git log --oneline main..HEAD` to list all commits on the current branch since it diverged from `main`.
+
+### 2. Review what changed
+
+Run `git diff main...HEAD --stat` for a file-level summary, then `git diff main...HEAD` for the full diff. Focus on intent, not just mechanics.
+
+### 3. Produce a fenced markdown block
+
+Always wrap the output in a ` ```markdown ` code fence — never render it as plain markdown.
+
+## Format
+
+```markdown
+## Summary
+
+One or two sentences explaining what this PR does and why. No bullet points here — write it as prose.
+
+## Changes
+
+- **`FileOrComponentName`** — what changed and why
+- Keep each bullet to one line where possible
+
+## Testing
+
+- How the change was verified (unit tests, manual check, build passing, etc.)
+- Note any areas that couldn't be covered automatically
+
+## Notes
+
+Any caveats, follow-up tickets, or decisions worth flagging for reviewers (optional — omit if nothing to say).
+```
+
+## Notes
+
+- Only include sections that have content — omit empty headings (especially `Notes` if there's nothing to flag)
+- Lead with the user-facing or functional change; CSS/test/doc tidy-ups can be secondary bullets
+- Keep the tone factual — describe what changed, not the effort involved
+- Do not include "Co-Authored-By" or other git trailer lines — those belong in the commit message, not the PR body

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

@@ -37,6 +37,7 @@ describe("ComponentName", () => {
 
   afterEach(() => {
     wrapper?.unmount();
+    vi.restoreAllMocks(); // always restore vi.spyOn() stubs after each test
   });
 
   // -------------------------
@@ -162,7 +163,7 @@ it("exposes headingId via scoped slot", async () => {
 ## Key rules
 
 - Always `mountSuspended` — never `mount` or `shallowMount` from `@vue/test-utils` directly.
-- Always `afterEach(() => wrapper?.unmount())` to prevent test leaks.
+- Always call both `wrapper?.unmount()` and `vi.restoreAllMocks()` in `afterEach`. The unmount cleans up Vue; the restore cleans up any `vi.spyOn()` stubs so they don't leak into later test files.
 - 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"`.
@@ -285,7 +286,9 @@ Import the child component directly in the test file — it is not auto-imported
 
 ## Mocking browser APIs
 
-Mock before the `describe` block if the component uses ResizeObserver, IntersectionObserver, etc.:
+### Global constructors (ResizeObserver, IntersectionObserver, etc.)
+
+Use `vi.stubGlobal` before the `describe` block. Do **not** call `vi.unstubAllGlobals()` in `afterEach` — it removes stubs from `vitest.setup.ts` (`$fetch`, etc.):
 
 ```ts
 const mockResizeObserver = vi.fn(() => ({
@@ -296,6 +299,41 @@ const mockResizeObserver = vi.fn(() => ({
 vi.stubGlobal("ResizeObserver", mockResizeObserver);
 ```
 
+### Prototype methods (Popover API, Canvas, etc.)
+
+When an API is missing from jsdom entirely (e.g. `hidePopover`, `showPopover`) use `Object.defineProperty` in `beforeEach`. **`vi.restoreAllMocks()` does not clean these up** — delete them explicitly in `afterEach`:
+
+```ts
+beforeEach(() => {
+  // vi.spyOn stubs are cleaned by vi.restoreAllMocks() in afterEach
+  vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue({} as never);
+
+  // Object.defineProperty stubs are NOT cleaned by vi.restoreAllMocks() —
+  // must be deleted explicitly to prevent leaking into other test files
+  Object.defineProperty(HTMLElement.prototype, "hidePopover", {
+    value: vi.fn(),
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(HTMLElement.prototype, "showPopover", {
+    value: vi.fn(),
+    writable: true,
+    configurable: true,
+  });
+});
+
+afterEach(() => {
+  wrapper?.unmount();
+  vi.restoreAllMocks(); // cleans up vi.spyOn stubs
+  // Remove Object.defineProperty prototype stubs — vi.restoreAllMocks() won't touch these
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>)["hidePopover"];
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>)["showPopover"];
+});
+```
+
+The `as unknown as Record<string, unknown>` double-cast is required because TypeScript's
+`HTMLElement` type has no index signature — cast through `unknown` first.
+
 ## Describe section conventions
 
 Use these section names consistently so tests are easy to scan: