@boostdev/design-system-components 1.1.0 → 1.1.2

package/src/components/ui/Tooltip/Tooltip.module.css

@@ -32,29 +32,29 @@
 
   /* Placement: top (default) */
   .--placement_top {
-    bottom: calc(100% + var(--bds-space_xs));
-    left: 50%;
+    inset-block-end: calc(100% + var(--bds-space_xs));
+    inset-inline-start: 50%;
     transform: translateX(-50%);
   }
 
   /* Placement: bottom */
   .--placement_bottom {
-    top: calc(100% + var(--bds-space_xs));
-    left: 50%;
+    inset-block-start: calc(100% + var(--bds-space_xs));
+    inset-inline-start: 50%;
     transform: translateX(-50%);
   }
 
   /* Placement: left */
   .--placement_left {
-    right: calc(100% + var(--bds-space_xs));
-    top: 50%;
+    inset-inline-end: calc(100% + var(--bds-space_xs));
+    inset-block-start: 50%;
     transform: translateY(-50%);
   }
 
   /* Placement: right */
   .--placement_right {
-    left: calc(100% + var(--bds-space_xs));
-    top: 50%;
+    inset-inline-start: calc(100% + var(--bds-space_xs));
+    inset-block-start: 50%;
     transform: translateY(-50%);
   }
 

package/src/components/ui/Typography/Typography.native.mdx

@@ -0,0 +1,56 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Typography.native.stories';
+
+<Meta of={Stories} />
+
+# Typography (React Native)
+
+React Native typography component wrapping `Text` with semantic variants. Use instead of bare `<Text>` to ensure consistent sizing, weight, and line-height from the design token scale.
+
+> **Status: alpha** — API may change before stable release.
+
+## Usage
+
+```tsx
+import { Typography } from '@boostdev/components';
+
+<Typography variant="h1">Page title</Typography>
+<Typography variant="body">Body copy text.</Typography>
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Heading 1
+<Canvas of={Stories.Heading1} />
+
+### Heading 2
+<Canvas of={Stories.Heading2} />
+
+### Heading 3
+<Canvas of={Stories.Heading3} />
+
+### Body
+<Canvas of={Stories.Body} />
+
+### Body small
+<Canvas of={Stories.BodySmall} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Props reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"h1" \| "h2" \| "h3" \| "body" \| "body_s"` | `"body"` | Typographic scale |
+| `children` | `ReactNode` | — | Text content |
+| `style` | `StyleProp<TextStyle>` | — | Override text styles |
+
+## Accessibility
+
+- `h1`/`h2`/`h3` variants set `accessibilityRole="header"` automatically
+- Override with the `accessibilityRole` prop if the visual hierarchy doesn't match the semantic hierarchy

package/src/polyfill-invoker-commands.ts

@@ -0,0 +1,68 @@
+/**
+ * Invoker Commands API polyfill (Baseline 2025).
+ *
+ * Handles `commandfor` / `command` attributes on <button> elements for browsers
+ * that don't yet support the native API. Dispatches a synthetic `command` event
+ * on the target element before performing the action — identical to native
+ * behaviour — so any existing `command` event listeners continue to work.
+ *
+ * Supports the dialog-specific commands used by this library:
+ *   command="show-modal"  →  dialog.showModal()
+ *   command="close"       →  dialog.close()
+ *
+ * Installation is idempotent and SSR-safe. The function is called automatically
+ * when the Dialog component is imported; consumers do not need to call it.
+ */
+
+let installed = false;
+
+export function installInvokerCommandsPolyfill(): void {
+  if (installed) return;
+  if (typeof window === 'undefined') return;
+  if ('command' in HTMLButtonElement.prototype) return; // native support present
+
+  installed = true;
+
+  document.addEventListener('click', (e: MouseEvent) => {
+    const button = (e.target as Element | null)?.closest<HTMLButtonElement>('button[commandfor]');
+    if (!button) return;
+
+    const targetId = button.getAttribute('commandfor');
+    const command = button.getAttribute('command');
+    if (!targetId || !command) return;
+
+    const target = document.getElementById(targetId);
+    if (!target) return;
+
+    // Dispatch a synthetic command event that mirrors the native CommandEvent.
+    const commandEvent = new Event('command', { cancelable: true, bubbles: false });
+    Object.defineProperty(commandEvent, 'command', { value: command, configurable: true });
+    Object.defineProperty(commandEvent, 'source', { value: button, configurable: true });
+    const notCancelled = target.dispatchEvent(commandEvent);
+
+    if (!notCancelled) return;
+
+    if (target instanceof HTMLDialogElement) {
+      if (command === 'show-modal' && !target.open) {
+        target.showModal();
+      } else if (command === 'close' && target.open) {
+        target.close();
+      }
+    } else if (target.hasAttribute('popover') && 'showPopover' in target) {
+      // Popover API commands — Popover API is Baseline 2024 so showPopover exists
+      // in any browser that lacks native invoker command support.
+      const popover = target as HTMLElement & {
+        showPopover(): void;
+        hidePopover(): void;
+        togglePopover(force?: boolean): boolean;
+      };
+      if (command === 'toggle-popover') {
+        popover.togglePopover();
+      } else if (command === 'show-popover') {
+        popover.showPopover();
+      } else if (command === 'hide-popover') {
+        popover.hidePopover();
+      }
+    }
+  });
+}

