@boostdev/design-system-components 1.2.0 → 1.2.1

package/src/web-components/interaction/BdsCollapsible.mdx

@@ -3,44 +3,114 @@ import * as Stories from './BdsCollapsible.stories';
 
 <Meta of={Stories} />
 
-# Collapsible
+# &lt;bds-collapsible&gt;
 
-`<bds-collapsible>` reveals or hides content on demand. Built on native `<details>/<summary>` semantics for built-in accessibility. Set the same `name` on multiple collapsibles to link them — opening one will close the others.
+Framework-agnostic Collapsible custom element. Wraps a native `<details>`/`<summary>` pair for built-in toggle behaviour with design-system styling and a `bds-toggle` event.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+Or in HTML without a bundler:
 
 ```html
-<bds-collapsible>
-  <span slot="summary">Show more</span>
-  <p>Hidden content revealed on click.</p>
-</bds-collapsible>
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
 ```
 
+## When to use
+
+- Revealing secondary content on demand (e.g. "More details", "Advanced options")
+- Standalone expandable sections that are independent of each other
+- When accordion-style coordination is not required
+
+## When not to use
+
+- When multiple related sections need to be coordinated (open one, close others) — use `<bds-accordion>` instead
+- For navigation menus — use a dedicated nav component
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Open by default
+<Canvas of={Stories.Open} />
+
+### Grouped (only one open at a time)
+<Canvas of={Stories.Grouped} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
 ## Attributes
 
-| Attribute | Type      | Default     | Description                                  |
-|-----------|-----------|-------------|----------------------------------------------|
-| `open`    | `boolean` | `false`     | Controls the open/closed state               |
-| `name`    | `string`  | `undefined` | Links collapsibles into a mutually-exclusive group |
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `open` | boolean | `false` | Whether the panel is currently expanded |
+| `name` | string | `""` | Groups collapsibles so only one in a group is open at a time (native `<details name>` behaviour) |
 
 ## Slots
 
-| Slot      | Description                      |
-|-----------|----------------------------------|
-| `summary` | The always-visible clickable label |
-| (default) | The collapsible body content     |
+| Slot | Description |
+|------|-------------|
+| `summary` | The always-visible trigger text |
+| `(default)` | The content revealed when expanded |
 
 ## Events
 
-| Event        | Detail                          | Description                    |
-|--------------|---------------------------------|--------------------------------|
-| `bds-toggle` | `{ open: boolean }`             | Fired when open state changes  |
+| Event | Bubbles | Detail | Description |
+|-------|---------|--------|-------------|
+| `bds-toggle` | Yes | `{ open: boolean }` | Fired when the collapsible opens or closes; `detail.open` reflects the new state |
 
-## Stories
+## Usage in plain HTML
 
-<Canvas of={Stories.Default} />
-<Canvas of={Stories.Grouped} />
+```html
+<bds-collapsible>
+  <span slot="summary">Show details</span>
+  <p>Hidden content revealed on toggle.</p>
+</bds-collapsible>
+
+<!-- Open by default -->
+<bds-collapsible open>
+  <span slot="summary">Open section</span>
+  <p>This is visible immediately.</p>
+</bds-collapsible>
+
+<!-- Grouped: only one open at a time -->
+<bds-collapsible name="faq">
+  <span slot="summary">Question 1</span>
+  <p>Answer 1</p>
+</bds-collapsible>
+<bds-collapsible name="faq">
+  <span slot="summary">Question 2</span>
+  <p>Answer 2</p>
+</bds-collapsible>
+```
 
-## Controls
+## CSS Custom Properties
 
