@boostdev/design-system-components 0.1.13 → 0.1.14

package/src/components/interaction/Toast/Toast.mdx

@@ -0,0 +1,78 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Toast.stories';
+
+<Meta of={Stories} />
+
+# Toast
+
+Transient feedback notification that auto-dismisses after 5 seconds. Provided via a context provider and `useToast` hook.
+
+## When to use
+- Confirmation after a user action (save, delete, send)
+- Non-blocking error or warning messages that do not require immediate action
+
+## When not to use
+- Critical errors that require user acknowledgement — use `Alert` or `Dialog`
+- Status that needs to persist — use `Alert` or `NotificationBanner`
+
+## Setup
+
+Wrap your app (or layout root) once with `ToastProvider`:
+
+```tsx
+import { ToastProvider } from '@boostdev/components';
+
+<ToastProvider>
+  <App />
+</ToastProvider>
+```
+
+Then call `showToast` anywhere inside:
+
+```tsx
+import { useToast } from '@boostdev/components';
+
+const { showToast } = useToast();
+
+showToast('Changes saved', 'success');
+showToast('Something went wrong', 'error');
+showToast('New message received', 'info');
+```
+
+## Examples
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Error
+<Canvas of={Stories.Error} />
+
+### Info
+<Canvas of={Stories.Info} />
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--toast_color`</td><td>Toast background</td></tr>
+<tr><td>`--toast_on-color`</td><td>Toast text colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Toast container uses `role="status"` and `aria-live="polite"` — announcements are non-intrusive
+- Auto-dismisses after 5 seconds; users can also manually dismiss
+- Animation respects `prefers-reduced-motion`

package/src/components/interaction/Toast/Toast.module.css

@@ -13,7 +13,6 @@
     padding: var(--space_m) var(--space_l);
     background-color: var(--toast_color, var(--color_bg));
     color: var(--toast_on-color, var(--color_on-bg));
-    border: 1px solid currentcolor;
     border-radius: var(--border_radius--s);
     box-shadow: var(--shadow_s);
     display: flex;
@@ -23,6 +22,26 @@
     animation: slideIn var(--animation_duration--fast) var(--animation_easing);
   }
 
+  .toast.--variant_success {
+    --toast_color: var(--color_success);
+    --toast_on-color: var(--color_on-success);
+  }
+
+  .toast.--variant_warning {
+    --toast_color: var(--color_warning);
+    --toast_on-color: var(--color_on-warning);
+  }
+
+  .toast.--variant_info {
+    --toast_color: var(--color_bg--subtle);
+    --toast_on-color: var(--color_on-bg--subtle);
+  }
+
+  .toast.--variant_error {
+    --toast_color: var(--color_error);
+    --toast_on-color: var(--color_on-error);
+  }
+
   .message {
     flex: 1;
   }
@@ -38,12 +57,7 @@
     background: none;
     border: none;
     cursor: pointer;
-    color: inherit;
-    opacity: 0.6;
-  }
-
-  .closeButton:hover {
-    opacity: 1;
+    color: var(--toast_on-color);
   }
 
   .closeButton svg {

package/src/components/interaction/Toast/Toast.stories.tsx

@@ -5,7 +5,6 @@ import { Button } from '../Button/Button';
 const meta = {
   title: 'Interaction/Toast',
   component: ToastProvider,
-  tags: ['autodocs'],
 } satisfies Meta<typeof ToastProvider>;
 
 export default meta;

package/src/components/interaction/form/Checkbox/Checkbox.mdx

@@ -0,0 +1,57 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Checkbox.stories';
+
+<Meta of={Stories} />
+
+# Checkbox
+
+Binary toggle for opt-in/opt-out choices. Renders a styled native `<input type="checkbox">` with label, hint, and error support.
+
+## When to use
+- Independent on/off choices (newsletter opt-in, terms acceptance)
+- Multi-select within a group of options
+
+## When not to use
+- Mutually exclusive choices — use `Radio`
+- A single toggle that takes immediate effect — use `Switch`
+
+## Examples
+
+### Default (unchecked)
+<Canvas of={Stories.Default} />
+
+### Checked
+<Canvas of={Stories.Checked} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--checkbox_color-active`</td><td>`var(--color_active)`</td><td>Checked background</td></tr>
+<tr><td>`--checkbox_color-on-active`</td><td>`var(--color_on-active)`</td><td>Checkmark colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Native `<input type="checkbox">` — correct semantics without ARIA
+- Label is always associated via `htmlFor`/`id`
+- Error message is linked via `aria-describedby`

