@boostdev/design-system-components 1.0.3 → 1.1.0

package/src/components/ui/Table/Table.tsx

@@ -1,6 +1,7 @@
 import { ReactNode } from 'react';
 import css from './Table.module.css';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../types';
 
 export interface TableColumn<Row> {
   key: string;
@@ -9,14 +10,13 @@ export interface TableColumn<Row> {
   render?: (row: Row) => ReactNode;
 }
 
-interface TableProps<Row extends Record<string, unknown>> {
+interface TableProps<Row extends Record<string, unknown>> extends WithClassName {
   columns: TableColumn<Row>[];
   rows: Row[];
   caption?: string;
   sortKey?: string;
   sortDirection?: 'asc' | 'desc';
   onSort?: (key: string, direction: 'asc' | 'desc') => void;
-  className?: string;
 }
 
 export function Table<Row extends Record<string, unknown>>({

package/src/components/ui/Tabs/Tabs.stories.tsx

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { Tabs } from './Tabs';
 
 const meta = {
-  title: 'UI/Tabs',
+  title: 'React/UI/Tabs',
   component: Tabs,
 } satisfies Meta<typeof Tabs>;
 

package/src/components/ui/Tabs/Tabs.tsx

@@ -1,6 +1,7 @@
 import { KeyboardEvent, ReactNode, useId, useRef, useState } from 'react';
 import css from './Tabs.module.css';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../types';
 
 export interface TabItem {
   id: string;
@@ -9,10 +10,9 @@ export interface TabItem {
   disabled?: boolean;
 }
 
-interface TabsProps {
+interface TabsProps extends WithClassName {
   tabs: TabItem[];
   defaultTab?: string;
-  className?: string;
 }
 
 export function Tabs({ tabs, defaultTab, className }: Readonly<TabsProps>) {

package/src/components/ui/Tooltip/Tooltip.mdx

@@ -36,6 +36,20 @@ Short contextual label that appears on hover or focus. Use to supplement icon bu
 
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--tooltip_bg`</td><td>`var(--bds-color_on-bg)`</td><td>Tooltip background colour</td></tr>
+<tr><td>`--tooltip_text`</td><td>`var(--bds-color_bg)`</td><td>Tooltip text colour</td></tr>
+</tbody>
+</table>
+
+
 ## Accessibility
 
 - Tooltip content is linked via `aria-describedby` on the trigger element

package/src/components/ui/Tooltip/Tooltip.stories.tsx

@@ -3,7 +3,7 @@ import { Tooltip } from './Tooltip';
 import { Button } from '../../interaction/Button/Button';
 
 const meta = {
-  title: 'UI/Tooltip',
+  title: 'React/UI/Tooltip',
   component: Tooltip,
   argTypes: {
     placement: { control: 'radio', options: ['top', 'bottom', 'left', 'right'] },

package/src/components/ui/Tooltip/Tooltip.tsx

@@ -1,12 +1,12 @@
 import { ReactElement, ReactNode, cloneElement, isValidElement, useId, useState } from 'react';
 import css from './Tooltip.module.css';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../types';
 
-interface TooltipProps {
+interface TooltipProps extends WithClassName {
   content: ReactNode;
   placement?: 'top' | 'bottom' | 'left' | 'right';
   children: ReactElement;
-  className?: string;
 }
 
 export function Tooltip({

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

@@ -35,6 +35,19 @@ Renders a text element with a design-system variant. Decouples visual style from
 
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--typography_color`</td><td>`var(--bds-color_on-bg)`</td><td>Text colour override</td></tr>
+</tbody>
+</table>
+
+
 ## Accessibility
 
 - Defaults to the semantically correct element for each variant (`h1`–`h3`, `p`)

package/src/components/ui/Typography/Typography.native.stories.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider } from '../../../native/ThemeContext';
+import { Typography } from './Typography.native';
+
+const meta = {
+  tags: ['!stable', 'alpha'],
+  title: 'React Native/UI/Typography',
+  component: Typography,
+  decorators: [(Story) => <ThemeProvider><Story /></ThemeProvider>],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    variant: { control: 'select', options: ['h1', 'h2', 'h3', 'body', 'body_s'] },
+  },
+} satisfies Meta<typeof Typography>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Heading1: Story = { args: { children: 'Heading 1', variant: 'h1' } };
+export const Heading2: Story = { args: { children: 'Heading 2', variant: 'h2' } };
+export const Heading3: Story = { args: { children: 'Heading 3', variant: 'h3' } };
+export const Body: Story = { args: { children: 'The quick brown fox jumps over the lazy dog.', variant: 'body' } };
+export const BodySmall: Story = { args: { children: 'The quick brown fox jumps over the lazy dog.', variant: 'body_s' } };
+export const AllVariants: Story = {
+  args: { children: '' },
+  render: () => (
+    <ThemeProvider>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+        <Typography variant="h1">Heading 1</Typography>
+        <Typography variant="h2">Heading 2</Typography>
+        <Typography variant="h3">Heading 3</Typography>
+        <Typography variant="body">Body — The quick brown fox jumps over the lazy dog.</Typography>
+        <Typography variant="body_s">Body Small — The quick brown fox jumps over the lazy dog.</Typography>
+      </div>
+    </ThemeProvider>
+  ),
+};

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

@@ -0,0 +1,65 @@
+import { ReactNode } from 'react';
+import { StyleSheet, Text, StyleProp, TextStyle } from 'react-native';
+import { font, lineHeight } from '../../../native/tokens';
+import { useTheme } from '../../../native/ThemeContext';
+
+type TypographyVariant = 'h1' | 'h2' | 'h3' | 'body' | 'body_s';
+
+interface TypographyProps {
+  variant?: TypographyVariant;
+  children: ReactNode;
+  style?: StyleProp<TextStyle>;
+}
+
+const styles = StyleSheet.create({
+  base: {
+    fontFamily: font.family.body,
+    fontWeight: font.weight.body,
+  },
+  h1: {
+    fontSize: font.size.heading1,
+    fontFamily: font.family.heading,
+    fontWeight: font.weight.heading,
+    lineHeight: lineHeight.heading1,
+  },
+  h2: {
+    fontSize: font.size.heading2,
+    fontFamily: font.family.heading,
+    fontWeight: font.weight.heading,
+    lineHeight: lineHeight.heading2,
+  },
+  h3: {
+    fontSize: font.size.heading3,
+    fontFamily: font.family.heading,
+    fontWeight: font.weight.heading,
+    lineHeight: lineHeight.heading3,
+  },
+  body: {
+    fontSize: font.size.body,
+    lineHeight: lineHeight.body,
+  },
+  body_s: {
+    fontSize: font.size.bodyS,
+    lineHeight: lineHeight.bodyS,
+  },
+});
+
+const accessibilityRoles: Record<TypographyVariant, 'header' | 'text'> = {
+  h1: 'header',
+  h2: 'header',
+  h3: 'header',
+  body: 'text',
+  body_s: 'text',
+};
+
+export function Typography({ variant = 'body', children, style }: TypographyProps) {
+  const { colors } = useTheme();
+  return (
+    <Text
+      accessibilityRole={accessibilityRoles[variant]}
+      style={[styles.base, styles[variant], { color: colors.colorOnBg }, style]}
+    >
+      {children}
+    </Text>
+  );
+}

package/src/components/ui/Typography/Typography.stories.tsx

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { Typography } from './Typography';
 
 const meta = {
-  title: 'UI/Typography',
+  title: 'React/UI/Typography',
   component: Typography,
   argTypes: {
     variant: { control: 'select', options: ['h1', 'h2', 'h3', 'body', 'body_s'] },

package/src/components/ui/Typography/Typography.tsx

@@ -1,14 +1,14 @@
 import { ReactNode, ElementType } from 'react';
 import css from './Typography.module.css';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../types';
 
 type TypographyVariant = 'h1' | 'h2' | 'h3' | 'body' | 'body_s';
 
-interface TypographyProps {
+interface TypographyProps extends WithClassName {
   variant?: TypographyVariant;
   component?: ElementType;
   children: ReactNode;
-  className?: string;
 }
 
 const variantToElement: Record<TypographyVariant, ElementType> = {

package/src/css/bdc.css

@@ -55,6 +55,14 @@
     --bdc_color--focus: var(--bds-color_interactive);
     --bdc_color--error: var(--bds-color_error);
 
+    /* Active / selected state colours — override these to theme all filled form controls globally */
+    --bdc-color_active:            var(--bds-color_green);
+    --bdc-color_on-active:         var(--bds-color_on-green);
+    --bdc-color_active--subtle:    var(--bds-color_green--subtle);
+    --bdc-color_on-active--subtle: var(--bds-color_on-green--subtle);
+    --bdc-color_active--strong:    var(--bds-color_green--strong);
+    --bdc-color_on-active--strong: var(--bds-color_on-green--strong);
+
     /* Outline geometry */
     --bdc-outline_width:  1px;
     --bdc-outline_offset: -1px; /* inset — appears inside the element like a traditional border */

package/src/index.ts

@@ -73,3 +73,4 @@ export type { IconWrapperProps } from './components/layout/IconWrapper';
 
 // Utilities
 export { cn } from '@boostdev/design-system-foundation';
+export type { WithClassName } from './types';

package/src/native/ThemeContext.tsx

@@ -0,0 +1,28 @@
+import { createContext, ReactNode, useContext, useMemo } from 'react';
+import { useColorScheme } from 'react-native';
+import { colors } from './tokens';
+
+type ThemeColors = typeof colors.light | typeof colors.dark;
+
+interface ThemeContextValue {
+  colors: ThemeColors;
+  isDark: boolean;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const scheme = useColorScheme();
+  const isDark = scheme === 'dark';
+  const value = useMemo<ThemeContextValue>(
+    () => ({ colors: isDark ? colors.dark : colors.light, isDark }),
+    [isDark],
+  );
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error('useTheme must be used within ThemeProvider');
+  return ctx;
+}

package/src/native/tokens.ts

@@ -0,0 +1,13 @@
+import { colors, spacing, font, border, zIndex, animation } from '@boostdev/design-system-foundation/native';
+
+export { colors, spacing, font, border, zIndex, animation };
+
+/** Absolute lineHeight values for React Native (ratio × fontSize). */
+export const lineHeight = {
+  display: Math.round(font.size.display * font.lineHeight.display),
+  heading1: Math.round(font.size.heading1 * font.lineHeight.heading),
+  heading2: Math.round(font.size.heading2 * font.lineHeight.heading),
+  heading3: Math.round(font.size.heading3 * font.lineHeight.heading),
+  body: Math.round(font.size.body * font.lineHeight.body),
+  bodyS: Math.round(font.size.bodyS * font.lineHeight.body),
+} as const;

package/src/native.ts

@@ -0,0 +1,39 @@
+// React Native component barrel
+// Explicitly imports *.native.tsx variants so tsup compiles them into dist/native/index.js.
+// Metro resolves this via the "react-native" export condition in package.json.
+
+// Infrastructure
+export { ThemeProvider, useTheme } from './native/ThemeContext';
+
+// UI
+export { Typography } from './components/ui/Typography/Typography.native';
+export { Badge } from './components/ui/Badge/Badge.native';
+export { Avatar } from './components/ui/Avatar/Avatar.native';
+export { Separator } from './components/ui/Separator/Separator.native';
+export { Loading } from './components/ui/Loading/Loading.native';
+export { Progress } from './components/ui/Progress/Progress.native';
+export { Skeleton } from './components/ui/Skeleton/Skeleton.native';
+export { Alert } from './components/ui/Alert/Alert.native';
+export { NotificationBanner } from './components/ui/NotificationBanner/NotificationBanner.native';
+
+// Layout
+export { Card } from './components/layout/Card/Card.native';
+export { SectionHeader } from './components/layout/SectionHeader/SectionHeader.native';
+export { IconWrapper } from './components/layout/IconWrapper/IconWrapper.native';
+export type { IconWrapperProps } from './components/layout/IconWrapper/IconWrapper.native';
+export { ButtonGroup } from './components/layout/ButtonGroup/ButtonGroup.native';
+export type { ButtonGroupProps } from './components/layout/ButtonGroup/ButtonGroup.native';
+
+// Interaction
+export { Button } from './components/interaction/Button/Button.native';
+export type { ButtonProps } from './components/interaction/Button/Button.native';
+export { Switch } from './components/interaction/form/Switch/Switch.native';
+export { Checkbox } from './components/interaction/form/Checkbox/Checkbox.native';
+export { Radio } from './components/interaction/form/Radio/Radio.native';
+
+// Atoms
+export { Label } from './components/interaction/form/atoms/Label.native';
+export { Message } from './components/interaction/form/atoms/Message.native';
+
+// Tokens (re-exported for convenience)
+export { colors, spacing, font, border, zIndex, animation, lineHeight } from './native/tokens';

package/src/react-augment.d.ts

@@ -0,0 +1,13 @@
+// This file MUST be a module (not a global script) so that `declare module 'react'`
+// is treated as an augmentation that merges with @types/react rather than as an
+// ambient module declaration that would shadow @types/react entirely.
+// The `export {}` below is what makes TypeScript treat this as a module.
+export {};
+
+// CSS Anchor Positioning properties — not yet in React's CSSProperties types.
+declare module 'react' {
+  interface CSSProperties {
+    anchorName?: string;
+    positionAnchor?: string;
+  }
+}

package/src/stories/DesignSystem/DarkMode.mdx

@@ -0,0 +1,130 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Dark Mode" />
+
+# Dark Mode
+
+All components adapt to dark mode automatically. No extra CSS imports or component changes are needed — switching the theme updates every token at once.
+
+## How it works
+
+The design system foundation ships two sets of semantic tokens: one for light mode and one for dark mode. When dark mode is active, the `--bds-color_*` tokens remap to their dark counterparts. Because every component is built on these tokens, the entire UI responds in a single cascade update.
+
+## Enabling dark mode
+
+### Via `data-theme` attribute (recommended)
+
+Set `data-theme="dark"` on a container element — typically `<html>` for a global switch, or any wrapper for a scoped one.
+
+```html
+<!-- global dark mode -->
+<html data-theme="dark">
+
+<!-- scoped dark mode (only this subtree) -->
+<div data-theme="dark">
+  <Button>Dark button</Button>
+</div>
+```
+
+Remove the attribute (or set `data-theme="light"`) to return to light mode.
+
+### Via `prefers-color-scheme` (automatic)
+
+No attribute needed. When a user has dark mode enabled at the OS level, the design system tokens switch automatically:
+
+```css
+/* this is built into @boostdev/design-system-foundation — nothing to add */
+@media (prefers-color-scheme: dark) {
+  :root { /* dark token values */ }
+}
+```
+
+`data-theme` always takes precedence over `prefers-color-scheme`, so you can override the system preference.
+
+## Building a theme toggle
+
+A minimal React hook that syncs with the system preference and lets the user override it:
+
+```tsx
+import { useEffect, useState } from 'react';
+
+type Theme = 'light' | 'dark';
+
+function getSystemTheme(): Theme {
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+export function useTheme() {
+  const [theme, setTheme] = useState<Theme>(
+    () => (localStorage.getItem('theme') as Theme) ?? getSystemTheme()
+  );
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', theme);
+    localStorage.setItem('theme', theme);
+  }, [theme]);
+
+  const toggle = () => setTheme(t => (t === 'dark' ? 'light' : 'dark'));
+
+  return { theme, toggle };
+}
+```
+
+Usage:
+
+```tsx
+function ThemeToggle() {
+  const { theme, toggle } = useTheme();
+  return (
+    <Button onClick={toggle}>
+      {theme === 'dark' ? 'Switch to light' : 'Switch to dark'}
+    </Button>
+  );
+}
+```
+
+## Customising tokens in dark mode
+
+Override any token in `@layer tokens.override` — the rule applies regardless of the active theme unless you scope it:
+
+```css
+@import "@boostdev/design-system-foundation/css";
+
+/* override for all themes */
+@layer tokens.override {
+  :root {
+    --bds-color_green: oklch(60% 0.15 145);
+  }
+}
+
+/* override for dark mode only */
+@layer tokens.override {
+  [data-theme="dark"],
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      --bds-color_green: oklch(75% 0.15 145);
+    }
+  }
+}
+```
+
+## Component-level dark mode overrides
+
+Use component CSS variables to restyle a specific component in dark mode without touching global tokens:
+
+```css
+/* make all Tooltips use a high-contrast dark style in both themes */
+.my-app {
+  --tooltip_bg: #1a1a1a;
+  --tooltip_text: #f5f5f5;
+}
+
+/* only override in dark mode */
+[data-theme="dark"] .my-card {
+  --card_color: #1e1e1e;
+}
+```
+
+## Testing dark mode in Storybook
+
+Use the **Theme** toolbar toggle in the top bar to switch between light and dark mode while browsing stories. This sets `data-theme` on the story canvas root.

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.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>
+  ),
+};