@boostdev/design-system-components 2.5.1 → 2.7.0

package/src/components/interaction/Button/Button.module.css

@@ -46,17 +46,20 @@
     white-space: nowrap;
     line-height: 1;
 
-    /* Colour model: override --button_color + --button_on-color to re-theme */
+    /* Identity tokens — override --button_color + --button_on-color to re-theme */
     --button_color:        var(--bds-color_interactive);
     --button_on-color:     var(--bds-color_on-interactive);
 
-    /* Text-safe variant of --button_color for use on page background (ghost text/border) */
+    /* Text-safe variant of --button_color for use on page background (outline text/border) */
     --button_color--on-bg: var(--bds-color_interactive_on-bg);
 
-    background-color: var(--button_bg, var(--button_color));
-    color: var(--button_text, var(--button_on-color));
-    border: var(--button_border, none);
-    --bdc_color: transparent;
+    /* Layered cascade: the consumer-facing overrides (--button_bg, --button_text,
+       --button_border) are read OUTERMOST so an ancestor-set value always wins
+       over variant + hover defaults. Variants and hover write to the inner
+       --button_*--variant slot, never to the public tokens. */
+    background-color: var(--button_bg, var(--button_bg--variant, var(--button_color)));
+    color:            var(--button_text, var(--button_text--variant, var(--button_on-color)));
+    --bdc_color:      var(--button_border, var(--button_border--variant, transparent));
 
     box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
     transition: var(--bds-animation_transition), --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing);
@@ -65,12 +68,14 @@
   /* Default: filled with --button_color, no visible border */
   .button.--default { /* inherits base — no overrides needed */ }
 
-  /* Outline: transparent background, border and text use text-safe --button_color--on-bg */
+  /* Outline: transparent background, border and text use text-safe --button_color--on-bg.
+     Resting overrides (--button_bg--outline, --button_text--outline, --button_border--outline)
+     are honored if the consumer sets them. */
   .button.--outline,
   .button.--ghost /* @deprecated — use variant="outline" */ {
-    --button_bg:   transparent;
-    --button_text: var(--button_color--on-bg);
-    --bdc_color:   var(--button_color--on-bg);
+    --button_bg--variant:     var(--button_bg--outline, transparent);
+    --button_text--variant:   var(--button_text--outline, var(--button_color--on-bg));
+    --button_border--variant: var(--button_border--outline, var(--button_color--on-bg));
   }
 
   .button.--size_small {
@@ -164,10 +169,10 @@
   /* Default hover: outline appears, bg becomes page surface */
   @media (hover: hover) and (pointer: fine) {
     .button.--default:hover {
-      --button_bg:          var(--button_bg--hover, var(--bds-color_bg));
-      --button_text:        var(--button_text--hover, var(--bds-color_interactive_on-bg));
-      --button_pulse-color: var(--button_pulse-color--hover, var(--bds-color_interactive_on-bg));
-      --bdc_color:          currentcolor;
+      --button_bg--variant:     var(--button_bg--hover, var(--bds-color_bg));
+      --button_text--variant:   var(--button_text--hover, var(--bds-color_interactive_on-bg));
+      --button_border--variant: var(--button_border--hover, currentcolor);
+      --button_pulse-color:     var(--button_pulse-color--hover, var(--bds-color_interactive_on-bg));
     }
   }
 
@@ -175,9 +180,9 @@
   @media (hover: hover) and (pointer: fine) {
     .button.--outline:hover,
     .button.--ghost:hover {
-      --button_bg:   var(--button_bg--outline-hover, var(--button_color));
-      --button_text: var(--button_text--outline-hover, var(--button_on-color));
-      --bdc_color:   transparent;
+      --button_bg--variant:     var(--button_bg--outline-hover, var(--button_color));
+      --button_text--variant:   var(--button_text--outline-hover, var(--button_on-color));
+      --button_border--variant: var(--button_border--outline-hover, transparent);
     }
   }
 }

package/src/components/interaction/Toast/Toast.mdx

@@ -67,17 +67,36 @@ showToast('New message received', 'info');
 
 ## CSS variables
 
