@boostdev/design-system-components 0.1.13 → 0.1.15

package/src/components/ui/Avatar/Avatar.mdx

@@ -0,0 +1,53 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Avatar.stories';
+
+<Meta of={Stories} />
+
+# Avatar
+
+Circular user representation. Displays a profile image when available, falling back to initials derived from `name`, then a generic placeholder.
+
+## When to use
+- User identity in comments, messages, or list items
+- Profile headers
+
+## Examples
+
+### With image
+<Canvas of={Stories.WithImage} />
+
+### With initials
+<Canvas of={Stories.WithInitials} />
+
+### All sizes
+<Canvas of={Stories.AllSizes} />
+
+### Single name (one initial)
+<Canvas of={Stories.SingleName} />
+
+### No name fallback
+<Canvas of={Stories.NoName} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--avatar_color`</td><td>Background colour for initials fallback</td></tr>
+<tr><td>`--avatar_on-color`</td><td>Text colour for initials</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Always provide a meaningful `alt` when passing `src`
+- When no image is shown, `aria-label` is derived from `name` to describe the avatar to screen readers
+- Touch target meets 44×44px minimum at `medium` size and above

package/src/components/ui/Avatar/Avatar.module.css

@@ -1,22 +1,18 @@
 @layer component {
   .avatar {
-    --avatar_size:   3em;
-    --avatar_bg:     var(--color_blue);
-    --avatar_text:   var(--color_on-blue);
-
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    width: var(--avatar_size);
-    height: var(--avatar_size);
+    width: var(--avatar_size, 3em);
+    height: var(--avatar_size, 3em);
     border-radius: 50%;
     overflow: hidden;
     flex-shrink: 0;
   }
 
   .avatar.--fallback {
-    background-color: var(--avatar_bg);
-    color: var(--avatar_text);
+    background-color: var(--avatar_bg, var(--color_blue));
+    color: var(--avatar_text, var(--color_on-blue));
     font-weight: var(--font_weight--semibold);
   }
 

package/src/components/ui/Avatar/Avatar.stories.tsx

@@ -4,7 +4,6 @@ import { Avatar } from './Avatar';
 const meta = {
   title: 'UI/Avatar',
   component: Avatar,
-  tags: ['autodocs'],
   argTypes: {
     size: { control: 'radio', options: ['small', 'medium', 'large'] },
   },

package/src/components/ui/Badge/Badge.mdx

@@ -0,0 +1,62 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Badge.stories';
+
+<Meta of={Stories} />
+
+# Badge
+
+Compact inline label for status, category, or count. Renders a `<span>` with a semantic variant colour.
+
+## When to use
+- Highlight status on a record (active, error, draft)
+- Show a count alongside a navigation item
+- Label items in a list by category
+
+## When not to use
+- As a call-to-action — use `Button` instead
+- For long text — badges are single words or short phrases
+
+## Examples
+
+### Variants
+<Canvas of={Stories.AllVariants} />
+
+### Primary
+<Canvas of={Stories.Primary} />
+
+### Secondary
+<Canvas of={Stories.Secondary} />
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Error
+<Canvas of={Stories.Error} />
+
+### Warning
+<Canvas of={Stories.Warning} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+Override these on a parent element to customise the badge without touching global tokens:
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--badge_color`</td><td>`var(--color_cta--subtle)`</td><td>Background colour</td></tr>
+<tr><td>`--badge_on-color`</td><td>`var(--color_on-cta--subtle)`</td><td>Text colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Renders as `<span>` — purely decorative/informational, no interactive role
+- Ensure the badge text is meaningful without surrounding context, or supplement it with a visually-hidden description for screen readers

package/src/components/ui/Badge/Badge.module.css

