@boostdev/design-system-components 1.2.0 → 1.2.2

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

@@ -3,36 +3,74 @@ import * as Stories from './BdsSelect.stories';
 
 <Meta of={Stories} />
 
-# Select
+# &lt;bds-select&gt;
 
-`<bds-select>` is a form-associated Select custom element. It uses a JSON `options` attribute because slotting `<option>` elements into a shadow DOM `<select>` is not cross-browser supported.
+Form-associated select custom element. Wraps a native `<select>` with consistent styling. Options are passed as a JSON attribute because slotting `<option>` elements into shadow DOM is not supported cross-browser.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-select
-  name="country"
-  placeholder="Choose…"
-  options='[{"value":"nl","label":"Netherlands"},{"value":"be","label":"Belgium"}]'
-></bds-select>
+## Installation
+
+```js
+import '@boostdev/components/web-components';
 ```
 
-## Attributes
+## When to use
 
-| Attribute     | Type      | Default | Description                                          |
-|---------------|-----------|---------|------------------------------------------------------|
-| `name`        | `string`  | `""`    | Form field name                                      |
-| `value`       | `string`  | `""`    | Currently selected value                             |
-| `options`     | `string`  | `"[]"`  | JSON array of `{ value, label, disabled? }` objects  |
-| `placeholder` | `string`  | `""`    | Placeholder option label (disabled, empty value)     |
-| `required`    | `boolean` | `false` | Marks the field as required                          |
-| `disabled`    | `boolean` | `false` | Disables the select                                  |
+Use `<bds-select>` for pick-from-list dropdowns where users cannot type to search. For searchable/filterable lists, use `<bds-combobox>` instead.
 
-## Stories
+## Examples
 
+### Default (pre-selected value)
 <Canvas of={Stories.Default} />
-<Canvas of={Stories.AllVariants} />
 
-## Controls
+### With placeholder
+<Canvas of={Stories.WithPlaceholder} />
+
+### Required
+<Canvas of={Stories.Required} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+### With a disabled option
+<Canvas of={Stories.WithDisabledOption} />
+
+## Props
 
 <ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute     | Type    | Default | Description                                                    |
+|---------------|---------|---------|----------------------------------------------------------------|
+| `name`        | string  | `""`    | Form field name                                                |
+| `value`       | string  | `""`    | Currently selected value                                       |
+| `options`     | string  | `"[]"`  | JSON array of `{ value, label, disabled? }` option objects     |
+| `placeholder` | string  | `""`    | Placeholder option label (disabled, empty value)               |
+| `required`    | boolean | `false` | Marks the field as required                                    |
+| `disabled`    | boolean | `false` | Disables the select                                            |
+
+## Events
+
+| Event    | Detail | Description                                           |
+|----------|--------|-------------------------------------------------------|
+| `change` | —      | Native change event forwarded from the inner `<select>` |
+
+## Usage in plain HTML
+
+```html
+<bds-select
+  name="country"
+  placeholder="Choose a country…"
+  options='[{"value":"nl","label":"Netherlands"},{"value":"be","label":"Belgium"}]'
+></bds-select>
+```
+
+## Accessibility
+
+- Wraps a native `<select>` which has full browser and assistive technology support
+- The custom chevron icon is `aria-hidden="true"` to avoid duplicate announcements
+- `required` uses the native `<select required>` attribute for browser validation
+- `disabled` uses the native `<select disabled>` attribute
+- Participates in HTML forms via the Form-Associated Custom Elements API

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

@@ -1,31 +1,44 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import type { SelectOption } from './bds-select';
-import '../../index';
+import '../../index'; // auto-registers all custom elements
 
-const COUNTRIES: SelectOption[] = [
+const COUNTRIES = JSON.stringify([
   { value: 'nl', label: 'Netherlands' },
   { value: 'be', label: 'Belgium' },
   { value: 'de', label: 'Germany' },
   { value: 'fr', label: 'France' },
-  { value: 'gb', label: 'United Kingdom', disabled: true },
-];
+  { value: 'gb', label: 'United Kingdom' },
+]);
+
+const COUNTRIES_WITH_DISABLED = JSON.stringify([
+  { value: 'nl', label: 'Netherlands' },
+  { value: 'be', label: 'Belgium' },
+  { value: 'de', label: 'Germany', disabled: true },
+  { value: 'fr', label: 'France' },
+]);
 
 function BdsSelect({
-  placeholder = 'Choose an option…',
-  disabled,
+  name,
+  value,
+  options,
+  placeholder,
   required,
+  disabled,
 }: {
+  name?: string;
+  value?: string;
+  options?: string;
   placeholder?: string;
-  disabled?: boolean;
   required?: boolean;
+  disabled?: boolean;
 }) {
   return React.createElement('bds-select', {
-    options: JSON.stringify(COUNTRIES),
+    name,
+    value,
+    options,
     placeholder,
-    disabled: disabled || undefined,
     required: required || undefined,
-    style: { minInlineSize: '200px', display: 'block' },
+    disabled: disabled || undefined,
   });
 }
 
