srcdev-nuxt-components 9.6.11 → 9.6.13

package/app/components/02.molecules/display-tooltip-rich/stories/DisplayTooltipRich.stories.ts

@@ -0,0 +1,254 @@
+import { computed, ref } from "vue";
+import DisplayTooltipRich from "../DisplayTooltipRich.vue";
+import DisplayTooltip from "../../../01.atoms/display-tooltip/DisplayTooltip.vue";
+import { useTooltipsGuide } from "~/composables/useTooltips";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { TooltipContentText } from "~/types/components";
+
+type LineClamp = "none" | "1" | "2" | "3";
+
+type StoryArgs = {
+  tooltipId: string;
+  contentText: TooltipContentText;
+  triggerAriaLabel: string;
+  triggerIcon: string;
+  closeButtonText: string;
+  closeButtonAriaLabel: string;
+  titleLineClamp: LineClamp;
+  bodyLineClamp: LineClamp;
+  actionLineClamp: LineClamp;
+  styleClassPassthrough?: string | string[];
+};
+
+const contentText: TooltipContentText = {
+  tooltipTitle: { tag: "h4", text: "Free delivery" },
+  tooltipContent: { tag: "p", text: "Orders over £50 qualify for free standard delivery." },
+  tooltipAction: { tag: "span", text: "See delivery policy" },
+};
+
+const lineClampControl = (element: string) => ({
+  control: { type: "select" as const },
+  options: ["none", "1", "2", "3"],
+  description: `Story-only CSS token, not a prop: sets \`--display-tooltip-rich-${element}-line-clamp\` on a wrapper (\`1\` is single-line ellipsis).`,
+  table: { category: "CSS tokens (story-only)" },
+});
+
+const meta: Meta<StoryArgs> = {
+  title: "Molecules/DisplayTooltipRich",
+  component: DisplayTooltipRich,
+  argTypes: {
+    tooltipId: {
+      control: "text",
+      description: "Base id for the popover, prefixed with `nuxt-tooltip-`. Auto-generated when omitted.",
+      table: { category: "Basic" },
+    },
+    triggerIcon: {
+      control: "text",
+      description: "Iconify name for the trigger button icon (DisplayTooltip's default when empty)",
+      table: { category: "Basic" },
+    },
+    triggerAriaLabel: {
+      control: "text",
+      description: "aria-label on the trigger button (override for localisation)",
+      table: { category: "Accessibility" },
+    },
+    closeButtonText: {
+      control: "text",
+      description: "Visible close button text (override for localisation)",
+      table: { category: "Content" },
+    },
+    closeButtonAriaLabel: {
+      control: "text",
+      description: "aria-label on the close button; keep the visible text inside it",
+      table: { category: "Accessibility" },
+    },
+    titleLineClamp: lineClampControl("title"),
+    bodyLineClamp: lineClampControl("body"),
+    actionLineClamp: lineClampControl("action"),
+    contentText: { table: { disable: true } },
+    styleClassPassthrough: { table: { disable: true } },
+  },
+  args: {
+    contentText,
+    triggerAriaLabel: "Toggle the popover",
+    closeButtonText: "Close",
+    closeButtonAriaLabel: "Close tool tip",
+    titleLineClamp: "none",
+    bodyLineClamp: "none",
+    actionLineClamp: "none",
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Material 3's rich tooltip, built on DisplayTooltip: a structured panel where `contentText` supplies an optional title, body and action line (each with its own tag), followed by a built-in close button (an `InputButton`) wired to the popover and to DisplayTooltip's `close()`. Props localise the trigger and close button (`triggerAriaLabel`, `triggerIcon`, `closeButtonText`, `closeButtonAriaLabel`); the `triggerContent` slot passes through. For free-form panel content use DisplayTooltip directly.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<StoryArgs>;
+
+const clampSetup = (args: StoryArgs) => ({
+  componentArgs: computed(() => {
+    const { titleLineClamp: _t, bodyLineClamp: _b, actionLineClamp: _a, ...rest } = args;
+    return { ...rest, triggerIcon: rest.triggerIcon || undefined };
+  }),
+  clampStyle: computed(() => ({
+    "--display-tooltip-rich-title-line-clamp": args.titleLineClamp,
+    "--display-tooltip-rich-body-line-clamp": args.bodyLineClamp,
+    "--display-tooltip-rich-action-line-clamp": args.actionLineClamp,
+  })),
+});
+
+const renderWithClampTokens: Story["render"] = (args) => ({
+  components: { DisplayTooltipRich },
+  setup: () => clampSetup(args),
+  template: `<div style="padding: 8rem;" :style="clampStyle"><DisplayTooltipRich v-bind="componentArgs" /></div>`,
+});
+
+export const Default: Story = {
+  render: renderWithClampTokens,
+};
+
+export const TitleOnly: Story = {
+  args: {
+    contentText: { tooltipTitle: { tag: "h4", text: "Just a title" } },
+  },
+  render: renderWithClampTokens,
+};
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: {
+    contentText: {
+      tooltipTitle: {
+        tag: "h4",
+        text: "😀 Kostenloselieferungfürallebestellungenübereinemmindestbestellwert <b>not bold</b> التوصيل المجاني",
+      },
+      tooltipContent: {
+        tag: "",
+        text: "https://example.invalid/a/very/long/unbroken/url/that/never/offers/a/break/opportunity/anywhere ".repeat(2) +
+          "Bestellungen über fünfzig Pfund qualifizieren sich für die kostenlose Standardlieferung innerhalb des Vereinigten Königreichs, ausgenommen sind Inseln und abgelegene Regionen.",
+      },
+      tooltipAction: { tag: "span", text: "Lieferrichtliniensowierückgabebedingungenansehen" },
+    },
+    triggerAriaLabel: "Weitereinformationenzurlieferunganzeigen 😀",
+    closeButtonText: "Schließenundzurückzurbestellübersicht",
+    closeButtonAriaLabel: "Schließenundzurückzurbestellübersicht",
+    titleLineClamp: "2",
+    bodyLineClamp: "none",
+    actionLineClamp: "1",
+  },
+  render: (args) => ({
+    components: { DisplayTooltipRich },
+    setup: () => clampSetup(args),
+    template: `
+      <div style="display: grid; gap: 2.4rem; padding: 2.4rem; font-size: 1.4rem;" :style="clampStyle">
+        <p style="margin: 0;">Every field at its worst, an empty body tag (falls back to <code>&lt;p&gt;</code>) and a long unbroken close label. The line-clamp controls apply to this tooltip.</p>
+        <div style="inline-size: 18rem; outline: 0.1rem dashed currentColor;">
+          <DisplayTooltipRich v-bind="componentArgs">
+            <template #triggerContent>
+              <span>Lieferkostenundversandbedingungen</span>
+            </template>
+          </DisplayTooltipRich>
+        </div>
+
+        <p style="margin: 0;">Empty <code>contentText</code>: the panel holds only the close button.</p>
+        <DisplayTooltipRich :content-text="{}"></DisplayTooltipRich>
+
+        <p style="margin: 0;">Single characters in every field.</p>
+        <DisplayTooltipRich
+          :content-text="{ tooltipTitle: { tag: 'h4', text: 'T' }, tooltipContent: { tag: 'p', text: 'B' }, tooltipAction: { tag: 'span', text: 'A' } }"
+          close-button-text="X"
+          close-button-aria-label="X"
+        ></DisplayTooltipRich>
+
+        <p style="margin: 0;">Right-to-left content at the right edge: the panel flips to the left of the trigger.</p>
+        <div style="display: flex; justify-content: flex-end;">
+          <DisplayTooltipRich
+            :content-text="{ tooltipTitle: { tag: 'h4', text: 'التوصيل المجاني' }, tooltipContent: { tag: 'p', text: 'الطلبات التي تزيد عن خمسين جنيهًا مؤهلة للتوصيل المجاني.' } }"
+          ></DisplayTooltipRich>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      story: { inline: false, height: "900px" },
+      description: {
+        story:
+          "Worst-case `contentText`. Open each tooltip and check: unbroken title, body, action and close-button text wraps inside the panel and the panel never gets wider than the viewport; HTML-like text renders as text; the title is capped at two lines and the action at one with an ellipsis (change them with the story-only line-clamp controls); the close button stays right-aligned at its natural width instead of stretching; an empty `contentText` leaves just the close button; a trigger at the right edge opens its panel to the left.",
+      },
+    },
+  },
+};
+
+export const GuidedTour: Story = {
+  parameters: {
+    docs: {
+      story: { inline: false, height: "500px" },
+      description: {
+        story:
+          "`useTooltipsGuide` walks a container's `[popover]` elements in DOM order, opening each and waiting for its close button before advancing. Mixes a `DisplayTooltipRich` step (its close button relabelled \"Next\" via `closeButtonText`) with a plain `DisplayTooltip` step. A hand-written close button must call the `tooltipContent` slot's `close()` as well as carrying `popovertargetaction=\"hide\"`: the attribute alone does nothing on Safari 16, which has no Popover API. The guide auto-starts 800ms after mount; use \"Run guide again\" to replay it.",
+      },
+    },
+  },
+  render: () => ({
+    components: { DisplayTooltipRich, DisplayTooltip },
+    setup() {
+      const guideContainer = ref<HTMLElement | null>(null);
+      const { isGuideRunning, restartGuide, currentTooltipIndex, totalPopovers } = useTooltipsGuide(guideContainer, {
+        autoStart: true,
+        startDelay: 800,
+      });
+
+      return { guideContainer, isGuideRunning, restartGuide, currentTooltipIndex, totalPopovers };
+    },
+    template: `
+      <div style="padding: 4rem; display: grid; gap: 2rem; max-width: 48rem;">
+        <div style="display: flex; align-items: center; gap: 1.2rem;">
+          <button type="button" @click="restartGuide" :disabled="isGuideRunning" style="padding: 0.6rem 1.2rem;">
+            {{ isGuideRunning ? 'Guide running…' : 'Run guide again' }}
+          </button>
+          <span v-if="isGuideRunning" style="font-size: 1.3rem; color: #666;">
+            Step {{ currentTooltipIndex + 1 }} of {{ totalPopovers }}: click Next (Close on the last step) to advance
+          </span>
+        </div>
+
+        <div ref="guideContainer" style="display: grid; gap: 2rem;">
+          <DisplayTooltipRich
+            close-button-text="Next"
+            close-button-aria-label="Next step"
+            :content-text="{
+              tooltipTitle: { tag: 'h3', text: 'Step 1' },
+              tooltipContent: { tag: 'p', text: 'This step uses DisplayTooltipRich: structured title/body/action content plus a built-in close button.' },
+              tooltipAction: { tag: 'p', text: 'Step 1 of 2' },
+            }"
+          >
+            <template #triggerContent>Trigger from DisplayTooltipRich</template>
+          </DisplayTooltipRich>
+
+          <DisplayTooltip tooltip-id="guided-tour-step-2">
+            <template #triggerContent>Trigger from plain DisplayTooltip</template>
+            <template #tooltipContent="{ close }">
+              <p>This step uses plain DisplayTooltip: you supply the close button yourself via the tooltipContent slot.</p>
+              <button
+                type="button"
+                popovertarget="guided-tour-step-2"
+                popovertargetaction="hide"
+                class="display-tooltip-close-button"
+                style="align-self: flex-end;"
+                aria-label="Close tool tip"
+                @click="close"
+              >
+                Close
+              </button>
+            </template>
+          </DisplayTooltip>
+        </div>
+      </div>
+    `,
+  }),
+};

