@boostdev/design-system-components 1.2.0 → 1.2.2

package/src/web-components/ui/BdsBreadcrumb.mdx

@@ -5,7 +5,7 @@ import * as Stories from './BdsBreadcrumb.stories';
 
 # <bds-breadcrumb>
 
-Framework-agnostic Breadcrumb navigation custom element. Renders an ordered list of links showing the user's location in the site hierarchy.
+Framework-agnostic Breadcrumb custom element. Renders a horizontal navigation trail from a JSON array of `{ label, href? }` items. The last item is treated as the current page and rendered without a link.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,16 +15,21 @@ Framework-agnostic Breadcrumb navigation custom element. Renders an ordered list
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- On pages more than one level deep in a hierarchy to help users understand their location
+- Always include a link back to the root/home as the first item
+
 ## Examples
 
-### Default (3 levels)
+### Default
 <Canvas of={Stories.Default} />
 
-### Deep nested
-<Canvas of={Stories.DeepNested} />
+### Short (two levels)
+<Canvas of={Stories.Short} />
 
-### All variants
-<Canvas of={Stories.AllVariants} />
+### Long (five levels)
+<Canvas of={Stories.Long} />
 
 ## Props
 
@@ -34,30 +39,28 @@ import '@boostdev/components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `items` | JSON string | `"[]"` | Array of `{ label: string, href?: string }` objects. The last item is the current page (no link). |
+| `items` | `Array<{ label: string; href?: string }>` | `[]` | Breadcrumb items as a JSON-serialisable array. The last item is always the current page. |
 
 ## Usage in plain HTML
 
 ```html
-<bds-breadcrumb items='[
-  {"label":"Home","href":"/"},
-  {"label":"Products","href":"/products"},
-  {"label":"Detail"}
-]'></bds-breadcrumb>
+<bds-breadcrumb
+  items='[{"label":"Home","href":"/"},{"label":"Products","href":"/products"},{"label":"Item"}]'>
+</bds-breadcrumb>
 ```
 
-In JavaScript:
+Or set the property in JavaScript:
+
 ```js
-const crumb = document.querySelector('bds-breadcrumb');
-crumb.items = [
+document.querySelector('bds-breadcrumb').items = [
   { label: 'Home', href: '/' },
   { label: 'Products', href: '/products' },
-  { label: 'Detail' },
+  { label: 'Item' },
 ];
 ```
 
 ## Accessibility
 
-- Renders as `<nav aria-label="Breadcrumb">` with an `<ol>` list
-- The last item gets `aria-current="page"` — it is not a link
-- Separators (`›`) are hidden from screen readers with `aria-hidden="true"`
+- Wrapped in `<nav aria-label="Breadcrumb">` with an `<ol>` list structure
+- The current page item carries `aria-current="page"`
+- Separator characters are `aria-hidden="true"` to avoid screen reader noise

package/src/web-components/ui/BdsBreadcrumb.stories.tsx

@@ -1,17 +1,17 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import type { BreadcrumbItem } from './bds-breadcrumb';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsBreadcrumb({ items = [] }: { items?: BreadcrumbItem[] }) {
-  return React.createElement('bds-breadcrumb', { items: JSON.stringify(items) });
+  return React.createElement('bds-breadcrumb', { items });
 }
 
 const meta = {
   title: 'Web Components/UI/Breadcrumb',
   component: BdsBreadcrumb,
   tags: ['!stable', 'experimental'],
-  parameters: { layout: 'padded' },
+  parameters: { layout: 'centered' },
 } satisfies Meta<typeof BdsBreadcrumb>;
 
 export default meta;
@@ -22,38 +22,28 @@ export const Default: Story = {
     items: [
       { label: 'Home', href: '/' },
       { label: 'Products', href: '/products' },
-      { label: 'Current page' },
+      { label: 'Item' },
     ],
   },
 };
 
