@boostdev/design-system-components 1.2.0 → 1.2.1

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

@@ -3,37 +3,74 @@ import * as Stories from './BdsCheckbox.stories';
 
 <Meta of={Stories} />
 
-# Checkbox
+# &lt;bds-checkbox&gt;
 
-`<bds-checkbox>` is a form-associated custom element that participates in HTML forms via the Form-Associated Custom Elements API. Native browser validation (`required`) works without any wrapper.
+Form-associated checkbox custom element. Participates in HTML forms via the Form-Associated Custom Elements API — native browser validation (required, etc.) works without any wrapper.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-checkbox name="agree" value="yes" required>I agree to the terms</bds-checkbox>
+## Installation
+
+```js
+import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+Use `<bds-checkbox>` whenever you need a single boolean toggle that participates in a form. For grouping multiple checkboxes under a shared label, wrap them in `<bds-checkbox-group>`.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Checked
+<Canvas of={Stories.Checked} />
+
+### Required
+<Canvas of={Stories.Required} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+### Visual group (without group wrapper)
+<Canvas of={Stories.WithGroup} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
 ## Attributes
 
-| Attribute  | Type      | Default | Description                         |
-|------------|-----------|---------|-------------------------------------|
-| `name`     | `string`  | `""`    | Form field name                     |
-| `value`    | `string`  | `"on"`  | Submitted value when checked        |
-| `checked`  | `boolean` | `false` | Whether the checkbox is checked     |
-| `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 checked                     |
+| `checked`  | boolean | `false` | Whether the checkbox is checked                  |
+| `required` | boolean | `false` | Marks the field as required                      |
+| `disabled` | boolean | `false` | Disables the checkbox                            |
 
 ## 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` | —      | Native change event forwarded from the inner `<input>` |
 
-## Controls
+## Usage in plain HTML
 
-<ArgTypes of={Stories} />
+```html
+<bds-checkbox name="agree" value="yes" required>I agree to the terms</bds-checkbox>
+```
+
+## Accessibility
+
+- The inner `<input type="checkbox">` is associated with a `<label>` via matching `id`/`for` attributes
+- `required` triggers native browser validation
+- `disabled` sets `pointer-events: none` and reduces opacity
+- Use `<bds-checkbox-group>` for accessible grouping with `<fieldset>`/`<legend>`

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

@@ -1,26 +1,32 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../../index';
+import '../../index'; // auto-registers all custom elements
 
 function BdsCheckbox({
-  label = 'Check me',
+  name,
+  value,
   checked,
-  disabled,
   required,
+  disabled,
+  children,
 }: {
-  label?: string;
+  name?: string;
+  value?: string;
   checked?: boolean;
-  disabled?: boolean;
   required?: boolean;
+  disabled?: boolean;
+  children?: React.ReactNode;
 }) {
   return React.createElement(
     'bds-checkbox',
     {
+      name,
+      value,
       checked: checked || undefined,
-      disabled: disabled || undefined,
       required: required || undefined,
+      disabled: disabled || undefined,
     },
-    label,
+    children,
   );
 }
 
@@ -28,46 +34,39 @@ const meta = {
   title: 'Web Components/Interaction/Form/Checkbox',
   component: BdsCheckbox,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
     checked: { control: 'boolean' },
-    disabled: { control: 'boolean' },
     required: { control: 'boolean' },
+    disabled: { control: 'boolean' },
   },
 } satisfies Meta<typeof BdsCheckbox>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { label: 'Accept terms and conditions' } };
-export const Checked: Story = { args: { label: 'Already checked', checked: true } };
-export const Disabled: Story = { args: { label: 'Disabled option', disabled: true } };
-export const DisabledChecked: Story = { args: { label: 'Disabled and checked', checked: true, disabled: true } };
+export const Default: Story = {
+  args: { name: 'option', value: 'yes', children: 'Accept terms' },
+};
+
+export const Checked: Story = {
+  args: { name: 'option', value: 'yes', checked: true, children: 'Checked by default' },
+};
 
-export const AllVariants: Story = {
+export const Disabled: Story = {
+  args: { name: 'option', value: 'yes', disabled: true, children: 'Disabled' },
+};
+
+export const Required: Story = {
+  args: { name: 'option', value: 'yes', required: true, children: 'Required field' },
+};
+
+export const WithGroup: Story = {
   render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
-      {React.createElement('bds-checkbox', null, 'Unchecked')}
-      {React.createElement('bds-checkbox', { checked: true }, 'Checked')}
-      {React.createElement('bds-checkbox', { disabled: true }, 'Disabled')}
-      {React.createElement('bds-checkbox', { checked: true, disabled: true }, 'Disabled checked')}
-      {React.createElement('bds-checkbox', { required: true }, 'Required')}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+      <BdsCheckbox name="interests" value="sports">Sports</BdsCheckbox>
+      <BdsCheckbox name="interests" value="music" checked>Music</BdsCheckbox>
+      <BdsCheckbox name="interests" value="travel">Travel</BdsCheckbox>
     </div>
   ),
 };