package/app/components/02.molecules/display-tooltip-rich/tests/DisplayTooltipRich.spec.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import DisplayTooltipRich from "../DisplayTooltipRich.vue";
+import type { TooltipContentText } from "~/types/components";
+
+const contentText: TooltipContentText = {
+  tooltipTitle: { tag: "h4", text: "Title" },
+  tooltipContent: { tag: "p", text: "Body copy" },
+  tooltipAction: { tag: "span", text: "Learn more" },
+};
+
+const mounted: { unmount: () => void }[] = [];
+
+const mountDefined = async (options: Parameters<typeof mountSuspended<typeof DisplayTooltipRich>>[1] = {}) => {
+  const wrapper = await mountSuspended(DisplayTooltipRich, options);
+  mounted.push(wrapper);
+  return wrapper;
+};
+
+describe("DisplayTooltipRich", () => {
+  afterEach(() => {
+    mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+    vi.restoreAllMocks();
+  });
+
+  it("mounts without error", async () => {
+    const wrapper = await mountDefined();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure", async () => {
+    const wrapper = await mountDefined({ props: { contentText, tooltipId: "fixed" } });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders the title, body, and action from contentText", async () => {
+    const wrapper = await mountDefined({ props: { contentText } });
+    expect(wrapper.find(".display-tooltip-rich-title").text()).toBe("Title");
+    expect(wrapper.find(".display-tooltip-rich-body").text()).toBe("Body copy");
+    expect(wrapper.find(".display-tooltip-rich-action").text()).toBe("Learn more");
+  });
+
+  it("renders each contentText field with its given tag", async () => {
+    const wrapper = await mountDefined({ props: { contentText } });
+    expect(wrapper.find(".display-tooltip-rich-title").element.tagName.toLowerCase()).toBe("h4");
+    expect(wrapper.find(".display-tooltip-rich-body").element.tagName.toLowerCase()).toBe("p");
+    expect(wrapper.find(".display-tooltip-rich-action").element.tagName.toLowerCase()).toBe("span");
+  });
+
+  it("omits a field when not present in contentText", async () => {
+    const wrapper = await mountDefined({
+      props: { contentText: { tooltipTitle: { tag: "h4", text: "Only a title" } } },
+    });
+    expect(wrapper.find(".display-tooltip-rich-title").exists()).toBe(true);
+    expect(wrapper.find(".display-tooltip-rich-body").exists()).toBe(false);
+    expect(wrapper.find(".display-tooltip-rich-action").exists()).toBe(false);
+  });
+
+  it("renders a close button wired to the tooltip id", async () => {
+    const wrapper = await mountDefined({ props: { tooltipId: "my-tip" } });
+    const closeButton = wrapper.find(".display-tooltip-close-button");
+    expect(closeButton.attributes("popovertarget")).toBe("nuxt-tooltip-my-tip");
+    expect(closeButton.attributes("popovertargetaction")).toBe("hide");
+  });
+
+  it("renders the close button as an inline InputButton of type button with localisable copy", async () => {
+    const wrapper = await mountDefined({ props: { closeButtonText: "Fermer", closeButtonAriaLabel: "Fermer l'info-bulle" } });
+    const closeButton = wrapper.find(".display-tooltip-close-button");
+    expect(closeButton.element.tagName).toBe("BUTTON");
+    expect(closeButton.classes()).toContain("input-button");
+    expect(closeButton.attributes("type")).toBe("button");
+    expect(closeButton.attributes("data-variant")).toBe("inline");
+    expect(closeButton.text()).toBe("Fermer");
+    expect(closeButton.attributes("aria-label")).toBe("Fermer l'info-bulle");
+  });
+
+  it("adds its own root class alongside DisplayTooltip's", async () => {
+    const wrapper = await mountDefined();
+    expect(wrapper.classes()).toEqual(expect.arrayContaining(["display-tooltip", "display-tooltip-rich"]));
+  });
+
+  it("keeps its root class when styleClassPassthrough changes", async () => {
+    const wrapper = await mountDefined({ props: { styleClassPassthrough: "first" } });
+    await wrapper.setProps({ styleClassPassthrough: ["second"] });
+    expect(wrapper.classes()).toEqual(expect.arrayContaining(["display-tooltip-rich", "second"]));
+    expect(wrapper.classes()).not.toContain("first");
+  });
+
+  it("forwards triggerIcon and triggerAriaLabel to the trigger", async () => {
+    const wrapper = await mountDefined({ props: { triggerIcon: "lucide:info", triggerAriaLabel: "Plus d'informations" } });
+    const trigger = wrapper.find(".display-tooltip-trigger-button");
+    expect(trigger.attributes("aria-label")).toBe("Plus d'informations");
+    expect(trigger.find(".display-tooltip-trigger-icon").classes().join(" ")).toContain("lucide:info");
+  });
+
+  it("falls back to a default tag when a contentText tag is empty", async () => {
+    const wrapper = await mountDefined({
+      props: {
+        contentText: {
+          tooltipTitle: { tag: "", text: "T" },
+          tooltipContent: { tag: "  ", text: "B" },
+          tooltipAction: { tag: "", text: "A" },
+        },
+      },
+    });
+    expect(wrapper.find(".display-tooltip-rich-title").element.tagName).toBe("P");
+    expect(wrapper.find(".display-tooltip-rich-body").element.tagName).toBe("P");
+    expect(wrapper.find(".display-tooltip-rich-action").element.tagName).toBe("SPAN");
+  });
+
+  it("keeps the generated id stable and links the trigger, panel and close button", async () => {
+    const wrapper = await mountDefined();
+    const target = wrapper.find(".display-tooltip-trigger-button").attributes("popovertarget");
+    expect(target).toMatch(/^nuxt-tooltip-/);
+    expect(wrapper.find(".display-tooltip-popover").attributes("id")).toBe(target);
+    expect(wrapper.find(".display-tooltip-close-button").attributes("popovertarget")).toBe(target);
+
+    await wrapper.setProps({ tooltipId: "tip" });
+    expect(wrapper.find(".display-tooltip-close-button").attributes("popovertarget")).toBe("nuxt-tooltip-tip");
+    await wrapper.setProps({ tooltipId: "" });
+    expect(wrapper.find(".display-tooltip-close-button").attributes("popovertarget")).toBe(target);
+  });
+
+  it("renders the triggerContent slot", async () => {
+    const wrapper = await mountDefined({
+      slots: { triggerContent: "<span class='slot-trigger'>?</span>" },
+    });
+    expect(wrapper.find(".slot-trigger").text()).toBe("?");
+  });
+
+  it("applies styleClassPassthrough classes to the underlying DisplayTooltip", async () => {
+    const wrapper = await mountDefined({
+      props: { styleClassPassthrough: ["custom-class"] },
+    });
+    expect(wrapper.classes()).toContain("custom-class");
+  });
+
+  describe("without the Popover API", () => {
+    beforeEach(() => {
+      Object.defineProperty(HTMLElement.prototype, "showPopover", { value: undefined, writable: true, configurable: true });
+    });
+
+    afterEach(() => {
+      delete (HTMLElement.prototype as unknown as Record<string, unknown>)["showPopover"];
+    });
+
+    it("closes from the close button", async () => {
+      const wrapper = await mountDefined({ props: { contentText } });
+      await wrapper.find(".display-tooltip-trigger-button").trigger("click");
+      expect(wrapper.find(".display-tooltip-popover").classes()).toContain("display-tooltip-popover-open");
+
+      await wrapper.find(".display-tooltip-close-button").trigger("click");
+      expect(wrapper.find(".display-tooltip-popover").classes()).not.toContain("display-tooltip-popover-open");
+    });
+  });
+});