@@ -1,22 +1,16 @@
 @layer component {
   .badge {
-    /* Component tokens — override from a parent context or inline style */
-    --badge_bg:        var(--color_blue);
-    --badge_text:      var(--color_on-blue);
-    --badge_radius:    2em;
-    --badge_font-size: var(--font_size--body--s);
-
     display: inline-flex;
     align-items: center;
     justify-content: center;
     padding: var(--space_xxs) var(--space_xs);
-    border-radius: var(--badge_radius);
-    font-size: var(--badge_font-size);
+    border-radius: var(--badge_radius, 2em);
+    font-size: var(--badge_font-size, var(--font_size--body--s));
     font-weight: var(--font_weight--semibold);
     line-height: 1;
     white-space: nowrap;
-    background-color: var(--badge_bg);
-    color: var(--badge_text);
+    background-color: var(--badge_bg, var(--color_blue));
+    color: var(--badge_text, var(--color_on-blue));
   }
 
   .--variant_primary {

package/src/components/ui/Badge/Badge.stories.tsx

@@ -4,7 +4,6 @@ import { Badge } from './Badge';
 const meta = {
   title: 'UI/Badge',
   component: Badge,
-  tags: ['autodocs'],
   argTypes: {
     variant: { control: 'select', options: ['primary', 'secondary', 'success', 'error', 'warning'] },
   },

package/src/components/ui/Breadcrumb/Breadcrumb.mdx

@@ -0,0 +1,36 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Breadcrumb.stories';
+
+<Meta of={Stories} />
+
+# Breadcrumb
+
+Hierarchical navigation trail showing the user's location within the site structure.
+
+## When to use
+- Multi-level site structures (3+ levels deep)
+- Pages where users may arrive directly and benefit from context
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Single level
+<Canvas of={Stories.SingleLevel} />
+
+### Two levels
+<Canvas of={Stories.TwoLevels} />
+
+### Deep nested
+<Canvas of={Stories.DeepNested} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Wraps in `<nav aria-label="Breadcrumb">`
+- The current page item has `aria-current="page"`
+- Separator glyphs are `aria-hidden="true"`

package/src/components/ui/Breadcrumb/Breadcrumb.stories.tsx

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

package/src/components/ui/Calendar/Calendar.mdx

@@ -0,0 +1,34 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Calendar.stories';
+
+<Meta of={Stories} />
+
+# Calendar
+
+Date picker calendar grid. Use standalone or as the popover content inside a date input.
+
+## When to use
+- Date selection in forms where a visual calendar improves comprehension
+- Booking flows, scheduling tools, date range pickers
+
+## Examples
+
+### Default (uncontrolled)
+<Canvas of={Stories.Default} />
+
+### With default value
+<Canvas of={Stories.WithDefaultValue} />
+
+### With min/max constraints
+<Canvas of={Stories.WithMinMax} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Grid uses `role="grid"` with `role="gridcell"` for each day
+- Selected date has `aria-selected="true"`; disabled dates have `aria-disabled="true"`
+- Month navigation buttons have descriptive `aria-label` values
+- Arrow keys move focus within the grid; `Enter`/`Space` select a date

package/src/components/ui/Calendar/Calendar.stories.tsx

@@ -5,7 +5,6 @@ import { Calendar } from './Calendar';
 const meta = {
   title: 'UI/Calendar',
   component: Calendar,
-  tags: ['autodocs'],
   decorators: [
     Story => (
       <div style={{ display: 'flex', justifyContent: 'center', padding: '2rem' }}>

package/src/components/ui/Carousel/Carousel.mdx

@@ -0,0 +1,31 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Carousel.stories';
+
+<Meta of={Stories} />
+
+# Carousel
+
+Horizontally scrollable slide container with previous/next navigation.
+
+## When to use
+- Image galleries, featured content, or step-by-step flows where all items share equal priority
+- When screen space is limited and items benefit from a browse interaction
+
+## When not to use
+- Critical content — most users do not interact with carousels; place key content outside
+- More than 5–6 slides — consider a grid or tabbed layout
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Prev/next buttons have `aria-label="Previous"` / `"Next"`
+- The slide container has `aria-live="polite"` to announce slide changes
+- Fully keyboard navigable: buttons receive focus, slides are accessible via arrow keys

package/src/components/ui/Carousel/Carousel.stories.tsx

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

package/src/components/ui/Collapsible/Collapsible.mdx

@@ -0,0 +1,59 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Collapsible.stories';
+
+<Meta of={Stories} />
+
+# Collapsible
+
+Disclosure widget that shows or hides content. Built on the native `<details>`/`<summary>` HTML elements — no JavaScript required for basic toggle behaviour.
+
+## When to use
+- A single section of content that users may or may not need (FAQs, help text, optional details)
+- When you want progressive disclosure without routing to a new page
+
+## When not to use
+- Multiple interrelated sections with complex state — use `Accordion` instead
+- Navigation or tabbed views — use `Tabs`
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Starts open
+<Canvas of={Stories.DefaultOpen} />
+
+### Grouped (accordion behaviour)
+Use the `name` prop to link multiple Collapsibles so only one can be open at a time — this uses the native `<details name="…">` attribute.
+<Canvas of={Stories.Group} />
+
+### Rich summary content
+<Canvas of={Stories.RichSummary} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--collapsible_border-color`</td><td>`var(--color_bg--subtle)`</td><td>Border and separator colour</td></tr>
+<tr><td>`--collapsible_border-width`</td><td>`1px`</td><td>Border and separator width</td></tr>
+<tr><td>`--collapsible_border-radius`</td><td>`var(--border_radius--m)`</td><td>Corner radius</td></tr>
+<tr><td>`--collapsible_bg`</td><td>`var(--color_bg)`</td><td>Summary background</td></tr>
+<tr><td>`--collapsible_bg--hover`</td><td>`var(--color_bg--subtle)`</td><td>Summary background on hover</td></tr>
+<tr><td>`--collapsible_color`</td><td>`var(--color_on-bg)`</td><td>Summary text colour</td></tr>
+<tr><td>`--collapsible_on-color`</td><td>`var(--color_on-bg)`</td><td>Content text colour</td></tr>
+</tbody>
+</table>
+
+## Accessibility
+
+- Uses semantic `<details>`/`<summary>` — the browser applies `role="group"` implicitly
+- Keyboard: `Enter` or `Space` on the focused summary toggles the panel
+- Arrow keys do **not** move between grouped Collapsibles (unlike `Accordion`); use `Tab` to navigate
+- No `aria-expanded` needed — the native element communicates state to screen readers

package/src/components/ui/Collapsible/Collapsible.module.css

@@ -0,0 +1,76 @@
+@layer component {
+  .collapsible {
+    border: var(--collapsible_border-width, 1px) solid var(--collapsible_border-color, var(--color_bg--subtle));
+    border-radius: var(--collapsible_border-radius, var(--border_radius--m));
+    overflow: hidden;
+  }
+
+  .summary {
+    list-style: none; /* removes native disclosure triangle */
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space_m);
+    padding: var(--space_m);
+    cursor: pointer;
+    font-weight: var(--font_weight--semibold);
+    font-size: var(--font_size--body);
+    color: var(--collapsible_color, var(--color_on-bg));
+    background-color: var(--collapsible_bg, var(--color_bg));
+    user-select: none;
+    transition: var(--animation_transition);
+  }
+
+  /* Remove WebKit disclosure triangle */
+  .summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .summary:focus-visible {
+    outline: var(--outline_default);
+    outline-offset: calc(var(--outline_offset) * -1);
+  }
+
+  @media (hover: hover) and (pointer: fine) {
+    .summary:hover {
+      background-color: var(--collapsible_bg--hover, var(--color_bg--subtle));
+    }
+  }
+
+  /* Separator when open */
+  .collapsible[open] > .summary {
+    border-block-end: var(--collapsible_border-width, 1px) solid var(--collapsible_border-color, var(--color_bg--subtle));
+  }
+
+  .summaryContent {
+    flex: 1;
+  }
+
+  /* Chevron drawn with CSS borders */
+  .icon {
+    width: 0.5rem;
+    height: 0.5rem;
+    border-right: 2px solid currentcolor;
+    border-bottom: 2px solid currentcolor;
+    transform: rotate(45deg);
+    flex-shrink: 0;
+    transition: transform var(--animation_transition-duration) var(--animation_easing);
+  }
+
+  .collapsible[open] > .summary .icon {
+    transform: rotate(-135deg);
+  }
+
+  .content {
+    padding: var(--space_m);
+    color: var(--collapsible_on-color, var(--color_on-bg));
+    font-size: var(--font_size--body);
+    line-height: var(--font_line-height--body);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .icon {
+      transition: none;
+    }
+  }
+}

package/src/components/ui/Collapsible/Collapsible.spec.tsx

@@ -0,0 +1,75 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Collapsible } from './Collapsible';
+
+describe('Collapsible', () => {
+  it('renders summary text', () => {
+    render(<Collapsible summary="Toggle me">Content</Collapsible>);
+    expect(screen.getByText('Toggle me')).toBeInTheDocument();
+  });
+
+  it('hides content by default', () => {
+    render(<Collapsible summary="Toggle">Hidden content</Collapsible>);
+    expect(screen.getByRole('group')).not.toHaveAttribute('open');
+  });
+
+  it('shows content when defaultOpen is true', () => {
+    render(<Collapsible summary="Toggle" defaultOpen>Visible content</Collapsible>);
+    expect(screen.getByRole('group')).toHaveAttribute('open');
+  });
+
+  it('expands on summary click', async () => {
+    const user = userEvent.setup();
+    render(<Collapsible summary="Toggle">Content</Collapsible>);
+    const details = screen.getByRole('group');
+    expect(details).not.toHaveAttribute('open');
+    await user.click(screen.getByText('Toggle'));
+    expect(details).toHaveAttribute('open');
+  });
+
+  it('collapses on second click', async () => {
+    const user = userEvent.setup();
+    render(<Collapsible summary="Toggle" defaultOpen>Content</Collapsible>);
+    const details = screen.getByRole('group');
+    await user.click(screen.getByText('Toggle'));
+    expect(details).not.toHaveAttribute('open');
+  });
+
+  it('calls onToggle with new open state when expanded', async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<Collapsible summary="Toggle" onToggle={onToggle}>Content</Collapsible>);
+    await user.click(screen.getByText('Toggle'));
+    expect(onToggle).toHaveBeenCalledWith(true);
+  });
+
+  it('calls onToggle with false when collapsed', async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<Collapsible summary="Toggle" defaultOpen onToggle={onToggle}>Content</Collapsible>);
+    await user.click(screen.getByText('Toggle'));
+    expect(onToggle).toHaveBeenCalledWith(false);
+  });
+
+  it('respects controlled open prop', () => {
+    render(<Collapsible summary="Toggle" open>Content</Collapsible>);
+    expect(screen.getByRole('group')).toHaveAttribute('open');
+  });
+
+  it('renders with name attribute for grouping', () => {
+    render(
+      <>
+        <Collapsible summary="A" name="group">Content A</Collapsible>
+        <Collapsible summary="B" name="group">Content B</Collapsible>
+      </>,
+    );
+    const groups = screen.getAllByRole('group');
+    expect(groups[0]).toHaveAttribute('name', 'group');
+    expect(groups[1]).toHaveAttribute('name', 'group');
+  });
+
+  it('accepts className', () => {
+    render(<Collapsible summary="Toggle" className="custom">Content</Collapsible>);
+    expect(screen.getByRole('group')).toHaveClass('custom');
+  });
+});

package/src/components/ui/Collapsible/Collapsible.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Collapsible } from './Collapsible';
+
+const meta = {
+  title: 'UI/Collapsible',
+  component: Collapsible,
+} satisfies Meta<typeof Collapsible>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    summary: 'What is the return policy?',
+    children: 'You can return any item within 30 days of purchase for a full refund.',
+  },
+};
+
+export const DefaultOpen: Story = {
+  args: {
+    summary: 'Expanded by default',
+    children: 'This panel starts open. Click the summary to collapse it.',
+    defaultOpen: true,
+  },
+};
+
+export const Group: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem', maxWidth: '480px' }}>
+      <Collapsible name="faq" summary="What is your return policy?">
+        You can return any item within 30 days of purchase for a full refund.
+      </Collapsible>
+      <Collapsible name="faq" summary="How long does shipping take?" defaultOpen>
+        Standard shipping takes 3–5 business days. Express shipping is available at checkout.
+      </Collapsible>
+      <Collapsible name="faq" summary="Do you ship internationally?">
+        Yes, we ship to over 50 countries. International shipping times vary by destination.
+      </Collapsible>
+    </div>
+  ),
+};
+
+export const RichSummary: Story = {
+  args: {
+    summary: (
+      <span style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+        <strong>Advanced settings</strong>
+        <span style={{ fontSize: '0.75rem', opacity: 0.6 }}>optional</span>
+      </span>
+    ),
+    children: (
+      <p style={{ margin: 0 }}>
+        Configure advanced options here. These settings are optional and have sensible defaults.
+      </p>
+    ),
+  },
+};

package/src/components/ui/Collapsible/Collapsible.tsx

@@ -0,0 +1,55 @@
+import { HTMLAttributes, ReactNode, SyntheticEvent } from 'react';
+import css from './Collapsible.module.css';
+import { cn } from '@boostdev/design-system-foundation';
+
+export interface CollapsibleProps extends Omit<HTMLAttributes<HTMLDetailsElement>, 'onToggle'> {
+  /** The trigger label — always visible */
+  summary: ReactNode;
+  /** The content revealed when expanded */
+  children: ReactNode;
+  /** Controlled open state */
+  open?: boolean;
+  /** Uncontrolled initial open state */
+  defaultOpen?: boolean;
+  /** Called after each toggle with the new open state */
+  onToggle?: (open: boolean) => void;
+  /**
+   * Groups multiple Collapsible elements so only one is open at a time
+   * (native <details name="…"> behaviour).
+   */
+  name?: string;
+  className?: string;
+}
+
+export function Collapsible({
+  summary,
+  children,
+  open,
+  defaultOpen,
+  onToggle,
+  name,
+  className,
+  ...rest
+}: Readonly<CollapsibleProps>) {
+  const handleToggle = (e: SyntheticEvent<HTMLDetailsElement>) => {
+    onToggle?.(e.currentTarget.open);
+  };
+
+  return (
+    <details
+      className={cn(css.collapsible, className)}
+      open={open ?? defaultOpen}
+      name={name}
+      onToggle={handleToggle}
+      {...rest}
+    >
+      <summary className={css.summary}>
+        <span className={css.summaryContent}>{summary}</span>
+        <span className={css.icon} aria-hidden="true" />
+      </summary>
+      <div className={css.content}>
+        {children}
+      </div>
+    </details>
+  );
+}

package/src/components/ui/Collapsible/index.ts

@@ -0,0 +1,2 @@
+export { Collapsible } from './Collapsible';
+export type { CollapsibleProps } from './Collapsible';

package/src/components/ui/DescriptionList/DescriptionList.mdx

@@ -0,0 +1,28 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './DescriptionList.stories';
+
+<Meta of={Stories} />
+
+# DescriptionList
+
+Key-value pairs rendered as a semantic `<dl>` element. Supports stacked and inline layouts.
+
+## When to use
+- Product details, order summaries, profile information
+- Any list of labelled values where semantic key-value association matters
+
+## Examples
+
+### Stacked (default)
+<Canvas of={Stories.Stacked} />
+
+### Inline
+<Canvas of={Stories.Inline} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Uses native `<dl>`, `<dt>`, `<dd>` — correct semantics without extra ARIA