package/src/react-augment.d.ts

@@ -10,4 +10,23 @@ declare module 'react' {
     anchorName?: string;
     positionAnchor?: string;
   }
+
+  // Invoker Commands API (Baseline 2025) — not yet in @types/react.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ButtonHTMLAttributes<T> {
+    commandfor?: string;
+    command?: string;
+  }
+}
+
+// CommandEvent and its entry in the DOM event map — not yet in TypeScript's lib.dom.
+declare global {
+  interface CommandEvent extends Event {
+    readonly command: string;
+    readonly source: Element;
+  }
+
+  interface HTMLElementEventMap {
+    command: CommandEvent;
+  }
 }

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/index.ts

@@ -10,3 +10,50 @@ export { BdsAlert } from './ui/bds-alert';
 // Phase 2 — layout-driven components
 export { BdsPopover } from './interaction/bds-popover';
 export { BdsToastProvider } from './interaction/bds-toast-provider';
+
+// Phase 3 — simple UI display
+export { BdsSeparator } from './ui/bds-separator';
+export { BdsSkeleton } from './ui/bds-skeleton';
+export { BdsLoading } from './ui/bds-loading';
+export { BdsAvatar } from './ui/bds-avatar';
+export { BdsTypography } from './ui/bds-typography';
+export { BdsProgress } from './ui/bds-progress';
+export { BdsProgressCircle } from './ui/bds-progress-circle';
+export { BdsRating } from './ui/bds-rating';
+
+// Phase 3 — interactive with state
+export { BdsCollapsible } from './interaction/bds-collapsible';
+export { BdsAccordionItem } from './interaction/bds-accordion-item';
+export { BdsAccordion } from './interaction/bds-accordion';
+export { BdsTab } from './interaction/bds-tab';
+export { BdsTabPanel } from './interaction/bds-tab-panel';
+export { BdsTabs } from './interaction/bds-tabs';
+export { BdsTooltip } from './interaction/bds-tooltip';
+export { BdsSkipLink } from './interaction/bds-skip-link';
+
+// Phase 4 — modal overlays
+export { BdsDialog } from './interaction/bds-dialog';
+export { BdsDrawer } from './interaction/bds-drawer';
+
+// Phase 5 — basic form inputs (ElementInternals)
+export { BdsCheckbox } from './interaction/form/bds-checkbox';
+export { BdsRadio } from './interaction/form/bds-radio';
+export { BdsSwitch } from './interaction/form/bds-switch';
+export { BdsSelect } from './interaction/form/bds-select';
+export { BdsTextarea } from './interaction/form/bds-textarea';
+
+// Phase 6 — complex form inputs (ElementInternals)
+export { BdsNumberInput } from './interaction/form/bds-number-input';
+export { BdsSlider } from './interaction/form/bds-slider';
+export { BdsSegmentedControl } from './interaction/form/bds-segmented-control';
+export { BdsFileInput } from './interaction/form/bds-file-input';
+export { BdsCombobox } from './interaction/form/bds-combobox';
+
+// Phase 7 — slotted content display
+export { BdsNotificationBanner } from './ui/bds-notification-banner';
+export { BdsCard } from './ui/bds-card';
+export { BdsSectionHeader } from './ui/bds-section-header';
+export { BdsIconWrapper } from './ui/bds-icon-wrapper';
+export { BdsDescriptionList } from './ui/bds-description-list';
+export { BdsBreadcrumb } from './ui/bds-breadcrumb';
+export { BdsLink } from './ui/bds-link';

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