package/app/components/02.molecules/display-tooltip-rich/tests/__snapshots__/DisplayTooltipRich.spec.ts.snap

@@ -0,0 +1,22 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`DisplayTooltipRich > renders correct HTML structure 1`] = `
+"<div class="display-tooltip display-tooltip-rich" style="--_anchor-name: --tooltip-anchor-v-0-0-1;">
+  <div class="display-tooltip-trigger-wrapper">
+    <!--v-if--><button popovertarget="nuxt-tooltip-fixed" popovertargetaction="toggle" type="button" class="display-tooltip-trigger-button" aria-label="Toggle the popover" aria-expanded="false"><span class="iconify i-fa7-solid:circle-question display-tooltip-trigger-icon" aria-hidden="true"></span></button>
+  </div>
+  <div id="nuxt-tooltip-fixed" popover="" class="display-tooltip-popover">
+    <div class="display-tooltip-popover-content">
+      <div class="display-tooltip-rich-content">
+        <h4 class="display-tooltip-rich-title">Title</h4>
+        <p class="display-tooltip-rich-body">Body copy</p><span class="display-tooltip-rich-action">Learn more</span><button type="button" data-testid="input-button" data-theme="default" data-variant="inline" class="input-button display-tooltip-close-button" popovertarget="nuxt-tooltip-fixed" popovertargetaction="hide" aria-label="Close tool tip">
+          <!--v-if-->
+          <!--v-if--><span class="input-button-text">Close</span>
+          <!--v-if-->
+          <!--v-if-->
+        </button>
+      </div>
+    </div>
+  </div>
+</div>"
+`;

