srcdev-nuxt-components 9.1.20 → 9.1.21

package/.claude/settings.json

@@ -26,7 +26,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(npm install:*)",
-      "Bash(npm run:*)"
+      "Bash(npm run:*)",
+      "Bash(git add:*)"
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/content-wrappers/content-width",

package/.claude/skills/component-dynamic-slots.md

@@ -138,6 +138,72 @@ Some components pair multiple slot types per index (e.g. TabsCore):
 
 ---
 
+## Pattern 3 — Prefixed Slot Inference
+
+The component iterates over a **named subset** of provided slots, filtered by a prefix pattern. Consumer adds `profile-info-1`, `profile-info-2`, etc. and the component renders exactly those — no count prop required.
+
+Use this when:
+
+- Slot names follow a predictable prefix+index convention (`prefix-N`)
+- The component should render however many the consumer passes, without needing a count prop kept in sync
+- A fallback count is still useful for demos/Storybook when no matching slots are provided
+
+### Implementation
+
+```vue
+<template>
+  <div v-for="slotName in prefixedSlots" :key="slotName" class="item-block">
+    <slot :name="slotName">
+      <p>Fallback content for {{ slotName }}</p>
+    </slot>
+  </div>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  itemCount?: number; // fallback only — used when no matching slots are provided
+}
+const props = withDefaults(defineProps<Props>(), { itemCount: 3 });
+
+const slots = useSlots();
+
+const prefixedSlots = computed(() => {
+  const provided = Object.keys(slots)
+    .filter((key) => /^my-prefix-\d+$/.test(key))
+    .sort((a, b) => parseInt(a.split("-")[2] ?? "0") - parseInt(b.split("-")[2] ?? "0"));
+  return provided.length > 0
+    ? provided
+    : Array.from({ length: props.itemCount }, (_, i) => `my-prefix-${i + 1}`);
+});
+</script>
+```
+
+### Key details
+
+- `useSlots()` is required (not `$slots`) because the filtering logic lives in `<script setup>`
+- Sort numerically, not lexicographically — `"10"` must come after `"9"`
+- The `itemCount` fallback keeps demos and Storybook working without needing real slot content
+- Do **not** pass `:heading-id` or other scoped props via these slots unless the consumer genuinely needs them — it creates duplicate-id risk when the same value is forwarded to multiple slots
+
+### Consumer usage
+
+No count prop needed — just add slots:
+
+```vue
+<ProfileSection>
+  <template #profile-info-1>...</template>
+  <template #profile-info-2>...</template>
+  <template #profile-info-3>...</template>
+  <template #profile-info-4>...</template>  <!-- automatically picked up -->
+</ProfileSection>
+```
+
+### Examples (prefixed slot inference)
+
+- `app/components/02.molecules/profile-section/ProfileSection.vue`
+
+---
+
 ## Comparison
 
 | | Named dynamic slots | Indexed dynamic slots |

package/.claude/skills/component-local-style-override.md

@@ -2,17 +2,75 @@
 
 ## Overview
 
-When including a component in a page or consuming component, visual customisation can be applied
-locally using `styleClassPassthrough` combined with a scoped style block in the consuming file.
-This avoids adding one-off props to the component and keeps customisation co-located with the usage.
+When including a component in a consuming page or component, visual customisation (theming and
+geometry) can be applied locally without modifying the component. Two patterns exist depending
+on context.
 
-No changes to the component are required.
+No changes to the layer component are required for either pattern.
 
 ---
 
-## Pattern
+## Pattern 1 — Page-level scoping (preferred for single-use or section-scoped instances)
 
-### 1. Pass a modifier class via styleClassPassthrough
+The consuming page has a unique wrapper or body class. The `<style>` block is **unscoped** — no
+`scoped` attribute — so component class names are targeted directly by nesting within the page
+scope. No `:deep()` is needed.
+
+```vue
+<!-- In page template or parent component -->
+<template>
+  <div class="contact-page">
+    <div class="hero-section">
+      <SocialIconsList :items="socialItems" />
+    </div>
+  </div>
+</template>
+
+<!-- Unscoped style block — no `scoped` attribute -->
+<style lang="css">
+.contact-page {
+  .hero-section {
+    .social-icons-list {
+      /* Theming */
+      --theme-social-icon-size: 3.2rem;
+      --theme-social-icon-gap: 2rem;
+      color: var(--colour-brand-primary); /* drives currentColor on icons */
+
+      /* Geometry */
+      margin-block-start: 1.6rem;
+
+      .social-icon-link {
+        border-radius: 0.4rem;
+        padding: 0.4rem;
+      }
+    }
+  }
+}
+</style>
+```
+
+**Body class pattern**: Pages often set a unique class via `bodyAttrs.class` in `useHead()`, then
+use that as the root scope for all page-specific overrides:
+
+```ts
+useHead({ bodyAttrs: { class: "contact-page" } })
+```
+
+```css
+/* All overrides for the page nested under the body class */
+.contact-page {
+  .social-icons-list { ... }
+  .hero-text { ... }
+}
+```
+
+---
+
+## Pattern 2 — Per-instance modifier via styleClassPassthrough
+
+Use when the same component appears multiple times on a page and you need to target a specific
+instance, or when the consuming file uses `<style scoped>` and needs an anchor class that survives
+scoping.
 
 ```vue
 <CardCore :style-class-passthrough="['featured-card']">
@@ -20,11 +78,6 @@ No changes to the component are required.
 </CardCore>
 ```
 
