@boostdev/design-system-components 1.2.0 → 1.2.2

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

@@ -3,39 +3,70 @@ import * as Stories from './BdsRadio.stories';
 
 <Meta of={Stories} />
 
-# Radio
+# &lt;bds-radio&gt;
 
-`<bds-radio>` is a form-associated radio button custom element. Use multiple elements with the same `name` to create a radio group where only one option can be selected.
+Form-associated radio button custom element. Use multiple `<bds-radio>` elements with the same `name` to form a mutually exclusive group. For a labelled group with error/hint support, use `<bds-radio-group>`.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-radio name="size" value="s">Small</bds-radio>
-<bds-radio name="size" value="m" checked>Medium</bds-radio>
-<bds-radio name="size" value="l">Large</bds-radio>
+## Installation
+
+```js
+import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+Use `<bds-radio>` for single-choice selection from a set of options. Always group radios that belong to the same choice under `<bds-radio-group>` for accessibility.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Checked
+<Canvas of={Stories.Checked} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
 ## Attributes
 
-| Attribute  | Type      | Default | Description                         |
-|------------|-----------|---------|-------------------------------------|
-| `name`     | `string`  | `""`    | Groups radio buttons together       |
-| `value`    | `string`  | `""`    | Submitted value when selected       |
-| `checked`  | `boolean` | `false` | Whether this option is selected     |
-| `required` | `boolean` | `false` | Marks the field as required         |
-| `disabled` | `boolean` | `false` | Disables this option                |
+| Attribute  | Type    | Default | Description                                      |
+|------------|---------|---------|--------------------------------------------------|
+| `name`     | string  | `""`    | Form field name (groups radio buttons)           |
+| `value`    | string  | `""`    | Value submitted when this option is selected     |
+| `checked`  | boolean | `false` | Whether this option is selected                  |
+| `required` | boolean | `false` | Marks the field as required                      |
+| `disabled` | boolean | `false` | Disables this radio option                       |
 
 ## Slots
 
-| Slot      | Description   |
-|-----------|---------------|
-| (default) | Label text    |
+| Slot        | Description        |
+|-------------|--------------------|
+| `(default)` | Label text content |
 
-## Stories
+## Events
 
-<Canvas of={Stories.Group} />
-<Canvas of={Stories.AllVariants} />
+| Event    | Detail | Description                                    |
+|----------|--------|------------------------------------------------|
+| `change` | —      | Native change event forwarded from the inner `<input>` |
 
-## Controls
+## Usage in plain HTML
 
-<ArgTypes of={Stories} />
+```html
+<bds-radio name="size" value="s">Small</bds-radio>
+<bds-radio name="size" value="m" checked>Medium</bds-radio>
+<bds-radio name="size" value="l">Large</bds-radio>
+```
+
+## Accessibility
+
+- The inner `<input type="radio">` is associated with a `<label>` via matching `id`/`for` attributes
+- Radios with the same `name` form a mutually exclusive group for keyboard navigation
+- Use `<bds-radio-group>` to wrap related radios in a `<fieldset>`/`<legend>` for proper screen reader announcements
+- Participates in HTML forms via the Form-Associated Custom Elements API

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

@@ -1,27 +1,32 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../../index';
+import '../../index'; // auto-registers all custom elements
 
 function BdsRadio({
-  label = 'Option',
-  value = 'option',
+  name,
+  value,
   checked,
+  required,
   disabled,
+  children,
 }: {
-  label?: string;
+  name?: string;
   value?: string;
   checked?: boolean;
+  required?: boolean;
   disabled?: boolean;
+  children?: React.ReactNode;
 }) {
   return React.createElement(
     'bds-radio',
     {
-      name: 'demo',
+      name,
       value,
       checked: checked || undefined,
+      required: required || undefined,
       disabled: disabled || undefined,
     },
-    label,
+    children,
   );
 }
 
@@ -29,9 +34,10 @@ const meta = {
   title: 'Web Components/Interaction/Form/Radio',
   component: BdsRadio,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
     checked: { control: 'boolean' },
+    required: { control: 'boolean' },
     disabled: { control: 'boolean' },
   },
 } satisfies Meta<typeof BdsRadio>;
@@ -39,52 +45,14 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { label: 'Option A', value: 'a' } };
-export const Checked: Story = { args: { label: 'Pre-selected', value: 'b', checked: true } };
-export const Disabled: Story = { args: { label: 'Disabled option', value: 'c', disabled: true } };
-
-export const Group: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
-      {React.createElement('bds-radio', { name: 'size', value: 's' }, 'Small')}
-      {React.createElement('bds-radio', { name: 'size', value: 'm', checked: true }, 'Medium')}
-      {React.createElement('bds-radio', { name: 'size', value: 'l' }, 'Large')}
-      {React.createElement('bds-radio', { name: 'size', value: 'xl', disabled: true }, 'Extra Large (unavailable)')}
-    </div>
-  ),
+export const Default: Story = {
+  args: { name: 'size', value: 'm', children: 'Medium' },
 };
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
-      {React.createElement('bds-radio', { name: 'v', value: 'a' }, 'Unselected')}
-      {React.createElement('bds-radio', { name: 'v', value: 'b', checked: true }, 'Selected')}
-      {React.createElement('bds-radio', { name: 'v', value: 'c', disabled: true }, 'Disabled')}
-      {React.createElement('bds-radio', { name: 'v', value: 'd', checked: true, disabled: true }, 'Disabled selected')}
-    </div>
-  ),
+export const Checked: Story = {
+  args: { name: 'size', value: 'm', checked: true, children: 'Medium (checked)' },
 };
 
-export const Interactive: Story = {
-  render: () => {
-    const [value, setValue] = React.useState('m');
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
-        <p style={{ margin: '0 0 8px', fontSize: '0.875rem' }}>Selected: {value}</p>
-        {(['s', 'm', 'l'] as const).map(v =>
-          React.createElement(
-            'bds-radio',
-            {
-              key: v,
-              name: 'ctrl',
-              value: v,
-              checked: value === v || undefined,
-              onChange: () => setValue(v),
-            },
-            v === 's' ? 'Small' : v === 'm' ? 'Medium' : 'Large',
-          ),
-        )}
-      </div>
-    );
-  },
+export const Disabled: Story = {
+  args: { name: 'size', value: 'm', disabled: true, children: 'Medium (disabled)' },
 };

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

@@ -0,0 +1,73 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsRadioGroup.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-radio-group&gt;
+
+Groups related radio buttons with a shared label and name. Renders a `<fieldset>` with a `<legend>`, and propagates the `name` attribute to all slotted `<bds-radio>` children so they form a mutually exclusive set.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+Use `<bds-radio-group>` whenever you have a set of mutually exclusive options. The `<fieldset>`/`<legend>` structure ensures screen readers announce the group label alongside each radio option.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute  | Type    | Default | Description                                                       |
+|------------|---------|---------|-------------------------------------------------------------------|
+| `label`    | string  | `""`    | Group label rendered as `<legend>`                                |
+| `name`     | string  | `""`    | Shared name propagated to all slotted `<bds-radio>` elements      |
+| `error`    | string  | —       | Error message shown below items; takes priority over `hint`       |
+| `hint`     | string  | —       | Helper text shown below items                                     |
+| `required` | boolean | `false` | Shows a required indicator on the legend                          |
+| `disabled` | boolean | `false` | Disables the entire fieldset                                      |
+
+## Slots
+
+| Slot        | Description               |
+|-------------|---------------------------|
+| `(default)` | `<bds-radio>` elements    |
+
+## Usage in plain HTML
+
+```html
+<bds-radio-group label="Preferred contact" name="contact" required>
+  <bds-radio value="email">Email</bds-radio>
+  <bds-radio value="phone">Phone</bds-radio>
+  <bds-radio value="post">Post</bds-radio>
+</bds-radio-group>
+```
+
+## Accessibility
+
+- Renders a `<fieldset>` with a `<legend>`, which is announced as a group by screen readers
+- The `name` attribute is automatically propagated to all slotted `<bds-radio>` elements
+- `required` adds a visual asterisk to the legend
+- `disabled` on the group disables all contained radios via the native `<fieldset disabled>` behaviour
+- Error messages use `role="alert"` so they are announced immediately

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

@@ -0,0 +1,88 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsRadioGroup({
+  label,
+  name,
+  error,
+  hint,
+  required,
+  disabled,
+  children,
+}: {
+  label?: string;
+  name?: string;
+  error?: string;
+  hint?: string;
+  required?: boolean;
+  disabled?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-radio-group',
+    {
+      label,
+      name,
+      error,
+      hint,
+      required: required || undefined,
+      disabled: disabled || undefined,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/RadioGroup',
+  component: BdsRadioGroup,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    required: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsRadioGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <BdsRadioGroup label="Preferred contact" name="contact">
+      {React.createElement('bds-radio', { value: 'email' }, 'Email')}
+      {React.createElement('bds-radio', { value: 'phone' }, 'Phone')}
+      {React.createElement('bds-radio', { value: 'post' }, 'Post')}
+    </BdsRadioGroup>
+  ),
+};
+
+export const WithError: Story = {
+  render: () => (
+    <BdsRadioGroup label="Preferred contact" name="contact" error="Please select a contact method.">
+      {React.createElement('bds-radio', { value: 'email' }, 'Email')}
+      {React.createElement('bds-radio', { value: 'phone' }, 'Phone')}
+      {React.createElement('bds-radio', { value: 'post' }, 'Post')}
+    </BdsRadioGroup>
+  ),
+};
+
+export const WithHint: Story = {
+  render: () => (
+    <BdsRadioGroup label="Preferred contact" name="contact" hint="We will only contact you via the selected method.">
+      {React.createElement('bds-radio', { value: 'email' }, 'Email')}
+      {React.createElement('bds-radio', { value: 'phone' }, 'Phone')}
+      {React.createElement('bds-radio', { value: 'post' }, 'Post')}
+    </BdsRadioGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <BdsRadioGroup label="Preferred contact" name="contact" disabled>
+      {React.createElement('bds-radio', { value: 'email' }, 'Email')}
+      {React.createElement('bds-radio', { value: 'phone' }, 'Phone')}
+      {React.createElement('bds-radio', { value: 'post' }, 'Post')}
+    </BdsRadioGroup>
+  ),
+};

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

@@ -3,40 +3,93 @@ import * as Stories from './BdsSegmentedControl.stories';
 
 <Meta of={Stories} />
 
-# Segmented Control
+# &lt;bds-segmented-control&gt;
 
-`<bds-segmented-control>` renders a group of radio buttons styled as a unified segmented control with an animated sliding thumb. Uses a JSON `options` attribute.
+Form-associated segmented control. Renders a group of radio buttons (or anchor links) styled as a unified segmented bar. Supports two visual variants: `outline` (sliding inset-border indicator) and `filled` (sliding filled thumb).
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-segmented-control
-  name="view"
-  value="list"
-  options='[{"value":"list","label":"List"},{"value":"grid","label":"Grid"}]'
-></bds-segmented-control>
+## Installation
+
+```js
+import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+Use `<bds-segmented-control>` for mutually exclusive view or mode toggles where all options are visible simultaneously — for example, switching between List, Grid, and Map views. When used with `href` options it renders `<a>` links for navigation.
+
+## Examples
+
+### Default (outline variant)
+<Canvas of={Stories.Default} />
+
+### Filled variant
+<Canvas of={Stories.Filled} />
+
+### With a disabled option
+<Canvas of={Stories.WithDisabledOption} />
+
+### As navigation links
+<Canvas of={Stories.AsNavLinks} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
 ## Attributes
 
