@boostdev/design-system-components 1.1.0 → 1.1.1

package/src/stories/ReactNative.mdx

@@ -0,0 +1,121 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="React Native/Overview" />
+
+# React Native
+
+> **Status: alpha** — components and APIs may change before stable release.
+
+`@boostdev/components` ships native implementations for 19 components. These use React Native primitives (`View`, `Text`, `Pressable`, `StyleSheet`) rather than HTML elements, and consume a dedicated token layer instead of CSS custom properties.
+
+## Installation
+
+```bash
+npm install @boostdev/components
+# or
+pnpm add @boostdev/components
+```
+
+Metro automatically resolves the native entry point via the `"react-native"` export condition in `package.json` — no extra configuration needed.
+
+```ts
+// Import is identical to the web version:
+import { Button, Alert, Badge, Avatar, Typography } from '@boostdev/components';
+```
+
+## Setup — ThemeProvider
+
+Wrap your app (or the relevant subtree) in `ThemeProvider` to give native components access to the design token context:
+
+```tsx
+import { ThemeProvider } from '@boostdev/components/native/ThemeContext';
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      {/* your app */}
+    </ThemeProvider>
+  );
+}
+```
+
+`ThemeProvider` reads the current colour scheme via `useColorScheme()` and applies the corresponding dark/light token set automatically.
+
+## Design Tokens
+
+Native components consume tokens from `src/native/tokens.ts` — a JS object mirroring the CSS custom properties from `@boostdev/design-system-foundation`. Token categories:
+
+| Category | Example |
+|----------|---------|
+| `colors` | `tokens.colors.bg`, `tokens.colors.interactive` |
+| `spacing` | `tokens.spacing.xs`, `tokens.spacing.m` |
+| `font` | `tokens.font.sizeBody`, `tokens.font.weightBold` |
+| `border` | `tokens.border.radiusS`, `tokens.border.radiusM` |
+| `zIndex` | `tokens.zIndex.modal` |
+| `animation` | `tokens.animation.duration` |
+
+Tokens are accessed inside components via `useTheme()`:
+
+```tsx
+import { useTheme } from '@boostdev/components/native/ThemeContext';
+
+function MyComponent() {
+  const { tokens } = useTheme();
+  return <View style={{ backgroundColor: tokens.colors.bg }} />;
+}
+```
+
+## Available Components
+
+### UI
+
+| Component | Description |
+|-----------|-------------|
+| `Typography` | Text with semantic variants: `h1`, `h2`, `h3`, `body`, `body_s` |
+| `Badge` | Short status label with 5 semantic variants |
+| `Avatar` | Initials-based avatar with 3 sizes |
+| `Alert` | Inline status message with optional title and dismiss |
+| `NotificationBanner` | Full-width banner notification |
+| `Progress` | Linear progress bar |
+| `Skeleton` | Loading placeholder |
+| `Loading` | Animated loading spinner |
+| `Separator` | Visual divider |
+
+### Layout
+
+| Component | Description |
+|-----------|-------------|
+| `Card` | Elevated content container |
+| `SectionHeader` | Section heading with optional action |
+| `ButtonGroup` | Horizontal or vertical button row |
+| `IconWrapper` | Consistent icon sizing wrapper |
+
+### Interaction
+
+| Component | Description |
+|-----------|-------------|
+| `Button` | Primary action element with `onPress` |
+
+### Form
+
+| Component | Description |
+|-----------|-------------|
+| `Checkbox` | Controlled checkbox with label, hint, and error |
+| `Radio` | Controlled radio button |
+| `Switch` | Toggle switch |
+| `Label` | Form field label atom |
+| `Message` | Form field hint/error atom |
+
+## Key differences from the web components
+
+| Web | React Native |
+|-----|-------------|
+| `onClick` | `onPress` |
+| `aria-label` | `accessibilityLabel` |
+| CSS `className` | `StyleSheet` / `style` prop |
+| `children` as string/HTML | `children` must be `<Text>` nodes (RN restriction) |
+| Design tokens via CSS custom properties | Design tokens via `useTheme()` JS object |
+
+## Dark mode
+
+`ThemeProvider` subscribes to `useColorScheme()` automatically. No extra work is needed — components adapt their colours when the device switches between light and dark mode.

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