package/app/components/02.molecules/navigation/deep-expanding-menu/DeepExpandingMenu.vue

@@ -7,6 +7,7 @@
         <div v-else class="navigation-group" :style="`--_anchor-name: --anchor-${uid}-${key};`">
           <button
             :ref="(el) => setElement(triggerEls, key, el)"
+            type="button"
             :popovertarget="`popovertarget-${uid}-${key}`"
             class="navigation-group-toggle"
             :aria-expanded="isOpen && activeKey === key"

package/app/components/02.molecules/navigation/deep-expanding-menu/tests/__snapshots__/DeepExpandingMenu.spec.ts.snap

@@ -3,7 +3,7 @@
 exports[`DeepExpandingMenu > renders correct HTML structure 1`] = `
 "<nav class="deep-expanding-menu">
   <div class="inner"><a href="/" class="navigation-link">Home</a>
-    <div class="navigation-group" style="--_anchor-name: --anchor-v-0-0-1;"><button popovertarget="popovertarget-v-0-0-1" class="navigation-group-toggle" aria-expanded="false"><span>Services</span><span class="iconify i-bi:caret-down-fill icon" aria-hidden="true"></span></button>
+    <div class="navigation-group" style="--_anchor-name: --anchor-v-0-0-1;"><button type="button" popovertarget="popovertarget-v-0-0-1" class="navigation-group-toggle" aria-expanded="false"><span>Services</span><span class="iconify i-bi:caret-down-fill icon" aria-hidden="true"></span></button>
       <div id="popovertarget-v-0-0-1" class="navigation-group-panel" popover="">
         <h4 class="page-heading-4 mb-6">Our services</h4>
         <ul class="navigation-group-list">

package/app/components/03.organisms/image-galleries/carousel-flip/CarouselFlip.vue

@@ -37,6 +37,7 @@
         <ul class="markers-list">
           <li v-for="index in itemCount" :key="index" class="markers-item">
             <button
+              type="button"
               class="btn-marker"
               :class="[{ active: displayActiveIndex === index - 1 }]"
               :aria-label="`${jumpToItemLabel} ${index}`"

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

@@ -89,3 +89,10 @@ Or scoped by a page/section wrapper class:
 
 `:style-class-passthrough` (string or string array) adds classes to the root `.form-field` element.
 
+---
+
+## Notes
+
+- FormField sets no `overflow-wrap` or `min-inline-size` on its slot content. The `*Field`
+  components wrap their own long copy; plain text you slot in directly needs its own wrapping rule.
+

package/app/components/05.forms/form-field/stories/FormField.stories.ts

@@ -1,5 +1,9 @@
+import { ref } from "vue";
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import StorybookComponent from "../FormField.vue";
+import InputTextField from "../../input-text/InputTextField.vue";
+import CanvasSwitcher from "../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
+import type { MediaCanvas } from "~/types/components";
 
 interface FormFieldStoryArgs {
   width: "narrow" | "medium" | "wide";
@@ -27,6 +31,32 @@ export default {
     fieldHasError: false,
     styleClassPassthrough: "",
   },
+  decorators: [
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "fullWidthCanvas");
+        return { canvasName };
+      },
+      template: `
+        <div style="padding: 1.2rem 1.6rem; border-block-end: 1px solid currentColor;">
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </div>
+        <div :class="canvasName" style="margin-inline: auto;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Layout-only wrapper for one form control. `width` (`narrow`/`medium`/`wide`) caps its width, `has-gutter` insets it from the container edges, and `field-has-error` adds `data-invalid`, which switches every descendant to the error theme. Put an `*Field` component in the default slot; it renders no label, input or error text itself. `style-class-passthrough` lands on the `.form-field` root.",
+      },
+    },
+  },
 } as Meta<FormFieldStoryArgs>;
 
 const demoStyles = `
@@ -46,9 +76,23 @@ const demoStyles = `
       padding: 1.2rem;
       font-size: 1.4rem;
     }