-| Attribute  | Type      | Default | Description                                         |
-|------------|-----------|---------|-----------------------------------------------------|
-| `name`     | `string`  | `""`    | Form field name (also used for radio group)         |
-| `value`    | `string`  | `""`    | Currently selected value                            |
-| `options`  | `string`  | `"[]"`  | JSON array of `{ value, label, disabled? }` objects |
-| `disabled` | `boolean` | `false` | Disables all options                                |
+| Attribute  | Type                      | Default     | Description                                                    |
+|------------|---------------------------|-------------|----------------------------------------------------------------|
+| `name`     | string                    | `""`        | Form field name; also used as the internal radio group name    |
+| `value`    | string                    | `""`        | Currently selected value                                       |
+| `options`  | string                    | `"[]"`      | JSON array of `{ value, label, disabled?, href? }` objects     |
+| `disabled` | boolean                   | `false`     | Disables all options                                           |
+| `variant`  | `"outline" \| "filled"`   | `"outline"` | Visual style — sliding inset-border or sliding filled thumb    |
 
 ## Events
 
-| Event    | Description                          |
-|----------|--------------------------------------|
-| `change` | Fired when a new segment is selected |
+| Event    | Detail | Description                                              |
+|----------|--------|----------------------------------------------------------|
+| `change` | —      | Fired when a new segment is selected (radio mode only)   |
 