@@ -33,61 +46,39 @@ const meta = {
   title: 'Web Components/Interaction/Form/Select',
   component: BdsSelect,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
-    disabled: { control: 'boolean' },
     required: { control: 'boolean' },
+    disabled: { control: 'boolean' },
   },
+  decorators: [
+    (Story: React.ComponentType) => (
+      <div style={{ width: '280px' }}>
+        <Story />
+      </div>
+    ),
+  ],
 } satisfies Meta<typeof BdsSelect>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { placeholder: 'Select a country…' } };
-export const Disabled: Story = { args: { placeholder: 'Select a country…', disabled: true } };
-export const WithValue: Story = {
-  render: () =>
-    React.createElement('bds-select', {
-      options: JSON.stringify(COUNTRIES),
-      value: 'nl',
-      style: { minInlineSize: '200px', display: 'block' },
-    }),
+export const Default: Story = {
+  args: { name: 'country', options: COUNTRIES, value: 'nl' },
 };
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxInlineSize: '300px' }}>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Default</p>
-        {React.createElement('bds-select', { options: JSON.stringify(COUNTRIES), placeholder: 'Choose…' })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>With value</p>
-        {React.createElement('bds-select', { options: JSON.stringify(COUNTRIES), value: 'be' })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Disabled</p>
-        {React.createElement('bds-select', { options: JSON.stringify(COUNTRIES), placeholder: 'Choose…', disabled: true })}
-      </div>
-    </div>
-  ),
+export const WithPlaceholder: Story = {
+  args: { name: 'country', options: COUNTRIES, placeholder: 'Choose a country…' },
 };
 
-export const Interactive: Story = {
-  render: () => {
-    const [value, setValue] = React.useState('');
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', maxInlineSize: '300px' }}>
-        <p style={{ margin: '0 0 8px', fontSize: '0.875rem' }}>
-          Selected: {value ? COUNTRIES.find(c => c.value === value)?.label : '(none)'}
-        </p>
-        {React.createElement('bds-select', {
-          options: JSON.stringify(COUNTRIES),
-          placeholder: 'Select a country…',
-          value,
-          onChange: (e: Event) => setValue((e.target as HTMLSelectElement).value),
-        })}
-      </div>
-    );
-  },
+export const Required: Story = {
+  args: { name: 'country', options: COUNTRIES, placeholder: 'Choose a country…', required: true },
+};
+
+export const Disabled: Story = {
+  args: { name: 'country', options: COUNTRIES, value: 'nl', disabled: true },
+};
+
+export const WithDisabledOption: Story = {
+  args: { name: 'country', options: COUNTRIES_WITH_DISABLED, placeholder: 'Choose a country…' },
 };

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

@@ -3,47 +3,75 @@ import * as Stories from './BdsSlider.stories';
 
 <Meta of={Stories} />
 
-# Slider
+# &lt;bds-slider&gt;
 
-`<bds-slider>` is a form-associated range input. The fill track is driven by the `--slider_fill` CSS custom property and updates as the user drags.
+Form-associated range slider. Wraps a native `<input type="range">` with a styled fill track driven by the `--slider_fill` CSS custom property.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-slider name="volume" value="50" min="0" max="100" step="5"></bds-slider>
+## Installation
+
+```js
+import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+Use `<bds-slider>` for continuous or stepped numeric ranges — volume controls, price ranges, ratings, or any value that benefits from visual representation of position within a range.
+
+## Examples
+
+### Default (0–100)
+<Canvas of={Stories.Default} />
+
+### With step (25)
+<Canvas of={Stories.WithStep} />
+
+### With custom min/max (1–5)
+<Canvas of={Stories.WithMinMax} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
 ## 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 interaction             |
+| 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                      |
 
 ## Events
 
-| Event    | Description                   |
-|----------|-------------------------------|
-| `input`  | Fired as the user drags       |
-| `change` | Fired when the user releases  |
+| Event    | Detail | Description                          |
+|----------|--------|--------------------------------------|
+| `input`  | —      | Fired continuously as the user drags |
+| `change` | —      | Fired when the user releases         |
 
 ## CSS Custom Properties
 
-| Property              | Description                    |
-|-----------------------|--------------------------------|
-| `--slider_fill-color` | Fill track color (default: `--bds-color_interactive`) |
-| `--slider_track-color`| Unfilled track color           |
-| `--slider_thumb-color`| Thumb color                    |
+| 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`) |
 