-### 2. Add a style block in the consuming file
-
-Scaffold this block when adding the component. Include a comment so future developers know it
-is safe to delete if no overrides are needed.
-
 ```vue
 <style>
 /* ─── CardCore local overrides ─────────────────────────────────────
@@ -40,54 +93,59 @@ is safe to delete if no overrides are needed.
 
     /* Geometry */
     /* border-radius: 1.6rem; */
-
-    /* Border / outline */
-    /* --_border-width: 0.3rem; */
   }
 }
 </style>
 ```
 
+The modifier class lands on the component's root element — nested element overrides use the full
+path: `.card-core.featured-card .card-row-header { ... }`.
+
+---
+
+## When to offer a scaffold
+
+After placing a component in a consuming page or component, offer a CSS override scaffold. Use the
+component's own class name and any `--theme-*` tokens it exposes as commented stubs. Cover theming
+(colours, tokens) and geometry (sizes, spacing, borders) — not behaviour (`display`, `pointer-events`,
+`z-index`, animations).
+
 ---
 
 ## What to override
 
 | Category | Examples | Approach |
 |---|---|---|
-| Colours | backgrounds, borders, text | CSS custom properties if the component exposes them, otherwise direct values |
-| Geometry | border-radius, padding, gap | Direct property or `--_` private variable |
+| Theming | icon colour, background, border colour | `--theme-*` tokens where exposed; otherwise direct values |
+| Geometry | border-radius, padding, gap, size | Direct property or `--_` private variable |
 | Border / outline | width, style, colour | Direct property or `--_` private variable |
 
 **Do not override behaviour** — `display`, `visibility`, `pointer-events`, `z-index`, animations.
-Those belong in the component or a structural parent, not a style modifier.
+Those belong in the component or a structural parent.
 
 ---
 
 ## CSS custom property targeting
 
-Components use `--_` prefixed private custom properties internally. These can be targeted via
-a modifier class at higher specificity:
+Components expose `--theme-*` public tokens and use `--_` private tokens internally:
 
 ```css
-/* Component internally defines: */
-.my-component {
-  --_background-color: white;
-  background-color: var(--_background-color);
+/* Component internally: --_icon-size: var(--theme-social-icon-size, 2.4rem) */
+
+/* Override via --theme-* (stable, recommended): */
+.social-icons-list {
+  --theme-social-icon-size: 3.2rem;
 }
 
-/* Consumer overrides via modifier: */
-.my-component {
+/* Override via --_ private token (fragile — may break on component update): */
+.social-icons-list {
   &.my-modifier {
-    --_background-color: var(--brand-surface); /* CSS token */
-    /* or */
-    --_background-color: #f5f0eb;              /* direct value */
+    --_icon-size: 3.2rem;
   }
 }
 ```
 
-Note: `--_` properties are component-internal. If the component is updated and renames them,
-the override will silently stop working. For shared/themeable overrides, prefer components that
-expose `--theme-*` public variables instead.
+Prefer `--theme-*` tokens. Only target `--_` private variables when no `--theme-*` equivalent exists.
 
 ---
 
@@ -115,12 +173,3 @@ expose `--theme-*` public variables instead.
 - Anything where visual inconsistency between instances would be a bug
 
 The test: *should all instances of this component look the same?* If yes → theme. If instances are expected to look different → local override.
-
----
-
-## Notes
-
-- `styleClassPassthrough` accepts a string or array — pass an array when combining multiple modifiers.
-- The modifier class lands on the component's root element, so nested element overrides need the
-  full selector path: `.card-core.featured-card .card-row-header { ... }`.
-- Keep the style block close to the component usage in the template — don't put it in a global stylesheet.

package/.claude/skills/components/social-icons-list.md

@@ -93,23 +93,38 @@ import type { ISocialIcon } from "srcdev-nuxt-components";
 
 ## Local style override scaffold
 