@@ -0,0 +1,106 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsButton.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-button&gt;
+
+Framework-agnostic button custom element. Renders as `<button>` or `<a>` depending on whether `href` is set. Matches the React `Button` component in variants, sizes, and theming.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+// Register all web components at once
+import '@boostdev/components/web-components';
+```
+
+Or in HTML without a bundler:
+
+```html
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
+```
+
+## Examples
+
+### All variants & sizes
+<Canvas of={Stories.AllVariants} />
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Ghost
+<Canvas of={Stories.Ghost} />
+
+### Sizes
+<Canvas of={Stories.Small} />
+<Canvas of={Stories.Medium} />
+<Canvas of={Stories.Large} />
+
+### Pulse (CTA emphasis)
+<Canvas of={Stories.WithPulse} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"default" \| "ghost"` | `"default"` | Visual style — filled or transparent outlined |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Height and padding scale |
+| `disabled` | boolean | `false` | Prevents interaction, sets `aria-disabled` |
+| `href` | string | — | Renders as `<a>` when set |
+| `target` | string | — | Forwarded to `<a>` when `href` is set |
+| `rel` | string | — | Forwarded to `<a>` when `href` is set |
+| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type |
+| `has-pulse` | boolean | `false` | Adds animated ring for CTA emphasis |
+| `aria-label` | string | — | Accessible label (required for icon-only buttons) |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Button label text |
+| `icon-start` | Icon placed before the label |
+| `icon-end` | Icon placed after the label |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--button_color` | Identity colour — fills the default variant, outlines the ghost variant |
+| `--button_on-color` | Text/icon colour on the button surface. Pair with `--button_color` |
+
+## Invoker Commands API
+
+`<bds-button>` can control a `<bds-popover>` declaratively using `commandfor` and `command`:
+
+```html
+<bds-button commandfor="my-popover" command="--toggle">Open popover</bds-button>
+<bds-popover id="my-popover">
+  <p>Popover content</p>
+</bds-popover>
+```
+
+## Usage in plain HTML
+
+```html
+<bds-button variant="default" size="medium">Save</bds-button>
+<bds-button variant="ghost">Cancel</bds-button>
+<bds-button href="/dashboard">Go to dashboard</bds-button>
+```
+
+## Accessibility
+
+- Always provide a label via slot content or `aria-label` (required for icon-only buttons)
+- `disabled` sets `aria-disabled="true"` and prevents click events
+- When rendered as `<a>`, `href` must point to a valid destination
+- `has-pulse` animation respects `prefers-reduced-motion`

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

@@ -0,0 +1,120 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsPopover.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-popover&gt;
+
+Framework-agnostic popover custom element. A non-modal floating panel anchored to a trigger element. Uses CSS Anchor Positioning for automatic repositioning when near viewport edges.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### Default (bottom)
+<Canvas of={Stories.Default} />
+
+### Top
+<Canvas of={Stories.Top} />
+
+### Right
+<Canvas of={Stories.Right} />
+
+### Left
+<Canvas of={Stories.Left} />
+
+### With rich content
+<Canvas of={Stories.WithRichContent} />
+
+### All placements
+<Canvas of={Stories.AllPlacements} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `placement` | `"bottom" \| "top" \| "left" \| "right"` | `"bottom"` | Preferred panel position relative to the trigger |
+| `open` | boolean | `false` | Controls panel visibility; reflects on the element |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `trigger` | Element that opens and closes the panel on click |
+| `(default)` | Panel content |
+
+## Events
+
+| Event | Detail | Bubbles | Composed | Description |
+|-------|--------|---------|----------|-------------|
+| `bds-open` | — | Yes | Yes | Fired when the panel opens |
+| `bds-close` | — | Yes | Yes | Fired when the panel closes |
+
+## Behaviour
+
+- Clicking the trigger toggles the panel open/closed
+- Pressing `Escape` closes an open panel
+- Clicking outside the element closes the panel
+- CSS Anchor Positioning automatically tries fallback placements (`@position-try`) when the preferred placement would overflow the viewport
+- Each instance gets a unique CSS anchor name — multiple popovers on the same page don't interfere
+
+## Invoker Commands API
+
+Control the popover declaratively from any `<button>` using `commandfor` and `command` — no JavaScript required:
+
+```html
+<button commandfor="my-popover" command="--toggle">Open</button>
+<button commandfor="my-popover" command="--open">Open only</button>
+<button commandfor="my-popover" command="--close">Close only</button>
+
+<bds-popover id="my-popover">
+  <p>Panel content</p>
+</bds-popover>
+```
+
+## Usage in plain HTML
+
+```html
+<bds-popover placement="bottom">
+  <button slot="trigger">Open menu</button>
+  <nav>
+    <a href="/profile">Profile</a>
+    <a href="/settings">Settings</a>
+    <a href="/logout">Log out</a>
+  </nav>
+</bds-popover>
+```
+
+Listen for open/close events:
+
+```js
+const popover = document.querySelector('bds-popover');
+popover.addEventListener('bds-open', () => console.log('opened'));
+popover.addEventListener('bds-close', () => console.log('closed'));
+```
+
+## CSS Custom Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--popover_color` | `--bds-color_bg` | Panel background |
+| `--popover_on-color` | `--bds-color_on-bg` | Panel text colour |
+| `--popover_shadow` | `--bds-shadow_m` | Panel drop shadow |
+| `--popover_z-index` | `100` | Stacking order |
+
+## Accessibility
+
+- The panel has `role="region"` and `aria-label="Popover"`
+- The trigger element retains its own role (e.g. `<button>`) — no ARIA is added by the component
+- For menus, use a `<nav>` or `role="menu"` inside the default slot as appropriate
+- The component does not trap focus — use `<bds-dialog>` for modal, focus-trapped overlays

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

