@boostdev/design-system-components 0.1.14 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",

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/index.ts

@@ -6,6 +6,8 @@ export { Avatar } from './components/ui/Avatar';
 export { Badge } from './components/ui/Badge';
 export { Breadcrumb } from './components/ui/Breadcrumb';
 export type { BreadcrumbItem } from './components/ui/Breadcrumb';
+export { Collapsible } from './components/ui/Collapsible';
+export type { CollapsibleProps } from './components/ui/Collapsible';
 export { Calendar } from './components/ui/Calendar';
 export { Carousel } from './components/ui/Carousel';
 export { DescriptionList } from './components/ui/DescriptionList';

package/src/stories/Introduction.mdx

@@ -20,8 +20,8 @@ import {Card} from "../components/layout/Card/index.ts";
             Accessible, token-driven React components. Zero extra runtime.
         </p>
         <ButtonGroup variant="content">
-            <Button variant="secondary" href="https://www.npmjs.com/package/@boostdev/foundation">DS Foundation</Button>
-            <Button variant="secondary" href="https://www.npmjs.com/package/@boostdev/components">DS Components</Button>
+            <Button variant="secondary" href="https://www.npmjs.com/package/@boostdev/design-system-foundation">DS Foundation</Button>
+            <Button variant="secondary" href="https://www.npmjs.com/package/@boostdev/design-system-components">DS Components</Button>
         </ButtonGroup>
     </div>
     ---