@boostdev/design-system-components 1.1.2 → 1.2.1

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

@@ -0,0 +1,102 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+const VIEW_OPTIONS = JSON.stringify([
+  { value: 'list', label: 'List' },
+  { value: 'grid', label: 'Grid' },
+  { value: 'map', label: 'Map' },
+]);
+
+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({
+  name,
+  value,
+  options,
+  disabled,
+  variant,
+}: {
+  name?: string;
+  value?: string;
+  options?: string;
+  disabled?: boolean;
+  variant?: 'outline' | 'filled';
+}) {
+  return React.createElement('bds-segmented-control', {
+    name,
+    value,
+    options,
+    disabled: disabled || undefined,
+    variant,
+  });
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/SegmentedControl',
+  component: BdsSegmentedControl,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    variant: { control: 'select', options: ['outline', 'filled'] },
+    disabled: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsSegmentedControl>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+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 = {
+  args: {
+    name: 'view',
+    value: 'list',
+    options: OPTIONS_WITH_DISABLED,
+    variant: 'outline',
+  },
+};
+
+export const AsNavLinks: Story = {
+  args: {
+    value: 'home',
+    options: NAV_OPTIONS,
+    variant: 'outline',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    name: 'view',
+    value: 'list',
+    options: VIEW_OPTIONS,
+    disabled: true,
+    variant: 'outline',
+  },
+};

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

@@ -0,0 +1,76 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSelect.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-select&gt;
+
+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.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+Use `<bds-select>` for pick-from-list dropdowns where users cannot type to search. For searchable/filterable lists, use `<bds-combobox>` instead.
+
+## Examples
+
+### Default (pre-selected value)
+<Canvas of={Stories.Default} />
+
+### 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

@@ -0,0 +1,84 @@
+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 BdsSelect({
+  name,
+  value,
+  options,
+  placeholder,
+  required,
+  disabled,
+}: {
+  name?: string;
+  value?: string;
+  options?: string;
+  placeholder?: string;
+  required?: boolean;
+  disabled?: boolean;
+}) {
+  return React.createElement('bds-select', {
+    name,
+    value,
+    options,
+    placeholder,
+    required: required || undefined,
+    disabled: disabled || undefined,
+  });
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/Select',
+  component: BdsSelect,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    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: { name: 'country', options: COUNTRIES, value: 'nl' },
+};
+
+export const WithPlaceholder: Story = {
+  args: { name: 'country', options: COUNTRIES, placeholder: 'Choose a country…' },
+};
+
+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

@@ -0,0 +1,77 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSlider.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-slider&gt;
+
+Form-associated range slider. Wraps a native `<input type="range">` with a styled fill track driven by the `--slider_fill` CSS custom property.
+
+> **Status: experimental** — API may change before stable release.
+
+## 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 the slider                      |
+
+## Events
+
+| 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 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`) |
+
+## Usage in plain HTML
+
+```html
+<bds-slider name="volume" value="50" min="0" max="100" step="5"></bds-slider>
+```
+
+## Accessibility
+
+- 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

@@ -0,0 +1,68 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsSlider({
+  name,
+  value,
+  min,
+  max,
+  step,
+  disabled,
+}: {
+  name?: string;
+  value?: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  disabled?: boolean;
+}) {
+  return React.createElement('bds-slider', {
+    name,
+    value,
+    min,
+    max,
+    step,
+    disabled: disabled || undefined,
+  });
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/Slider',
+  component: BdsSlider,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    value: { control: 'number' },
+    min: { control: 'number' },
+    max: { control: 'number' },
+    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: { name: 'volume', value: 50 },
+};
+
+export const WithStep: Story = {
+  args: { name: 'volume', value: 25, min: 0, max: 100, step: 25 },
+};
+
+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

@@ -0,0 +1,72 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSwitch.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-switch&gt;
+
+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.
+
+> **Status: experimental** — API may change before stable release.
+
+## 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"`  | 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 content |
+
+## Events
+
+| Event    | Detail | Description                                    |
+|----------|--------|------------------------------------------------|
+| `change` | —      | Fired when the switch state changes            |
+
+## 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>
+```
+
+## 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

@@ -0,0 +1,58 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsSwitch({
+  name,
+  value,
+  checked,
+  required,
+  disabled,
+  children,
+}: {
+  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,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/Switch',
+  component: BdsSwitch,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    checked: { control: 'boolean' },
+    required: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsSwitch>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { name: 'notifications', value: 'enabled', children: 'Enable notifications' },
+};
+
+export const Checked: Story = {
+  args: { name: 'notifications', value: 'enabled', checked: true, children: 'Notifications enabled' },
+};
+
+export const Disabled: Story = {
+  args: { name: 'notifications', value: 'enabled', disabled: true, children: 'Notifications (disabled)' },
+};

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

@@ -0,0 +1,73 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsTextarea.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-textarea&gt;
+
+Form-associated multiline text input. Wraps a native `<textarea>` with consistent styling while participating 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-textarea>` for multiline text entry — messages, comments, descriptions, or any input that may span more than one line.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Pre-filled value
+<Canvas of={Stories.WithValue} />
+
+### Tall (8 rows)
+<Canvas of={Stories.TallRows} />
+
+### 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  | `""`    | 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                    |
+
+## Events
+
+| Event    | Detail | Description                                         |
+|----------|--------|-----------------------------------------------------|
+| `input`  | —      | Fired on every keystroke (native input event)       |
+| `change` | —      | Fired when the value is committed (native change event) |
+
+## 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>
+```
+
+## Accessibility
+
+- Wraps a native `<textarea>` which has full browser and assistive technology support
+- `required` uses the native `required` attribute for browser validation
+- `disabled` sets `pointer-events: none`, reduces opacity, and removes the resize handle
+- Participates in HTML forms via the Form-Associated Custom Elements API

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

@@ -0,0 +1,70 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsTextarea({
+  name,
+  value,
+  placeholder,
+  rows,
+  required,
+  disabled,
+}: {
+  name?: string;
+  value?: string;
+  placeholder?: string;
+  rows?: number;
+  required?: boolean;
+  disabled?: boolean;
+}) {
+  return React.createElement('bds-textarea', {
+    name,
+    value,
+    placeholder,
+    rows,
+    required: required || undefined,
+    disabled: disabled || undefined,
+  });
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/Textarea',
+  component: BdsTextarea,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    rows: { control: 'number' },
+    required: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+  decorators: [
+    (Story: React.ComponentType) => (
+      <div style={{ width: '360px' }}>
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof BdsTextarea>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { name: 'message', placeholder: 'Enter your message…' },
+};
+
+export const WithValue: Story = {
+  args: { name: 'message', value: 'Hello, this is a pre-filled message.' },
+};
+
+export const TallRows: Story = {
+  args: { name: 'message', placeholder: 'Enter a longer text…', rows: 8 },
+};
+
+export const Required: Story = {
+  args: { name: 'message', placeholder: 'Required field', required: true },
+};
+
+export const Disabled: Story = {
+  args: { name: 'message', value: 'Read-only content', disabled: true },
+};