@boostdev/design-system-components 2.7.1 → 2.11.0

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsSlider.stories';
 
 # <bds-slider>
 
-Form-associated range slider. Wraps a native `<input type="range">` with a styled fill track driven by the `--slider_fill` CSS custom property.
+Form-associated range slider. Wraps a native `<input type="range">` with a styled fill track driven by the `--slider_fill` CSS custom property, plus label/hint/error wiring matching the other form web components.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -30,6 +30,12 @@ Use `<bds-slider>` for continuous or stepped numeric ranges — volume controls,
 ### With custom min/max (1–5)
 <Canvas of={Stories.WithMinMax} />
 
+### With label and value
+<Canvas of={Stories.WithLabel} />
+
+### Error state
+<Canvas of={Stories.WithError} />
+
 ### Disabled
 <Canvas of={Stories.Disabled} />
 
@@ -39,39 +45,50 @@ Use `<bds-slider>` for continuous or stepped numeric ranges — volume controls,
 
 ## Attributes
 
-| Attribute  | Type    | Default | Description                              |
-|------------|---------|---------|------------------------------------------|
-| `name`     | string  | `""`    | Form field name                          |
-| `value`    | number  | `0`     | Current value                            |
-| `min`      | number  | `0`     | Minimum value                            |
-| `max`      | number  | `100`   | Maximum value                            |
-| `step`     | number  | `1`     | Step increment                           |
-| `disabled` | boolean | `false` | Disables the slider                      |
+| Attribute    | Type    | Default | Description                                          |
+|--------------|---------|---------|-------------------------------------------------------|
+| `name`       | string  | `""`    | Form field name                                        |
+| `value`      | number  | `0`     | Current value                                          |
+| `min`        | number  | `0`     | Minimum value                                          |
+| `max`        | number  | `100`   | Maximum value                                          |
+| `step`       | number  | `1`     | Step increment                                         |
+| `label`      | string  | `""`    | Visible label text, associated with the input via `for`/`id` |
+| `hint`       | string  | —       | Helper text shown below the slider                     |
+| `error`      | string  | —       | Error message; when set the slider enters error state and the input gets `aria-invalid="true"` |
+| `show-value` | boolean | `false` | Shows the current value next to the label               |
+| `disabled`   | boolean | `false` | Disables the slider                                     |
 
 ## Events
 
-| Event    | Detail | Description                          |
-|----------|--------|--------------------------------------|
-| `input`  | —      | Fired continuously as the user drags |
-| `change` | —      | Fired when the user releases         |
+| Event        | Detail            | Description                                                                                             |
+|--------------|-------------------|-----------------------------------------------------------------------------------------------------------|
+| `input`      | —                 | Native event, fired continuously as the user drags                                                        |
+| `bds-change` | `{ value: number }` | Fired when the user releases. Re-dispatched from the host as a composed event so it reliably crosses the shadow boundary — the native `change` event does not. |
 
 ## CSS Custom Properties
 
-| Property                | Description                             |
-|-------------------------|-----------------------------------------|
-| `--slider_fill-color`   | Fill track colour (defaults to `--bds-color_interactive`) |
-| `--slider_track-color`  | Unfilled track colour (defaults to `--bds-color_bg--subtle`) |
-| `--slider_thumb-color`  | Thumb colour (defaults to `--bds-color_interactive`) |
+| Property                 | Description                                          | Default                          |
+|---------------------------|-------------------------------------------------------|-----------------------------------|
+| `--slider_color`          | Track `color` (used as a fallback text/context colour) | `--bds-color_on-bg`               |
+| `--slider_color-active`   | Fill track + thumb colour                              | `--bdc-color_active`              |
+| `--slider_color--error`   | Fill track + thumb colour when `error` is set          | `--bds-color_error`               |
+| `--slider_track-bg`       | Unfilled track colour                                  | `--bds-color_bg--subtle`          |
+| `--slider_track-height`   | Track thickness                                        | `--bds-space_xxs`                 |
+| `--slider_track-radius`   | Track corner radius                                    | `--bds-border_radius--full`       |
+| `--slider_thumb-size`     | Thumb diameter                                         | `calc(--bds-space_s * 2)`         |
+| `--slider_thumb-radius`   | Thumb corner radius                                    | `--bds-border_radius--circle`     |
 
 ## Usage in plain HTML
 
 ```html
-<bds-slider name="volume" value="50" min="0" max="100" step="5"></bds-slider>
+<bds-slider name="volume" label="Volume" value="50" min="0" max="100" step="5" show-value></bds-slider>
 ```
 
 ## Accessibility
 
 - Wraps a native `<input type="range">` which has full browser and assistive technology support
