@boostdev/design-system-components 1.2.0 → 1.2.2

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

@@ -3,42 +3,77 @@ import * as Stories from './BdsFileInput.stories';
 
 <Meta of={Stories} />
 
-# File Input
+# &lt;bds-file-input&gt;
 
-`<bds-file-input>` is a form-associated file upload zone with drag-and-drop support. The slot content customises the zone label text.
+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.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-file-input name="avatar" accept="image/*">Upload your photo</bds-file-input>
+## Installation
+
+```js
+import '@boostdev/components/web-components';
 ```
 
-## Attributes
+## When to use
 
-| Attribute  | Type      | Default | Description                              |
-|------------|-----------|---------|------------------------------------------|
-| `name`     | `string`  | `""`    | Form field name                          |
-| `accept`   | `string`  | `""`    | File types to accept (e.g. `"image/*"`)  |
-| `multiple` | `boolean` | `false` | Allow selecting multiple files           |
-| `disabled` | `boolean` | `false` | Disables the drop zone                   |
+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.
 
-## Events
+## Examples
 
-| Event        | Detail      | Description                              |
-|--------------|-------------|------------------------------------------|
-| `bds-change` | `FileList`  | Fired when files are selected or dropped |
+### Default
+<Canvas of={Stories.Default} />
 
-## Slots
+### Multiple files
+<Canvas of={Stories.Multiple} />
 
-| Slot      | Description                    |
-|-----------|--------------------------------|
-| (default) | Custom label text for the zone |
+### Accept images only
+<Canvas of={Stories.WithAccept} />
 
-## Stories
+### Accept PDFs and Word documents
+<Canvas of={Stories.WithPDFAccept} />
 
-<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                                      |
+| `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

@@ -1,84 +1,69 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../../index';
+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', {
-    accept,
-    multiple: multiple || undefined,
-    disabled: disabled || undefined,
-    style: { display: 'block', maxInlineSize: '480px' },
-  });
+  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: 'padded' },
+  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: {} };
-export const ImagesOnly: Story = { args: { accept: 'image/*' } };
-export const Multiple: Story = { args: { multiple: true } };
-export const Disabled: Story = { args: { disabled: true } };
+export const Default: Story = {
+  args: { name: 'file' },
+};
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '24px', maxInlineSize: '480px' }}>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888' }}>Any file type</p>
-        {React.createElement('bds-file-input', { style: { display: 'block' } })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888' }}>Images only</p>
-        {React.createElement('bds-file-input', { accept: 'image/*', style: { display: 'block' } })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888' }}>Multiple files</p>
-        {React.createElement('bds-file-input', { multiple: true, style: { display: 'block' } })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888' }}>Disabled</p>
-        {React.createElement('bds-file-input', { disabled: true, style: { display: 'block' } })}
-      </div>
-    </div>
-  ),
+export const Multiple: Story = {
+  args: { name: 'files', multiple: true },
 };
 
-export const Interactive: Story = {
-  render: () => {
-    const [files, setFiles] = React.useState<string[]>([]);
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxInlineSize: '480px' }}>
-        {React.createElement('bds-file-input', {
-          multiple: true,
-          style: { display: 'block' },
-          'onbds-change': (e: CustomEvent<FileList>) => {
-            setFiles(Array.from(e.detail).map(f => f.name));
-          },
-        })}
-        {files.length > 0 && (
-          <ul style={{ margin: 0, padding: '0 0 0 16px', fontSize: '0.875rem' }}>
-            {files.map(name => <li key={name}>{name}</li>)}
-          </ul>
-        )}
-      </div>
-    );
-  },
+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

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

@@ -3,39 +3,68 @@ import * as Stories from './BdsNumberInput.stories';
 
 <Meta of={Stories} />
 
-# Number Input
+# &lt;bds-number-input&gt;
 
-`<bds-number-input>` is a form-associated number input with decrement/increment stepper buttons. The native browser spin buttons are hidden in favour of the custom steppers.
+Form-associated number input with increment and decrement stepper buttons. Hides the browser's native spinners and provides styled stepper controls instead.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-number-input name="qty" value="1" min="0" max="99" step="1"></bds-number-input>
+## 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`  | `undefined` | Minimum allowed value              |
-| `max`      | `number`  | `undefined` | Maximum allowed value              |
-| `step`     | `number`  | `1`         | Increment/decrement step           |
-| `disabled` | `boolean` | `false`     | Disables all interaction           |
+| 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    | Description                                |
-|----------|--------------------------------------------|
-| `input`  | Fired on stepper click and native input    |
-| `change` | Native change event                        |
+| Event    | Detail | Description                                           |
+|----------|--------|-------------------------------------------------------|
+| `input`  | —      | Fired on stepper click and native input               |
+| `change` | —      | Native change event from the inner `<input type="number">` |
 
