@boostdev/design-system-components 2.6.0 → 2.7.0

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

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

@@ -0,0 +1,64 @@
+import { Children, CSSProperties, FieldsetHTMLAttributes, ReactNode } from 'react';
+import { cn } from '@boostdev/design-system-foundation';
+import css from './FieldGroup.module.css';
+import type { WithClassName } from '../../../../types';
+
+/**
+ * Layout variants for FieldGroup.
+ *
+ * - `horizontal` (default) — fields flow into a row, each claiming at least
+ *   `--fieldGroup_min-field-width`. When the container's inline-size is too
+ *   narrow to fit the row, a CSS container query collapses the layout to a
+ *   single column.
+ * - `vertical` — fields always stack one per row.
+ */
+export type FieldGroupVariant = 'horizontal' | 'vertical';
+
+export interface FieldGroupProps
+  extends WithClassName,
+    FieldsetHTMLAttributes<HTMLFieldSetElement> {
+  /** Layout direction. Defaults to `horizontal`. */
+  variant?: FieldGroupVariant;
+  /**
+   * Optional legend rendered above the fields. When omitted, set
+   * `aria-label` or `aria-labelledby` on the fieldset for accessibility.
+   */
+  legend?: ReactNode;
+}
+
+/**
+ * `FieldGroup` semantically groups related form fields under a single
+ * `<fieldset>` and lays them out either horizontally (with container-query
+ * fallback to vertical) or vertically.
+ */
+export function FieldGroup({
+  variant = 'horizontal',
+  legend,
+  children,
+  className,
+  style,
+  ...rest
+}: Readonly<FieldGroupProps>) {
+  // Surface the field count to CSS so the @container collapse threshold
+  // scales with the actual content. The CSS uses
+  //   N * --fieldGroup_min-field-width + (N - 1) * --fieldGroup_gap
+  // which is exactly the inline-size required to lay all fields out at
+  // their minimum width with the configured gap. When the FieldGroup's own
+  // inline-size drops below that, the layout collapses to a single column.
+  const fieldCount = Children.count(children);
+  const styleWithCount = {
+    ...style,
+    '--fieldGroup_field-count': fieldCount,
+  } as CSSProperties;
+
+  return (
+    <fieldset
+      {...rest}
+      style={styleWithCount}
+      className={cn(css.fieldGroup, css[`--variant_${variant}`], className)}
+    >
+      {legend !== undefined && <legend className={css.legend}>{legend}</legend>}
+      <div className={css.fields}>{children}</div>
+    </fieldset>
+  );
+}

package/src/components/interaction/form/FieldGroup/index.ts

@@ -0,0 +1,2 @@
+export { FieldGroup } from './FieldGroup';
+export type { FieldGroupProps, FieldGroupVariant } from './FieldGroup';

package/src/components/interaction/form/atoms/Message.module.css

@@ -8,4 +8,8 @@
   .error {
     color: var(--bds-color_error_on-bg);
   }
+
+  .hint {
+    font-style: italic;
+  }
 }

package/src/index.ts

@@ -48,6 +48,8 @@ export { Checkbox } from './components/interaction/form/Checkbox';
 export { CheckboxGroup } from './components/interaction/form/CheckboxGroup';
 export type { CheckboxGroupProps } from './components/interaction/form/CheckboxGroup';
 export { Combobox } from './components/interaction/form/Combobox';
+export { FieldGroup } from './components/interaction/form/FieldGroup';
+export type { FieldGroupProps, FieldGroupVariant } from './components/interaction/form/FieldGroup';
 export type { ComboboxOption } from './components/interaction/form/Combobox';
 export { FileInput } from './components/interaction/form/FileInput';
 export { FormInput } from './components/interaction/form/FormInput';

package/src/web-components/index.ts

@@ -68,6 +68,8 @@ export { BdsTable } from './ui/bds-table';
 export { BdsPagination } from './ui/bds-pagination';
 export { BdsCheckboxGroup } from './interaction/form/bds-checkbox-group';
 export { BdsRadioGroup } from './interaction/form/bds-radio-group';
+export { BdsFieldGroup } from './interaction/form/bds-field-group';
+export type { FieldGroupVariant as BdsFieldGroupVariant } from './interaction/form/bds-field-group';
 export { BdsFormInput } from './interaction/form/bds-form-input';
 export { BdsCarousel } from './ui/bds-carousel';
 export { BdsCalendar } from './ui/bds-calendar';

package/src/web-components/interaction/form/BdsFieldGroup.mdx