-## Stories
+## Usage in plain HTML
 
-<Canvas of={Stories.Default} />
-<Canvas of={Stories.AllVariants} />
+```html
+<bds-slider name="volume" value="50" min="0" max="100" step="5"></bds-slider>
+```
 
-## Controls
+## Accessibility
 
-<ArgTypes of={Stories} />
+- Wraps a native `<input type="range">` which has full browser and assistive technology support
+- 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

@@ -1,14 +1,16 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../../index';
+import '../../index'; // auto-registers all custom elements
 
 function BdsSlider({
+  name,
   value,
   min,
   max,
   step,
   disabled,
 }: {
+  name?: string;
   value?: number;
   min?: number;
   max?: number;
@@ -16,12 +18,12 @@ function BdsSlider({
   disabled?: boolean;
 }) {
   return React.createElement('bds-slider', {
+    name,
     value,
     min,
     max,
     step,
     disabled: disabled || undefined,
-    style: { display: 'block', maxInlineSize: '320px' },
   });
 }
 
@@ -29,7 +31,7 @@ const meta = {
   title: 'Web Components/Interaction/Form/Slider',
   component: BdsSlider,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
     value: { control: 'number' },
     min: { control: 'number' },
@@ -37,53 +39,30 @@ const meta = {
     step: { control: 'number' },
     disabled: { control: 'boolean' },
   },
+  decorators: [
+    (Story: React.ComponentType) => (
+      <div style={{ width: '300px' }}>
+        <Story />
+      </div>
+    ),
+  ],
 } satisfies Meta<typeof BdsSlider>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { value: 50 } };
-export const WithStep: Story = { args: { value: 25, min: 0, max: 100, step: 25 } };
-export const Disabled: Story = { args: { value: 60, disabled: true } };
+export const Default: Story = {
+  args: { name: 'volume', value: 50 },
+};
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '24px', maxInlineSize: '320px' }}>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Default (0%)</p>
-        {React.createElement('bds-slider', { value: 0, style: { display: 'block' } })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Mid (50%)</p>
-        {React.createElement('bds-slider', { value: 50, style: { display: 'block' } })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Full (100%)</p>
-        {React.createElement('bds-slider', { value: 100, style: { display: 'block' } })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Disabled</p>
-        {React.createElement('bds-slider', { value: 40, disabled: true, style: { display: 'block' } })}
-      </div>
-    </div>
-  ),
+export const WithStep: Story = {
+  args: { name: 'volume', value: 25, min: 0, max: 100, step: 25 },
 };
 
-export const Interactive: Story = {
-  render: () => {
-    const [volume, setVolume] = React.useState(50);
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', maxInlineSize: '320px' }}>
-        <p style={{ margin: '0 0 4px', fontSize: '0.875rem' }}>Volume: {volume}%</p>
-        {React.createElement('bds-slider', {
-          value: volume,
-          min: 0,
-          max: 100,
-          step: 1,
-          style: { display: 'block' },
-          onInput: (e: Event) => setVolume(parseFloat((e.target as HTMLInputElement).value)),
-        })}
-      </div>
-    );
-  },
+export const WithMinMax: Story = {
+  args: { name: 'rating', value: 3, min: 1, max: 5 },
+};
+
+export const Disabled: Story = {
+  args: { name: 'volume', value: 40, disabled: true },
 };

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

@@ -3,37 +3,70 @@ import * as Stories from './BdsSwitch.stories';
 
 <Meta of={Stories} />
 
-# Switch
+# &lt;bds-switch&gt;
 
-`<bds-switch>` is a visually styled toggle switch. Semantically equivalent to a checkbox (`role="switch"`), it participates in HTML forms via the Form-Associated Custom Elements API.
+Form-associated toggle switch. Visually a sliding toggle but semantically equivalent to a checkbox (`role="switch"`). Participates in HTML forms via the Form-Associated Custom Elements API.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-switch name="notifications" value="enabled">Enable notifications</bds-switch>
+## Installation
+
+```js
+import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+Use `<bds-switch>` for binary on/off settings where the change takes immediate effect, such as enabling or disabling a feature. For settings that require form submission, `<bds-checkbox>` may be more appropriate.
+
+## Examples
+
+### Default (off)
+<Canvas of={Stories.Default} />
+
+### Checked (on)
+<Canvas of={Stories.Checked} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
 ## Attributes
 
-| Attribute  | Type      | Default | Description                         |
-|------------|-----------|---------|-------------------------------------|
-| `name`     | `string`  | `""`    | Form field name                     |
-| `value`    | `string`  | `"on"`  | Submitted value when on             |
-| `checked`  | `boolean` | `false` | Whether the switch is on            |
-| `required` | `boolean` | `false` | Marks the field as required         |
-| `disabled` | `boolean` | `false` | Disables interaction                |
+| 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                              |
 
 ## Slots
 
-| Slot      | Description   |
-|-----------|---------------|
-| (default) | Label text    |
+| Slot        | Description        |
+|-------------|--------------------|
+| `(default)` | Label text content |
 
-## Stories
+## Events
 
-<Canvas of={Stories.Default} />
-<Canvas of={Stories.AllVariants} />
+| Event    | Detail | Description                                    |
+|----------|--------|------------------------------------------------|
+| `change` | —      | Fired when the switch state changes            |
 
-## Controls
+## Usage in plain HTML
 
-<ArgTypes of={Stories} />
+```html
+<bds-switch name="notifications" value="enabled">Enable notifications</bds-switch>
+<bds-switch name="darkMode" value="on" checked>Dark mode</bds-switch>
+```
+
+## 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

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

@@ -1,23 +1,32 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../../index';
+import '../../index'; // auto-registers all custom elements
 
 function BdsSwitch({
-  label = 'Enable feature',
+  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-switch',
     {
+      name,
+      value,
       checked: checked || undefined,
+      required: required || undefined,
       disabled: disabled || undefined,
     },
-    label,
+    children,
   );
 }
 
@@ -25,9 +34,10 @@ const meta = {
   title: 'Web Components/Interaction/Form/Switch',
   component: BdsSwitch,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
     checked: { control: 'boolean' },
+    required: { control: 'boolean' },
     disabled: { control: 'boolean' },
   },
 } satisfies Meta<typeof BdsSwitch>;
@@ -35,39 +45,14 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { label: 'Enable notifications' } };
-export const On: Story = { args: { label: 'Notifications enabled', checked: true } };
-export const Disabled: Story = { args: { label: 'Managed by admin', disabled: true } };
-export const DisabledOn: Story = { args: { label: 'Always on (managed)', checked: true, disabled: true } };
+export const Default: Story = {
+  args: { name: 'notifications', value: 'enabled', children: 'Enable notifications' },
+};
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
-      {React.createElement('bds-switch', null, 'Off (default)')}
-      {React.createElement('bds-switch', { checked: true }, 'On')}
-      {React.createElement('bds-switch', { disabled: true }, 'Disabled off')}
-      {React.createElement('bds-switch', { checked: true, disabled: true }, 'Disabled on')}
-    </div>
-  ),
+export const Checked: Story = {
+  args: { name: 'notifications', value: 'enabled', checked: true, children: 'Notifications enabled' },
 };
 
-export const Interactive: Story = {
-  render: () => {
-    const [enabled, setEnabled] = React.useState(false);
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
-        <p style={{ margin: '0 0 8px', fontSize: '0.875rem' }}>
-          Dark mode: {enabled ? 'enabled' : 'disabled'}
-        </p>
-        {React.createElement(
-          'bds-switch',
-          {
-            checked: enabled || undefined,
-            onChange: (e: Event) => setEnabled((e.target as HTMLInputElement).checked),
-          },
-          'Dark mode',
-        )}
-      </div>
-    );
-  },
+export const Disabled: Story = {
+  args: { name: 'notifications', value: 'enabled', disabled: true, children: 'Notifications (disabled)' },
 };