+    .form-field-story-note {
+      font-size: 1.4rem;
+      margin: 1.6rem;
+    }
   </component>
 `;
 
+// Links in the canvas open in the Storybook manager (target="_top"), not inside the preview iframe.
+const usageNote = `
+  <p class="form-field-story-note">
+    Dashed outline: container. Solid outline and tint: the FormField. For FormField wrapping real
+    fields inside a form, open the
+    <a href="/?path=/story/patterns-contact-form--default" target="_top">Contact Form</a> pattern or the
+    <a href="/?path=/story/components-forms-form-wrapper-formwrapper--default" target="_top">FormWrapper</a> story.
+  </p>
+`;
+
 const Template: StoryFn<FormFieldStoryArgs> = (args) => ({
   components: { StorybookComponent },
   setup() {
@@ -57,7 +101,7 @@ const Template: StoryFn<FormFieldStoryArgs> = (args) => ({
   template: `
     <div>
       ${demoStyles}
-      <p style="font-size: 1.4rem; margin: 1.6rem;">Dashed outline: container. Solid outline and tint: the FormField.</p>
+      ${usageNote}
       <div class="form-field-story-frame">
         <StorybookComponent
           :width="args.width"
@@ -73,6 +117,9 @@ const Template: StoryFn<FormFieldStoryArgs> = (args) => ({
 });
 
 export const Default = Template.bind({});