@@ -0,0 +1,94 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsToastProvider.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-toast-provider&gt;
+
+Framework-agnostic toast notification provider. Wrap your page content in `<bds-toast-provider>` to enable toast notifications that render in the browser top layer (above fixed/sticky elements). Auto-dismisses after 5 seconds.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### Static API
+<Canvas of={Stories.Default} />
+
+### Event API (no import required)
+<Canvas of={Stories.EventAPI} />
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Page content. `<bds-toast-provider>` renders as `display: contents` so it is invisible in the layout |
+
+## Three ways to show a toast
+
+### 1. Static method (import required)
+
+```js
+import { BdsToastProvider } from '@boostdev/components/web-components';
+
+BdsToastProvider.show('File saved', 'success');
+BdsToastProvider.show('Something went wrong', 'error');
+```
+
+### 2. Instance method
+
+```js
+const provider = document.querySelector('bds-toast-provider');
+provider.showToast('Settings updated', 'info');
+```
+
+### 3. Document event (no import required)
+
+Useful in frameworks or contexts where importing the class is inconvenient:
+
+```js
+document.dispatchEvent(new CustomEvent('bds-show-toast', {
+  detail: { message: 'Copied to clipboard', variant: 'success' },
+}));
+```
+
+## Toast variants
+
+| Variant | Use for |
+|---------|---------|
+| `info` | Neutral status updates |
+| `success` | Completed actions |
+| `warning` | Potential issues the user should know about |
+| `error` | Failures requiring attention |
+
+## Setup in plain HTML
+
+```html
+<bds-toast-provider>
+  <!-- all your page content goes here -->
+  <main>…</main>
+</bds-toast-provider>
+
+<script type="module">
+  import '@boostdev/components/web-components';
+  // or use the document event API — no import needed
+</script>
+```
+
+## Behaviour
+
+- Toasts render in the browser top layer via the Popover API (`popover="manual"`) — they appear above `position: fixed` elements and `z-index` stacking
+- Each toast auto-dismisses after **5000 ms**
+- Multiple toasts stack vertically and each has its own dismissal timer
+- A visible dismiss (×) button is always present on each toast
+
+## Accessibility
+
+- Each toast renders with `role="status"` + `aria-live="polite"` by default so screen readers announce it without interrupting the user
+- `error` toasts use `role="alert"` + `aria-live="assertive"` for immediate announcement
+- The dismiss button has an accessible label

package/src/web-components/interaction/bds-popover.spec.ts

