@boostdev/design-system-components 1.1.2 → 1.2.1

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

@@ -0,0 +1,139 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsFormInput({
+  name,
+  type,
+  value,
+  placeholder,
+  label,
+  hint,
+  error,
+  disabled,
+  required,
+  prefix,
+  suffix,
+}: {
+  name?: string;
+  type?: string;
+  value?: string;
+  placeholder?: string;
+  label?: string;
+  hint?: string;
+  error?: string;
+  disabled?: boolean;
+  required?: boolean;
+  prefix?: React.ReactNode;
+  suffix?: React.ReactNode;
+}) {
+  const prefixSlot = prefix
+    ? React.createElement('span', { slot: 'prefix' }, prefix)
+    : undefined;
+  const suffixSlot = suffix
+    ? React.createElement('span', { slot: 'suffix' }, suffix)
+    : undefined;
+
+  return React.createElement(
+    'bds-form-input',
+    {
+      name,
+      type,
+      value,
+      placeholder,
+      label,
+      hint,
+      error,
+      disabled: disabled || undefined,
+      required: required || undefined,
+    },
+    prefixSlot,
+    suffixSlot,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/FormInput',
+  component: BdsFormInput,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    type: {
+      control: 'select',
+      options: ['text', 'email', 'password', 'search', 'url', 'tel'],
+    },
+    disabled: { control: 'boolean' },
+    required: { control: 'boolean' },
+  },
+  decorators: [
+    (Story: React.ComponentType) => (
+      <div style={{ width: '320px' }}>
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof BdsFormInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { name: 'text', placeholder: 'Enter text…' },
+};
+
+export const WithLabel: Story = {
+  args: { name: 'username', label: 'Username', placeholder: 'e.g. johndoe' },
+};
+
+export const WithHint: Story = {
+  args: {
+    name: 'username',
+    label: 'Username',
+    placeholder: 'e.g. johndoe',
+    hint: 'Must be 3–20 characters.',
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    name: 'username',
+    label: 'Username',
+    placeholder: 'e.g. johndoe',
+    error: 'Username is already taken.',
+  },
+};
+
+export const WithPrefix: Story = {
+  render: () => (
+    <div style={{ width: '320px' }}>
+      <BdsFormInput name="price" label="Price" placeholder="0.00" prefix="€" />
+    </div>
+  ),
+};
+
+export const WithSuffix: Story = {
+  render: () => (
+    <div style={{ width: '320px' }}>
+      <BdsFormInput name="weight" label="Weight" placeholder="0" suffix="kg" />
+    </div>
+  ),
+};
+
+export const Email: Story = {
+  args: {
+    name: 'email',
+    type: 'email',
+    label: 'Email address',
+    placeholder: 'you@example.com',
+    required: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    name: 'username',
+    label: 'Username',
+    value: 'johndoe',
+    disabled: true,
+  },
+};

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

@@ -0,0 +1,70 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsNumberInput.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-number-input&gt;
+
+Form-associated number input with increment and decrement stepper buttons. Hides the browser's native spinners and provides styled stepper controls instead.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+Use `<bds-number-input>` for quantity selectors, counters, or any numeric field where step-by-step incrementing is a common interaction pattern.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With min and max
+<Canvas of={Stories.WithMinMax} />
+
+### With custom step (5)
+<Canvas of={Stories.WithStep} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute  | Type    | Default     | Description                              |
+|------------|---------|-------------|------------------------------------------|
+| `name`     | string  | `""`        | Form field name                          |
+| `value`    | number  | `0`         | Current numeric value                    |
+| `min`      | number  | —           | Minimum allowed value                    |
+| `max`      | number  | —           | Maximum allowed value                    |
+| `step`     | number  | `1`         | Increment/decrement step                 |
+| `disabled` | boolean | `false`     | Disables the input and steppers          |
+
+## Events
+
+| Event    | Detail | Description                                           |
+|----------|--------|-------------------------------------------------------|
+| `input`  | —      | Fired on stepper click and native input               |
+| `change` | —      | Native change event from the inner `<input type="number">` |
+
+## Usage in plain HTML
+
+```html
+<bds-number-input name="qty" value="1" min="0" max="99" step="1"></bds-number-input>
+```
+
+## Accessibility
+
+- Decrement button has `aria-label="Decrease"` and increment has `aria-label="Increase"`
+- Stepper buttons are disabled when the value is at `min` or `max`
+- The stepper buttons use `tabindex="-1"` so keyboard users navigate directly to the numeric input
+- `disabled` disables both the input and the stepper buttons
+- Participates in HTML forms via the Form-Associated Custom Elements API

package/src/web-components/interaction/form/BdsNumberInput.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 BdsNumberInput({
+  name,
+  value,
+  min,
+  max,
+  step,
+  disabled,
+}: {
+  name?: string;
+  value?: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  disabled?: boolean;
+}) {
+  return React.createElement('bds-number-input', {
+    name,
+    value,
+    min,
+    max,
+    step,
+    disabled: disabled || undefined,
+  });
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/NumberInput',
+  component: BdsNumberInput,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    disabled: { control: 'boolean' },
+    value: { control: 'number' },
+    min: { control: 'number' },
+    max: { control: 'number' },
+    step: { control: 'number' },
+  },
+  decorators: [
+    (Story: React.ComponentType) => (
+      <div style={{ width: '200px' }}>
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof BdsNumberInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { name: 'quantity', value: 0 },
+};
+
+export const WithMinMax: Story = {
+  args: { name: 'quantity', value: 5, min: 0, max: 10 },
+};
+
+export const WithStep: Story = {
+  args: { name: 'quantity', value: 0, step: 5, min: 0, max: 100 },
+};
+
+export const Disabled: Story = {
+  args: { name: 'quantity', value: 3, disabled: true },
+};

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

@@ -0,0 +1,72 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsRadio.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-radio&gt;
+
+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>`.
+
+> **Status: experimental** — API may change before stable release.
+
+## 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  | `""`    | 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 content |
+
+## Events
+
+| Event    | Detail | Description                                    |
+|----------|--------|------------------------------------------------|
+| `change` | —      | Native change event forwarded from the inner `<input>` |
+
+## Usage in plain HTML
+
+```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

@@ -0,0 +1,58 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsRadio({
+  name,
+  value,
+  checked,
+  required,
+  disabled,
+  children,
+}: {
+  name?: string;
+  value?: string;
+  checked?: boolean;
+  required?: boolean;
+  disabled?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-radio',
+    {
+      name,
+      value,
+      checked: checked || undefined,
+      required: required || undefined,
+      disabled: disabled || undefined,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/Radio',
+  component: BdsRadio,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    checked: { control: 'boolean' },
+    required: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsRadio>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { name: 'size', value: 'm', children: 'Medium' },
+};
+
+export const Checked: Story = {
+  args: { name: 'size', value: 'm', checked: true, children: 'Medium (checked)' },
+};
+
+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

@@ -0,0 +1,95 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSegmentedControl.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-segmented-control&gt;
+
+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).
+
+> **Status: experimental** — API may change before stable release.
+
+## 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 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    | Detail | Description                                              |
+|----------|--------|----------------------------------------------------------|
+| `change` | —      | Fired when a new segment is selected (radio mode only)   |
+
+## Usage in plain HTML
+
+```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>
+```
+
+## CSS Custom Properties
+
+| 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)