@boostdev/design-system-components 1.1.2 → 1.2.1

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

@@ -0,0 +1,49 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { BreadcrumbItem } from './bds-breadcrumb';
+import '../index'; // auto-registers all custom elements
+
+function BdsBreadcrumb({ items = [] }: { items?: BreadcrumbItem[] }) {
+  return React.createElement('bds-breadcrumb', { items });
+}
+
+const meta = {
+  title: 'Web Components/UI/Breadcrumb',
+  component: BdsBreadcrumb,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+} satisfies Meta<typeof BdsBreadcrumb>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Products', href: '/products' },
+      { label: 'Item' },
+    ],
+  },
+};
+
+export const Short: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Current Page' },
+    ],
+  },
+};
+
+export const Long: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Catalogue', href: '/catalogue' },
+      { label: 'Electronics', href: '/catalogue/electronics' },
+      { label: 'Phones', href: '/catalogue/electronics/phones' },
+      { label: 'Smartphone X' },
+    ],
+  },
+};

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

@@ -0,0 +1,88 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCard.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-card&gt;
+
+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.
+
+## Installation
+
+```js
+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.Clickable} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `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
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Card content |
+
+## Events
+
+| 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/foreground colour |
+
+## Usage in plain HTML
+
+```html
+<bds-card variant="elevated" padding="large">
+  <p>Card content</p>
+</bds-card>
+
+<bds-card clickable aria-label="Open details">
+  <p>Clickable card</p>
+</bds-card>
+```
+
+## Accessibility
+
+- 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

@@ -0,0 +1,67 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { CardVariant, CardPadding, CardTextAlign } from './bds-card';
+import '../index'; // auto-registers all custom elements
+
+function BdsCard({
+  variant = 'default',
+  padding = 'medium',
+  textAlign = 'start',
+  clickable,
+  ariaLabel,
+  children,
+}: {
+  variant?: CardVariant;
+  padding?: CardPadding;
+  textAlign?: CardTextAlign;
+  clickable?: boolean;
+  ariaLabel?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-card',
+    {
+      variant,
+      padding,
+      'text-align': textAlign,
+      clickable: clickable || undefined,
+      'aria-label': ariaLabel,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/UI/Card',
+  component: BdsCard,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    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>;
+
+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: 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>
+  ),
+};

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

@@ -0,0 +1,83 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCarousel.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-carousel&gt;
+
+Framework-agnostic Carousel custom element. A scroll-snap based slider where each direct child becomes a slide. Supports dot indicators, looping, and custom previous/next buttons via named slots.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- Cycling through a set of related content cards, images, or feature highlights
+- Use `indicators` to help users understand how many slides exist and which one is active
+- Use `loop` for continuous navigation without boundaries
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With indicators
+<Canvas of={Stories.WithIndicators} />
+
+### Loop
+<Canvas of={Stories.Loop} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `current-index` | number | `0` | Active slide index (0-based) |
+| `indicators` | boolean | `false` | Shows dot indicator buttons below the slides |
+| `loop` | boolean | `false` | Wraps from last slide to first and vice versa |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Slide content — each direct child is one slide |
+| `prev` | Custom previous button (replaces the built-in button) |
+| `next` | Custom next button (replaces the built-in button) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `bds-slide-change` | `{ index: number }` | Fired when the active slide changes |
+
+## Usage in plain HTML
+
+```html
+<bds-carousel indicators loop>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</bds-carousel>
+
+<script>
+  document.querySelector('bds-carousel')
+    .addEventListener('bds-slide-change', e => {
+      console.log('Active slide:', e.detail.index);
+    });
+</script>
+```
+
+## Accessibility
+
+- The slide track has `role="region"` with `aria-label="Carousel"`
+- Dot indicators carry `role="tab"` and `aria-selected`; the indicator list has `role="tablist"`
+- Navigation buttons have descriptive `aria-label` values and are disabled at boundaries (unless `loop` is set)
+- Smooth scroll is suppressed when `prefers-reduced-motion: reduce` is set

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

@@ -0,0 +1,96 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsCarousel({
+  currentIndex = 0,
+  indicators,
+  loop,
+  children,
+}: {
+  currentIndex?: number;
+  indicators?: boolean;
+  loop?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-carousel',
+    {
+      'current-index': currentIndex,
+      indicators: indicators || undefined,
+      loop: loop || undefined,
+    },
+    children,
+  );
+}
+
+const slides = ['Slide 1', 'Slide 2', 'Slide 3'].map(label =>
+  React.createElement(
+    'div',
+    {
+      key: label,
+      style: {
+        background: 'var(--bds-color_bg--subtle, #f3f4f6)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        height: 160,
+        fontSize: '1.25rem',
+        fontWeight: 600,
+        borderRadius: 8,
+      },
+    },
+    label,
+  ),
+);
+
+const meta = {
+  title: 'Web Components/UI/Carousel',
+  component: BdsCarousel,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    currentIndex: { control: 'number' },
+    indicators:   { control: 'boolean' },
+    loop:         { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsCarousel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      {React.createElement(
+        'bds-carousel',
+        {},
+        ...slides,
+      )}
+    </div>
+  ),
+};
+
+export const WithIndicators: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      {React.createElement(
+        'bds-carousel',
+        { indicators: true },
+        ...slides,
+      )}
+    </div>
+  ),
+};
+
+export const Loop: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      {React.createElement(
+        'bds-carousel',
+        { indicators: true, loop: true },
+        ...slides,
+      )}
+    </div>
+  ),
+};