srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/04.templates/page-hero-highlights/stories/PageHeroHighlights.stories.ts

@@ -37,7 +37,7 @@ const meta: Meta<StoryArgs> = {
     widthConstrained: {
       control: "boolean",
       description:
-        "When true, caps the central column at --max-width (default 1064px). Gutters grow responsively to enforce the constraint. Override --max-width via styleClassPassthrough to change the cap value.",
+        "When true, caps the central column at --page-hero-highlights-max-width (default 1064px). Gutters grow responsively to enforce the constraint. Override --page-hero-highlights-max-width via styleClassPassthrough to change the cap value.",
     },
     contentAlign: {
       control: { type: "inline-radio" },
@@ -53,15 +53,15 @@ const meta: Meta<StoryArgs> = {
     highlightTitleBaseline: {
       control: "boolean",
       description:
-        "When true, fixes the highlight title row to a set height so titles align to the header baseline. Override --highlight-title-height in the consuming page to tune the value.",
+        "When true, fixes the highlight title row to a set height so titles align to the header baseline. Override --page-hero-highlights-title-height in the consuming page to tune the value.",
     },
     headerBackground: {
       control: "color",
-      description: "Background colour of the header zone (sets --header-row-background-colour)",
+      description: "Background colour of the header zone (sets --page-hero-highlights-header-background)",
     },
     contentBackground: {
       control: "color",
-      description: "Background colour of the content zone (sets --content-row-background-color)",
+      description: "Background colour of the content zone (sets --page-hero-highlights-content-background)",
     },
     highlightCount: {
       control: { type: "select" },
@@ -95,8 +95,8 @@ type Story = StoryObj<typeof PageHeroHighlights>;
 
 function useStorySetup(args: StoryArgs) {
   const bgStyles = computed(() => ({
-    ...(args.headerBackground ? { "--header-row-background-colour": args.headerBackground } : {}),
-    ...(args.contentBackground ? { "--content-row-background-color": args.contentBackground } : {}),
+    ...(args.headerBackground ? { "--page-hero-highlights-header-background": args.headerBackground } : {}),
+    ...(args.contentBackground ? { "--page-hero-highlights-content-background": args.contentBackground } : {}),
   }));
   const highlightCount = computed(() => args.highlightCount ?? 3);
   const componentArgs = computed(() => {
@@ -119,46 +119,44 @@ All layout and visual properties are customisable via CSS custom properties. Set
 \`\`\`css
 .page-hero-highlights {
   /* Grid layout */
-  --max-width: 1064px;
+  --page-hero-highlights-max-width: 1064px;
   --page-hero-highlights-gutter-mobile: 16px;
   --page-hero-highlights-gutter-tablet: 40px;
   --page-hero-highlights-gutter-desktop: 32px;
 
   /* Header zone */
-  --header-row-background-colour: darkblue;
+  --page-hero-highlights-header-background: darkblue;
 
   /* Highlights strip */
-  --highlights-row-item-gap: 1rem;
-  --highlights-row-initial-item-offset: 1.2rem;
+  --page-hero-highlights-strip-gap: 1rem;
+  --page-hero-highlights-strip-inset: 1.2rem;
 
   /* Highlight cards */
-  --highlight-rows-gap: 1.2rem;
-  --highlight-title-height: 1fr; /* see: highlight-title-baseline prop */
-  --highlight-padding-block-start: 1.2rem;
-  --highlight-padding: 1.2rem;
-  --highlight-background-color: white;
-  --highlight-border: 1px solid black;
-  --highlight-border-radius: 8px;
-  --highlight-color: black;
+  --page-hero-highlights-item-rows-gap: 1.2rem;
+  --page-hero-highlights-title-height: 1fr; /* see: highlight-title-baseline prop */
+  --page-hero-highlights-item-padding-block-start: 1.2rem;
+  --page-hero-highlights-item-padding: 1.2rem;
+  --page-hero-highlights-item-background: white;
+  --page-hero-highlights-item-border: 1px solid black;
+  --page-hero-highlights-item-border-radius: 8px;
+  --page-hero-highlights-item-colour: black;
 
   /* Content zone */
-  --content-row-background-color: var(--slate-01); /* transparent */
-  --content-row-start-gap: 1.2rem;
-  --content-row-end-gap: 1.2rem;
+  --page-hero-highlights-content-background: var(--slate-01); /* transparent */
+  --page-hero-highlights-content-start-gap: 1.2rem;
+  --page-hero-highlights-content-end-gap: 1.2rem;
 
   /* Content slot decorative border */
-  --content-slot-margin-block-start: 2.4rem;
-  --content-slot-margin: var(--highlights-row-initial-item-offset);
-  --content-slot-background-color: var(--slate-00);
-  --content-slot-border: 1px solid var(--slate-06);
-  --content-slot-border-radius: 0.8rem;
-  --content-slot-outline: 1px solid var(--slate-02);
+  --page-hero-highlights-content-margin-block-start: 2.4rem;
+  --page-hero-highlights-content-margin: var(--page-hero-highlights-strip-inset);
+  --page-hero-highlights-panel-background: var(--slate-00);
+  --page-hero-highlights-panel-border: 1px solid var(--slate-06);
+  --page-hero-highlights-panel-border-radius: 0.8rem;
+  --page-hero-highlights-panel-outline: 1px solid var(--slate-02);
 
   /* When using :highlight-title-baseline="true" */
-  &.highlight-title-baseline {
-    --highlight-title-height: 4rem; /* proportional value preferred */
-    --highlight-padding-block-start: 0;
-  }
+  --page-hero-highlights-title-height-baseline: 4rem; /* proportional value preferred */
+    --page-hero-highlights-item-padding-block-start-baseline: 0;
 }
 \`\`\`
         `,
@@ -202,46 +200,44 @@ All layout and visual properties are customisable via CSS custom properties. Set
 .page-hero-highlights {
 
   /* Grid layout */
-  --max-width: 1064px;
+  --page-hero-highlights-max-width: 1064px;
   --page-hero-highlights-gutter-mobile: 16px;
   --page-hero-highlights-gutter-tablet: 40px;
   --page-hero-highlights-gutter-desktop: 32px;
 
   /* Header zone */
-  --header-row-background-colour: darkblue;
+  --page-hero-highlights-header-background: darkblue;
 
   /* Highlights strip */
-  --highlights-row-item-gap: 1rem;
-  --highlights-row-initial-item-offset: 1.2rem;
+  --page-hero-highlights-strip-gap: 1rem;
+  --page-hero-highlights-strip-inset: 1.2rem;
 
   /* Highlight cards */
-  --highlight-rows-gap: 1.2rem;
-  --highlight-title-height: 1fr; /* see: highlight-title-baseline prop */
-  --highlight-padding-block-start: 1.2rem;
-  --highlight-padding: 1.2rem;
-  --highlight-background-color: white;
-  --highlight-border: 1px solid black;
-  --highlight-border-radius: 8px;
-  --highlight-color: black;
+  --page-hero-highlights-item-rows-gap: 1.2rem;
+  --page-hero-highlights-title-height: 1fr; /* see: highlight-title-baseline prop */
+  --page-hero-highlights-item-padding-block-start: 1.2rem;
+  --page-hero-highlights-item-padding: 1.2rem;
+  --page-hero-highlights-item-background: white;
+  --page-hero-highlights-item-border: 1px solid black;
+  --page-hero-highlights-item-border-radius: 8px;
+  --page-hero-highlights-item-colour: black;
 
   /* Content zone */
-  --content-row-background-color: var(--slate-01); /* transparent */
-  --content-row-start-gap: 1.2rem;
-  --content-row-end-gap: 1.2rem;
+  --page-hero-highlights-content-background: var(--slate-01); /* transparent */
+  --page-hero-highlights-content-start-gap: 1.2rem;
+  --page-hero-highlights-content-end-gap: 1.2rem;
 
   /* Content slot decorative border */
-  --content-slot-margin-block-start: 2.4rem;
-  --content-slot-margin: var(--highlights-row-initial-item-offset);
-  --content-slot-background-color: var(--slate-00);
-  --content-slot-border: 1px solid var(--slate-06);
-  --content-slot-border-radius: 0.8rem;
-  --content-slot-outline: 1px solid var(--slate-02);
+  --page-hero-highlights-content-margin-block-start: 2.4rem;
+  --page-hero-highlights-content-margin: var(--page-hero-highlights-strip-inset);
+  --page-hero-highlights-panel-background: var(--slate-00);
+  --page-hero-highlights-panel-border: 1px solid var(--slate-06);
+  --page-hero-highlights-panel-border-radius: 0.8rem;
+  --page-hero-highlights-panel-outline: 1px solid var(--slate-02);
 
   /* When using :highlight-title-baseline="true" */
-  &.highlight-title-baseline {
-    --highlight-title-height: 4rem; /* proportional value preferred */
-    --highlight-padding-block-start: 0;
-  }
+  --page-hero-highlights-title-height-baseline: 4rem; /* proportional value preferred */
+    --page-hero-highlights-item-padding-block-start-baseline: 0;
 }</pre>
         </template>
       </PageHeroHighlights>
@@ -341,7 +337,7 @@ export const NoSlotContent: Story = {
   }),
 };
 
-/** Max width centered — content column capped at --max-width (1064px) with equal growing gutters either side. */
+/** Max width centered — content column capped at --page-hero-highlights-max-width (1064px) with equal growing gutters either side. */
 export const MaxWidthCentered: Story = {
   name: "Max Width — Centered",
   args: { widthConstrained: true, contentAlign: "center" },
@@ -354,7 +350,7 @@ export const MaxWidthCentered: Story = {
       <PageHeroHighlights v-bind="componentArgs" :style="bgStyles">
         <template #header>
           <p class="page-heading-1">Dashboard</p>
-          <p class="page-body-normal">Content column is capped at --max-width (1064px by default) — gutters grow equally on both sides.</p>
+          <p class="page-body-normal">Content column is capped at --page-hero-highlights-max-width (1064px by default) — gutters grow equally on both sides.</p>
         </template>
 
         <template #highlights>
@@ -381,7 +377,7 @@ export const MaxWidthCentered: Story = {
   }),
 };
 
-/** Max width start — content column capped at --max-width (1064px), pinned to the left. */
+/** Max width start — content column capped at --page-hero-highlights-max-width (1064px), pinned to the left. */
 export const MaxWidthStart: Story = {
   name: "Max Width — Start",
   args: { widthConstrained: true, contentAlign: "start" },
@@ -394,7 +390,7 @@ export const MaxWidthStart: Story = {
       <PageHeroHighlights v-bind="componentArgs" :style="bgStyles">
         <template #header>
           <p class="page-heading-1">Dashboard</p>
-          <p class="page-body-normal">Content column is capped at --max-width (1064px by default), aligned to the start — right side takes the remaining space.</p>
+          <p class="page-body-normal">Content column is capped at --page-hero-highlights-max-width (1064px by default), aligned to the start — right side takes the remaining space.</p>
         </template>
 
         <template #highlights>

package/app/components/04.templates/page-hero-highlights/stories/PageHeroHighlightsHeader.stories.ts

@@ -31,7 +31,7 @@ export const Default: Story = {
       return { args };
     },
     template: `
-      <PageHeroHighlights tag="section" style="--header-row-background-colour: #2d4a35;">
+      <PageHeroHighlights tag="section" style="--page-hero-highlights-header-background: #2d4a35;">
         <template #header>
           <PageHeroHighlightsHeader v-bind="args">
             <template #start>
@@ -56,7 +56,7 @@ export const WithActions: Story = {
       return { args };
     },
     template: `
-      <PageHeroHighlights tag="section" style="--header-row-background-colour: #2d4a35;">
+      <PageHeroHighlights tag="section" style="--page-hero-highlights-header-background: #2d4a35;">
         <template #header>
           <PageHeroHighlightsHeader v-bind="args">
             <template #start>

package/app/components/04.templates/page-hero-highlights/tests/PageHeroHighlights.spec.ts

@@ -63,14 +63,14 @@ describe("PageHeroHighlights", () => {
     const wrapper = await mountSuspended(PageHeroHighlights, {
       slots: { content: "<p class='body-text'>Page body</p>" },
     });
-    expect(wrapper.find(".content-slot .body-text").exists()).toBe(true);
+    expect(wrapper.find(".page-hero-highlights-content-slot .body-text").exists()).toBe(true);
   });
 
   it("header slot is rendered inside .header-slot", async () => {
     const wrapper = await mountSuspended(PageHeroHighlights, {
       slots: { header: "<h1 class='page-title'>Dashboard</h1>" },
     });
-    expect(wrapper.find(".header-slot .page-title").exists()).toBe(true);
+    expect(wrapper.find(".page-hero-highlights-header-slot .page-title").exists()).toBe(true);
   });
 
   it("adds aria-labelledby when tag is section", async () => {
@@ -108,21 +108,21 @@ describe("PageHeroHighlights", () => {
 
   it("applies flexible-widths class by default", async () => {
     const wrapper = await mountSuspended(PageHeroHighlights);
-    expect(wrapper.find(".highlights-row").classes()).toContain("flexible-widths");
-    expect(wrapper.find(".highlights-row").classes()).not.toContain("equal-widths");
+    expect(wrapper.find(".page-hero-highlights-strip").classes()).toContain("flexible-widths");
+    expect(wrapper.find(".page-hero-highlights-strip").classes()).not.toContain("equal-widths");
   });
 
   it("applies equal-widths class when highlightsEqualWidths is true", async () => {
     const wrapper = await mountSuspended(PageHeroHighlights, {
       props: { highlightsEqualWidths: true },
     });
-    expect(wrapper.find(".highlights-row").classes()).toContain("equal-widths");
-    expect(wrapper.find(".highlights-row").classes()).not.toContain("flexible-widths");
+    expect(wrapper.find(".page-hero-highlights-strip").classes()).toContain("equal-widths");
+    expect(wrapper.find(".page-hero-highlights-strip").classes()).not.toContain("flexible-widths");
   });
 
   it("applies justify-start class by default", async () => {
     const wrapper = await mountSuspended(PageHeroHighlights);
-    expect(wrapper.find(".highlights-row").classes()).toContain("justify-start");
+    expect(wrapper.find(".page-hero-highlights-strip").classes()).toContain("justify-start");
   });
 
   it("applies the correct justify class for each highlightsJustify value", async () => {
@@ -131,7 +131,7 @@ describe("PageHeroHighlights", () => {
       const wrapper = await mountSuspended(PageHeroHighlights, {
         props: { highlightsJustify: value },
       });
-      expect(wrapper.find(".highlights-row").classes()).toContain(`justify-${value}`);
+      expect(wrapper.find(".page-hero-highlights-strip").classes()).toContain(`justify-${value}`);
     }
   });
 
@@ -171,7 +171,7 @@ describe("PageHeroHighlights", () => {
   describe("grid layout classes", () => {
     it("applies center class by default", async () => {
       const wrapper = await mountSuspended(PageHeroHighlights);
-      expect(wrapper.find(".page-hero-highlights").classes()).toContain("center");
+      expect(wrapper.find(".page-hero-highlights").classes()).toContain("content-align-center");
     });
 
     it("does not apply width-constrained class by default", async () => {
@@ -190,7 +190,7 @@ describe("PageHeroHighlights", () => {
       const wrapper = await mountSuspended(PageHeroHighlights, {
         props: { contentAlign: "start" },
       });
-      expect(wrapper.find(".page-hero-highlights").classes()).toContain("start");
+      expect(wrapper.find(".page-hero-highlights").classes()).toContain("content-align-start");
       expect(wrapper.find(".page-hero-highlights").classes()).not.toContain("center");
     });
   });

package/app/components/04.templates/page-hero-highlights/tests/PageHeroHighlightsHeader.spec.ts

@@ -12,7 +12,7 @@ describe("PageHeroHighlightsHeader", () => {
     const wrapper = await mountSuspended(PageHeroHighlightsHeader, {
       slots: { start: "<h1 class='page-title'>Surplus needs</h1>" },
     });
-    expect(wrapper.find(".phh-start .page-title").exists()).toBe(true);
+    expect(wrapper.find(".page-hero-highlights-header-start .page-title").exists()).toBe(true);
     expect(wrapper.html()).toContain("Surplus needs");
   });
 
@@ -23,22 +23,22 @@ describe("PageHeroHighlightsHeader", () => {
         end: "<button class='cta'>Create new need</button>",
       },
     });
-    expect(wrapper.find(".phh-end .cta").exists()).toBe(true);
+    expect(wrapper.find(".page-hero-highlights-header-end .cta").exists()).toBe(true);
   });
 
-  it("does not render .phh-end when no end slot is provided", async () => {
+  it("does not render .page-hero-highlights-header-end when no end slot is provided", async () => {
     const wrapper = await mountSuspended(PageHeroHighlightsHeader, {
       slots: { start: "<h1>Title</h1>" },
     });
-    expect(wrapper.find(".phh-end").exists()).toBe(false);
+    expect(wrapper.find(".page-hero-highlights-header-end").exists()).toBe(false);
   });
 
-  it("renders .phh-start as full width when no end slot is provided", async () => {
+  it("renders .page-hero-highlights-header-start as full width when no end slot is provided", async () => {
     const wrapper = await mountSuspended(PageHeroHighlightsHeader, {
       slots: { start: "<h1>Title</h1>" },
     });
-    expect(wrapper.find(".phh-start").exists()).toBe(true);
-    expect(wrapper.find(".phh-end").exists()).toBe(false);
+    expect(wrapper.find(".page-hero-highlights-header-start").exists()).toBe(true);
+    expect(wrapper.find(".page-hero-highlights-header-end").exists()).toBe(false);
   });
 
   it("applies styleClassPassthrough classes", async () => {

package/app/components/04.templates/page-hero-highlights/tests/__snapshots__/PageHeroHighlights.spec.ts.snap

@@ -1,17 +1,17 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`PageHeroHighlights > renders correct HTML structure 1`] = `
-"<div class="page-hero-highlights center has-content-panel">
-  <div class="header-row">
-    <div class="header-slot">
+"<div class="page-hero-highlights content-align-center has-content-panel">
+  <div class="page-hero-highlights-header-row">
+    <div class="page-hero-highlights-header-slot">
       <h1>Page Title</h1>
     </div>
   </div>
-  <div class="highlights-row flexible-widths justify-start">
+  <div class="page-hero-highlights-strip flexible-widths justify-start">
     <div class="highlight">Highlight 1</div>
   </div>
-  <div class="content-row">
-    <div class="content-slot">
+  <div class="page-hero-highlights-content-row">
+    <div class="page-hero-highlights-content-slot">
       <p>Content</p>
     </div>
   </div>

package/app/components/05.forms/form-errors/CONSUMER-STYLING.md

@@ -0,0 +1,112 @@
+# InputError — Consumer Styling Guide
+
+`InputError` is the red error message strip rendered under a form control by every `*Field`
+wrapper (`InputTextWithLabel`, `InputNumberField`, `InputSelectWithLabel`, `SingleCheckbox`, ...).
+It animates open (`grid-template-rows: 0fr → 1fr` plus opacity) when the field is in error.
+
+## Public token API
+
+Every token is consumed as `var(--input-error-*, {default})`, so none is declared on the element
+itself: set them on any ancestor (or `:root`) and they inherit down.
+
+| Token | Default | Controls |
+|---|---|---|
+| `--input-error-text-color` | `var(--input-error-color)` (`white`) | Message text colour |
+| `--input-error-icon-color` | `--input-error-text-color` | Icon colour |
+| `--input-error-icon-size` | `1em` | Icon size (applied as `font-size`, see pitfall #24) |
+| `--input-error-background-color` | `var(--theme-error-surface)` | Strip background |
+| `--input-error-border-color` | `var(--theme-error-border)` | Border colour while visible |
+| `--input-error-outline-color` | `var(--theme-error-outline)` | Outline colour while visible (attached `underlined` variant always has no outline) |
+| `--input-error-border-radius` | `var(--form-input-border-radius)` (`0.5rem`) | Corner radius (bottom corners when attached, all corners when detached) |
+| `--input-error-font-family` | `var(--font-family)` | Message font family |
+| `--input-error-font-size` | `1.6rem` | Message font size |
+| `--input-error-font-weight` | `500` | Message font weight |
+| `--input-error-padding-inline` | `1.2rem` | Inline padding of the message, and the icon's inset from the start edge |
+| `--input-error-padding-block-start` | `1.2rem` (`normal` variant), `1rem` (others) | Message top padding. Setting it overrides every variant |
+| `--input-error-padding-block-end` | `1rem` | Message bottom padding |
+| `--input-error-list-gap` | `0.6rem` | Gap between messages when `error-message` is an array |
+| `--input-error-detached-offset` | `2rem` | Gap above a visible detached error |
+| `--input-error-margin-block-start` | `0.25rem` | Gap above an attached error. Declared globally in `03.theming/_default.css` |
+| `--input-error-transition-duration` | `var(--theme-form-transition-duration)` (`0.2s`) | Open/close animation duration. The animation is disabled under `prefers-reduced-motion: reduce` |
+
+### Why component tokens instead of the `--theme-error-*` ones
+
+The root carries `data-theme="error"`, which matches the global `:where([data-theme="error"])`
+rule in `03.theming/_error.css`. That rule **re-declares** `--input-error-color` and the three
+`--theme-error-*` tokens on the error element itself, so overriding those on an ancestor never
+reaches `InputError`. The `--input-error-*` tokens above aren't declared anywhere by default, so an
+ancestor override always lands. If you really want to change the global ones, target
+`.input-error-message` directly.
+
+Private tokens (not public API): `--_text-color`, `--_border-radius`, `--_padding-inline`,
+`--_transition-duration` (resolved intermediates reused across rules) and
+`--_padding-block-start` (swapped by `data-input-variant`).
+
+---
+
+## State hooks
+
+| Attribute on `.input-error-message` | When |
+|---|---|
+| `data-visible` | `show-error` is `true` |
+| `data-detached` | `is-detached` is `true` (error sits below the control with a gap, fully rounded) |
+| `data-input-variant="normal" \| "outlined" \| "underlined"` | Always, mirrors `input-variant` |
+
+Inner elements: `.input-error-message-inner`, `.input-error-message-content`,
+`.input-error-message-icon-wrapper`, `.input-error-message-icon`, `.input-error-message-text`,
+`.input-error-message-single`, `.input-error-message-list`, `.input-error-message-list-item`.
+
+> **Changed 2026-09-26**: state used to be bare classes (`.show`, `.detached`, `.normal`,
+> `.outlined`, `.underlined`) and the inner elements used generic names (`.inner`,
+> `.inner-content`, `.inner-icon`, `.icon`, `.message`, `.message-single`, `.message-list`,
+> `.message-list-item`). Update selectors: `.input-error-message.show` →
+> `.input-error-message[data-visible]`, `.inner .message` → `.input-error-message-text`, etc.
+> Most old overrides (colour, font size, padding) can now be replaced by a token.
+
+---
+
+## Global theming
+
+```css
+:where(html) {
+  --input-error-font-size: 1.4rem;
+  --input-error-border-radius: 0;
+}
+```
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** set the `--input-error-*` tokens, not `--input-error-color` or the `--theme-error-*`
+ones: the root's `data-theme="error"` re-declares those on the element itself (see **Why component
+tokens instead of the `--theme-error-*` ones** above).
+
+### Page or section
+
+```css
+.contact-page {
+  --input-error-background-color: var(--red-08);
+  --input-error-border-color: var(--red-08);
+  --input-error-detached-offset: 0.8rem;
+
+  .input-error-message[data-input-variant="underlined"] {
+    --input-error-padding-inline: 0;
+  }
+}
+```
+
+---
+
+## Class passthrough
+
+`:style-class-passthrough` (string or string array) adds classes to the root
+`.input-error-message` element. Field wrappers don't forward it, so in practice use the tokens
+above.
+