-## Stories
+## Usage in plain HTML
 
-<Canvas of={Stories.Default} />
-<Canvas of={Stories.AllVariants} />
+```html
+<!-- Radio mode -->
+<bds-segmented-control
+  name="view"
+  value="list"
+  options='[{"value":"list","label":"List"},{"value":"grid","label":"Grid"}]'
+></bds-segmented-control>
+
+<!-- Link mode -->
+<bds-segmented-control
+  variant="outline"
+  value="home"
+  options='[{"value":"home","label":"Home","href":"/"},{"value":"about","label":"About","href":"/about"}]'
+></bds-segmented-control>
+```
 
-## Controls
+## CSS Custom Properties
 
-<ArgTypes of={Stories} />
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--segmented_color_bg` | `var(--bds-color_bg--subtle)` | Track background colour (both variants) |
+| `--segmented_item-bg` | `transparent` | Inactive item background (outline variant) |
+| `--segmented_item-bg--active` | `var(--bds-color_bg)` | Active item background (outline variant) |
+| `--segmented_thumb-color` | `var(--bds-color_interactive)` | Filled thumb colour (filled variant) |
+| `--segmented_color` | `var(--bds-color_on-bg)` | Item text colour |
+| `--segmented_color--active` | `var(--bds-color_on-interactive)` (filled) / `var(--bds-color_interactive)` (outline) | Active item text colour |
+
+## Accessibility
+
+- In radio mode, each option renders as a visually hidden `<input type="radio">` inside a `<label>`, so keyboard users can navigate with arrow keys
+- In link mode, options render as `<a>` elements with `aria-current="page"` on the active item
+- Disabled options have `aria-disabled="true"` and remove the `href` from link mode items
+- `disabled` on the host element disables all options
+- The sliding thumb and indicator use `aria-hidden="true"` so they are not announced by screen readers
+- Participates in HTML forms via the Form-Associated Custom Elements API (radio mode only)

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

@@ -1,33 +1,44 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import type { SegmentedOption } from './bds-segmented-control';
-import '../../index';
+import '../../index'; // auto-registers all custom elements
 
-const VIEW_OPTIONS: SegmentedOption[] = [
+const VIEW_OPTIONS = JSON.stringify([
   { value: 'list', label: 'List' },
   { value: 'grid', label: 'Grid' },
-  { value: 'table', label: 'Table' },
-];
+  { value: 'map', label: 'Map' },
+]);
 
-const PERIOD_OPTIONS: SegmentedOption[] = [
-  { value: 'day', label: 'Day' },
-  { value: 'week', label: 'Week' },
-  { value: 'month', label: 'Month' },
-  { value: 'year', label: 'Year', disabled: true },
-];
+const OPTIONS_WITH_DISABLED = JSON.stringify([
+  { value: 'list', label: 'List' },
+  { value: 'grid', label: 'Grid', disabled: true },
+  { value: 'map', label: 'Map' },
+]);
+
+const NAV_OPTIONS = JSON.stringify([
+  { value: 'home', label: 'Home', href: '/' },
+  { value: 'about', label: 'About', href: '/about' },
+  { value: 'contact', label: 'Contact', href: '/contact' },
+]);
 
 function BdsSegmentedControl({
-  value = 'list',
+  name,
+  value,
+  options,
   disabled,
+  variant,
 }: {
+  name?: string;
   value?: string;
+  options?: string;
   disabled?: boolean;
+  variant?: 'outline' | 'filled';
 }) {
   return React.createElement('bds-segmented-control', {
-    name: 'view',
+    name,
     value,
-    options: JSON.stringify(VIEW_OPTIONS),
+    options,
     disabled: disabled || undefined,
+    variant,
   });
 }
 
@@ -35,8 +46,9 @@ const meta = {
   title: 'Web Components/Interaction/Form/SegmentedControl',
   component: BdsSegmentedControl,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
+    variant: { control: 'select', options: ['outline', 'filled'] },
     disabled: { control: 'boolean' },
   },
 } satisfies Meta<typeof BdsSegmentedControl>;
@@ -44,49 +56,47 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { value: 'list' } };
-export const Disabled: Story = { args: { value: 'grid', disabled: true } };
+export const Default: Story = {
+  args: {
+    name: 'view',
+    value: 'list',
+    options: VIEW_OPTIONS,
+    variant: 'outline',
+  },
+};
+
+export const Filled: Story = {
+  args: {
+    name: 'view',
+    value: 'list',
+    options: VIEW_OPTIONS,
+    variant: 'filled',
+  },
+};
+
 export const WithDisabledOption: Story = {
-  render: () =>
-    React.createElement('bds-segmented-control', {
-      name: 'period',
-      value: 'week',
-      options: JSON.stringify(PERIOD_OPTIONS),
-    }),
+  args: {
+    name: 'view',
+    value: 'list',
+    options: OPTIONS_WITH_DISABLED,
+    variant: 'outline',
+  },
 };
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '24px' }}>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888' }}>View mode</p>
-        {React.createElement('bds-segmented-control', { name: 'view1', value: 'grid', options: JSON.stringify(VIEW_OPTIONS) })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888' }}>Time period (year disabled)</p>
-        {React.createElement('bds-segmented-control', { name: 'period1', value: 'week', options: JSON.stringify(PERIOD_OPTIONS) })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888' }}>Disabled</p>
-        {React.createElement('bds-segmented-control', { name: 'view2', value: 'list', options: JSON.stringify(VIEW_OPTIONS), disabled: true })}
-      </div>
-    </div>
-  ),
+export const AsNavLinks: Story = {
+  args: {
+    value: 'home',
+    options: NAV_OPTIONS,
+    variant: 'outline',
+  },
 };
 
-export const Interactive: Story = {
-  render: () => {
-    const [view, setView] = React.useState('list');
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
-        <p style={{ margin: 0, fontSize: '0.875rem' }}>Active view: {view}</p>
-        {React.createElement('bds-segmented-control', {
-          name: 'view-ctrl',
-          value: view,
-          options: JSON.stringify(VIEW_OPTIONS),
-          onChange: (e: Event) => setView((e.target as HTMLInputElement).value),
-        })}
-      </div>
-    );
+export const Disabled: Story = {
+  args: {
+    name: 'view',
+    value: 'list',
+    options: VIEW_OPTIONS,
+    disabled: true,
+    variant: 'outline',
   },
 };