@boostdev/design-system-components 1.1.2 → 1.2.1

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

@@ -0,0 +1,72 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsCheckbox({
+  name,
+  value,
+  checked,
+  required,
+  disabled,
+  children,
+}: {
+  name?: string;
+  value?: string;
+  checked?: boolean;
+  required?: boolean;
+  disabled?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-checkbox',
+    {
+      name,
+      value,
+      checked: checked || undefined,
+      required: required || undefined,
+      disabled: disabled || undefined,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/Checkbox',
+  component: BdsCheckbox,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    checked: { 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: { name: 'option', value: 'yes', children: 'Accept terms' },
+};
+
+export const Checked: Story = {
+  args: { name: 'option', value: 'yes', checked: true, children: 'Checked by default' },
+};
+
+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: '8px' }}>
+      <BdsCheckbox name="interests" value="sports">Sports</BdsCheckbox>
+      <BdsCheckbox name="interests" value="music" checked>Music</BdsCheckbox>
+      <BdsCheckbox name="interests" value="travel">Travel</BdsCheckbox>
+    </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

@@ -0,0 +1,71 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCombobox.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-combobox&gt;
+
+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.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+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>`.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With disabled option
+<Canvas of={Stories.WithDisabledOption} />
+
+### Required
+<Canvas of={Stories.Required} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## 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

@@ -0,0 +1,93 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+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' },
+]);
+
+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({
+  name,
+  value,
+  options,
+  placeholder,
+  disabled,
+}: {
+  name?: string;
+  value?: string;
+  options?: string;
+  placeholder?: string;
+  disabled?: boolean;
+}) {
+  return React.createElement('bds-combobox', {
+    name,
+    value,
+    options,
+    placeholder,
+    disabled: disabled || undefined,
+  });
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/Combobox',
+  component: BdsCombobox,
+  tags: ['!stable', 'experimental'],
+  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: {
+    name: 'country',
+    options: COUNTRIES,
+    placeholder: 'Search country…',
+  },
+};
+
+export const WithDisabledOption: Story = {
+  args: {
+    name: 'country',
+    options: COUNTRIES_WITH_DISABLED,
+    placeholder: 'Search country…',
+  },
+};
+
+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,
+  },
+};

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

@@ -0,0 +1,79 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsFileInput.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-file-input&gt;
+
+Form-associated file upload zone with drag-and-drop support. Renders a styled drop zone that opens the native file picker on click or keyboard activation.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+Use `<bds-file-input>` wherever users need to attach one or more files to a form. It provides drag-and-drop as a progressive enhancement on top of the native file picker.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Multiple files
+<Canvas of={Stories.Multiple} />
+
+### Accept images only
+<Canvas of={Stories.WithAccept} />
+
+### Accept PDFs and Word documents
+<Canvas of={Stories.WithPDFAccept} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute  | Type    | Default | Description                                          |
+|------------|---------|---------|------------------------------------------------------|
+| `name`     | string  | `""`    | Form field name                                      |
+| `accept`   | string  | `""`    | File types to accept (e.g. `"image/*"`, `".pdf"`)    |
+| `multiple` | boolean | `false` | Allow selecting multiple files                       |
+| `disabled` | boolean | `false` | Disables the file input                              |
+
+## Slots
+
+| Slot        | Description                                    |
+|-------------|------------------------------------------------|
+| `(default)` | Drop zone call-to-action text. Defaults to "Drag & drop or click to browse" |
+
+## Events
+
+| Event        | Detail       | Description                             |
+|--------------|--------------|-----------------------------------------|
+| `bds-change` | `FileList`   | Fired when files are selected or dropped |
+
+## Usage in plain HTML
+
+```html
+<bds-file-input name="avatar" accept="image/*">Upload photo</bds-file-input>
+
+<!-- Multiple files -->
+<bds-file-input name="documents" accept=".pdf,.docx" multiple></bds-file-input>
+```
+
+## Accessibility
+
+- The drop zone has `role="button"` and `tabindex="0"` so it is keyboard-reachable
+- `aria-label="Upload file"` is set on the zone for screen reader identification
+- `Enter` and `Space` open the native file picker from keyboard focus
+- `disabled` sets `tabindex="-1"` and `pointer-events: none`
+- Participates in HTML forms via the Form-Associated Custom Elements API; files are submitted as `FormData` entries

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

@@ -0,0 +1,69 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsFileInput({
+  name,
+  accept,
+  multiple,
+  disabled,
+  children,
+}: {
+  name?: string;
+  accept?: string;
+  multiple?: boolean;
+  disabled?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-file-input',
+    {
+      name,
+      accept,
+      multiple: multiple || undefined,
+      disabled: disabled || undefined,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/FileInput',
+  component: BdsFileInput,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    multiple: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+  decorators: [
+    (Story: React.ComponentType) => (
+      <div style={{ width: '360px' }}>
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof BdsFileInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { name: 'file' },
+};
+
+export const Multiple: Story = {
+  args: { name: 'files', multiple: true },
+};
+
+export const WithAccept: Story = {
+  args: { name: 'avatar', accept: 'image/*' },
+};
+
+export const WithPDFAccept: Story = {
+  args: { name: 'document', accept: '.pdf,.docx' },
+};
+
+export const Disabled: Story = {
+  args: { name: 'file', disabled: true },
+};

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

@@ -0,0 +1,98 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsFormInput.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-form-input&gt;
+
+Form-associated text input with label, hint, error, and prefix/suffix slot support. Participates in HTML forms via the Form-Associated Custom Elements API.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+Use `<bds-form-input>` for single-line text fields in forms. It handles label association, validation states, and prefix/suffix adornments in a single element.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With label
+<Canvas of={Stories.WithLabel} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### With prefix (currency symbol)
+<Canvas of={Stories.WithPrefix} />
+
+### With suffix (unit)
+<Canvas of={Stories.WithSuffix} />
+
+### Email type
+<Canvas of={Stories.Email} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute     | Type    | Default  | Description                                                    |
+|---------------|---------|----------|----------------------------------------------------------------|
+| `name`        | string  | `""`     | Form field name                                                |
+| `type`        | string  | `"text"` | Input type: `text`, `email`, `password`, `search`, `url`, `tel` |
+| `value`       | string  | `""`     | Current input value                                            |
+| `placeholder` | string  | `""`     | Placeholder text                                               |
+| `label`       | string  | `""`     | Visible label text                                             |
+| `hint`        | string  | —        | Helper text shown below the input                              |
+| `error`       | string  | —        | Error message; when set the input enters error state           |
+| `disabled`    | boolean | `false`  | Disables the input                                             |
+| `required`    | boolean | `false`  | Marks the field as required                                    |
+
+## Slots
+
+| Slot     | Description                               |
+|----------|-------------------------------------------|
+| `prefix` | Icon or text rendered before the input    |
+| `suffix` | Icon or text rendered after the input     |
+
+## Events
+
+| Event        | Detail                  | Description                         |
+|--------------|-------------------------|-------------------------------------|
+| `bds-input`  | `{ value: string }`     | Fired on every keystroke            |
+| `bds-change` | `{ value: string }`     | Fired when the value is committed   |
+
+## Usage in plain HTML
+
+```html
+<bds-form-input name="email" type="email" label="Email address" required></bds-form-input>
+
+<!-- With prefix -->
+<bds-form-input name="price" label="Price">
+  <span slot="prefix">€</span>
+</bds-form-input>
+```
+
+## Accessibility
+
+- `<label>` is associated with the inner `<input>` via matching `id`/`for` attributes
+- `required` adds `aria-required="true"` and a visual asterisk
+- `error` sets `aria-invalid="true"` and links the error message via `aria-describedby`
+- `hint` is linked via `aria-describedby` for screen reader announcement
+- Error messages use `role="alert"` so they are announced immediately
+- The focus ring is applied to the wrapper element, not the inner input