+Default.parameters = {
+  docs: { description: { story: "One FormField around a placeholder control. Use the Controls panel to try each width, the gutter and the error state." } },
+};
 
 const WidthsTemplate: StoryFn<FormFieldStoryArgs> = (args) => ({
   components: { StorybookComponent },
@@ -82,6 +129,7 @@ const WidthsTemplate: StoryFn<FormFieldStoryArgs> = (args) => ({
   template: `
     <div>
       ${demoStyles}
+      ${usageNote}
       <div class="form-field-story-frame">
         <StorybookComponent
           v-for="w in widths"
@@ -98,7 +146,73 @@ const WidthsTemplate: StoryFn<FormFieldStoryArgs> = (args) => ({
 });
 
 export const AllWidths = WidthsTemplate.bind({});
-AllWidths.parameters = { controls: { include: ["hasGutter", "fieldHasError"] } };
+AllWidths.parameters = {
+  controls: { include: ["hasGutter", "fieldHasError"] },
+  docs: {
+    description: {
+      story: "The three widths stacked. Each caps at its `--form-field-max-width-*` token and shrinks to the container (minus the gutter) below that.",
+    },
+  },
+};
 
 export const NoGutter = Template.bind({});
 NoGutter.args = { width: "wide", hasGutter: false };
+NoGutter.parameters = {
+  docs: { description: { story: "`has-gutter` off: the field runs edge to edge of its container. Use this when the parent already pads its content." } },
+};
+
+const stressLabel =
+  "📧 Elektronischepostadressefürdiebenachrichtigungüberbestellungen https://example.com/a/very/long/unbroken/url <b>not bold</b> البريد";
+const stressValue = "alex.morgan.with.a.very.long.unbroken.address@subdomain.northtown-example.co.uk";
+const stressError = "DieseadresseistleiderungültigbitteüberprüfenSiedieSchreibweise";
+
+const StressTemplate: StoryFn<FormFieldStoryArgs> = (args) => ({
+  components: { StorybookComponent, InputTextField },
+  setup() {
+    const fields = ref([
+      { width: "narrow", hasGutter: true, hasError: true, value: stressValue },
+      { width: "medium", hasGutter: true, hasError: false, value: "" },
+      { width: "wide", hasGutter: false, hasError: true, value: "x" },
+    ]);
+    return { args, fields, stressLabel, stressError };
+  },
+  template: `
+    <div>
+      ${demoStyles}
+      ${usageNote}
+      <div class="form-field-story-frame">
+        <StorybookComponent
+          v-for="(field, index) in fields"
+          :key="index"
+          :width="field.width"
+          :has-gutter="field.hasGutter"
+          :field-has-error="field.hasError"
+          :style-class-passthrough="args.styleClassPassthrough"
+        >
+          <InputTextField
+            v-model="field.value"
+            :name="'stress-' + index"
+            type="email"
+            :label="stressLabel"
+            :error-message="field.hasError ? stressError : ''"
+            :field-has-error="field.hasError"
+            required
+          ></InputTextField>
+        </StorybookComponent>
+      </div>
+    </div>
+  `,
+});
+
+export const StressTest = StressTemplate.bind({});
+StressTest.storyName = "Stress Test (Worst-Case Data)";
+StressTest.parameters = {
+  initialCanvas: "mobileCanvas",
+  controls: { include: ["styleClassPassthrough"] },
+  docs: {
+    description: {
+      story:
+        "Each width, with and without the gutter and error state, around an `InputTextField` carrying long unbroken German, a URL, emoji, HTML-like and right-to-left label copy, a long unbroken value and an unbroken error. Check at every canvas width: every FormField stays inside the dashed container, the gutter stays visible on both sides, and the error theme reaches the field inside. Wrapping the slot content is the slotted control's job (FormField doesn't change `overflow-wrap`), so plain text you slot in needs its own.",
+    },
+  },
+};

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

@@ -35,11 +35,14 @@ behaviour; setting the token now works as expected.
 
 | Selector | When |
 |---|---|
-| `.form-fieldset[aria-invalid="true"]` | `field-has-error` is `true` |
+| `.form-fieldset[aria-invalid="true"]` | `field-has-error` is `true` (the attribute is absent otherwise) |
 | `.form-fieldset[role="radiogroup"]` | Rendered by `MultipleRadiobuttons` (`group-role="radiogroup"`) |
 
 > **Changed 2026-09-26**: the fieldset no longer adds a bare `.error` class in the error state.
 > Target `[aria-invalid="true"]` instead.
+>
+> **Changed 2026-10-17**: a valid fieldset no longer renders `aria-invalid="false"`. Replace any
+> `[aria-invalid="false"]` selector with `:not([aria-invalid])`.
 
 The wrapping components add their own class too (`.single-checkbox-fieldset`,
 `.multiple-checkboxes-fieldset`, `.multiple-radiobuttons-fieldset`), so you can scope overrides
@@ -86,3 +89,10 @@ Set the tokens above on an element you own (a page or section class, or a class
 
 `:style-class-passthrough` (string or string array) adds classes to the `<fieldset>`.
 
+---
+
+## Notes
+
+- The fieldset sets `min-inline-size: 0`, so a native fieldset's min-content width can't push it
+  past a narrow column, and the legend wraps long unbroken copy (`overflow-wrap: anywhere`).
+  Wrapping the slotted controls is the slot content's job.