-export const TwoLevels: Story = {
+export const Short: Story = {
   args: {
     items: [
       { label: 'Home', href: '/' },
-      { label: 'Current page' },
+      { label: 'Current Page' },
     ],
   },
 };
 
-export const DeepNested: Story = {
+export const Long: Story = {
   args: {
     items: [
       { label: 'Home', href: '/' },
-      { label: 'Category', href: '/category' },
-      { label: 'Subcategory', href: '/category/sub' },
-      { label: 'Section', href: '/category/sub/section' },
-      { label: 'Current page' },
+      { label: 'Catalogue', href: '/catalogue' },
+      { label: 'Electronics', href: '/catalogue/electronics' },
+      { label: 'Phones', href: '/catalogue/electronics/phones' },
+      { label: 'Smartphone X' },
     ],
   },
 };
-
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
-      <BdsBreadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Current' }]} />
-      <BdsBreadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Products', href: '/products' }, { label: 'Detail' }]} />
-      <BdsBreadcrumb items={[{ label: 'Home', href: '/' }, { label: 'A', href: '/a' }, { label: 'B', href: '/a/b' }, { label: 'C', href: '/a/b/c' }, { label: 'Current' }]} />
-    </div>
-  ),
-};

package/src/web-components/ui/BdsButtonGroup.mdx

@@ -0,0 +1,69 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsButtonGroup.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-button-group&gt;
+
+Framework-agnostic Button Group custom element. Groups related `<bds-button>` elements in a flex container, collapsing adjacent border radii so they read as a single unit.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- Toggle groups (Day / Week / Month), segmented actions, or sets of closely related operations
+- Use `orientation="vertical"` for stacked navigation menus
+
+## Examples
+
+### Default (horizontal)
+<Canvas of={Stories.Default} />
+
+### Horizontal
+<Canvas of={Stories.Horizontal} />
+
+### Vertical
+<Canvas of={Stories.Vertical} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Flex direction of the group |
+| `aria-label` | string | — | Accessible label for the group container |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | `<bds-button>` elements |
+
+## Usage in plain HTML
+
+```html
+<bds-button-group aria-label="View options">
+  <bds-button>Day</bds-button>
+  <bds-button>Week</bds-button>
+  <bds-button>Month</bds-button>
+</bds-button-group>
+
+<bds-button-group orientation="vertical" aria-label="Navigation">
+  <bds-button>Profile</bds-button>
+  <bds-button>Settings</bds-button>
+</bds-button-group>
+```
+
+## Accessibility
+
+- Renders a `<div role="group">` with the provided `aria-label`
+- Always set `aria-label` to describe the purpose of the group

package/src/web-components/ui/BdsButtonGroup.stories.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { ButtonGroupOrientation } from './bds-button-group';
+import '../index'; // auto-registers all custom elements
+
+function BdsButtonGroup({
+  orientation = 'horizontal',
+  ariaLabel,
+  children,
+}: {
+  orientation?: ButtonGroupOrientation;
+  ariaLabel?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-button-group',
+    { orientation, 'aria-label': ariaLabel },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/UI/ButtonGroup',
+  component: BdsButtonGroup,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    orientation: { control: 'radio', options: ['horizontal', 'vertical'] },
+    ariaLabel: { control: 'text' },
+  },
+} satisfies Meta<typeof BdsButtonGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () =>
+    React.createElement(
+      'bds-button-group',
+      { 'aria-label': 'View options' },
+      React.createElement('bds-button', null, 'Day'),
+      React.createElement('bds-button', null, 'Week'),
+      React.createElement('bds-button', null, 'Month'),
+    ),
+};
+
+export const Horizontal: Story = {
+  render: () =>
+    React.createElement(
+      'bds-button-group',
+      { orientation: 'horizontal', 'aria-label': 'Actions' },
+      React.createElement('bds-button', null, 'Save'),
+      React.createElement('bds-button', { variant: 'ghost' }, 'Cancel'),
+    ),
+};
+
+export const Vertical: Story = {
+  render: () =>
+    React.createElement(
+      'bds-button-group',
+      { orientation: 'vertical', 'aria-label': 'Navigation' },
+      React.createElement('bds-button', null, 'Profile'),
+      React.createElement('bds-button', null, 'Settings'),
+      React.createElement('bds-button', null, 'Logout'),
+    ),
+};