@@ -1,4 +1,4 @@
-import { fixture, cleanup } from '../test/helpers';
+import { fixture, cleanup, makeCommandEvent } from '../test/helpers';
 import { BdsPopover } from './bds-popover';
 
 describe('bds-popover', () => {
@@ -114,6 +114,54 @@ describe('bds-popover', () => {
     cleanup(el);
   });
 
+  describe('Invoker Commands API (command event on host)', () => {
+    it('opens on --open command', async () => {
+      const el = await fixture('<bds-popover id="p1"><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      el.dispatchEvent(makeCommandEvent('--open'));
+      await el.updateComplete;
+      expect(el.open).toBe(true);
+      cleanup(el);
+    });
+
+    it('closes on --close command', async () => {
+      const el = await fixture('<bds-popover id="p2" open><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      await el.updateComplete;
+      el.dispatchEvent(makeCommandEvent('--close'));
+      await el.updateComplete;
+      expect(el.open).toBe(false);
+      cleanup(el);
+    });
+
+    it('toggles on --toggle command', async () => {
+      const el = await fixture('<bds-popover id="p3"><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      el.dispatchEvent(makeCommandEvent('--toggle'));
+      await el.updateComplete;
+      expect(el.open).toBe(true);
+      el.dispatchEvent(makeCommandEvent('--toggle'));
+      await el.updateComplete;
+      expect(el.open).toBe(false);
+      cleanup(el);
+    });
+
+    it('fires bds-open event on --open command', async () => {
+      const el = await fixture('<bds-popover id="p4"><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      const handler = vi.fn();
+      el.addEventListener('bds-open', handler);
+      el.dispatchEvent(makeCommandEvent('--open'));
+      await el.updateComplete;
+      expect(handler).toHaveBeenCalledOnce();
+      cleanup(el);
+    });
+
+    it('ignores unknown commands', async () => {
+      const el = await fixture('<bds-popover id="p5"><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      el.dispatchEvent(makeCommandEvent('--unknown'));
+      await el.updateComplete;
+      expect(el.open).toBe(false);
+      cleanup(el);
+    });
+  });
+
   it('two instances get different anchor names', async () => {
     const a = await fixture('<bds-popover><button slot="trigger">A</button></bds-popover>');
     const b = await fixture('<bds-popover><button slot="trigger">B</button></bds-popover>');

package/src/web-components/interaction/bds-popover.ts

@@ -157,18 +157,28 @@ export class BdsPopover extends LitElement {
     this.style.setProperty('--bds-popover-anchor', this._anchorName);
     document.addEventListener('keydown', this._onKeydown);
     document.addEventListener('mousedown', this._onOutsideClick);
+    // Invoker Commands API — host is in light DOM so commandfor can reference its id.
+    this.addEventListener('command', this._onCommand);
   }
 
   disconnectedCallback() {
     super.disconnectedCallback();
     document.removeEventListener('keydown', this._onKeydown);
     document.removeEventListener('mousedown', this._onOutsideClick);
+    this.removeEventListener('command', this._onCommand);
   }
 
   private _onKeydown = (e: KeyboardEvent) => {
     if (this.open && e.key === 'Escape') this._close();
   };
 
+  private _onCommand = (e: Event) => {
+    const command = (e as CommandEvent).command;
+    if (command === '--toggle') this._toggle();
+    else if (command === '--open') this._open();
+    else if (command === '--close') this._close();
+  };
+
   private _onOutsideClick = (e: MouseEvent) => {
     if (this.open && !this.contains(e.target as Node)) this._close();
   };
@@ -182,11 +192,13 @@ export class BdsPopover extends LitElement {
   }
 
   private _open() {
+    if (this.open) return;
     this.open = true;
     this.dispatchEvent(new CustomEvent('bds-open', { bubbles: true, composed: true }));
   }
 
   private _close() {
+    if (!this.open) return;
     this.open = false;
     this.dispatchEvent(new CustomEvent('bds-close', { bubbles: true, composed: true }));
   }

package/src/web-components/test/helpers.ts

@@ -12,3 +12,11 @@ export async function fixture(html: string): Promise<HTMLElement> {
 export function cleanup(el: HTMLElement) {
   el.remove();
 }
+
+/** Create a synthetic Invoker Commands API `command` event for testing. */
+export function makeCommandEvent(command: string): Event {
+  const event = new Event('command', { bubbles: false, cancelable: true });
+  Object.defineProperty(event, 'command', { value: command, configurable: true });
+  Object.defineProperty(event, 'source', { value: null, configurable: true });
+  return event;
+}

package/src/web-components/ui/BdsAlert.mdx

@@ -0,0 +1,90 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsAlert.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-alert&gt;
+
+Framework-agnostic alert custom element for inline status messages. Supports four semantic variants, an optional title, and a dismissible mode.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Info
+<Canvas of={Stories.Info} />
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Warning
+<Canvas of={Stories.Warning} />
+
+### Error
+<Canvas of={Stories.Error} />
+
+### With title
+<Canvas of={Stories.WithTitle} />
+
+### Dismissible
+<Canvas of={Stories.Dismissible} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Semantic colour and icon |
+| `title` | string | — | Optional heading displayed above body content |
+| `dismissible` | boolean | `false` | Shows a dismiss (×) button |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Alert body text or content |
+| `icon` | Custom icon, placed left of the content area |
+
+## Events
+
+| Event | Detail | Bubbles | Composed | Description |
+|-------|--------|---------|----------|-------------|
+| `bds-dismiss` | — | Yes | Yes | Fired when the dismiss button is clicked |
+
+## Usage in plain HTML
+
+```html
+<bds-alert variant="success" title="Saved">
+  Your changes have been saved successfully.
+</bds-alert>
+
+<bds-alert variant="error" dismissible>
+  Something went wrong. Please try again.
+</bds-alert>
+```
+
+Listen for dismiss:
+
+```js
+document.querySelector('bds-alert').addEventListener('bds-dismiss', () => {
+  // remove or hide the element
+});
+```
+
+## Accessibility
+
+- `error` and `warning` use `role="alert"` + `aria-live="assertive"` — content is announced immediately
+- `info` and `success` use `role="status"` + `aria-live="polite"` — content is announced at the next opportunity
+- The dismiss button has an accessible label; do not rely solely on its icon