@boostdev/design-system-components 2.6.0 → 2.7.0

package/dist/web-components/index.d.ts

@@ -426,6 +426,61 @@ declare global {
     }
 }
 
+type FieldGroupVariant = 'horizontal' | 'vertical';
+/**
+ * `<bds-field-group>` — framework-agnostic FieldGroup custom element.
+ *
+ * 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. Mirrors the React `FieldGroup` component.
+ *
+ * Attributes:
+ *   variant  — "horizontal" (default) | "vertical"
+ *   legend   — optional legend text rendered above the fields
+ *   disabled — boolean; forwarded to the inner <fieldset>
+ *
+ * Slots:
+ *   (default) — form fields (any element). The slotted-element count is
+ *     measured on each `slotchange` and surfaced via the
+ *     `--fieldGroup_field-count` custom property, which the auto-derived
+ *     collapse threshold reads.
+ *
+ * @example
+ * <bds-field-group variant="horizontal" legend="Contact details">
+ *   <bds-form-input label="First name" name="first"></bds-form-input>
+ *   <bds-form-input label="Last name"  name="last"></bds-form-input>
+ *   <bds-form-input label="Email"      name="email"></bds-form-input>
+ * </bds-field-group>
+ */
+declare class BdsFieldGroup extends LitElement {
+    static styles: lit.CSSResult;
+    static properties: {
+        variant: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        legend: {
+            type: StringConstructor;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+    };
+    variant: FieldGroupVariant;
+    legend: string;
+    disabled: boolean;
+    constructor();
+    private _onSlotChange;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'bds-field-group': BdsFieldGroup;
+    }
+}
+
 /**
  * `<bds-form-input>` — form-associated text input with label, hint, and error support.
  *
@@ -749,4 +804,4 @@ declare global {
     }
 }
 
-export { BdsButtonGroup, BdsCalendar, BdsCarousel, BdsCheckboxGroup, BdsDropdownMenu, BdsDropdownMenuItem, BdsFormInput, BdsGrid, BdsGridItem, BdsPagination, BdsRadioGroup, BdsTable };
+export { BdsButtonGroup, BdsCalendar, BdsCarousel, BdsCheckboxGroup, BdsDropdownMenu, BdsDropdownMenuItem, BdsFieldGroup, type FieldGroupVariant as BdsFieldGroupVariant, BdsFormInput, BdsGrid, BdsGridItem, BdsPagination, BdsRadioGroup, BdsTable };

package/dist/web-components/index.js

@@ -121,6 +121,7 @@ import {
   BdsDescriptionList
 } from "./chunk-AGKJTMJI.js";
 import {
+  A,
   T,
   i,
   i2
@@ -881,6 +882,7 @@ var BdsCheckboxGroup = class extends i2 {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
   static properties = {
@@ -957,6 +959,7 @@ var BdsRadioGroup = class extends i2 {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
   static properties = {
@@ -1007,6 +1010,118 @@ var BdsRadioGroup = class extends i2 {
 };
 customElements.define("bds-radio-group", BdsRadioGroup);
 
+// src/web-components/interaction/form/bds-field-group.ts
+var BdsFieldGroup = class extends i2 {
+  static styles = i`
+    :host {
+      display: block;
+
+      /* Establish an inline-size containment context so the @container rule
+         queries the host's own width — independent of the viewport. */
+      container-type: inline-size;
+      container-name: field-group;
+
+      /* Auto-derived collapse threshold (mirror of the React component).
+         --fieldGroup_field-count is set inline by _onSlotChange; the other
+         tokens use foundation-default fallbacks so the calc rebuilds when
+         a consumer overrides --fieldGroup_min-field-width or _gap. */
+      --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))
+        );
+    }
+
+    fieldset {
+      border: 0;
+      margin: 0;
+      padding: 0;
+      min-inline-size: 0;
+    }
+
+    .legend {
+      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));
+    }
+
+    :host([variant='horizontal']) .fields {
+      flex-flow: row wrap;
+    }
+
+    :host([variant='horizontal']) .fields ::slotted(*) {
+      flex: 1 1 var(--fieldGroup_min-field-width, 12rem);
+      min-inline-size: 0;
+    }
+
+    /* Auto-collapse: when the host's inline-size can't fit a complete
+       horizontal row, switch to a single-column stack. Threshold scales
+       with the actual slotted-element count (see :host calc above). */
+    @container field-group (max-inline-size: var(--fieldGroup_collapse-threshold)) {
+      :host([variant='horizontal']) .fields {
+        flex-direction: column;
+      }
+
+      :host([variant='horizontal']) .fields ::slotted(*) {
+        flex: 1 1 auto;
+      }
+    }
+  `;
+  static properties = {
+    variant: { type: String, reflect: true },
+    legend: { type: String },
+    disabled: { type: Boolean, reflect: true }
+  };
+  constructor() {
+    super();
+    this.variant = "horizontal";
+    this.legend = "";
+    this.disabled = false;
+  }
+  // Arrow-bound for stable identity (unused here but matches the
+  // bds-popover / bds-button conventions for handlers attached in render).
+  _onSlotChange = (e) => {
+    const slot = e.target;
+    const count = slot.assignedElements().length;
+    this.style.setProperty("--fieldGroup_field-count", String(count));
+  };
+  render() {
+    return T`
+      <fieldset ?disabled=${this.disabled}>
+        ${this.legend ? T`<legend class="legend">${this.legend}</legend>` : A}
+        <div class="fields">
+          <slot @slotchange=${this._onSlotChange}></slot>
+        </div>
+      </fieldset>
+    `;
+  }
+};
+customElements.define("bds-field-group", BdsFieldGroup);
+
 // src/web-components/interaction/form/bds-form-input.ts
 var BdsFormInput = class extends i2 {
   static formAssociated = true;
@@ -1118,6 +1233,7 @@ var BdsFormInput = class extends i2 {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
   static properties = {
@@ -2068,6 +2184,7 @@ export {
   BdsDrawer,
   BdsDropdownMenu,
   BdsDropdownMenuItem,
+  BdsFieldGroup,
   BdsFileInput,
   BdsFormInput,
   BdsGrid,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",
@@ -335,5 +335,6 @@
   ],
   "dependencies": {
     "@oddbird/css-anchor-positioning": "^0.9.0"
-  }
+  },
+  "packageManager": "pnpm@11.0.8"
 }

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);
+  });
+});