package/src/web-components/ui/BdsCalendar.mdx

@@ -0,0 +1,93 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCalendar.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-calendar&gt;
+
+Framework-agnostic Calendar date picker custom element. Renders a keyboard-navigable month grid for selecting a date. 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
+
+- Date selection fields in forms where a visual calendar grid aids comprehension
+- Pair with `min`/`max` to restrict selectable dates to a valid range
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With preselected value
+<Canvas of={Stories.WithValue} />
+
+### With min/max range
+<Canvas of={Stories.WithMinMax} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+### Inside a form
+<Canvas of={Stories.FormField} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | string | — | Form field name — required to participate in form submission |
+| `value` | string | — | Selected date in ISO 8601 format (`YYYY-MM-DD`) |
+| `min` | string | — | Minimum selectable date (ISO 8601) |
+| `max` | string | — | Maximum selectable date (ISO 8601) |
+| `disabled` | boolean | `false` | Disables all interaction |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `bds-date-select` | `{ date: string }` | Fired when the user selects a date; `date` is in `YYYY-MM-DD` format |
+
+## Usage in plain HTML
+
+```html
+<bds-calendar name="birthday" value="2026-04-15"></bds-calendar>
+
+<!-- With constraints -->
+<bds-calendar name="departure" min="2026-04-01" max="2026-12-31"></bds-calendar>
+
+<script>
+  document.querySelector('bds-calendar')
+    .addEventListener('bds-date-select', e => {
+      console.log('Selected date:', e.detail.date);
+    });
+</script>
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Arrow keys | Move focus between days |
+| Home | Move to start of week |
+| End | Move to end of week |
+| Page Up | Navigate to previous month |
+| Page Down | Navigate to next month |
+| Enter / Space | Select focused date |
+
+## Accessibility
+
+- Uses the ARIA grid pattern with `role="grid"` and `role="gridcell"` on day buttons
+- The month/year label uses `aria-live="polite"` for screen reader announcements on navigation
+- Each day carries `aria-selected` and `aria-current="date"` (today)
+- Disabled days carry `aria-disabled="true"` and are not focusable
+- Respects the `disabled` attribute at the host level

package/src/web-components/ui/BdsCalendar.stories.tsx

@@ -0,0 +1,63 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsCalendar({
+  name,
+  value,
+  min,
+  max,
+  disabled,
+}: {
+  name?: string;
+  value?: string;
+  min?: string;
+  max?: string;
+  disabled?: boolean;
+}) {
+  return React.createElement('bds-calendar', {
+    name,
+    value,
+    min,
+    max,
+    disabled: disabled || undefined,
+  });
+}
+
+const meta = {
+  title: 'Web Components/UI/Calendar',
+  component: BdsCalendar,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    value:    { control: 'text' },
+    min:      { control: 'text' },
+    max:      { control: 'text' },
+    disabled: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsCalendar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: {} };
+export const WithValue: Story = { args: { value: '2026-04-15' } };
+export const WithMinMax: Story = {
+  args: { value: '2026-04-10', min: '2026-04-05', max: '2026-04-25' },
+};
+export const Disabled: Story = { args: { value: '2026-04-10', disabled: true } };
+export const FormField: Story = {
+  render: () => (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        const data = new FormData(e.currentTarget);
+        alert(`Selected: ${data.get('birthday') ?? 'none'}`);
+      }}
+      style={{ display: 'flex', flexDirection: 'column', gap: 16, alignItems: 'flex-start' }}
+    >
+      {React.createElement('bds-calendar', { name: 'birthday' })}
+      <button type="submit">Submit</button>
+    </form>
+  ),
+};

package/src/web-components/ui/BdsCard.mdx

@@ -5,7 +5,7 @@ import * as Stories from './BdsCard.stories';
 
 # <bds-card>
 
-Framework-agnostic Card layout element. Groups related content in a contained surface with optional elevation or outline. Can be made clickable.
+Framework-agnostic Card layout custom element. A versatile container with three visual variants, configurable padding, text alignment, and an optional clickable mode.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,13 +15,27 @@ Framework-agnostic Card layout element. Groups related content in a contained su
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- Grouping related content visually (product listings, dashboard widgets, feature summaries)
+- Use `clickable` to turn the entire card into an interactive button (e.g. navigation tiles)
+
 ## Examples
 
 ### All variants
 <Canvas of={Stories.AllVariants} />
 
+### Default
+<Canvas of={Stories.Default} />
+
+### Elevated
+<Canvas of={Stories.Elevated} />
+
+### Outlined
+<Canvas of={Stories.Outlined} />
+
 ### Clickable
-<Canvas of={Stories.Interactive} />
+<Canvas of={Stories.Clickable} />
 
 ## Props
 
@@ -31,11 +45,11 @@ import '@boostdev/components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `variant` | `"default" \| "elevated" \| "outlined"` | `"default"` | Visual style |
-| `padding` | `"none" \| "small" \| "medium" \| "large"` | `"medium"` | Internal spacing |
-| `text-align` | `"start" \| "center" \| "end"` | `"start"` | Content alignment |
-| `clickable` | boolean | `false` | Renders as `<button>`, adds hover/active effects |
-| `aria-label` | string | — | Accessible label (required when `clickable` and the card content is not descriptive enough) |
+| `variant` | `"default" \| "elevated" \| "outlined"` | `"default"` | Shadow and border style |
+| `padding` | `"none" \| "small" \| "medium" \| "large"` | `"medium"` | Inner padding |
+| `text-align` | `"start" \| "center" \| "end"` | `"start"` | Text alignment |
+| `clickable` | boolean | `false` | Renders the card as a `<button>` with hover/active effects |
+| `aria-label` | string | — | Accessible label (recommended when `clickable` is set) |
 
 ## Slots
 
@@ -45,39 +59,30 @@ import '@boostdev/components/web-components';
 
 ## Events
 
-| Event | Detail | Bubbles | Composed | Description |
-|-------|--------|---------|----------|-------------|
-| `bds-click` | — | Yes | Yes | Fired when a clickable card is activated |
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `bds-click` | — | Fired when the card button is clicked (only when `clickable` is set) |
 
 ## CSS Custom Properties
 
 | Property | Description |
 |----------|-------------|
 | `--card_color` | Card background colour |
-| `--card_on-color` | Card text colour |
+| `--card_on-color` | Card text/foreground colour |
 
 ## Usage in plain HTML
 
 ```html
 <bds-card variant="elevated" padding="large">