-## Stories
+## Usage in plain HTML
 
-<Canvas of={Stories.Default} />
-<Canvas of={Stories.AllVariants} />
+```html
+<bds-number-input name="qty" value="1" min="0" max="99" step="1"></bds-number-input>
+```
 
-## Controls
+## Accessibility
 
-<ArgTypes of={Stories} />
+- 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

@@ -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 BdsNumberInput({
+  name,
   value,
   min,
   max,
   step,
   disabled,
 }: {
+  name?: string;
   value?: number;
   min?: number;
   max?: number;
@@ -16,12 +18,12 @@ function BdsNumberInput({
   disabled?: boolean;
 }) {
   return React.createElement('bds-number-input', {
+    name,
     value,
     min,
     max,
     step,
     disabled: disabled || undefined,
-    style: { display: 'block', maxInlineSize: '160px' },
   });
 }
 
@@ -29,62 +31,38 @@ const meta = {
   title: 'Web Components/Interaction/Form/NumberInput',
   component: BdsNumberInput,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
   argTypes: {
+    disabled: { control: 'boolean' },
     value: { control: 'number' },
     min: { control: 'number' },
     max: { control: 'number' },
     step: { control: 'number' },
-    disabled: { control: 'boolean' },
   },
+  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: { value: 0 } };
-export const WithBounds: Story = { args: { value: 5, min: 0, max: 10 } };
-export const WithStep: Story = { args: { value: 0, min: 0, max: 100, step: 5 } };
-export const Disabled: Story = { args: { value: 42, disabled: true } };
+export const Default: Story = {
+  args: { name: 'quantity', value: 0 },
+};
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Default</p>
-        {React.createElement('bds-number-input', { value: 0, style: { display: 'block', maxInlineSize: '160px' } })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Bounded (0–10)</p>
-        {React.createElement('bds-number-input', { value: 5, min: 0, max: 10, style: { display: 'block', maxInlineSize: '160px' } })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Step 5</p>
-        {React.createElement('bds-number-input', { value: 50, min: 0, max: 100, step: 5, style: { display: 'block', maxInlineSize: '160px' } })}
-      </div>
-      <div>
-        <p style={{ margin: '0 0 4px', fontSize: '0.75rem', color: '#888' }}>Disabled</p>
-        {React.createElement('bds-number-input', { value: 7, disabled: true, style: { display: 'block', maxInlineSize: '160px' } })}
-      </div>
-    </div>
-  ),
+export const WithMinMax: Story = {
+  args: { name: 'quantity', value: 5, min: 0, max: 10 },
 };
 
-export const Interactive: Story = {
-  render: () => {
-    const [qty, setQty] = React.useState(1);
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
-        <p style={{ margin: '0 0 4px', fontSize: '0.875rem' }}>Quantity: {qty}</p>
-        {React.createElement('bds-number-input', {
-          value: qty,
-          min: 1,
-          max: 99,
-          step: 1,
-          style: { display: 'block', maxInlineSize: '160px' },
-          onInput: (e: Event) => setQty(parseInt((e.target as HTMLInputElement).value, 10) || 1),
-        })}
-      </div>
-    );
-  },
+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 },
 };