-
-export const Interactive: Story = {
-  render: () => {
-    const [checked, setChecked] = React.useState(false);
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
-        <p style={{ margin: 0, fontSize: '0.875rem' }}>State: {checked ? 'checked' : 'unchecked'}</p>
-        {React.createElement(
-          'bds-checkbox',
-          { checked: checked || undefined, onChange: (e: Event) => setChecked((e.target as HTMLInputElement).checked) },
-          'Controlled checkbox',
-        )}
-      </div>
-    );
-  },
-};

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

@@ -0,0 +1,70 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCheckboxGroup.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-checkbox-group&gt;
+
+Groups related checkboxes with a shared label, hint, and error message. Renders a `<fieldset>` with a `<legend>` for accessible grouping.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+Use `<bds-checkbox-group>` when you have multiple related checkboxes that belong under a common heading. The `<fieldset>`/`<legend>` structure is announced by screen readers as a group.
+
+## 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>`                 |
+| `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-checkbox>` elements         |
+
+## Usage in plain HTML
+
+```html
+<bds-checkbox-group label="Notification preferences" required>
+  <bds-checkbox name="email" value="email">Email</bds-checkbox>
+  <bds-checkbox name="sms" value="sms">SMS</bds-checkbox>
+</bds-checkbox-group>
+```
+
+## Accessibility
+
+- Renders a `<fieldset>` with a `<legend>`, which is announced as a group by screen readers
+- `required` attribute adds a visual asterisk indicator to the legend
+- `disabled` on the group disables all contained checkboxes via the native `<fieldset disabled>` behaviour
+- Error messages use `role="alert"` so they are announced immediately

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

