@boostdev/design-system-components 1.2.0 → 1.2.2

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>
+    );
+  },
 };

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

@@ -3,48 +3,106 @@ import * as Stories from './BdsDrawer.stories';
 
 <Meta of={Stories} />
 
-# Drawer
+# &lt;bds-drawer&gt;
 
-`<bds-drawer>` is a slide-in side panel built on the native `<dialog>` element. It uses the same modal infrastructure as `<bds-dialog>` but positions itself at the edge of the viewport. Supports the native Invoker Commands API.
+Framework-agnostic Drawer (slide-in panel) custom element. Same modal infrastructure as `<bds-dialog>` but positioned as a side panel that slides in from either side of the viewport.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
 
-```html
-<bds-drawer id="settings-drawer" side="right">
-  <span slot="title">Settings</span>
-  <p>Drawer body content.</p>
-</bds-drawer>
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+Or in HTML without a bundler:
 
-<!-- Declarative open via Invoker API -->
-<button type="button" commandfor="settings-drawer" command="show-modal">Open settings</button>
+```html
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
 ```
 
+## When to use
+
+- Navigation panels (mobile nav, side menus)
+- Settings or configuration panels that don't interrupt the primary flow
+- Detail views that overlay the current content
+
+## When not to use
+
+- Short confirmations — use `<bds-dialog>` instead
+- Persistent side content that is always visible — use a regular sidebar layout
+
+## Examples
+
+### Default (right side)
+<Canvas of={Stories.Default} />
+
+### Left side
+<Canvas of={Stories.LeftSide} />
+
+### With rich content
+<Canvas of={Stories.WithRichContent} />
+
+### All placements
+<Canvas of={Stories.AllPlacements} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
 ## Attributes
 
-| Attribute | Type                    | Default   | Description                   |
-|-----------|-------------------------|-----------|-------------------------------|
-| `open`    | `boolean`               | `false`   | Controls the open state       |
-| `side`    | `"left" \| "right"`     | `"right"` | Which side the drawer slides in from |
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `open` | boolean | `false` | Controlled open state |
+| `side` | `"left" \| "right"` | `"right"` | Which side the panel slides in from |
 
 ## Slots
 
-| Slot      | Description                      |
-|-----------|----------------------------------|
-| `title`   | Drawer title text in the header  |
-| (default) | Drawer body content              |
+| Slot | Description |
+|------|-------------|
+| `title` | Drawer header title text |
+| `(default)` | Drawer body content |
 
 ## Events
 
-| Event       | Description                     |
-|-------------|---------------------------------|
-| `bds-open`  | Fired when the drawer opens     |
-| `bds-close` | Fired when the drawer closes    |
+| Event | Bubbles | Description |
+|-------|---------|-------------|
+| `bds-open` | Yes | Fired when the drawer opens |
+| `bds-close` | Yes | Fired when the drawer closes (backdrop click, Escape, or close button) |
 
-## Stories
+## Invoker Commands API
 
-<Canvas of={Stories.Right} />
-<Canvas of={Stories.InvokerAPI} />
+Open or close the drawer declaratively using the Invoker Commands API:
 
-## Controls
+```html
+<button commandfor="my-drawer" command="show-modal">Open</button>
+<bds-drawer id="my-drawer" side="right">
+  <span slot="title">Settings</span>
+  <p>Drawer content</p>
+</bds-drawer>
+```
 
-<ArgTypes of={Stories} />
+## Usage in plain HTML
+
+```html
+<bds-drawer id="my-drawer" side="right">
+  <span slot="title">Settings</span>
+  <p>Adjust your preferences here.</p>
+</bds-drawer>
+
+<button onclick="document.getElementById('my-drawer').open = true">Open settings</button>
+```
+
+## Accessibility
+
+- Renders a native `<dialog>` element with `aria-modal="true"`
+- Focus is trapped inside the drawer while open (Tab / Shift+Tab cycle)
+- Escape key closes the drawer
+- Clicking the backdrop closes the drawer
+- Focus returns to the triggering element on close
+- A close button is provided with `aria-label="Close drawer"`
+- `document.body.overflow` is set to `hidden` while the drawer is open
+- Slide-in animation respects `prefers-reduced-motion`