@@ -0,0 +1,67 @@
+import { Meta, Canvas } from '@storybook/blocks';
+import * as Stories from './BdsFieldGroup.stories';
+
+<Meta of={Stories} />
+
+# `<bds-field-group>`
+
+Framework-agnostic FieldGroup custom element. Wraps slotted fields in a `<fieldset>` with a styled `<legend>` and lays them out horizontally (with auto-collapse to vertical via CSS container query) or vertically.
+
+Mirrors the React `FieldGroup` component — same token surface, same behavior, same auto-derived collapse threshold.
+
+## Attributes
+
+| Attribute | Values | Default | Description |
+|-----------|--------|---------|-------------|
+| `variant` | `horizontal` \| `vertical` | `horizontal` | Layout direction. |
+| `legend` | string | — | Optional legend text. Falls back to `aria-label` semantics if you set that on the host directly. |
+| `disabled` | boolean | `false` | Forwards to the inner `<fieldset>`; the UA cascades it to descendant form controls (light-DOM children projected through the slot). |
+
+## Slots
+
+- `(default)` — projected form fields (`<bds-form-input>`, `<bds-select>`, etc.). The component listens for `slotchange` and surfaces the slotted-element count via `--fieldGroup_field-count`, which the auto-derived collapse threshold reads.
+
+## Examples
+
+### Horizontal
+<Canvas of={Stories.Horizontal} />
+
+### Vertical
+<Canvas of={Stories.Vertical} />
+
+### Horizontal collapses in a narrow container
+<Canvas of={Stories.HorizontalCollapsesInNarrowContainer} />
+
+### Without a legend
+<Canvas of={Stories.WithoutLegend} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## CSS variables
+
+Same surface as the React component. All public tokens are read with foundation-default fallbacks; consumers can set them on the host (or any ancestor) to theme one or many groups without touching internal classes.
+
+### Layout
+
+| Variable | Default |
+|----------|---------|
+| `--fieldGroup_gap` | `var(--bds-space_m)` |
+| `--fieldGroup_min-field-width` | `12rem` |
+| `--fieldGroup_collapse-threshold` | `calc(N × min-field-width + (N − 1) × gap)` (computed) |
+
+### Legend
+
+| Variable | Default |
+|----------|---------|
+| `--fieldGroup_legend-color` | `var(--bds-color_on-bg)` |
+| `--fieldGroup_legend-font-size` | `var(--bds-font_size--heading-3)` |
+| `--fieldGroup_legend-font-weight` | `var(--bds-font_weight--semibold)` |
+| `--fieldGroup_legend-line-height` | `var(--bds-font_line-height--heading)` |
+| `--fieldGroup_legend-padding-block` | `var(--bds-space_xs)` |
+| `--fieldGroup_legend-gap` | `var(--bds-space_m)` |
+| `--fieldGroup_legend-border-block-end` | `1px solid var(--bds-color_bg--subtle)` |
+
+## Notes on shadow DOM
+
+The component renders its own `<fieldset>` inside the shadow root and projects fields through a `<slot>`. Because slotted elements stay in the host's light DOM, the native `fieldset[disabled]` cascade onto descendants is browser-dependent — modern browsers do propagate disabled to slotted form controls; older ones may not. If you support an older runtime and need a hard guarantee, set `disabled` on each slotted field too.

package/src/web-components/interaction/form/BdsFieldGroup.stories.tsx