@@ -0,0 +1,81 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsCheckboxGroup({
+  label,
+  error,
+  hint,
+  required,
+  disabled,
+  children,
+}: {
+  label?: string;
+  error?: string;
+  hint?: string;
+  required?: boolean;
+  disabled?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-checkbox-group',
+    {
+      label,
+      error,
+      hint,
+      required: required || undefined,
+      disabled: disabled || undefined,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/CheckboxGroup',
+  component: BdsCheckboxGroup,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    required: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsCheckboxGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <BdsCheckboxGroup label="Interests">
+      {React.createElement('bds-checkbox', { name: 'sports', value: 'sports' }, 'Sports')}
+      {React.createElement('bds-checkbox', { name: 'music', value: 'music' }, 'Music')}
+    </BdsCheckboxGroup>
+  ),
+};
+
+export const WithError: Story = {
+  render: () => (
+    <BdsCheckboxGroup label="Interests" error="Please select at least one option.">
+      {React.createElement('bds-checkbox', { name: 'sports', value: 'sports' }, 'Sports')}
+      {React.createElement('bds-checkbox', { name: 'music', value: 'music' }, 'Music')}
+    </BdsCheckboxGroup>
+  ),
+};
+
+export const WithHint: Story = {
+  render: () => (
+    <BdsCheckboxGroup label="Interests" hint="You can select multiple options.">
+      {React.createElement('bds-checkbox', { name: 'sports', value: 'sports' }, 'Sports')}
+      {React.createElement('bds-checkbox', { name: 'music', value: 'music' }, 'Music')}
+    </BdsCheckboxGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <BdsCheckboxGroup label="Interests" disabled>
+      {React.createElement('bds-checkbox', { name: 'sports', value: 'sports' }, 'Sports')}
+      {React.createElement('bds-checkbox', { name: 'music', value: 'music' }, 'Music')}
+    </BdsCheckboxGroup>
+  ),
+};

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

@@ -3,50 +3,69 @@ import * as Stories from './BdsCombobox.stories';
 
 <Meta of={Stories} />
 
-# Combobox
+# &lt;bds-combobox&gt;
 
-`<bds-combobox>` is a form-associated autocomplete input. The user types to filter options and selects with Enter or mouse click. Keyboard navigation: ArrowDown/ArrowUp to move focus, Enter to select, Escape to close.
+Form-associated autocomplete combobox. Renders a text input with a filterable dropdown. Keyboard navigation: `ArrowDown`/`ArrowUp` to move focus, `Enter` to select, `Escape` to close.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-combobox
-  name="country"
-  placeholder="Search…"
-  options='[{"value":"nl","label":"Netherlands"},{"value":"be","label":"Belgium"}]'
-></bds-combobox>
-```
+## Installation
 
-## Attributes
+```js
+import '@boostdev/components/web-components';
+```
 
-| 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`  | `""`    | Input placeholder text                              |
-| `disabled`    | `boolean` | `false` | Disables the combobox                               |
+## When to use
 
-## Events
+Use `<bds-combobox>` when users need to search and filter a list of options. For a simpler pick-from-list without search, use `<bds-select>`.
 
-| Event        | Detail                     | Description                      |
-|--------------|----------------------------|----------------------------------|
-| `bds-change` | `{ value, label }`         | Fired when an option is selected |
+## Examples
 
-## Keyboard Navigation
+### Default
+<Canvas of={Stories.Default} />
 
-| Key         | Action                  |
-|-------------|-------------------------|
-| `ArrowDown` | Move to next option     |
-| `ArrowUp`   | Move to previous option |
-| `Enter`     | Select focused option   |
-| `Escape`    | Close the listbox       |
+### With disabled option
+<Canvas of={Stories.WithDisabledOption} />
 
-## Stories
+### Required
+<Canvas of={Stories.Required} />
 
-<Canvas of={Stories.Default} />
-<Canvas of={Stories.AllVariants} />
+### Disabled
+<Canvas of={Stories.Disabled} />
 
-## Controls
+## 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  | `""`    | Input placeholder text                                           |
+| `disabled`    | boolean | `false` | Disables the entire combobox                                     |
+
+## Events
+
+| Event        | Detail                          | Description                          |
+|--------------|---------------------------------|--------------------------------------|
+| `bds-change` | `{ value: string, label: string }` | Fired when an option is selected  |
+
+## Usage in plain HTML
+
+```html
+<bds-combobox
+  name="country"
+  placeholder="Search country…"
+  options='[{"value":"nl","label":"Netherlands"},{"value":"be","label":"Belgium"}]'
+></bds-combobox>
+```
+
+## Accessibility
+
+- Uses `role="combobox"` on the input with `aria-expanded`, `aria-autocomplete="list"`, and `aria-haspopup="listbox"`
+- Listbox uses `role="listbox"` and each option uses `role="option"` with `aria-selected` and `aria-disabled`
+- Full keyboard navigation: `ArrowDown`/`ArrowUp` to navigate, `Enter` to select, `Escape` to close
+- Participates in HTML forms via the Form-Associated Custom Elements API

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

@@ -1,30 +1,41 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import type { ComboboxOption } from './bds-combobox';
-import '../../index';
+import '../../index'; // auto-registers all custom elements
 
-const COUNTRIES: ComboboxOption[] = [
+const COUNTRIES = JSON.stringify([
   { value: 'nl', label: 'Netherlands' },
   { value: 'be', label: 'Belgium' },
   { value: 'de', label: 'Germany' },
   { value: 'fr', label: 'France' },
-  { value: 'es', label: 'Spain' },
-  { value: 'it', label: 'Italy' },
-  { 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 BdsCombobox({
-  placeholder = 'Search…',
+  name,
+  value,
+  options,
+  placeholder,
   disabled,
 }: {
+  name?: string;
+  value?: string;
+  options?: string;
   placeholder?: string;
   disabled?: boolean;
 }) {
   return React.createElement('bds-combobox', {
-    options: JSON.stringify(COUNTRIES),
+    name,
+    value,
+    options,
     placeholder,
     disabled: disabled || undefined,
-    style: { display: 'block', maxInlineSize: '280px' },
   });
 }
 
@@ -32,60 +43,51 @@ const meta = {
   title: 'Web Components/Interaction/Form/Combobox',
   component: BdsCombobox,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
     disabled: { control: 'boolean' },
   },
+  decorators: [
+    (Story: React.ComponentType) => (
+      <div style={{ width: '280px', paddingBlockEnd: '200px' }}>
+        <Story />
+      </div>
+    ),
+  ],
 } satisfies Meta<typeof BdsCombobox>;
 
 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-combobox', {
-      options: JSON.stringify(COUNTRIES),
-      value: 'nl',
-      placeholder: 'Search…',
-      style: { display: 'block', maxInlineSize: '280px' },
-    }),
+export const Default: Story = {
+  args: {
+    name: 'country',
+    options: COUNTRIES,
+    placeholder: 'Search country…',
+  },
 };
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxInlineSize: '280px' }}>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Default</p>
-        {React.createElement('bds-combobox', { options: JSON.stringify(COUNTRIES), placeholder: 'Search…' })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>With pre-selected value</p>
-        {React.createElement('bds-combobox', { options: JSON.stringify(COUNTRIES), value: 'be', placeholder: 'Search…' })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Disabled</p>
-        {React.createElement('bds-combobox', { options: JSON.stringify(COUNTRIES), placeholder: 'Search…', disabled: true })}
-      </div>
-    </div>
-  ),
+export const WithDisabledOption: Story = {
+  args: {
+    name: 'country',
+    options: COUNTRIES_WITH_DISABLED,
+    placeholder: 'Search country…',
+  },
 };
 
-export const Interactive: Story = {
-  render: () => {
-    const [selected, setSelected] = React.useState<{ value: string; label: string } | null>(null);
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', maxInlineSize: '280px' }}>
-        <p style={{ margin: '0 0 8px', fontSize: '0.875rem' }}>
-          Selected: {selected ? `${selected.label} (${selected.value})` : '(none)'}
-        </p>
-        {React.createElement('bds-combobox', {
-          options: JSON.stringify(COUNTRIES),
-          placeholder: 'Type to filter…',
-          'onbds-change': (e: CustomEvent<{ value: string; label: string }>) => setSelected(e.detail),
-        })}
-      </div>
-    );
+export const Required: Story = {
+  args: {
+    name: 'country',
+    options: COUNTRIES,
+    placeholder: 'Select a country…',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    name: 'country',
+    options: COUNTRIES,
+    placeholder: 'Disabled combobox',
+    disabled: true,
   },
 };