@boostdev/design-system-components 1.2.0 → 1.2.1

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`

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

@@ -1,28 +1,56 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import type { DrawerSide } from './bds-drawer';
-import '../index';
+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);
+  }, []);
 
-function DrawerDemo({ side = 'right' }: { side?: DrawerSide }) {
-  const [open, setOpen] = React.useState(false);
   return (
     <div>
-      <button type="button" onClick={() => setOpen(true)}>Open drawer</button>
+      <button
+        type="button"
+        onClick={() => setIsOpen(true)}
+        style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+      >
+        {triggerLabel}
+      </button>
       {React.createElement(
         'bds-drawer',
-        { open: open || undefined, side, onbdsclose: () => setOpen(false) },
-        React.createElement('span', { slot: 'title' }, side === 'left' ? 'Left Drawer' : 'Settings'),
-        React.createElement('p', { style: { margin: '0 0 12px' } }, 'Drawer content goes here. Press Escape or click × to close.'),
-        React.createElement('button', { type: 'button', onClick: () => setOpen(false) }, 'Close'),
+        {
+          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>
   );
 }
 
-function BdsDrawer({ side }: { side?: DrawerSide }) {
-  return React.createElement(DrawerDemo, { side });
-}
-
 const meta = {
   title: 'Web Components/Interaction/Drawer',
   component: BdsDrawer,
@@ -30,37 +58,139 @@ const meta = {
   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 Right: Story = { args: { side: 'right' } };
-export const Left: Story = { args: { side: 'left' } };
+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);
+  }, []);
 
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', gap: '12px' }}>
-      <DrawerDemo side="right" />
-      <DrawerDemo side="left" />
+  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),
 };
 
-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-drawer', command: 'show-modal' }, 'Open via commandfor')}
+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',
-        { id: 'invoker-drawer', side: 'right' },
-        React.createElement('span', { slot: 'title' }, 'Opened via Invoker API'),
-        React.createElement('p', { style: { margin: 0 } }, 'This drawer was opened declaratively using commandfor and command attributes.'),
+        { 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>
+  ),
+};

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

@@ -3,32 +3,88 @@ import * as Stories from './BdsSkipLink.stories';
 
 <Meta of={Stories} />
 
-# Skip Link
+# &lt;bds-skip-link&gt;
 
-`<bds-skip-link>` renders a visually hidden anchor that becomes visible on focus, allowing keyboard users to skip directly to the main content. This is a critical accessibility component that should be the first focusable element on every page.
+Framework-agnostic Skip Navigation Link custom element. Visually hidden until focused, allowing keyboard users to jump directly to the main content area and bypass repeated navigation.
 
-## Usage
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+Or in HTML without a bundler:
 
 ```html
-<bds-skip-link href="#main-content">Skip to main content</bds-skip-link>
-<!-- ... navigation ... -->
-<main id="main-content">...</main>
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
 ```
 
+## When to use
+
+- Place as the very first focusable element on every page that has a navigation region before the main content
+- Required on all pages to comply with WCAG 2.4.1 (Bypass Blocks, Level A)
+
+## When not to use
+
+- Do not place it anywhere other than the start of the document flow
+- Do not use it as a general-purpose navigation shortcut — it is specifically for skipping repetitive blocks
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With custom label
+<Canvas of={Stories.WithCustomLabel} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
 ## Attributes
 
-| Attribute | Type     | Default | Description                            |
-|-----------|----------|---------|----------------------------------------|
-| `href`    | `string` | `""`    | Target anchor ID (e.g. `#main-content`) |
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `href` | string | `"#main"` | The target anchor ID to jump to (e.g. `"#main-content"`) |
 
 ## Slots
 
-| Slot      | Description              |
-|-----------|--------------------------|
-| (default) | The visible link text    |
+| Slot | Description |
+|------|-------------|
+| `(default)` | Link text; defaults to `"Skip to main content"` when no content is provided |
+
+## Usage in plain HTML
+
+Place `<bds-skip-link>` as the very first element inside `<body>`:
+
+```html
+<body>
+  <bds-skip-link href="#main-content"></bds-skip-link>
+
+  <header>
+    <nav>...</nav>
+  </header>
+
+  <main id="main-content">
+    Page content
+  </main>
+</body>
+```
+
+With custom label text:
+
+```html
+<bds-skip-link href="#main-content">Skip to main content</bds-skip-link>
+```
 
-## Notes
+## Accessibility
 
-- The link is visually hidden until it receives keyboard focus (Tab key)
-- Place it as the very first element inside `<body>` before any navigation
-- The `href` must point to an `id` on the main content container
+- Visually hidden via `transform: translateY(...)` until focused — avoids `display: none` and `visibility: hidden` which remove the element from the accessibility tree
+- Becomes visible on `:focus-visible`, ensuring it is discoverable by keyboard and switch-access users
+- Uses an `<a>` element so it is announced as a link by screen readers
+- `z-index: 9999` ensures it appears above all other content when focused
+- Satisfies WCAG 2.4.1 Bypass Blocks (Level A)