+- `label` renders a shadow `<label for>` bound to the input — set it so the slider has an accessible name
+- `hint`/`error` text is wired to the input via `aria-describedby`; `error` also sets `aria-invalid="true"`
 - Arrow keys adjust the value by `step`
 - `disabled` prevents interaction and reduces opacity
 - Participates in HTML forms via the Form-Associated Custom Elements API

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

@@ -8,6 +8,10 @@ function BdsSlider({
   min,
   max,
   step,
+  label,
+  hint,
+  error,
+  showValue,
   disabled,
 }: {
   name?: string;
@@ -15,6 +19,10 @@ function BdsSlider({
   min?: number;
   max?: number;
   step?: number;
+  label?: string;
+  hint?: string;
+  error?: string;
+  showValue?: boolean;
   disabled?: boolean;
 }) {
   return React.createElement('bds-slider', {
@@ -23,6 +31,10 @@ function BdsSlider({
     min,
     max,
     step,
+    label,
+    hint,
+    error,
+    'show-value': showValue || undefined,
     disabled: disabled || undefined,
   });
 }
@@ -37,6 +49,10 @@ const meta = {
     min: { control: 'number' },
     max: { control: 'number' },
     step: { control: 'number' },
+    label: { control: 'text' },
+    hint: { control: 'text' },
+    error: { control: 'text' },
+    showValue: { control: 'boolean' },
     disabled: { control: 'boolean' },
   },
   decorators: [
@@ -63,6 +79,14 @@ export const WithMinMax: Story = {
   args: { name: 'rating', value: 3, min: 1, max: 5 },
 };
 
+export const WithLabel: Story = {
+  args: { name: 'volume', label: 'Volume', value: 50, showValue: true, hint: 'Adjust the playback volume' },
+};
+
+export const WithError: Story = {
+  args: { name: 'volume', label: 'Volume', value: 90, error: 'Value exceeds the recommended maximum' },
+};
+
 export const Disabled: Story = {
   args: { name: 'volume', value: 40, disabled: true },
 };

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

@@ -30,19 +30,27 @@ Use `<bds-switch>` for binary on/off settings where the change takes immediate e
 ### Disabled
 <Canvas of={Stories.Disabled} />
 
+### Small size
+<Canvas of={Stories.Small} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
 ## Props
 
 <ArgTypes of={Stories} />
 
 ## Attributes
 
-| Attribute  | Type    | Default | Description                                      |
-|------------|---------|---------|--------------------------------------------------|
-| `name`     | string  | `""`    | Form field name                                  |
-| `value`    | string  | `"on"`  | Value submitted when the switch is on            |
-| `checked`  | boolean | `false` | Whether the switch is on                         |
-| `required` | boolean | `false` | Marks the field as required                      |
-| `disabled` | boolean | `false` | Disables the switch                              |
+| Attribute  | Type    | Default    | Description                                                |
+|------------|---------|------------|--------------------------------------------------------------|
+| `name`     | string  | `""`       | Form field name                                             |
+| `value`    | string  | `"on"`     | Value submitted when the switch is on                       |
+| `checked`  | boolean | `false`    | Whether the switch is on                                    |
+| `required` | boolean | `false`    | Marks the field as required                                 |
+| `disabled` | boolean | `false`    | Disables the switch                                         |
+| `error`    | string  | —          | Error message; when set the track shows the error colour and the input reports `aria-invalid="true"` |
+| `size`     | string  | `"medium"` | Track/thumb size: `small`, `medium`, `large`                |
 
 ## Slots
 
@@ -52,21 +60,40 @@ Use `<bds-switch>` for binary on/off settings where the change takes immediate e
 
 ## Events
 
-| Event    | Detail | Description                                    |
-|----------|--------|------------------------------------------------|
-| `change` | —      | Fired when the switch state changes            |
+| Event        | Detail                 | Description                                                                                                  |
+|--------------|------------------------|----------------------------------------------------------------------------------------------------------------|
+| `bds-change` | `{ checked: boolean }` | Composed event fired when the switch is toggled; crosses the shadow boundary so it can be listened for on the host element |
 
 ## Usage in plain HTML
 
 ```html
 <bds-switch name="notifications" value="enabled">Enable notifications</bds-switch>
 <bds-switch name="darkMode" value="on" checked>Dark mode</bds-switch>
+<bds-switch name="compact" size="small">Compact mode</bds-switch>
+<bds-switch name="terms" required error="You must accept the terms">Accept terms</bds-switch>
 ```
 
+## CSS custom properties
+
+| Property                       | Default                                | Description                               |
+|----------------------------------|-------------------------------------------|---------------------------------------------|
+| `--switch_color`               | `var(--bds-color_on-bg)`               | Label text colour                         |
+| `--switch_thumb-size`          | `1.25em` (`1em` small / `1.5em` large) | Thumb diameter — also drives track sizing |
+| `--switch_track-pad`           | `var(--bds-space_xxxs)`                | Padding between track edge and thumb      |
+| `--switch_track-radius`        | `var(--bds-border_radius--full)`       | Track corner radius                       |
+| `--switch_track-bg`            | `var(--bds-color_grey--subtle)`        | Track background when off                 |
+| `--switch_track-bg--active`    | `var(--bdc-color_active--subtle)`      | Track background when on                  |
+| `--switch_thumb-bg`            | `var(--bds-color_interactive)`         | Thumb (and track border) colour when off  |
+| `--switch_thumb-bg--active`    | `var(--bds-color_interactive)`         | Thumb colour when on                      |
+| `--switch_thumb-radius`        | `var(--bds-border_radius--circle)`     | Thumb corner radius                       |
+| `--switch_border-color--error` | `var(--bds-color_error)`               | Track border colour when `error` is set   |
+| `--switch_shadow`              | `var(--bdc-outline_shadow)`            | Track box-shadow tail                     |
+
 ## Accessibility
 
 - Uses `role="switch"` on the inner `<input type="checkbox">` for correct screen reader announcement
 - The inner `<input>` is associated with a `<label>` via matching `id`/`for` attributes
 - The visual track and thumb are inside the `<label>` — clicking the label or the track both toggle the switch
 - `disabled` sets `pointer-events: none` and reduces opacity
-- Participates in HTML forms via the Form-Associated Custom Elements API
+- `error` sets `aria-invalid="true"` on the inner input
+- Participates in HTML forms via the Form-Associated Custom Elements API; `formResetCallback` restores the switch's initial `checked` state on form reset

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

@@ -8,6 +8,8 @@ function BdsSwitch({
   checked,
   required,
   disabled,
+  error,
+  size,
   children,
 }: {
   name?: string;
@@ -15,6 +17,8 @@ function BdsSwitch({
   checked?: boolean;
   required?: boolean;
   disabled?: boolean;
+  error?: string;
+  size?: 'small' | 'medium' | 'large';
   children?: React.ReactNode;
 }) {
   return React.createElement(
@@ -25,6 +29,8 @@ function BdsSwitch({
       checked: checked || undefined,
       required: required || undefined,
       disabled: disabled || undefined,
+      error,
+      size,
     },
     children,
   );
@@ -39,6 +45,8 @@ const meta = {
     checked: { control: 'boolean' },
     required: { control: 'boolean' },
     disabled: { control: 'boolean' },
+    error: { control: 'text' },
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
   },
 } satisfies Meta<typeof BdsSwitch>;
 
@@ -56,3 +64,11 @@ export const Checked: Story = {
 export const Disabled: Story = {
   args: { name: 'notifications', value: 'enabled', disabled: true, children: 'Notifications (disabled)' },
 };
+
+export const Small: Story = {
+  args: { name: 'compact', value: 'enabled', size: 'small', children: 'Compact mode' },
+};
+
+export const WithError: Story = {
+  args: { name: 'terms', value: 'accepted', required: true, error: 'You must accept the terms', children: 'Accept terms' },
+};

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

@@ -30,6 +30,15 @@ Use `<bds-textarea>` for multiline text entry — messages, comments, descriptio
 ### Tall (8 rows)
 <Canvas of={Stories.TallRows} />
 
+### With label
+<Canvas of={Stories.WithLabel} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
 ### Required
 <Canvas of={Stories.Required} />
 
@@ -42,32 +51,49 @@ Use `<bds-textarea>` for multiline text entry — messages, comments, descriptio
 
 ## Attributes
 
-| Attribute     | Type    | Default | Description                              |
-|---------------|---------|---------|------------------------------------------|
-| `name`        | string  | `""`    | Form field name                          |
-| `value`       | string  | `""`    | Text value                               |
-| `placeholder` | string  | `""`    | Placeholder text                         |
-| `rows`        | number  | `4`     | Number of visible rows                   |
-| `required`    | boolean | `false` | Marks the field as required              |
-| `disabled`    | boolean | `false` | Disables the textarea                    |
+| Attribute     | Type    | Default | Description                                             |
+|---------------|---------|---------|----------------------------------------------------------|
+| `name`        | string  | `""`    | Form field name                                          |
+| `value`       | string  | `""`    | Text value                                               |
+| `placeholder` | string  | `""`    | Placeholder text                                         |
+| `rows`        | number  | `4`     | Number of visible rows                                   |
+| `label`       | string  | `""`    | Visible label text, associated via `for`/`id`             |
+| `hint`        | string  | —       | Helper text shown below the textarea                     |
+| `error`       | string  | —       | Error message; when set the textarea enters error state  |
+| `required`    | boolean | `false` | Marks the field as required                               |
+| `disabled`    | boolean | `false` | Disables the textarea                                     |
 
 ## Events
 
-| Event    | Detail | Description                                         |
-|----------|--------|-----------------------------------------------------|
-| `input`  | —      | Fired on every keystroke (native input event)       |
-| `change` | —      | Fired when the value is committed (native change event) |
+| Event        | Detail                | Description                        |
+|--------------|------------------------|-------------------------------------|
+| `bds-input`  | `{ value: string }`   | Fired on every keystroke            |
+| `bds-change` | `{ value: string }`   | Fired when the value is committed   |
+
+## CSS Custom Properties
+
+| Property               | Description                                                     |
+|-------------------------|-------------------------------------------------------------------|
+| `--textarea_border`     | Native `border` shorthand (defaults to `none`; the frame is drawn by the inset bdc box-shadow) |
+| `--textarea_radius`     | Border radius (defaults to `--bdc-outline_radius--l`)             |
+| `--textarea_shadow`     | Extra `box-shadow` layer appended after the bdc frame shadow      |
+| `--textarea_color_bg`   | Background colour (defaults to `--bds-color_bg`)                  |
+| `--textarea_color`      | Text colour (defaults to `--bds-color_on-bg`)                     |
 
 ## Usage in plain HTML
 
 ```html
-<bds-textarea name="message" placeholder="Enter message…" rows="6"></bds-textarea>
-<bds-textarea name="bio" required rows="4"></bds-textarea>
+<bds-textarea name="message" label="Message" placeholder="Enter message…" rows="6"></bds-textarea>
+<bds-textarea name="bio" label="Bio" required rows="4"></bds-textarea>
+<bds-textarea name="feedback" label="Feedback" error="Feedback is required"></bds-textarea>
 ```
 
 ## Accessibility
 
 - Wraps a native `<textarea>` which has full browser and assistive technology support
-- `required` uses the native `required` attribute for browser validation
+- `label` renders a `<label for>` associated with the textarea via matching `id`
+- `error` sets `aria-invalid="true"` on the textarea and links the error message via `aria-describedby`; the message uses `role="alert"` so it is announced immediately
+- `hint` is linked to the textarea via `aria-describedby` for screen reader announcement
+- `required` uses the native `required` attribute for browser validation plus `aria-required="true"`
 - `disabled` sets `pointer-events: none`, reduces opacity, and removes the resize handle
-- Participates in HTML forms via the Form-Associated Custom Elements API
+- Participates in HTML forms via the Form-Associated Custom Elements API; `formResetCallback` restores the textarea's initial value

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

@@ -7,6 +7,9 @@ function BdsTextarea({
   value,
   placeholder,
   rows,
+  label,
+  hint,
+  error,
   required,
   disabled,
 }: {
@@ -14,6 +17,9 @@ function BdsTextarea({
   value?: string;
   placeholder?: string;
   rows?: number;
+  label?: string;
+  hint?: string;
+  error?: string;
   required?: boolean;
   disabled?: boolean;
 }) {
@@ -22,6 +28,9 @@ function BdsTextarea({
     value,
     placeholder,
     rows,
+    label,
+    hint,
+    error,
     required: required || undefined,
     disabled: disabled || undefined,
   });
@@ -61,6 +70,18 @@ export const TallRows: Story = {
   args: { name: 'message', placeholder: 'Enter a longer text…', rows: 8 },
 };
 
+export const WithLabel: Story = {
+  args: { name: 'message', label: 'Message', placeholder: 'Enter your message…' },
+};
+
+export const WithHint: Story = {
+  args: { name: 'message', label: 'Message', hint: 'Max 500 characters' },
+};
+
+export const WithError: Story = {
+  args: { name: 'message', label: 'Message', error: 'Message is required' },
+};
+
 export const Required: Story = {
   args: { name: 'message', placeholder: 'Required field', required: true },
 };

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

@@ -52,4 +52,103 @@ describe('bds-checkbox-group', () => {
     expect(message?.textContent?.trim()).toBe('Select all that apply');
     cleanup(el);
   });
+
+  it('propagates disabled to slotted bds-checkbox elements', async () => {
+    const el = await fixture(
+      '<bds-checkbox-group label="Interests" disabled>' +
+        '<bds-checkbox value="sports">Sports</bds-checkbox>' +
+        '<bds-checkbox value="music">Music</bds-checkbox>' +
+        '</bds-checkbox-group>',
+    ) as BdsCheckboxGroup;
+    await Promise.resolve();
+    const checkboxes = Array.from(el.querySelectorAll('bds-checkbox'));
+    expect(checkboxes.every(checkbox => checkbox.hasAttribute('disabled'))).toBe(true);
+    cleanup(el);
+  });
+
+  it('removes propagated disabled from slotted bds-checkbox elements when re-enabled, keeping individually-disabled ones', async () => {
+    const el = await fixture(
+      '<bds-checkbox-group label="Interests" disabled>' +
+        '<bds-checkbox value="sports">Sports</bds-checkbox>' +
+        '<bds-checkbox value="music" disabled>Music</bds-checkbox>' +
+        '</bds-checkbox-group>',
+    ) as BdsCheckboxGroup;
+    await Promise.resolve();
+
+    el.disabled = false;
+    await el.updateComplete;
+    await Promise.resolve();
+
+    const [sports, music] = Array.from(el.querySelectorAll('bds-checkbox'));
+    expect(sports.hasAttribute('disabled')).toBe(false);
+    expect(music.hasAttribute('disabled')).toBe(true);
+    cleanup(el);
+  });
+
+  it('propagates disabled to a bds-checkbox slotted in after the group is already disabled', async () => {
+    const el = await fixture('<bds-checkbox-group label="Interests" disabled></bds-checkbox-group>') as BdsCheckboxGroup;
+    const checkbox = document.createElement('bds-checkbox');
+    checkbox.setAttribute('value', 'sports');
+    el.appendChild(checkbox);
+    // slotchange fires asynchronously; allow a microtask.
+    await new Promise(r => requestAnimationFrame(() => r(null)));
+    expect(checkbox.hasAttribute('disabled')).toBe(true);
+    cleanup(el);
+  });
+
+  it('exposes a visually-hidden "(required)" text alternative instead of aria-required on the fieldset', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test" required></bds-checkbox-group>');
+    const fieldset = el.shadowRoot!.querySelector('fieldset')!;
+    // aria-required is not supported ARIA on role=group (which is what a bare
+    // <fieldset> maps to) — assert it is never set.
+    expect(fieldset.hasAttribute('aria-required')).toBe(false);
+    const requiredLabel = el.shadowRoot!.querySelector('.requiredLabel');
+    expect(requiredLabel?.textContent?.trim()).toBe('(required)');
+    cleanup(el);
+  });
+
+  it('omits the required text alternative when not required', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test"></bds-checkbox-group>');
+    expect(el.shadowRoot!.querySelector('.requiredLabel')).toBeNull();
+    cleanup(el);
+  });
+
+  it('wires aria-describedby on the fieldset to the error message id', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test" error="Select at least one"></bds-checkbox-group>');
+    const fieldset = el.shadowRoot!.querySelector('fieldset')!;
+    const message = el.shadowRoot!.querySelector('.message--error')!;
+    expect(fieldset.getAttribute('aria-describedby')).toBe(message.id);
+    cleanup(el);
+  });
+
+  it('wires aria-describedby on the fieldset to the hint message id', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test" hint="Select all that apply"></bds-checkbox-group>');
+    const fieldset = el.shadowRoot!.querySelector('fieldset')!;
+    const message = el.shadowRoot!.querySelector('.message--hint')!;
+    expect(fieldset.getAttribute('aria-describedby')).toBe(message.id);
+    cleanup(el);
+  });
+
+  it('omits aria-describedby on the fieldset when there is no error or hint', async () => {
+    const el = await fixture('<bds-checkbox-group label="Test"></bds-checkbox-group>');
+    const fieldset = el.shadowRoot!.querySelector('fieldset')!;
+    expect(fieldset.hasAttribute('aria-describedby')).toBe(false);
+    cleanup(el);
+  });
+
+  it('uses medium font-weight token for the legend (not semibold)', () => {
+    const styles = BdsCheckboxGroup.styles.toString();
+    expect(styles).toContain('--bds-font_weight--medium');
+    expect(styles).not.toContain('--bds-font_weight--semibold');
+  });
+
+  it('uses the on-bg error color token for the error message (not the raw error token)', () => {
+    const styles = BdsCheckboxGroup.styles.toString();
+    expect(styles).toContain('--bds-color_error_on-bg');
+  });
+
+  it('applies :host([disabled]) visual styling for the group', () => {
+    const styles = BdsCheckboxGroup.styles.toString();
+    expect(styles).toContain(':host([disabled])');
+  });
 });