@@ -0,0 +1,110 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsFieldGroup({
+  legend,
+  variant,
+  disabled,
+  children,
+}: {
+  legend?: string;
+  variant?: 'horizontal' | 'vertical';
+  disabled?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-field-group',
+    {
+      legend: legend || undefined,
+      variant: variant || undefined,
+      disabled: disabled || undefined,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Form/FieldGroup',
+  component: BdsFieldGroup,
+  tags: ['!stable', 'experimental'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Framework-agnostic FieldGroup. Wraps slotted fields in a `<fieldset>` ' +
+          'and lays them out horizontally with a CSS container query that auto-collapses ' +
+          'to a single column when the host is too narrow to fit a complete row at minimum field width.',
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: 'select', options: ['horizontal', 'vertical'] },
+    legend: { control: 'text' },
+    disabled: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsFieldGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const field = (name: string, label: string, type = 'text') =>
+  React.createElement('bds-form-input', { name, label, type });
+
+export const Horizontal: Story = {
+  args: { legend: 'Contact details', variant: 'horizontal' },
+  render: args => (
+    <BdsFieldGroup {...args}>
+      {field('first', 'First name')}
+      {field('last', 'Last name')}
+      {field('email', 'Email', 'email')}
+    </BdsFieldGroup>
+  ),
+};
+
+export const Vertical: Story = {
+  args: { legend: 'Contact details', variant: 'vertical' },
+  render: args => (
+    <BdsFieldGroup {...args}>
+      {field('first', 'First name')}
+      {field('last', 'Last name')}
+      {field('email', 'Email', 'email')}
+    </BdsFieldGroup>
+  ),
+};
+
+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' }}>
+      <BdsFieldGroup {...args}>
+        {field('first', 'First name')}
+        {field('last', 'Last name')}
+        {field('email', 'Email', 'email')}
+      </BdsFieldGroup>
+    </div>
+  ),
+};
+
+export const WithoutLegend: Story = {
+  args: { variant: 'horizontal' },
+  render: args => (
+    <BdsFieldGroup {...args}>
+      {field('q', 'Query')}
+      {field('from', 'From', 'date')}
+      {field('to', 'To', 'date')}
+    </BdsFieldGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { legend: 'Disabled section', variant: 'horizontal', disabled: true },
+  render: args => (
+    <BdsFieldGroup {...args}>
+      {field('first', 'First name')}
+      {field('last', 'Last name')}
+    </BdsFieldGroup>
+  ),
+};

package/src/web-components/interaction/form/bds-checkbox-group.ts

@@ -64,6 +64,7 @@ export class BdsCheckboxGroup extends LitElement {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
 

package/src/web-components/interaction/form/bds-field-group.spec.ts

@@ -0,0 +1,64 @@
+import { fixture, cleanup } from '../../test/helpers';
+import { BdsFieldGroup } from './bds-field-group';
+
+describe('bds-field-group', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-field-group')).toBe(BdsFieldGroup);
+  });
+
+  it('renders a fieldset in the shadow DOM', async () => {
+    const el = await fixture('<bds-field-group></bds-field-group>');
+    expect(el.shadowRoot!.querySelector('fieldset')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders the legend when the legend attribute is set', async () => {
+    const el = await fixture('<bds-field-group legend="Contact details"></bds-field-group>');
+    const legend = el.shadowRoot!.querySelector('legend');
+    expect(legend?.textContent?.trim()).toBe('Contact details');
+    cleanup(el);
+  });
+
+  it('omits the legend element when no legend attribute is set', async () => {
+    const el = await fixture('<bds-field-group></bds-field-group>');
+    expect(el.shadowRoot!.querySelector('legend')).toBeNull();
+    cleanup(el);
+  });
+
+  it('reflects the default horizontal variant onto the host', async () => {
+    const el = await fixture('<bds-field-group></bds-field-group>') as BdsFieldGroup;
+    expect(el.getAttribute('variant')).toBe('horizontal');
+  });
+
+  it('honors variant="vertical" on the host', async () => {
+    const el = await fixture('<bds-field-group variant="vertical"></bds-field-group>') as BdsFieldGroup;
+    expect(el.getAttribute('variant')).toBe('vertical');
+    cleanup(el);
+  });
+
+  it('forwards the disabled attribute to the inner fieldset', async () => {
+    const el = await fixture('<bds-field-group disabled></bds-field-group>');
+    const fieldset = el.shadowRoot!.querySelector('fieldset') as HTMLFieldSetElement;
+    expect(fieldset.disabled).toBe(true);
+    cleanup(el);
+  });
+
+  it('renders a slot for projected fields', async () => {
+    const el = await fixture(
+      '<bds-field-group><span id="a"></span><span id="b"></span></bds-field-group>',
+    );
+    expect(el.shadowRoot!.querySelector('slot')).not.toBeNull();
+    expect(el.querySelectorAll('span').length).toBe(2);
+    cleanup(el);
+  });
+
+  it('exposes the slotted-element count as --fieldGroup_field-count after slotchange', async () => {
+    const el = await fixture(
+      '<bds-field-group><span></span><span></span><span></span></bds-field-group>',
+    ) as BdsFieldGroup;
+    // slotchange fires synchronously after the initial render; allow a microtask.
+    await new Promise(r => requestAnimationFrame(() => r(null)));
+    expect(el.style.getPropertyValue('--fieldGroup_field-count')).toBe('3');
+    cleanup(el);
+  });
+});

package/src/web-components/interaction/form/bds-field-group.ts

@@ -0,0 +1,157 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+export 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>
+ */
+export class BdsFieldGroup extends LitElement {
+  static styles = css`
+    :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 },
+  };
+
+  declare variant: FieldGroupVariant;
+  declare legend: string;
+  declare disabled: boolean;
+
+  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).
+  private _onSlotChange = (e: Event) => {
+    const slot = e.target as HTMLSlotElement;
+    const count = slot.assignedElements().length;
+    this.style.setProperty('--fieldGroup_field-count', String(count));
+  };
+
+  render() {
+    return html`
+      <fieldset ?disabled=${this.disabled}>
+        ${this.legend
+          ? html`<legend class="legend">${this.legend}</legend>`
+          : nothing}
+        <div class="fields">
+          <slot @slotchange=${this._onSlotChange}></slot>
+        </div>
+      </fieldset>
+    `;
+  }
+}
+
+customElements.define('bds-field-group', BdsFieldGroup);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-field-group': BdsFieldGroup;
+  }
+}

package/src/web-components/interaction/form/bds-form-input.ts

@@ -138,6 +138,7 @@ export class BdsFormInput extends LitElement {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
 

package/src/web-components/interaction/form/bds-radio-group.ts

@@ -66,6 +66,7 @@ export class BdsRadioGroup extends LitElement {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;