@boostdev/design-system-components 1.1.2 → 1.2.1

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

@@ -0,0 +1,157 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+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);
+  }, []);
+
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={() => setIsOpen(true)}
+        style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+      >
+        {triggerLabel}
+      </button>
+      {React.createElement(
+        'bds-dialog',
+        {
+          id,
+          ref: dialogRef,
+          open: isOpen || undefined,
+        },
+        children ?? React.createElement('p', { style: { margin: 0 } }, 'Dialog content goes here.'),
+      )}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Dialog',
+  component: BdsDialog,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    triggerLabel: { control: 'text' },
+  },
+} satisfies Meta<typeof BdsDialog>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+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);
+
+  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,
+          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 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

@@ -0,0 +1,108 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsDrawer.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-drawer&gt;
+
+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.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+Or in HTML without a bundler:
+
+```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` | Controlled open state |
+| `side` | `"left" \| "right"` | `"right"` | Which side the panel slides in from |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `title` | Drawer header title text |
+| `(default)` | Drawer body content |
+
+## Events
+
+| 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) |
+
+## Invoker Commands API
+
+Open or close the drawer declaratively using the Invoker Commands API:
+
+```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>
+```
+
+## 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`

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

@@ -0,0 +1,196 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { DrawerSide } from './bds-drawer';
+import '../index'; // auto-registers all custom elements
+
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsDrawer({
+  side = 'right',
+  triggerLabel = 'Open drawer',
+  title = 'Drawer',
+  children,
+}: {
+  side?: DrawerSide;
+  triggerLabel?: string;
+  title?: string;
+  children?: React.ReactNode;
+}) {
+  const id = React.useId();
+  const [isOpen, setIsOpen] = React.useState(false);
+  const drawerRef = React.useRef<HTMLElement>(null);
+
+  React.useEffect(() => {
+    const el = drawerRef.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' }}
+      >
+        {triggerLabel}
+      </button>
+      {React.createElement(
+        'bds-drawer',
+        {
+          id,
+          ref: drawerRef,
+          side,
+          open: isOpen || undefined,
+        },
+        React.createElement('span', { slot: 'title' }, title),
+        children ?? React.createElement('p', { style: { margin: 0 } }, 'Drawer body content goes here.'),
+      )}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Drawer',
+  component: BdsDrawer,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    side: { control: 'select', options: ['left', 'right'] },
+    triggerLabel: { control: 'text' },
+    title: { control: 'text' },
+  },
+} satisfies Meta<typeof BdsDrawer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { side: 'right', title: 'Settings', triggerLabel: 'Open drawer' },
+};
+
+export const LeftSide: Story = {
+  args: { side: 'left', title: 'Navigation', triggerLabel: 'Open left drawer' },
+};
+
+function RichDrawer() {
+  const id = React.useId();
+  const [isOpen, setIsOpen] = React.useState(false);
+  const drawerRef = React.useRef<HTMLElement>(null);
+
+  React.useEffect(() => {
+    const el = drawerRef.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 rich drawer
+      </button>
+      {React.createElement(
+        'bds-drawer',
+        {
+          id,
+          ref: drawerRef,
+          side: 'right',
+          open: isOpen || undefined,
+        },
+        React.createElement('span', { slot: 'title' }, 'Edit settings'),
+        React.createElement(
+          'form',
+          {
+            style: { display: 'flex', flexDirection: 'column', gap: '1rem' },
+            onSubmit: (e: React.FormEvent) => { e.preventDefault(); setIsOpen(false); },
+          },
+          React.createElement(
+            'label',
+            { style: { display: 'flex', flexDirection: 'column', gap: '0.25rem' } },
+            'Display name',
+            React.createElement('input', { type: 'text', defaultValue: 'Jane Doe', style: { padding: '0.5rem' } }),
+          ),
+          React.createElement(
+            'label',
+            { style: { display: 'flex', flexDirection: 'column', gap: '0.25rem' } },
+            'Language',
+            React.createElement(
+              'select',
+              { style: { padding: '0.5rem' } },
+              React.createElement('option', null, 'English'),
+              React.createElement('option', null, 'Dutch'),
+              React.createElement('option', null, 'French'),
+            ),
+          ),
+          React.createElement(
+            'button',
+            { type: 'submit', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
+            'Save changes',
+          ),
+        ),
+      )}
+    </div>
+  );
+}
+
+export const WithRichContent: Story = {
+  render: () => React.createElement(RichDrawer),
+};
+
+function AllSides() {
+  const [openSide, setOpenSide] = React.useState<DrawerSide | null>(null);
+  const leftRef = React.useRef<HTMLElement>(null);
+  const rightRef = React.useRef<HTMLElement>(null);
+
+  React.useEffect(() => {
+    const close = () => setOpenSide(null);
+    const left = leftRef.current;
+    const right = rightRef.current;
+    left?.addEventListener('bds-close', close);
+    right?.addEventListener('bds-close', close);
+    return () => {
+      left?.removeEventListener('bds-close', close);
+      right?.removeEventListener('bds-close', close);
+    };
+  }, []);
+
+  return (
+    <div style={{ display: 'flex', gap: '1rem', flexWrap: 'wrap' }}>
+      {(['left', 'right'] as const).map(side =>
+        React.createElement(
+          'button',
+          {
+            key: side,
+            type: 'button',
+            onClick: () => setOpenSide(side),
+            style: { padding: '0.5rem 1rem', cursor: 'pointer' },
+          },
+          `Open ${side}`,
+        ),
+      )}
+      {React.createElement(
+        'bds-drawer',
+        { ref: leftRef, side: 'left', open: openSide === 'left' || undefined },
+        React.createElement('span', { slot: 'title' }, 'Left drawer'),
+        React.createElement('p', { style: { margin: 0 } }, 'This drawer slides in from the left.'),
+      )}
+      {React.createElement(
+        'bds-drawer',
+        { ref: rightRef, side: 'right', open: openSide === 'right' || undefined },
+        React.createElement('span', { slot: 'title' }, 'Right drawer'),
+        React.createElement('p', { style: { margin: 0 } }, 'This drawer slides in from the right.'),
+      )}
+    </div>
+  );
+}
+
+export const AllPlacements: Story = {
+  render: () => React.createElement(AllSides),
+};

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

@@ -0,0 +1,108 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsDropdownMenu.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-dropdown-menu&gt;
+
+Framework-agnostic Dropdown Menu custom element. A trigger-anchored menu panel with keyboard navigation, light-dismiss, and support for disabled and destructive items.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+Or in HTML without a bundler:
+
+```html
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
+```
+
+## When to use
+
+- Contextual action menus (e.g. row actions in a table)
+- Overflow menus triggered by a kebab (⋮) or ellipsis (…) button
+- Any set of related actions that shouldn't always be visible
+
+## When not to use
+
+- For selecting a value from a list — use `<bds-select>` or `<bds-combobox>` instead
+- For navigation links — use a nav element or `<bds-popover>`
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With destructive item
+<Canvas of={Stories.WithDestructiveItem} />
+
+### With disabled item
+<Canvas of={Stories.WithDisabledItem} />
+
+### All placements
+<Canvas of={Stories.AllPlacements} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes — `<bds-dropdown-menu>`
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `open` | boolean | `false` | Controls open/closed state (reflected) |
+| `placement` | `"bottom-start" \| "bottom-end" \| "top-start" \| "top-end"` | `"bottom-start"` | Menu position relative to the trigger |
+
+## Attributes — `<bds-dropdown-menu-item>`
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | string | `""` | Value emitted in `bds-select` event detail |
+| `disabled` | boolean | `false` | Prevents interaction; item is excluded from keyboard navigation |
+| `destructive` | boolean | `false` | Renders the item in a destructive (error colour) style |
+
+## Slots — `<bds-dropdown-menu>`
+
+| Slot | Description |
+|------|-------------|
+| `trigger` | The activating element (typically a `<button>`) |
+| `(default)` | `<bds-dropdown-menu-item>` elements |
+
+## Slots — `<bds-dropdown-menu-item>`
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Item label text |
+
+## Events
+
+| Event | Fired by | Bubbles | Detail | Description |
+|-------|----------|---------|--------|-------------|
+| `bds-open` | `<bds-dropdown-menu>` | Yes | — | Fired when the menu opens |
+| `bds-close` | `<bds-dropdown-menu>` | Yes | — | Fired when the menu closes |
+| `bds-select` | `<bds-dropdown-menu-item>` | Yes | `{ value: string }` | Fired when an item is clicked or activated via keyboard |
+
+## Usage in plain HTML
+
+```html
+<bds-dropdown-menu placement="bottom-start">
+  <button slot="trigger" type="button">Options</button>
+  <bds-dropdown-menu-item value="edit">Edit</bds-dropdown-menu-item>
+  <bds-dropdown-menu-item value="duplicate">Duplicate</bds-dropdown-menu-item>
+  <bds-dropdown-menu-item value="delete" destructive>Delete</bds-dropdown-menu-item>
+</bds-dropdown-menu>
+```
+
+## Accessibility
+
+- The menu panel has `role="menu"` and `aria-hidden` toggled on open/close
+- Each item renders a `<button role="menuitem">`
+- Keyboard navigation: ArrowDown / ArrowUp moves between enabled items; Escape closes and returns focus to the trigger; Tab closes the menu
+- Disabled items are excluded from keyboard navigation
+- Focus returns to the trigger element on close

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

@@ -0,0 +1,91 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { DropdownMenuPlacement } from './bds-dropdown-menu';
+import '../index'; // auto-registers all custom elements
+
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsDropdownMenu({
+  placement = 'bottom-start',
+  triggerLabel = 'Options',
+  children,
+}: {
+  placement?: DropdownMenuPlacement;
+  triggerLabel?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-dropdown-menu',
+    { placement },
+    React.createElement('button', { slot: 'trigger', type: 'button' }, triggerLabel),
+    children ?? [
+      React.createElement('bds-dropdown-menu-item', { key: 'edit', value: 'edit' }, 'Edit'),
+      React.createElement('bds-dropdown-menu-item', { key: 'duplicate', value: 'duplicate' }, 'Duplicate'),
+      React.createElement('bds-dropdown-menu-item', { key: 'archive', value: 'archive' }, 'Archive'),
+    ],
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/DropdownMenu',
+  component: BdsDropdownMenu,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    placement: {
+      control: 'select',
+      options: ['bottom-start', 'bottom-end', 'top-start', 'top-end'],
+    },
+    triggerLabel: { control: 'text' },
+  },
+} satisfies Meta<typeof BdsDropdownMenu>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { placement: 'bottom-start', triggerLabel: 'Options' },
+};
+
+export const WithDestructiveItem: Story = {
+  render: () =>
+    React.createElement(
+      'bds-dropdown-menu',
+      { placement: 'bottom-start' },
+      React.createElement('button', { slot: 'trigger', type: 'button' }, 'Manage'),
+      React.createElement('bds-dropdown-menu-item', { value: 'edit' }, 'Edit'),
+      React.createElement('bds-dropdown-menu-item', { value: 'duplicate' }, 'Duplicate'),
+      React.createElement('bds-dropdown-menu-item', { value: 'delete', destructive: '' }, 'Delete'),
+    ),
+};
+
+export const WithDisabledItem: Story = {
+  render: () =>
+    React.createElement(
+      'bds-dropdown-menu',
+      { placement: 'bottom-start' },
+      React.createElement('button', { slot: 'trigger', type: 'button' }, 'Actions'),
+      React.createElement('bds-dropdown-menu-item', { value: 'view' }, 'View'),
+      React.createElement('bds-dropdown-menu-item', { value: 'export', disabled: '' }, 'Export (unavailable)'),
+      React.createElement('bds-dropdown-menu-item', { value: 'share' }, 'Share'),
+    ),
+};
+
+export const AllPlacements: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, auto)', gap: '6rem', padding: '5rem' }}>
+      {(['bottom-start', 'bottom-end', 'top-start', 'top-end'] as const).map(p =>
+        React.createElement(
+          'div',
+          { key: p, style: { display: 'flex', justifyContent: 'center' } },
+          React.createElement(
+            'bds-dropdown-menu',
+            { placement: p },
+            React.createElement('button', { slot: 'trigger', type: 'button' }, p),
+            React.createElement('bds-dropdown-menu-item', { value: 'a' }, 'Item A'),
+            React.createElement('bds-dropdown-menu-item', { value: 'b' }, 'Item B'),
+          ),
+        ),
+      )}
+    </div>
+  ),
+};