-  <h3>Card title</h3>
-  <p>Card body text.</p>
+  <p>Card content</p>
 </bds-card>
 
-<bds-card clickable aria-label="View product details">
-  <strong>Clickable card</strong>
+<bds-card clickable aria-label="Open details">
+  <p>Clickable card</p>
 </bds-card>
 ```
 
-Listen for click:
-```js
-document.querySelector('bds-card[clickable]').addEventListener('bds-click', () => {
-  console.log('card clicked');
-});
-```
-
 ## Accessibility
 
-- Non-clickable cards are `<div>` elements — they have no interactive role
-- Clickable cards render as `<button>` with keyboard and pointer support
-- Always provide `aria-label` on clickable cards when the text content alone is not descriptive
+- Static cards render as `<div>`; clickable cards render as `<button type="button">`
+- Always provide `aria-label` on clickable cards to give a meaningful accessible name

package/src/web-components/ui/BdsCard.stories.tsx

@@ -1,15 +1,14 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import type { CardVariant, CardPadding, CardTextAlign } from './bds-card';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsCard({
-  variant,
-  padding,
-  textAlign,
+  variant = 'default',
+  padding = 'medium',
+  textAlign = 'start',
   clickable,
   ariaLabel,
-  onClick,
   children,
 }: {
   variant?: CardVariant;
@@ -17,7 +16,6 @@ function BdsCard({
   textAlign?: CardTextAlign;
   clickable?: boolean;
   ariaLabel?: string;
-  onClick?: () => void;
   children?: React.ReactNode;
 }) {
   return React.createElement(
@@ -28,7 +26,6 @@ function BdsCard({
       'text-align': textAlign,
       clickable: clickable || undefined,
       'aria-label': ariaLabel,
-      onbdsclick: onClick,
     },
     children,
   );
@@ -40,51 +37,31 @@ const meta = {
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
-    variant: { control: 'select', options: ['default', 'elevated', 'outlined'] },
-    padding: { control: 'select', options: ['none', 'small', 'medium', 'large'] },
+    variant:   { control: 'select', options: ['default', 'elevated', 'outlined'] },
+    padding:   { control: 'select', options: ['none', 'small', 'medium', 'large'] },
     textAlign: { control: 'select', options: ['start', 'center', 'end'] },
+    clickable: { control: 'boolean' },
   },
 } satisfies Meta<typeof BdsCard>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-const cardContent = React.createElement(
-  'div',
-  null,
-  React.createElement('strong', null, 'Card title'),
-  React.createElement('p', { style: { margin: '8px 0 0' } }, 'Card body with some descriptive text.'),
-);
-
-export const Default: Story = { args: { variant: 'default', children: cardContent } };
-export const Elevated: Story = { args: { variant: 'elevated', children: cardContent } };
-export const Outlined: Story = { args: { variant: 'outlined', children: cardContent } };
-export const Clickable: Story = { args: { variant: 'default', clickable: true, ariaLabel: 'Open details', children: cardContent } };
+export const Default: Story = { args: { variant: 'default', padding: 'medium', children: 'Card content goes here.' } };
+export const Elevated: Story = { args: { variant: 'elevated', padding: 'medium', children: 'Elevated card.' } };
+export const Outlined: Story = { args: { variant: 'outlined', padding: 'medium', children: 'Outlined card.' } };
+export const Clickable: Story = {
+  args: { variant: 'default', padding: 'medium', clickable: true, ariaLabel: 'Open details', children: 'Clickable card — hover me.' },
+};
 
 export const AllVariants: Story = {
   render: () => (
-    <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
-      {(['default', 'elevated', 'outlined'] as const).map(v => (
-        <BdsCard key={v} variant={v} style={{ width: '200px' } as React.CSSProperties}>
-          <strong>{v}</strong>
-          <p style={{ margin: '8px 0 0' }}>Card variant</p>
-        </BdsCard>
-      ))}
+    <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap', maxWidth: 600 }}>
+      {(['default', 'elevated', 'outlined'] as const).map(v =>
+        React.createElement('bds-card', { key: v, variant: v, padding: 'medium', style: 'width: 160px' },
+          React.createElement('p', { style: 'margin: 0' }, v),
+        ),
+      )}
     </div>
   ),
 };
-
-export const Interactive: Story = {
-  render: () => {
-    const [count, setCount] = React.useState(0);
-    return (
-      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '16px' }}>
-        <BdsCard variant="elevated" clickable ariaLabel="Click me" onClick={() => setCount(c => c + 1)}>
-          <strong>Clickable card</strong>
-          <p style={{ margin: '8px 0 0' }}>Click to increment counter</p>
-        </BdsCard>
-        <p style={{ margin: 0 }}>Clicked {count} times</p>
-      </div>
-    );
-  },
-};