package/src/components/interaction/form/Checkbox/Checkbox.stories.tsx

@@ -4,7 +4,6 @@ import { Checkbox } from './Checkbox';
 const meta = {
   title: 'Form/Checkbox',
   component: Checkbox,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Checkbox>;
 
 export default meta;

package/src/components/interaction/form/Combobox/Combobox.mdx

@@ -0,0 +1,37 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Combobox.stories';
+
+<Meta of={Stories} />
+
+# Combobox
+
+Searchable select with type-ahead filtering. Combines a text input with a dropdown option list.
+
+## When to use
+- Large option lists (10+) where filtering helps the user find their choice
+- Data that may be loaded asynchronously
+
+## When not to use
+- Small, static option sets (< 10 items) — use `Select` for simplicity
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Input uses `role="combobox"` with `aria-autocomplete="list"` and `aria-controls`
+- Listbox uses `role="listbox"` with `role="option"` items
+- `aria-activedescendant` tracks keyboard-highlighted option
+- `Escape` closes the dropdown; `Enter` selects the active option

package/src/components/interaction/form/Combobox/Combobox.stories.tsx

@@ -14,7 +14,6 @@ const options = [
 const meta = {
   title: 'Form/Combobox',
   component: Combobox,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Combobox>;
 
 export default meta;

package/src/components/interaction/form/FileInput/FileInput.mdx

@@ -0,0 +1,38 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './FileInput.stories';
+
+<Meta of={Stories} />
+
+# FileInput
+
+File upload input with styled trigger button, hint, and error support.
+
+## When to use
+- Any form that requires file attachments
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With accept restriction
+<Canvas of={Stories.WithAccept} />
+
+### Multiple files
+<Canvas of={Stories.Multiple} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Native `<input type="file">` — opens the OS file picker
+- Label linked via `id`/`htmlFor`
+- `accept` restricts the file picker but does not validate — validate on the server too

package/src/components/interaction/form/FileInput/FileInput.stories.tsx

@@ -4,7 +4,6 @@ import { FileInput } from './FileInput';
 const meta = {
   title: 'Form/FileInput',
   component: FileInput,
-  tags: ['autodocs'],
 } satisfies Meta<typeof FileInput>;
 
 export default meta;

package/src/components/interaction/form/FormInput/FormInput.mdx

@@ -0,0 +1,54 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './FormInput.stories';
+
+<Meta of={Stories} />
+
+# FormInput
+
+Text input field with label, optional hint, and error state. The label and input are connected via `htmlFor`/`id` automatically.
+
+## When to use
+- Any single-line text, email, password, or number input in a form
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Required
+<Canvas of={Stories.Required} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--input_border-color`</td><td>Border colour (set by state — focus, error)</td></tr>
+<tr><td>`--input_color`</td><td>Background colour</td></tr>
+<tr><td>`--input_on-color`</td><td>Text colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- `label` is always rendered and linked to the input via `id`/`htmlFor`
+- Error message uses `aria-describedby` to associate with the input
+- `required` sets both the HTML attribute and a visual indicator
+- `disabled` removes the field from the tab order

package/src/components/interaction/form/FormInput/FormInput.stories.tsx

@@ -4,7 +4,6 @@ import { FormInput } from './FormInput';
 const meta = {
   title: 'Form/FormInput',
   component: FormInput,
-  tags: ['autodocs'],
 } satisfies Meta<typeof FormInput>;
 
 export default meta;

package/src/components/interaction/form/NumberInput/NumberInput.mdx

@@ -0,0 +1,38 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './NumberInput.stories';
+
+<Meta of={Stories} />
+
+# NumberInput
+
+Numeric text input with increment/decrement stepper buttons. Enforces `min`, `max`, and `step` constraints.
+
+## When to use
+- Quantity selectors, precise numeric values where a slider would be too imprecise
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With range
+<Canvas of={Stories.WithRange} />
+
+### With step
+<Canvas of={Stories.WithStep} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Renders `<input type="number">` — browser-native spinner support
+- Stepper buttons have `aria-label="Increment"` / `"Decrement"`
+- Label linked via `id`/`htmlFor`

package/src/components/interaction/form/NumberInput/NumberInput.stories.tsx

@@ -4,7 +4,6 @@ import { NumberInput } from './NumberInput';
 const meta = {
   title: 'Form/NumberInput',
   component: NumberInput,
-  tags: ['autodocs'],
 } satisfies Meta<typeof NumberInput>;
 
 export default meta;

package/src/components/interaction/form/Radio/Radio.mdx

@@ -0,0 +1,60 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Radio.stories';
+
+<Meta of={Stories} />
+
+# Radio
+
+Single-select option within a group. Renders a styled native `<input type="radio">`. Group radios by a shared `name` attribute.
+
+## When to use
+- Mutually exclusive choices where all options are visible (2–6 options)
+
+## When not to use
+- More than 6 options — use `Select` or `Combobox`
+- Independent on/off choices — use `Checkbox`
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Selected
+<Canvas of={Stories.Selected} />
+
+### With description
+<Canvas of={Stories.WithDescription} />
+
+### Group
+<Canvas of={Stories.Group} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--radio_color-active`</td><td>`var(--color_active)`</td><td>Selected fill and border colour</td></tr>
+<tr><td>`--radio_color-on-active`</td><td>`var(--color_on-active)`</td><td>Inner dot colour</td></tr>
+<tr><td>`--radio_description-color`</td><td>`var(--color_on-bg--subtle)`</td><td>Description text colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Native `<input type="radio">` — group semantics via shared `name`
+- Wrap groups in `<fieldset>` with a `<legend>` for a group label
+- Arrow keys move between radios in the same group

package/src/components/interaction/form/Radio/Radio.module.css

@@ -9,23 +9,36 @@
 
   .inputWrapper {
     display: flex;
-    align-items: stretch;
+    align-items: flex-start;
     gap: var(--space_xs);
   }
 
+  .textWrapper {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space_xxxs);
+    padding-block-start: var(--space_xxxs);
+  }
+
+  .description {
+    font-size: var(--font_size--body--s);
+    color: var(--radio_description-color, var(--color_on-bg--subtle));
+    line-height: var(--font_line-height--body);
+  }
+
   .radio {
     flex-shrink: 0;
-    margin-block-start: 0.25em;
+    margin-block-start: 0.2em;
     width: var(--inputSize);
     height: var(--inputSize);
     color: var(--radio_color, var(--color_on-bg));
-    border: 1px solid currentcolor;
+    border: 1.5px solid currentcolor;
     border-radius: 50%;
     appearance: none;
     background-color: var(--radio_color_bg, var(--color_bg));
     cursor: pointer;
     position: relative;
-    transition: background-color 0.3s ease, border-color 0.3s ease;
+    transition: background-color 0.2s ease, border-color 0.2s ease;
   }
 
   .radio:checked {
@@ -36,13 +49,13 @@
   .radio:checked::after {
     content: '';
     position: absolute;
-    left: 0.6em;
-    top: 0.25em;
-    width: 0.5em;
-    height: 1em;
-    border: solid var(--radio_color-on-active, var(--color_on-active));
-    border-width: 0 2px 2px 0;
-    transform: rotate(45deg);
+    left: 50%;
+    top: 50%;
+    transform: translate(-50%, -50%);
+    width: 0.4em;
+    height: 0.4em;
+    border-radius: 50%;
+    background-color: var(--radio_color-on-active, var(--color_on-active));
   }
 
   .radio:focus {

package/src/components/interaction/form/Radio/Radio.stories.tsx

@@ -4,7 +4,6 @@ import { Radio } from './Radio';
 const meta = {
   title: 'Form/Radio',
   component: Radio,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Radio>;
 
 export default meta;
@@ -12,14 +11,15 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = { args: { label: 'Option A', name: 'choice', value: 'a' } };
 export const Selected: Story = { args: { label: 'Selected', name: 'choice2', value: 'b', defaultChecked: true } };
+export const WithDescription: Story = { args: { label: 'Option A', name: 'choice5', value: 'a', description: 'Additional context about this option.' } };
 export const WithError: Story = { args: { label: 'Required', name: 'choice3', value: 'c', error: 'Please select an option' } };
 export const WithHint: Story = { args: { label: 'Option', name: 'choice4', value: 'd', hint: 'Choose carefully' } };
 export const Group: Story = {
   render: () => (
-    <fieldset>
-      <legend>Pick one</legend>
-      <Radio label="Option A" name="group" value="a" />
-      <Radio label="Option B" name="group" value="b" />
+    <fieldset style={{ border: 'none', padding: 0, margin: 0, display: 'flex', flexDirection: 'column', gap: '0.75rem' }}>
+      <legend style={{ fontWeight: 'var(--font_weight--semibold)', marginBottom: '0.5rem' }}>Pick one</legend>
+      <Radio label="Option A" name="group" value="a" description="Short description for option A." />
+      <Radio label="Option B" name="group" value="b" description="Short description for option B." />
       <Radio label="Option C" name="group" value="c" />
     </fieldset>
   ),

package/src/components/interaction/form/Radio/Radio.tsx

@@ -8,12 +8,13 @@ import { cn } from '@boostdev/design-system-foundation';
 interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
   label: string;
   name: string;
+  description?: string;
   error?: string;
   hint?: string;
   className?: string;
 }
 
-export function Radio({ label, name, error, hint, className, ...props }: RadioProps) {
+export function Radio({ label, name, description, error, hint, className, ...props }: RadioProps) {
   const id = name + useId();
   const hintId = id + 'hint';
   const errorId = id + 'error';
@@ -31,7 +32,10 @@ export function Radio({ label, name, error, hint, className, ...props }: RadioPr
           className={cn(css.radio, error && css.radioError)}
           {...props}
         />
-        <Label id={id} label={label} />
+        <div className={css.textWrapper}>
+          <Label id={id} label={label} />
+          {description && <span className={css.description}>{description}</span>}
+        </div>
       </div>
       <Message inputId={id} type="error" message={error} />
       <Message inputId={id} type="hint" message={hint} />

package/src/components/interaction/form/Select/Select.mdx

@@ -0,0 +1,58 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Select.stories';
+
+<Meta of={Stories} />
+
+# Select
+
+Native dropdown for choosing one option from a list. Renders a styled `<select>` element.
+
+## When to use
+- 5+ mutually exclusive options
+- When space is constrained and a radio group would be too tall
+
+## When not to use
+- Fewer than 5 options — prefer `Radio` buttons for better scannability
+- Searchable or async-loaded options — use `Combobox`
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With placeholder
+<Canvas of={Stories.WithPlaceholder} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--select_border-color`</td><td>Border colour</td></tr>
+<tr><td>`--select_color`</td><td>Background colour</td></tr>
+<tr><td>`--select_on-color`</td><td>Text colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Native `<select>` — keyboard, screen reader, and mobile support built-in
+- Label always associated via `id`/`htmlFor`
+- Error message linked via `aria-describedby`

package/src/components/interaction/form/Select/Select.stories.tsx

@@ -11,7 +11,6 @@ const options = [
 const meta = {
   title: 'Form/Select',
   component: Select,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Select>;
 
 export default meta;