@boostdev/design-system-components 1.0.3 → 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/types.ts

@@ -0,0 +1,2 @@
+/** Allows consumers to pass a CSS class to the component's root element. */
+export type WithClassName = { className?: string | undefined };

package/src/typings.d.ts

@@ -2,3 +2,6 @@ declare module '*.module.css' {
   const classes: Record<string, string>;
   export default classes;
 }
+
+// CSS Anchor Positioning augmentation lives in react-augment.d.ts — see that
+// file for why it must be a separate module file rather than declared here.

package/src/web-components/globals.ts

@@ -0,0 +1,61 @@
+/**
+ * Injects the bdc border-decoration @property rules into the document's adopted stylesheets.
+ *
+ * @property declarations must live at the document level — they cannot be scoped to a Shadow DOM.
+ * This module is imported once by src/web-components/index.ts and runs as a side effect.
+ */
+
+const bdcCss = `
+  @property --bdc_color {
+    syntax: '<color>';
+    inherits: false;
+    initial-value: currentcolor;
+  }
+
+  @property --bdc-outline_width {
+    syntax: '<length>';
+    inherits: false;
+    initial-value: 1px;
+  }
+
+  @property --bdc-outline_offset {
+    syntax: '<length>';
+    inherits: false;
+    initial-value: -1px;
+  }
+
+  @property --bdc-outline_radius {
+    syntax: '<length-percentage>';
+    inherits: false;
+    initial-value: 0;
+  }
+
+  @property --bdc-outline_shadow {
+    syntax: '*';
+    inherits: false;
+    initial-value: none;
+  }
+
+  @layer component {
+    :root {
+      --bdc-outline_border: none;
+
+      --bdc_color:        currentcolor;
+      --bdc_color--focus: var(--bds-color_interactive);
+      --bdc_color--error: var(--bds-color_error);
+
+      --bdc-outline_width:  1px;
+      --bdc-outline_offset: -1px;
+      --bdc-outline_radius: var(--bds-border_radius--xs);
+      --bdc-outline_shadow: none;
+    }
+  }
+`;
+
+// Guard against double-injection during hot-reload or test re-evaluation.
+if (!('__bdcInjected' in document)) {
+  Object.defineProperty(document, '__bdcInjected', { value: true });
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(bdcCss);
+  document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+}

package/src/web-components/index.ts

@@ -0,0 +1,12 @@
+// Inject global bdc @property declarations into the document.
+// Must run before any component that uses --bdc_color / --bdc-outline_* tokens.
+import './globals';
+
+// Phase 1 — proof of concept components
+export { BdsBadge } from './ui/bds-badge';
+export { BdsButton } from './interaction/bds-button';
+export { BdsAlert } from './ui/bds-alert';
+
+// Phase 2 — layout-driven components
+export { BdsPopover } from './interaction/bds-popover';
+export { BdsToastProvider } from './interaction/bds-toast-provider';

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/BdsButton.stories.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { ButtonVariant, ButtonSize } from './bds-button';
+import '../index'; // auto-registers all custom elements
+
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsButton({
+  variant = 'default',
+  size = 'medium',
+  disabled,
+  href,
+  hasPulse,
+  children,
+}: {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  disabled?: boolean;
+  href?: string;
+  hasPulse?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-button',
+    { variant, size, disabled: disabled || undefined, href, 'has-pulse': hasPulse || undefined },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Button',
+  component: BdsButton,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    variant: { control: 'select', options: ['default', 'ghost'] },
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
+  },
+} satisfies Meta<typeof BdsButton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { children: 'Default', variant: 'default' } };
+export const Ghost: Story = { args: { children: 'Ghost', variant: 'ghost' } };
+export const Small: Story = { args: { children: 'Small', size: 'small' } };
+export const Medium: Story = { args: { children: 'Medium', size: 'medium' } };
+export const Large: Story = { args: { children: 'Large', size: 'large' } };
+export const WithPulse: Story = { args: { children: 'Pulsing', hasPulse: true } };
+export const Disabled: Story = { args: { children: 'Disabled', disabled: true } };
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
+      {(['default', 'ghost'] as const).flatMap(v =>
+        (['small', 'medium', 'large'] as const).map(s => (
+          <BdsButton key={`${v}-${s}`} variant={v} size={s}>{v} {s}</BdsButton>
+        )),
+      )}
+    </div>
+  ),
+};

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/BdsPopover.stories.tsx

@@ -0,0 +1,70 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { PopoverPlacement } from './bds-popover';
+import '../index'; // auto-registers all custom elements
+
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsPopover({
+  placement = 'bottom',
+  children,
+  trigger,
+}: {
+  placement?: PopoverPlacement;
+  children?: React.ReactNode;
+  trigger?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-popover',
+    { placement },
+    trigger ?? React.createElement('button', { slot: 'trigger' }, 'Open popover'),
+    children ?? React.createElement('p', { style: { margin: 0 } }, 'Popover content'),
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Popover',
+  component: BdsPopover,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    placement: { control: 'select', options: ['bottom', 'top', 'left', 'right'] },
+  },
+} satisfies Meta<typeof BdsPopover>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { placement: 'bottom' } };
+export const Top: Story = { args: { placement: 'top' } };
+export const Right: Story = { args: { placement: 'right' } };
+export const Left: Story = { args: { placement: 'left' } };
+
+export const WithRichContent: Story = {
+  args: { placement: 'bottom' },
+  render: (args) => (
+    <BdsPopover {...args}>
+      {React.createElement(
+        'div',
+        { style: { display: 'flex', flexDirection: 'column', gap: '0.5rem' } },
+        React.createElement('strong', null, 'Actions'),
+        React.createElement('button', null, 'Edit'),
+        React.createElement('button', null, 'Duplicate'),
+        React.createElement('button', null, 'Delete'),
+      )}
+    </BdsPopover>
+  ),
+};
+
+export const AllPlacements: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, auto)', gap: '3rem', padding: '4rem' }}>
+      {(['bottom', 'top', 'right', 'left'] as const).map(p => (
+        <div key={p} style={{ display: 'flex', justifyContent: 'center' }}>
+          <BdsPopover placement={p}>
+            {React.createElement('p', { style: { margin: 0 } }, `Placed ${p}`)}
+          </BdsPopover>
+        </div>
+      ))}
+    </div>
+  ),
+};

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