-<ArgTypes of={Stories} />
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--collapsible_bg` | `var(--bds-color_bg)` | Summary (header) background colour |
+| `--collapsible_bg--hover` | `var(--bds-color_bg--subtle)` | Summary background on hover |
+| `--collapsible_content-bg` | `var(--bds-color_bg)` | Content panel background colour |
+| `--collapsible_color` | `var(--bds-color_on-bg)` | Summary text colour |
+| `--collapsible_on-color` | `var(--bds-color_on-bg)` | Content text colour |
+| `--collapsible_border-color` | `var(--bds-color_bg--subtle)` | Border colour |
+| `--collapsible_border-width` | `1px` | Border width |
+| `--collapsible_border-radius` | `var(--bds-border_radius--m)` | Border radius |
+
+## Accessibility
+
+- Built on native `<details>`/`<summary>`, which is keyboard accessible out of the box
+- The `summary` slot element is focusable and responds to Enter/Space
+- Focus outline follows design system tokens
+- Chevron icon is `aria-hidden="true"`
+- `prefers-reduced-motion` disables the chevron transition

package/src/web-components/interaction/BdsCollapsible.stories.tsx

@@ -1,25 +1,24 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
+// Thin React wrapper so Storybook controls work with the custom element's props
 function BdsCollapsible({
-  open,
+  open = false,
   name,
   summary,
   children,
-  onToggle,
 }: {
   open?: boolean;
   name?: string;
   summary?: string;
   children?: React.ReactNode;
-  onToggle?: (e: Event) => void;
 }) {
   return React.createElement(
     'bds-collapsible',
-    { open: open || undefined, name, onbdstoggle: onToggle },
+    { open: open || undefined, name: name || undefined },
     React.createElement('span', { slot: 'summary' }, summary ?? 'Toggle section'),
-    children ?? React.createElement('p', { style: { margin: 0 } }, 'Collapsible content goes here.'),
+    children ?? React.createElement('p', { style: { margin: 0 } }, 'Collapsible panel content.'),
   );
 }
 
@@ -30,58 +29,40 @@ const meta = {
   parameters: { layout: 'padded' },
   argTypes: {
     open: { control: 'boolean' },
+    name: { control: 'text' },
+    summary: { control: 'text' },
   },
 } satisfies Meta<typeof BdsCollapsible>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { summary: 'Show more details' } };
-export const OpenByDefault: Story = { args: { summary: 'Open by default', open: true } };
+export const Default: Story = {
+  args: {
+    summary: 'Show details',
+    open: false,
+  },
+};
 
-export const Grouped: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', maxWidth: '480px' }}>
-      <BdsCollapsible name="faq" summary="What is this component?">
-        <p style={{ margin: 0 }}>A Collapsible reveals or hides content on demand.</p>
-      </BdsCollapsible>
-      <BdsCollapsible name="faq" summary="How does grouping work?">
-        <p style={{ margin: 0 }}>Setting the same `name` on multiple collapsibles links them — opening one closes the others.</p>
-      </BdsCollapsible>
-      <BdsCollapsible name="faq" summary="Is it accessible?">
-        <p style={{ margin: 0 }}>Yes — built on native `&lt;details&gt;/&lt;summary&gt;` semantics.</p>
-      </BdsCollapsible>
-    </div>
-  ),
+export const Open: Story = {
+  args: {
+    summary: 'Open by default',
+    open: true,
+    children: React.createElement('p', { style: { margin: 0 } }, 'This collapsible is open by default via the open attribute.'),
+  },
 };
 
-export const AllVariants: Story = {
+export const Grouped: Story = {
   render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '480px' }}>
-      <BdsCollapsible summary="Closed by default">
-        <p style={{ margin: 0 }}>This starts closed.</p>
-      </BdsCollapsible>
-      <BdsCollapsible summary="Open by default" open>
-        <p style={{ margin: 0 }}>This starts open.</p>
-      </BdsCollapsible>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem', maxWidth: '480px' }}>
+      {(['Section A', 'Section B', 'Section C'] as const).map((label, i) =>
+        React.createElement(
+          'bds-collapsible',
+          { key: label, name: 'group', open: i === 0 ? '' : undefined },
+          React.createElement('span', { slot: 'summary' }, label),
+          React.createElement('p', { style: { margin: 0 } }, `Content for ${label}. Only one section in this group can be open at a time.`),
+        ),
+      )}
     </div>
   ),
 };
-
-export const Interactive: Story = {
-  render: () => {
-    const [isOpen, setIsOpen] = React.useState(false);
-    return (
-      <div style={{ maxWidth: '480px' }}>
-        <p style={{ margin: '0 0 8px', fontSize: '0.875rem' }}>State: {isOpen ? 'open' : 'closed'}</p>
-        <BdsCollapsible
-          summary="Controlled collapsible"
-          open={isOpen}
-          onToggle={(e: Event) => setIsOpen((e as CustomEvent<{ open: boolean }>).detail.open)}
-        >
-          <p style={{ margin: 0 }}>Controlled via React state. The bds-toggle event updates the parent.</p>
-        </BdsCollapsible>
-      </div>
-    );
-  },
-};

package/src/web-components/interaction/BdsDialog.mdx

@@ -3,47 +3,108 @@ import * as Stories from './BdsDialog.stories';
 
 <Meta of={Stories} />
 
-# Dialog
+# &lt;bds-dialog&gt;
 
-`<bds-dialog>` is a modal dialog built on the native `<dialog>` element. It traps focus while open, dismisses on Escape and backdrop click, and restores focus to the trigger element on close. Supports the native Invoker Commands API.
+Framework-agnostic Dialog custom element. Wraps a native `<dialog>` element with `showModal()` / `close()` lifecycle, backdrop-click to dismiss, Escape key handling, Tab focus trapping, and the Invoker Commands API.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-dialog id="my-dialog">
-  <h2>Dialog title</h2>
-  <p>Dialog body content.</p>
-  <button type="button">Close</button>
-</bds-dialog>
+## Installation
 
-<!-- Declarative open via Invoker API -->
-<button type="button" commandfor="my-dialog" command="show-modal">Open</button>
+```js
+import '@boostdev/components/web-components';
 ```
 
-## Attributes
+Or in HTML without a bundler:
 
-| Attribute | Type      | Default | Description                 |
-|-----------|-----------|---------|-----------------------------|
-| `open`    | `boolean` | `false` | Controls the open state     |
+```html
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
+```
 
-## Events
+## When to use
 
-| Event       | Description                           |
-|-------------|---------------------------------------|
-| `bds-open`  | Fired when the dialog opens           |
-| `bds-close` | Fired when the dialog closes          |
+- Confirmations that require a decision before continuing
+- Short forms (edit profile, create item) that interrupt the current flow
+- Alerts or notices that must be acknowledged
 
-## Slots
+## When not to use
 
-| Slot      | Description                         |
-|-----------|-------------------------------------|
-| (default) | Dialog content (title, body, actions) |
+- Complex multi-step flows — consider a dedicated page instead
+- Non-blocking panels — use `<bds-drawer>` or `<bds-popover>` instead
+- Displaying lots of scrollable content — prefer a full page or `<bds-drawer>`
 
-## Stories
+## Examples
 
+### Default
 <Canvas of={Stories.Default} />
-<Canvas of={Stories.InvokerAPI} />
 
-## Controls
+### With form content
+<Canvas of={Stories.WithForm} />
+
+### Invoker Commands API
+<Canvas of={Stories.InvokerCommands} />
+
+## Props
 
 <ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `open` | boolean | `false` | Controlled open state — syncs to native `showModal()` / `close()` |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Dialog content |
+
+## Events
+
+| Event | Bubbles | Description |
+|-------|---------|-------------|
+| `bds-open` | Yes | Fired when the dialog opens |
+| `bds-close` | Yes | Fired when the dialog closes (backdrop click, Escape, or close button) |
+
+## Invoker Commands API
+
+Open or close the dialog declaratively using the Invoker Commands API:
+
+```html
+<button commandfor="my-dialog" command="show-modal">Open</button>
+<button commandfor="my-dialog" command="close">Close</button>
+
+<bds-dialog id="my-dialog">
+  <p>Dialog content</p>
+</bds-dialog>
+```
+
+The Invoker Commands API is a native browser feature. For browsers that do not support it yet, use the `open` attribute or JavaScript.
+
+## Usage in plain HTML
+
+```html
+<bds-dialog id="my-dialog">
+  <h2>Confirm deletion</h2>
+  <p>This action cannot be undone.</p>
+  <div>
+    <button onclick="document.getElementById('my-dialog').open = false">Cancel</button>
+    <button>Delete</button>
+  </div>
+</bds-dialog>
+
+<button onclick="document.getElementById('my-dialog').open = true">Delete item</button>
+```
+
+## Accessibility
+
+- Renders a native `<dialog>` element with `aria-modal="true"`
+- Focus is trapped inside the dialog while open (Tab / Shift+Tab cycle)
+- Escape key closes the dialog
+- Clicking the backdrop closes the dialog
+- Focus returns to the triggering element on close
+- A visually positioned close button is provided with `aria-label="Close dialog"`
+- `document.body.overflow` is set to `hidden` while the dialog is open to prevent background scroll

package/src/web-components/interaction/BdsDialog.stories.tsx

@@ -1,75 +1,157 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
+
+// Thin React wrapper for bds-dialog + its trigger button
+function BdsDialog({
+  open,
+  triggerLabel = 'Open dialog',
+  children,
+}: {
+  open?: boolean;
+  triggerLabel?: string;
+  children?: React.ReactNode;
+}) {
+  const id = React.useId();
+  const [isOpen, setIsOpen] = React.useState(open ?? false);
+  const dialogRef = React.useRef<HTMLElement>(null);
+
+  React.useEffect(() => {
+    setIsOpen(open ?? false);
+  }, [open]);
+
+  React.useEffect(() => {
+    const el = dialogRef.current;
+    if (!el) return;
+    const handler = () => setIsOpen(false);
+    el.addEventListener('bds-close', handler);
+    return () => el.removeEventListener('bds-close', handler);
+  }, []);
 
-function DialogDemo({ title = 'Dialog title', withForm = false }: { title?: string; withForm?: boolean }) {
-  const [open, setOpen] = React.useState(false);
   return (
     <div>
-      <button type="button" onClick={() => setOpen(true)}>Open dialog</button>
+      <button
+        type="button"
+        onClick={() => setIsOpen(true)}
+        style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+      >
+        {triggerLabel}
+      </button>
       {React.createElement(
         'bds-dialog',
-        { open: open || undefined, onbdsclose: () => setOpen(false) },
-        React.createElement('h2', { style: { margin: '0 0 12px' } }, title),
-        withForm
-          ? React.createElement(
-              'form',
-              { style: { display: 'flex', flexDirection: 'column', gap: '12px' } },
-              React.createElement('label', null,
-                'Name',
-                React.createElement('input', { type: 'text', placeholder: 'Your name', style: { display: 'block', width: '100%', marginTop: '4px' } }),
-              ),
-              React.createElement('label', null,
-                'Email',
-                React.createElement('input', { type: 'email', placeholder: 'you@example.com', style: { display: 'block', width: '100%', marginTop: '4px' } }),
-              ),
-            )
-          : React.createElement('p', { style: { margin: '0 0 12px' } }, 'This is the dialog body. Press Escape or click the × button to close.'),
-        React.createElement(
-          'div',
-          { style: { display: 'flex', gap: '8px', justifyContent: 'flex-end', marginTop: '12px' } },
-          React.createElement('button', { type: 'button', onClick: () => setOpen(false) }, 'Cancel'),
-          React.createElement('button', { type: 'button', onClick: () => setOpen(false) }, 'Confirm'),
-        ),
+        {
+          id,
+          ref: dialogRef,
+          open: isOpen || undefined,
+        },
+        children ?? React.createElement('p', { style: { margin: 0 } }, 'Dialog content goes here.'),
       )}
     </div>
   );
 }
 
-function BdsDialogStory({ withForm }: { withForm?: boolean }) {
-  return React.createElement(DialogDemo, { withForm });
-}
-
 const meta = {
   title: 'Web Components/Interaction/Dialog',
-  component: BdsDialogStory,
+  component: BdsDialog,
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
-} satisfies Meta<typeof BdsDialogStory>;
+  argTypes: {
+    triggerLabel: { control: 'text' },
+  },
+} satisfies Meta<typeof BdsDialog>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { withForm: false } };
-export const WithForm: Story = { args: { withForm: true } };
+export const Default: Story = {
+  args: { triggerLabel: 'Open dialog' },
+};
+
+function WithFormDialog() {
+  const id = React.useId();
+  const [isOpen, setIsOpen] = React.useState(false);
+  const dialogRef = React.useRef<HTMLElement>(null);
 
-export const InvokerAPI: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '16px' }}>
-      <p style={{ margin: 0, fontSize: '0.875rem', color: '#666' }}>
-        Uses native Invoker Commands API — no JavaScript needed.
-      </p>
-      {React.createElement('button', { type: 'button', commandfor: 'invoker-dialog', command: 'show-modal' }, 'Open via commandfor')}
+  React.useEffect(() => {
+    const el = dialogRef.current;
+    if (!el) return;
+    const handler = () => setIsOpen(false);
+    el.addEventListener('bds-close', handler);
+    return () => el.removeEventListener('bds-close', handler);
+  }, []);
+
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={() => setIsOpen(true)}
+        style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+      >
+        Open form dialog
+      </button>
       {React.createElement(
         'bds-dialog',
-        { id: 'invoker-dialog' },
-        React.createElement('h2', { style: { margin: '0 0 12px' } }, 'Opened via Invoker API'),
-        React.createElement('p', { style: { margin: 0 } }, 'This dialog was opened declaratively using commandfor and command attributes.'),
+        {
+          id,
+          ref: dialogRef,
+          open: isOpen || undefined,
+        },
+        React.createElement(
+          'form',
+          {
+            style: { display: 'flex', flexDirection: 'column', gap: '1rem', minWidth: '280px' },
+            onSubmit: (e: React.FormEvent) => { e.preventDefault(); setIsOpen(false); },
+          },
+          React.createElement('h2', { style: { margin: 0 } }, 'Edit profile'),
+          React.createElement(
+            'label',
+            { style: { display: 'flex', flexDirection: 'column', gap: '0.25rem' } },
+            'Name',
+            React.createElement('input', { type: 'text', defaultValue: 'Jane Doe', style: { padding: '0.5rem' } }),
+          ),
+          React.createElement(
+            'label',
+            { style: { display: 'flex', flexDirection: 'column', gap: '0.25rem' } },
+            'Email',
+            React.createElement('input', { type: 'email', defaultValue: 'jane@example.com', style: { padding: '0.5rem' } }),
+          ),
+          React.createElement(
+            'div',
+            { style: { display: 'flex', gap: '0.5rem', justifyContent: 'flex-end' } },
+            React.createElement('button', { type: 'button', onClick: () => setIsOpen(false) }, 'Cancel'),
+            React.createElement('button', { type: 'submit' }, 'Save'),
+          ),
+        ),
       )}
     </div>
-  ),
+  );
+}
+
+export const WithForm: Story = {
+  render: () => React.createElement(WithFormDialog),
 };
 
-export const AllVariants: Story = {
-  render: () => React.createElement(DialogDemo, { title: 'Confirmation' }),
+export const InvokerCommands: Story = {
+  render: () => {
+    const dialogId = 'story-dialog-invoker';
+    return (
+      <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
+        {React.createElement(
+          'button',
+          { commandFor: dialogId, command: 'show-modal', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
+          'Open with Invoker Command',
+        )}
+        {React.createElement(
+          'bds-dialog',
+          { id: dialogId },
+          React.createElement(
+            'div',
+            { style: { minWidth: '260px' } },
+            React.createElement('h2', { style: { margin: '0 0 0.5rem' } }, 'Invoker Commands'),
+            React.createElement('p', { style: { margin: 0 } }, 'This dialog was opened using the Invoker Commands API (commandfor + command="show-modal").'),
+          ),
+        )}
+      </div>
+    );
+  },
 };