+The override surface is **layered**. Setting a public token on the toast (or any ancestor) themes every variant; setting a per-variant token themes only that one variant.
+
+### Public override tokens (win over variant defaults)
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--toast_color`</td><td>per variant</td><td>Toast background. Set to theme every variant at once.</td></tr>
+<tr><td>`--toast_on-color`</td><td>per variant</td><td>Toast text colour.</td></tr>
+</tbody>
+</table>
+
+### Per-variant overrides
 
 <table>
 <thead>
-<tr><th>Variable</th><th>Description</th></tr>
+<tr><th>Variant</th><th>Background</th><th>Text</th></tr>
 </thead>
 <tbody>
-<tr><td>`--toast_color`</td><td>Toast background</td></tr>
-<tr><td>`--toast_on-color`</td><td>Toast text colour</td></tr>
+<tr><td>`info`</td><td>`--toast_color--info`</td><td>`--toast_on-color--info`</td></tr>
+<tr><td>`success`</td><td>`--toast_color--success`</td><td>`--toast_on-color--success`</td></tr>
+<tr><td>`warning`</td><td>`--toast_color--warning`</td><td>`--toast_on-color--warning`</td></tr>
+<tr><td>`error`</td><td>`--toast_color--error`</td><td>`--toast_on-color--error`</td></tr>
 </tbody>
 </table>
 
+Defaults resolve to the corresponding foundation tokens.
+
 
 ## Accessibility
 

package/src/components/interaction/Toast/Toast.module.css

@@ -16,8 +16,11 @@
 
   .toast {
     padding: var(--bds-space_m) var(--bds-space_l);
-    background-color: var(--toast_color, var(--bds-color_bg));
-    color: var(--toast_on-color, var(--bds-color_on-bg));
+
+    /* Layered cascade: public overrides (--toast_color, --toast_on-color) win
+       over per-variant defaults. Variants write to the inner --toast_*--variant slot. */
+    background-color: var(--toast_color, var(--toast_color--variant, var(--bds-color_bg)));
+    color:            var(--toast_on-color, var(--toast_on-color--variant, var(--bds-color_on-bg)));
     border-radius: var(--bds-border_radius--s);
     box-shadow: var(--bds-shadow_s);
     display: flex;
@@ -28,23 +31,23 @@
   }
 
   .toast.--variant_success {
-    --toast_color: var(--bds-color_success);
-    --toast_on-color: var(--bds-color_on-success);
+    --toast_color--variant:    var(--toast_color--success, var(--bds-color_success));
+    --toast_on-color--variant: var(--toast_on-color--success, var(--bds-color_on-success));
   }
 
   .toast.--variant_warning {
-    --toast_color: var(--bds-color_warning);
-    --toast_on-color: var(--bds-color_on-warning);
+    --toast_color--variant:    var(--toast_color--warning, var(--bds-color_warning));
+    --toast_on-color--variant: var(--toast_on-color--warning, var(--bds-color_on-warning));
   }
 
   .toast.--variant_info {
-    --toast_color: var(--bds-color_bg--subtle);
-    --toast_on-color: var(--bds-color_on-bg--subtle);
+    --toast_color--variant:    var(--toast_color--info, var(--bds-color_bg--subtle));
+    --toast_on-color--variant: var(--toast_on-color--info, var(--bds-color_on-bg--subtle));
   }
 
   .toast.--variant_error {
-    --toast_color: var(--bds-color_error);
-    --toast_on-color: var(--bds-color_on-error);
+    --toast_color--variant:    var(--toast_color--error, var(--bds-color_error));
+    --toast_on-color--variant: var(--toast_on-color--error, var(--bds-color_on-error));
   }
 
   .message {

package/src/components/interaction/form/FieldGroup/FieldGroup.mdx

@@ -0,0 +1,113 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './FieldGroup.stories';
+
+<Meta of={Stories} />
+
+# FieldGroup
+
+Semantically groups related form fields under a single `<fieldset>` and lays them out either horizontally (with a CSS container query that collapses to a vertical stack when the FieldGroup itself is too narrow) or vertically.
+
+Use this any time multiple fields belong to the same conceptual section — contact details, address, search filters, registration step — and you want them grouped for screen readers AND visually arranged on a single row when there's room.
+
+## When to use
+
+- Two or more related form fields that should sit side by side on wide screens.
+- Sections inside a longer form that need a visual + semantic boundary.
+- A fieldset whose layout should adapt to its **container's** width, not the viewport's (e.g. a form rendered inside a sidebar or dialog).
+
+## When **not** to use
+
+- A group of related checkboxes — use `CheckboxGroup` instead (it manages legend + error/hint slots specifically for the boolean-list case).
+- A group of related radio inputs — use `RadioGroup`.
+- A single field — wrap nothing; just render the field.
+
+## Variants
+
+- **`horizontal`** (default) — fields flow into a row; each claims at least `--fieldGroup_min-field-width`. When the FieldGroup's own inline-size drops below the **auto-derived** threshold (`N × min-field-width + (N − 1) × gap`, where `N` is the actual number of children), the layout collapses to a single column via a CSS container query. A 2-field group collapses earlier than a 5-field group; you don't have to tune anything per call site.
+- **`vertical`** — fields always stack one per row.
+
+<Canvas of={Stories.Horizontal} />
+<Canvas of={Stories.Vertical} />
+
+### Container query in action
+
+The collapse-to-vertical threshold measures the **FieldGroup itself**, not the viewport. The FieldGroup below sits inside a 20 rem wrapper, so the same horizontal variant collapses cleanly to a single column even though the page is wide.
+
+<Canvas of={Stories.HorizontalCollapsesInNarrowContainer} />
+
+### Mixed inputs
+
+Any form input works as a child — `FormInput`, `Select`, `Combobox`, `NumberInput`, `Textarea`, `Switch`, etc.
+
+<Canvas of={Stories.WithSelectAndInputs} />
+
+### Without a legend
+
+Omit `legend` and provide an `aria-label` (or `aria-labelledby`) on the fieldset directly when the surrounding context already names the group.
+
+<Canvas of={Stories.WithoutLegend} />
+
+### Disabled
+
+The native `disabled` attribute on the fieldset disables every form control inside it without per-field wiring.
+
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## HTML attribute forwarding
+
+Extends `FieldsetHTMLAttributes<HTMLFieldSetElement>`; spreads all unrecognised props onto the root `<fieldset>` (`id`, `name`, `form`, `disabled`, `aria-*`, `data-*`, every DOM event handler, etc.). The consumer-provided `className` is merged with the internal classes via `cn()`.
+
+## CSS variables
+
+All public override tokens. Set on the FieldGroup or any ancestor; they cascade.
+
+### Layout
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--fieldGroup_gap` | `var(--bds-space_m)` | Gap between fields. |
+| `--fieldGroup_min-field-width` | `12rem` | Minimum width each field claims in horizontal mode before wrapping. |
+
+### Legend
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--fieldGroup_legend-color` | `var(--bds-color_on-bg)` | Legend text colour. |
+| `--fieldGroup_legend-font-size` | `var(--bds-font_size--heading-3)` | Legend font size. |
+| `--fieldGroup_legend-font-weight` | `var(--bds-font_weight--semibold)` | Legend font weight. |
+| `--fieldGroup_legend-line-height` | `var(--bds-font_line-height--heading)` | Legend line height. |
+| `--fieldGroup_legend-padding-block` | `var(--bds-space_xs)` | Legend block padding. |
+| `--fieldGroup_legend-gap` | `var(--bds-space_m)` | Space below the legend before the fields. |
+| `--fieldGroup_legend-border-block-end` | `1px solid var(--bds-color_bg--subtle)` | Subtle separator under the legend. Set to `none` to remove. |
+
+## Accessibility
+
+- Renders as `<fieldset>` so assistive tech announces the legend before each field, and the native `disabled` attribute cascades to all descendants.
+- When `legend` is omitted, you must provide `aria-label` or `aria-labelledby` on the FieldGroup so the group still has an accessible name.
+- The container query is a layout-only change — DOM order stays in source order, so the tab/reading order is unaffected by the horizontal-to-vertical switch.
+
+## How the responsive layout works
+
+The horizontal variant uses `display: flex; flex-flow: row wrap;` with each child claiming at least `--fieldGroup_min-field-width`. This handles natural wrapping across multiple rows.
+
+Layered on top, a CSS [`@container`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@container) query forces a clean single-column layout when the FieldGroup itself is narrower than the **auto-derived** collapse threshold:
+
+```css
+--fieldGroup_collapse-threshold:
+  calc(
+    var(--fieldGroup_field-count) * var(--fieldGroup_min-field-width)
+    + (var(--fieldGroup_field-count) - 1) * var(--fieldGroup_gap)
+  );
+
+@container field-group (max-inline-size: var(--fieldGroup_collapse-threshold)) {
+  .fieldGroup.--variant_horizontal .fields { flex-direction: column; }
+}
+```
+
+`--fieldGroup_field-count` is set by the React component as an inline `style` custom property derived from `Children.count(children)`, so the threshold scales with the actual content. A 2-field group collapses around `2 × 12rem + 1 × gap`; a 5-field group collapses around `5 × 12rem + 4 × gap`. No magic numbers per call site.
+
+Because the query is bound to the FieldGroup's own inline-size (via `container-type: inline-size`), the same FieldGroup behaves correctly whether you place it in a sidebar, a modal, a 2-up grid cell, or a full-width page — with zero media-query wiring at the call site.

package/src/components/interaction/form/FieldGroup/FieldGroup.module.css

@@ -0,0 +1,96 @@
+@layer boostdev.component {
+  .fieldGroup {
+    /* Reset fieldset defaults */
+    border: 0;
+    margin: 0;
+    padding: 0;
+    min-inline-size: 0;
+
+    /* Establish an inline-size containment context so descendant rules can
+       use @container against the FieldGroup's own width — independent of the
+       viewport. Without this, the @container rule below would never match. */
+    container-type: inline-size;
+    container-name: field-group;
+
+    /* Field count is injected by the React component as an inline style:
+       `style={{ '--fieldGroup_field-count': N }}`. Read with a `1` fallback
+       so the calc below stays well-formed if the property is ever missing
+       (SSR pre-hydration, manual `<fieldset class="…">` usage in tests).
+       This is the only public token we *write* — every other public token is
+       only ever *read* with a foundation default as fallback, so a consumer
+       can override `--fieldGroup_*` on any ancestor and the new value
+       cascades in without being clobbered by a local declaration. */
+    --fieldGroup_collapse-threshold:
+      calc(
+        var(--fieldGroup_field-count, 1)
+        * var(--fieldGroup_min-field-width, 12rem)
+        + (var(--fieldGroup_field-count, 1) - 1)
+        * var(--fieldGroup_gap, var(--bds-space_m))
+      );
+  }
+
+  .legend {
+    /* Reset legend's UA quirks: float, default offset, default font.
+       <legend> is a fieldset child, not a flex/grid child of .fields, so it
+       gets its own positioning. We render it as a block-level section heading. */
+    inline-size: 100%;
+    padding-inline: 0;
+    padding-block:
+      var(--fieldGroup_legend-padding-block, var(--bds-space_xs));
+    margin-block-end:
+      var(--fieldGroup_legend-gap, var(--bds-space_m));
+    border-block-end:
+      var(--fieldGroup_legend-border-block-end, 1px solid var(--bds-color_bg--subtle));
+    color:
+      var(--fieldGroup_legend-color, var(--bds-color_on-bg));
+    font-family: var(--bds-font_family--body);
+    font-size:
+      var(--fieldGroup_legend-font-size, var(--bds-font_size--heading-3));
+    font-weight:
+      var(--fieldGroup_legend-font-weight, var(--bds-font_weight--semibold));
+    line-height:
+      var(--fieldGroup_legend-line-height, var(--bds-font_line-height--heading));
+  }
+
+  .fields {
+    display: flex;
+    flex-direction: column;
+    gap: var(--fieldGroup_gap, var(--bds-space_m));
+  }
+
+  /* Horizontal variant: row layout with flex-wrap. Each child claims at least
+     --fieldGroup_min-field-width and grows to fill remaining space. The
+     `flex-wrap` already handles partial wrapping; the @container rule below
+     forces a clean single-column stack when the whole row would no longer
+     fit cleanly. */
+  .fieldGroup.--variant_horizontal .fields {
+    flex-flow: row wrap;
+
+    /* `align-items` left at its `stretch` default — each field's
+       label/input/message stays top-anchored by block flow, so the inputs
+       line up regardless. Consumers that want a non-default cross-axis
+       behavior set it from the outside via the consumer-supplied
+       className. */
+  }
+
+  .fieldGroup.--variant_horizontal .fields > * {
+    flex: 1 1 var(--fieldGroup_min-field-width, 12rem);
+    min-inline-size: 0;
+  }
+
+  /* When the FieldGroup itself is too narrow to fit a complete horizontal
+     row of all its fields at minimum width + gaps, collapse to a clean
+     single column. The threshold is derived automatically from the field
+     count + min-field-width + gap (see --fieldGroup_collapse-threshold
+     above), so the same FieldGroup adapts whether it has 2 or 6 fields,
+     in any container — no media-query wiring at the call site. */
+  @container field-group (max-inline-size: var(--fieldGroup_collapse-threshold)) {
+    .fieldGroup.--variant_horizontal .fields {
+      flex-direction: column;
+    }
+
+    .fieldGroup.--variant_horizontal .fields > * {
+      flex: 1 1 auto;
+    }
+  }
+}

package/src/components/interaction/form/FieldGroup/FieldGroup.spec.tsx

@@ -0,0 +1,196 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { render, screen } from '@testing-library/react';
+import { FieldGroup } from './FieldGroup';
+
+const cssSource = readFileSync(
+  resolve(process.cwd(), 'src/components/interaction/form/FieldGroup/FieldGroup.module.css'),
+  'utf8',
+);
+
+describe('FieldGroup', () => {
+  it('renders a <fieldset> with the children inside', () => {
+    render(
+      <FieldGroup>
+        <input data-testid="email" />
+        <input data-testid="phone" />
+      </FieldGroup>,
+    );
+    const group = screen.getByRole('group');
+    expect(group.tagName).toBe('FIELDSET');
+    expect(screen.getByTestId('email')).toBeInTheDocument();
+    expect(screen.getByTestId('phone')).toBeInTheDocument();
+  });
+
+  it('renders the legend when provided', () => {
+    render(
+      <FieldGroup legend="Contact details">
+        <input />
+      </FieldGroup>,
+    );
+    expect(screen.getByRole('group', { name: 'Contact details' })).toBeInTheDocument();
+    expect(screen.getByText('Contact details').tagName).toBe('LEGEND');
+  });
+
+  it('omits the legend when not provided', () => {
+    render(
+      <FieldGroup aria-label="Address">
+        <input />
+      </FieldGroup>,
+    );
+    expect(screen.queryByText(/./, { selector: 'legend' })).not.toBeInTheDocument();
+  });
+
+  it('applies the horizontal variant class by default', () => {
+    const { container } = render(
+      <FieldGroup>
+        <input />
+      </FieldGroup>,
+    );
+    const fieldset = container.querySelector('fieldset');
+    expect(fieldset?.className).toMatch(/--variant_horizontal/);
+  });
+
+  it('applies the vertical variant class when requested', () => {
+    const { container } = render(
+      <FieldGroup variant="vertical">
+        <input />
+      </FieldGroup>,
+    );
+    const fieldset = container.querySelector('fieldset');
+    expect(fieldset?.className).toMatch(/--variant_vertical/);
+    expect(fieldset?.className).not.toMatch(/--variant_horizontal/);
+  });
+
+  it('merges a consumer-provided className alongside the internal classes', () => {
+    const { container } = render(
+      <FieldGroup className="my-group">
+        <input />
+      </FieldGroup>,
+    );
+    const fieldset = container.querySelector('fieldset')!;
+    expect(fieldset.classList.contains('my-group')).toBe(true);
+    expect(fieldset.className).toMatch(/fieldGroup/);
+  });
+
+  it('forwards arbitrary HTML attributes to the fieldset', () => {
+    render(
+      <FieldGroup id="contact" data-testid="grp" aria-describedby="hint">
+        <input />
+      </FieldGroup>,
+    );
+    const group = screen.getByTestId('grp');
+    expect(group.id).toBe('contact');
+    expect(group.getAttribute('aria-describedby')).toBe('hint');
+  });
+
+  it('exposes the field count as a CSS custom property for the collapse threshold', () => {
+    const { rerender } = render(
+      <FieldGroup>
+        <input />
+        <input />
+        <input />
+      </FieldGroup>,
+    );
+    let fieldset = screen.getByRole('group') as HTMLFieldSetElement;
+    // The CSS @container rule resolves `--fieldGroup_collapse-threshold` from
+    // this value, so a wrong count silently makes the auto-collapse fire at
+    // the wrong width.
+    expect(fieldset.style.getPropertyValue('--fieldGroup_field-count')).toBe('3');
+
+    rerender(
+      <FieldGroup>
+        <input />
+        <input />
+      </FieldGroup>,
+    );
+    fieldset = screen.getByRole('group') as HTMLFieldSetElement;
+    expect(fieldset.style.getPropertyValue('--fieldGroup_field-count')).toBe('2');
+  });
+
+  it('renders cleanly with zero children and sets the field count to 0', () => {
+    // Threshold calc with N=0 produces a negative max-inline-size; container
+    // queries with a negative length never match, so the layout stays in its
+    // declared variant. No fields, no row, no crash.
+    const { container } = render(<FieldGroup legend="Empty section" />);
+    const fieldset = container.querySelector('fieldset')!;
+    expect(fieldset.style.getPropertyValue('--fieldGroup_field-count')).toBe('0');
+    expect(container.querySelector('legend')).toBeInTheDocument();
+  });
+
+  it('reads every documented public token with a foundation-default fallback', () => {
+    // A reader-site like `color: var(--fieldGroup_legend-color);` (no fallback)
+    // would silently leave unthemed legends unstyled. Lock in the contract:
+    // every documented public token must appear inside a `var(name, ...)`
+    // with a non-empty fallback somewhere in the CSS.
+    const PUBLIC_TOKENS = [
+      '--fieldGroup_gap',
+      '--fieldGroup_min-field-width',
+      '--fieldGroup_legend-color',
+      '--fieldGroup_legend-font-size',
+      '--fieldGroup_legend-font-weight',
+      '--fieldGroup_legend-line-height',
+      '--fieldGroup_legend-padding-block',
+      '--fieldGroup_legend-gap',
+      '--fieldGroup_legend-border-block-end',
+    ];
+
+    for (const token of PUBLIC_TOKENS) {
+      // Match `var(<token>, ...)` with at least one non-whitespace char before
+      // the closing `)`. Captures any read site with a real fallback.
+      const pattern = new RegExp(
+        `var\\(\\s*${token.replace('-', '\\-')}\\s*,\\s*\\S`,
+      );
+      expect(cssSource).toMatch(pattern);
+    }
+  });
+
+  it('does not redeclare any public --fieldGroup_* token at root, so consumer overrides cascade in', () => {
+    // Public override tokens are READ with foundation-default fallbacks
+    // throughout the CSS — never DECLARED at root. If anyone reintroduces a
+    // root-level `--fieldGroup_legend-color: ...` etc., a consumer's override
+    // on an ancestor would be silently clobbered (same bug pattern fixed
+    // across Alert/Badge/Toast/Link/Card/Pagination/Tabs in MR !63).
+    //
+    // The only declarations we allow are:
+    //   - --fieldGroup_collapse-threshold (computed from the public tokens
+    //     via calc; consumers can still override it at any level if they
+    //     want to bypass the formula entirely).
+    //   - --fieldGroup_field-count (set by React inline style, not CSS).
+    //
+    // Anything else with the --fieldGroup_ prefix on a left-hand side is a
+    // regression.
+    const declarations = [
+      ...cssSource.matchAll(/^\s*(--fieldGroup_[A-Za-z0-9_-]+)\s*:/gm),
+    ].map(m => m[1]);
+
+    const publicTokenDeclarations = declarations.filter(
+      name => name !== '--fieldGroup_collapse-threshold',
+    );
+    expect(publicTokenDeclarations).toEqual([]);
+  });
+
+  it('preserves a consumer-supplied inline style alongside the field count', () => {
+    render(
+      <FieldGroup style={{ marginBlockEnd: '2rem' }}>
+        <input />
+      </FieldGroup>,
+    );
+    const fieldset = screen.getByRole('group') as HTMLFieldSetElement;
+    expect(fieldset.style.marginBlockEnd).toBe('2rem');
+    expect(fieldset.style.getPropertyValue('--fieldGroup_field-count')).toBe('1');
+  });
+
+  it('forwards the disabled attribute to the fieldset', () => {
+    render(
+      <FieldGroup disabled>
+        <input />
+      </FieldGroup>,
+    );
+    // jsdom does not propagate fieldset[disabled] to descendants the way real
+    // browsers do; assert the attribute lands on the fieldset itself. The
+    // descendant-disabling behaviour is a UA contract on top of that.
+    const fieldset = screen.getByRole('group') as HTMLFieldSetElement;
+    expect(fieldset.disabled).toBe(true);
+  });
+});

package/src/components/interaction/form/FieldGroup/FieldGroup.stories.tsx

@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { FieldGroup } from './FieldGroup';
+import { FormInput } from '../FormInput';
+import { Select } from '../Select';
+
+const meta = {
+  title: 'React/Form/FieldGroup',
+  component: FieldGroup,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A `<fieldset>` wrapper that groups related form fields under a styled `<legend>`. ' +
+          'The `horizontal` variant lays fields out in a row that auto-collapses to a single ' +
+          'column via a CSS container query when the FieldGroup itself is too narrow.',
+      },
+    },
+  },
+} satisfies Meta<typeof FieldGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Horizontal: Story = {
+  args: { legend: 'Contact details', variant: 'horizontal' },
+  render: args => (
+    <FieldGroup {...args}>
+      <FormInput label="First name" name="firstName" />
+      <FormInput label="Last name" name="lastName" />
+      <FormInput label="Email" name="email" type="email" />
+    </FieldGroup>
+  ),
+};
+
+export const Vertical: Story = {
+  args: { legend: 'Contact details', variant: 'vertical' },
+  render: args => (
+    <FieldGroup {...args}>
+      <FormInput label="First name" name="firstName" />
+      <FormInput label="Last name" name="lastName" />
+      <FormInput label="Email" name="email" type="email" />
+    </FieldGroup>
+  ),
+};
+
+export const HorizontalCollapsesInNarrowContainer: Story = {
+  name: 'Horizontal — collapses in narrow container',
+  args: { legend: 'Same fields, narrower parent', variant: 'horizontal' },
+  render: args => (
+    <div style={{ inlineSize: '20rem', border: '1px dashed currentcolor', padding: '1rem' }}>
+      <FieldGroup {...args}>
+        <FormInput label="First name" name="firstName" />
+        <FormInput label="Last name" name="lastName" />
+        <FormInput label="Email" name="email" type="email" />
+      </FieldGroup>
+    </div>
+  ),
+};
+
+export const WithSelectAndInputs: Story = {
+  args: { legend: 'Address', variant: 'horizontal' },
+  render: args => (
+    <FieldGroup {...args}>
+      <FormInput label="Street" name="street" />
+      <FormInput label="House number" name="houseNumber" />
+      <FormInput label="Postal code" name="postalCode" />
+      <Select
+        label="Country"
+        name="country"
+        options={[
+          { value: 'nl', label: 'Netherlands' },
+          { value: 'be', label: 'Belgium' },
+          { value: 'de', label: 'Germany' },
+        ]}
+      />
+    </FieldGroup>
+  ),
+};
+
+export const WithoutLegend: Story = {
+  args: { 'aria-label': 'Search filters', variant: 'horizontal' },
+  render: args => (
+    <FieldGroup {...args}>
+      <FormInput label="Query" name="q" />
+      <FormInput label="From" name="from" type="date" />
+      <FormInput label="To" name="to" type="date" />
+    </FieldGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { legend: 'Disabled section', variant: 'horizontal', disabled: true },
+  render: args => (
+    <FieldGroup {...args}>
+      <FormInput label="First name" name="firstName" />
+      <FormInput label="Last name" name="lastName" />
+    </FieldGroup>
+  ),
+};