+Offer this scaffold when placing the component in a consuming page or section. The style block is
+**unscoped** — no `:deep()` needed. Scope by the page or section's existing wrapper class.
+
 ```vue
-<SocialIconsList :style-class-passthrough="['my-social-icons']" :items="items" />
+<template>
+  <SocialIconsList :items="items" />
+</template>
 
-<style>
+<style lang="css">
 /* ─── SocialIconsList local overrides ──────────────────────────────
    Geometry and size only — brand colours are baked into logos: SVGs.
    Delete this block if no overrides are needed.
    ─────────────────────────────────────────────────────────────────── */
-.social-icons-list {
-  &.my-social-icons {
+.my-page-or-section {
+  .social-icons-list {
     /* --theme-social-icon-size: 3.2rem; */
-    /* --theme-social-icon-gap: 2rem; */
+    /* --theme-social-icon-gap: 1.6rem; */
+    /* margin-block-start: 1.6rem; */
+
+    .social-icon-link {
+      /* border-radius: 0.4rem; */
+      /* padding: 0.4rem; */
+      /* outline: 1px solid transparent; */
+    }
   }
 }
 </style>
 ```
 
+Use `styleClassPassthrough` only if the same component appears multiple times on the page and you
+need to target a specific instance. See `component-local-style-override.md` for full pattern guidance.
+
 ---
 
 ## Notes

package/app/components/02.molecules/expandable/expanding-panel/ExpandingPanel.vue

@@ -1,6 +1,6 @@
 <template>
   <div class="expanding-panel" :class="[elementClasses]">
-    <details class="expanding-panel-details" :name :open>
+    <details class="expanding-panel-details" :name :open @toggle="onDetailsToggle">
       <summary
         :id="`id-${name}-trigger`"
         class="expanding-panel-summary"
@@ -59,6 +59,10 @@ const handleToggle = (event: Event) => {
   }
   isPanelOpen.value = !isPanelOpen.value;
 };
+
+const onDetailsToggle = (event: Event) => {
+  isPanelOpen.value = (event.target as HTMLDetailsElement).open;
+};
 </script>
 
 <style lang="css">

package/app/components/02.molecules/expandable/expanding-panel/tests/ExpandingPanel.spec.ts

@@ -225,6 +225,39 @@ describe("ExpandingPanel", () => {
     expect(wrapper.emitted("update:modelValue")?.[0]).toEqual([true]);
   });
 
+  it("syncs isPanelOpen to false when <details> is closed externally via toggle event", async () => {
+    const wrapper = await mountSuspended(ExpandingPanel, {
+      props: { name: "external-close" },
+      attrs: { modelValue: true },
+    });
+    const vm = wrapper.vm as unknown as ExpandingPanelInstance;
+    expect(vm.isPanelOpen).toBe(true);
+
+    // Simulate browser closing <details> externally (e.g. exclusive accordion name group)
+    const details = wrapper.find("details").element as HTMLDetailsElement;
+    details.open = false;
+    await wrapper.find("details").trigger("toggle");
+    await nextTick();
+
+    expect(vm.isPanelOpen).toBe(false);
+  });
+
+  it("syncs isPanelOpen to true when <details> is opened externally via toggle event", async () => {
+    const wrapper = await mountSuspended(ExpandingPanel, {
+      props: { name: "external-open" },
+    });
+    const vm = wrapper.vm as unknown as ExpandingPanelInstance;
+    expect(vm.isPanelOpen).toBe(false);
+
+    // Simulate browser opening <details> externally
+    const details = wrapper.find("details").element as HTMLDetailsElement;
+    details.open = true;
+    await wrapper.find("details").trigger("toggle");
+    await nextTick();
+
+    expect(vm.isPanelOpen).toBe(true);
+  });
+
   it("updates aria-expanded after toggle", async () => {
     const wrapper = await mountSuspended(ExpandingPanel, {
       props: { name: "aria-toggle" },

package/app/components/02.molecules/profile-section/tests/__snapshots__/ProfileSection.spec.ts.snap

@@ -11,13 +11,13 @@ exports[`ProfileSection > renders correct HTML structure 1`] = `
     <div class="profile-info">
       <div class="profile-info-content">
         <div class="profile-info-block">
-          <p>Profile info content 1</p>
+          <p>Profile info content profile-info-1</p>
         </div>
         <div class="profile-info-block">
-          <p>Profile info content 2</p>
+          <p>Profile info content profile-info-2</p>
         </div>
         <div class="profile-info-block">
-          <p>Profile info content 3</p>
+          <p>Profile info content profile-info-3</p>
         </div>
       </div>
       <!--v-if-->

package/app/pages/ui/accordian.vue

@@ -8,7 +8,7 @@
 
           <AccordianCore
             :item-count="data.length ?? 0"
-            :animation-duration="3000"
+            :animation-duration="1000"
             :style-class-passthrough="['class-modifier-narrow']"
           >
             <template v-for="(item, key) in data" :key="`summary-${key}`" #[`accordian-${key}-summary`]>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.1.20",
+  "version": "9.1.21",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",