@boostdev/design-system-components 1.0.3 → 1.1.1

package/src/components/interaction/Toast/Toast.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, createContext, useContext, ReactNode, useCallback, useMemo } from 'react';
+import { useState, useEffect, createContext, useContext, ReactNode, useCallback, useMemo, useRef } from 'react';
 import css from './Toast.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 
@@ -18,6 +18,7 @@ const ToastContext = createContext<ToastContextType | undefined>(undefined);
 
 export function ToastProvider({ children }: { children: ReactNode }) {
   const [toasts, setToasts] = useState<Toast[]>([]);
+  const containerRef = useRef<HTMLDivElement>(null);
 
   const showToast = useCallback((message: string, variant: ToastVariant) => {
     const id = Math.random().toString(36).substring(2, 9);
@@ -28,12 +29,31 @@ export function ToastProvider({ children }: { children: ReactNode }) {
     setToasts(prev => prev.filter(toast => toast.id !== id));
   }, []);
 
+  // Sync the popover's top-layer visibility with the toast queue.
+  // showPopover() is a no-op when already open (safe to call multiple times).
+  // hidePopover() throws InvalidStateError when already hidden, so catch silently.
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    if (toasts.length > 0) {
+      container.showPopover?.();
+    } else {
+      try { container.hidePopover?.(); } catch { /* already hidden on initial mount */ }
+    }
+  }, [toasts.length]);
+
   const value = useMemo(() => ({ showToast }), [showToast]);
 
   return (
     <ToastContext.Provider value={value}>
       {children}
-      <div className={css.toastContainer}>
+      <div
+        ref={containerRef}
+        popover="manual"
+        role="region"
+        aria-label="Notifications"
+        className={css.toastContainer}
+      >
         {toasts.map(toast => (
           <ToastItem
             key={toast.id}

package/src/components/interaction/form/Checkbox/Checkbox.mdx

@@ -44,8 +44,8 @@ Binary toggle for opt-in/opt-out choices. Renders a styled native `<input type="
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--checkbox_color-active`</td><td>`var(--bds-active)`</td><td>Checked background</td></tr>
-<tr><td>`--checkbox_color-on-active`</td><td>`var(--bds-on-active)`</td><td>Checkmark colour</td></tr>
+<tr><td>`--checkbox_color-active`</td><td>`var(--bdc-color_active)`</td><td>Checked background</td></tr>
+<tr><td>`--checkbox_color-on-active`</td><td>`var(--bdc-color_on-active)`</td><td>Checkmark colour</td></tr>
 </tbody>
 </table>
 

package/src/components/interaction/form/Checkbox/Checkbox.module.css

@@ -14,8 +14,8 @@
 
   .checkbox {
     margin-block-start: 0.25em;
-    width: var(--inputSize);
-    height: var(--inputSize);
+    inline-size: var(--inputSize);
+    block-size: var(--inputSize);
     color: var(--checkbox_color, var(--bds-color_on-bg));
     border: var(--checkbox_border, none);
     --bdc_color: currentcolor;
@@ -33,18 +33,18 @@
   }
 
   .checkbox:checked {
-    background-color: var(--checkbox_color-active, var(--bds-color_green));
-    --bdc_color: var(--checkbox_color-active, var(--bds-color_green));
+    background-color: var(--checkbox_color-active, var(--bdc-color_active));
+    --bdc_color: var(--checkbox_color-active, var(--bdc-color_active));
   }
 
   .checkbox:checked::after {
     content: '';
     position: absolute;
-    left: 0.6em;
-    top: 0.2em;
-    width: 0.5em;
-    height: 1em;
-    border: solid var(--checkbox_color-on-active, var(--bds-color_on-green));
+    inset-inline-start: 0.6em;
+    inset-block-start: 0.2em;
+    inline-size: 0.5em;
+    block-size: 1em;
+    border: solid var(--checkbox_color-on-active, var(--bdc-color_on-active));
     border-width: 0 2px 2px 0;
     transform: rotate(45deg);
   }

package/src/components/interaction/form/Checkbox/Checkbox.native.mdx

@@ -0,0 +1,74 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Checkbox.native.stories';
+
+<Meta of={Stories} />
+
+# Checkbox (React Native)
+
+React Native checkbox component with label, optional hint, and error state. Fully controlled — manage checked state via `checked` + `onChange`.
+
+> **Status: alpha** — API may change before stable release.
+
+## Usage
+
+```tsx
+import { Checkbox } from '@boostdev/components';
+import { useState } from 'react';
+
+function Example() {
+  const [checked, setChecked] = useState(false);
+  return (
+    <Checkbox
+      name="terms"
+      label="Accept terms and conditions"
+      checked={checked}
+      onChange={setChecked}
+    />
+  );
+}
+```
+
+## Examples
+
+### Interactive
+<Canvas of={Stories.Interactive} />
+
+### Unchecked
+<Canvas of={Stories.Unchecked} />
+
+### Checked
+<Canvas of={Stories.Checked} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+### Disabled + checked
+<Canvas of={Stories.DisabledChecked} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Props reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | string | — | Field name (used for accessibility grouping) |
+| `label` | string | — | Visible label text |
+| `checked` | boolean | `false` | Controlled checked state |
+| `onChange` | `(checked: boolean) => void` | — | Called with the new value on press |
+| `disabled` | boolean | `false` | Prevents interaction, reduces opacity |
+| `hint` | string | — | Helper text below the label |
+| `error` | string | — | Error message; shown instead of hint when set |
+
+## Accessibility
+
+- The label, hint, and error are announced together by screen readers
+- `disabled` communicates the disabled state via `accessibilityState`
+- Group related checkboxes using a wrapping `View` with `accessibilityRole="radiogroup"` or a labelled `fieldset` equivalent

package/src/components/interaction/form/Checkbox/Checkbox.native.spec.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from '@testing-library/react';
+import { ThemeProvider } from '../../../../native/ThemeContext';
+import { Checkbox } from './Checkbox.native';
+
+function renderWithTheme(ui: React.ReactElement) {
+  return render(<ThemeProvider>{ui}</ThemeProvider>);
+}
+
+describe('Checkbox (native)', () => {
+  it('has checkbox role with label', () => {
+    renderWithTheme(<Checkbox label="Accept terms" name="terms" />);
+    expect(screen.getByRole('checkbox', { name: 'Accept terms' })).toBeInTheDocument();
+  });
+
+  it('shows the checkmark when checked', () => {
+    renderWithTheme(<Checkbox label="Accept terms" name="terms" checked={true} />);
+    expect(screen.getByText('✓')).toBeInTheDocument();
+  });
+
+  it('hides the checkmark when unchecked', () => {
+    renderWithTheme(<Checkbox label="Accept terms" name="terms" checked={false} />);
+    expect(screen.queryByText('✓')).not.toBeInTheDocument();
+  });
+
+  it('checkmark uses theme color (contrast regression: was hardcoded #fff)', () => {
+    // Previously the checkmark had color: '#fff' hardcoded in the StyleSheet.
+    // Now it uses colors.colorOnInteractive from the theme, which is #000 in dark
+    // mode — fixing the 2.52:1 contrast failure on the dark interactive blue.
+    renderWithTheme(<Checkbox label="Accept terms" name="terms" checked={true} />);
+    const checkmark = screen.getByText('✓');
+    // The color must be applied as an inline style (overrides StyleSheet), not absent.
+    // In light mode colorOnInteractive=#fff; in dark mode it is #000.
+    expect(checkmark.style.color).toBeTruthy();
+  });
+
+  it('renders with error message', () => {
+    renderWithTheme(
+      <Checkbox label="Accept terms" name="terms" error="You must accept." />,
+    );
+    expect(screen.getByRole('alert')).toHaveTextContent('You must accept.');
+  });
+});

package/src/components/interaction/form/Checkbox/Checkbox.native.stories.tsx

@@ -0,0 +1,36 @@
+import React, { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider } from '../../../../native/ThemeContext';
+import { Checkbox } from './Checkbox.native';
+
+const meta = {
+  tags: ['!stable', 'alpha'],
+  title: 'React Native/Form/Checkbox',
+  component: Checkbox,
+  decorators: [(Story) => <ThemeProvider><Story /></ThemeProvider>],
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof Checkbox>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Unchecked: Story = { args: { label: 'Accept terms', name: 'terms', checked: false } };
+export const Checked: Story = { args: { label: 'Accept terms', name: 'terms', checked: true } };
+export const Disabled: Story = { args: { label: 'Accept terms', name: 'terms', disabled: true } };
+export const DisabledChecked: Story = { args: { label: 'Accept terms', name: 'terms', checked: true, disabled: true } };
+export const WithError: Story = {
+  args: { label: 'Accept terms', name: 'terms', error: 'You must accept the terms.' },
+};
+export const WithHint: Story = {
+  args: { label: 'Subscribe to newsletter', name: 'newsletter', hint: 'Max one email per week.' },
+};
+export const Interactive: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(false);
+    return (
+      <ThemeProvider>
+        <Checkbox label="Accept terms and conditions" name="terms" checked={checked} onChange={setChecked} />
+      </ThemeProvider>
+    );
+  },
+};

package/src/components/interaction/form/Checkbox/Checkbox.native.tsx

@@ -0,0 +1,80 @@
+import { ReactNode } from 'react';
+import { StyleSheet, View, Pressable, StyleProp, ViewStyle } from 'react-native';
+import { spacing, border } from '../../../../native/tokens';
+import { useTheme } from '../../../../native/ThemeContext';
+import { Label } from '../atoms/Label.native';
+import { Message } from '../atoms/Message.native';
+
+interface CheckboxProps {
+  label: ReactNode;
+  name: string;
+  checked?: boolean;
+  onChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  error?: string;
+  hint?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+const BOX = 22;
+
+const styles = StyleSheet.create({
+  container: {
+    gap: spacing.xxs,
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.xs,
+    minHeight: 44,
+  },
+  box: {
+    width: BOX,
+    height: BOX,
+    borderRadius: border.radius.xs,
+    borderWidth: 2,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  checkmark: {
+    fontSize: 14,
+    fontWeight: '700',
+    lineHeight: 16,
+  },
+});
+
+export function Checkbox({
+  label,
+  name,
+  checked = false,
+  onChange,
+  disabled = false,
+  error,
+  hint,
+  style,
+}: CheckboxProps) {
+  const { colors } = useTheme();
+
+  const borderColor = error ? colors.colorError : checked ? colors.colorInteractive : colors.colorBgSubtle;
+  const bgColor = checked ? colors.colorInteractive : 'transparent';
+
+  return (
+    <View style={[styles.container, style]}>
+      <Pressable
+        onPress={() => !disabled && onChange?.(!checked)}
+        accessibilityRole="checkbox"
+        accessibilityLabel={typeof label === 'string' ? label : name}
+        accessibilityState={{ checked, disabled }}
+        disabled={disabled}
+        style={({ pressed }) => [styles.row, pressed && { opacity: 0.7 }, disabled && { opacity: 0.4 }]}
+      >
+        <View style={[styles.box, { borderColor, backgroundColor: bgColor }]}>
+          {checked && <Label label="✓" style={[styles.checkmark, { color: colors.colorOnInteractive }]} />}
+        </View>
+        <Label label={label} />
+      </Pressable>
+      <Message type="error" message={error} />
+      <Message type="hint" message={hint} />
+    </View>
+  );
+}

package/src/components/interaction/form/Checkbox/Checkbox.stories.tsx

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

package/src/components/interaction/form/Checkbox/Checkbox.tsx

@@ -4,13 +4,13 @@ import { Message } from '../atoms/Message';
 import { Label } from '../atoms/Label';
 import { cn } from '@boostdev/design-system-foundation';
 import { InputContainer } from '../atoms/InputContainer';
+import type { WithClassName } from '../../../../types';
 
-interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
+interface CheckboxProps extends WithClassName, Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
   label: ReactNode;
   name: string;
   error?: string;
   hint?: string;
-  className?: string;
 }
 
 export function Checkbox({ label, name, error, hint, className, ...props }: CheckboxProps) {

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.mdx

@@ -0,0 +1,44 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './CheckboxGroup.stories';
+
+<Meta of={Stories} />
+
+# CheckboxGroup
+
+Groups multiple `Checkbox` inputs under a shared label. Renders a `<fieldset>` with a `<legend>` for accessible grouping.
+
+## When to use
+- Multi-select option sets where several choices can be active simultaneously
+- Any time two or more checkboxes share a common label or question
+
+## When not to use
+- A single independent toggle — use `Checkbox` on its own
+- Mutually exclusive choices — use `RadioGroup`
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### Required
+<Canvas of={Stories.Required} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Wraps checkboxes in a `<fieldset>` with a `<legend>` — screen readers announce the group label before each option
+- `disabled` on the group sets the HTML `disabled` attribute on the `<fieldset>`, which disables all child inputs
+- `aria-required` is set on the `<fieldset>` when `required` is true
+- Error and hint messages are linked via `aria-describedby`

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.stories.tsx

@@ -3,7 +3,7 @@ import { Checkbox } from '../Checkbox';
 import { CheckboxGroup } from './CheckboxGroup';
 
 const meta = {
-  title: 'Form/CheckboxGroup',
+  title: 'React/Form/CheckboxGroup',
   component: CheckboxGroup,
 } satisfies Meta<typeof CheckboxGroup>;
 

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.tsx

@@ -2,15 +2,15 @@ import { ReactNode, useId } from 'react';
 import css from './CheckboxGroup.module.css';
 import { Message } from '../atoms/Message';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../../types';
 
-export interface CheckboxGroupProps {
+export interface CheckboxGroupProps extends WithClassName {
   legend: string;
   children: ReactNode;
   error?: string;
   hint?: string;
   required?: boolean;
   disabled?: boolean;
-  className?: string;
 }
 
 export function CheckboxGroup({

package/src/components/interaction/form/Combobox/Combobox.mdx

@@ -29,6 +29,27 @@ Searchable select with type-ahead filtering. Combines a text input with a dropdo
 
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--combobox_color_bg`</td><td>`var(--bds-color_bg)`</td><td>Input background colour</td></tr>
+<tr><td>`--combobox_color`</td><td>`var(--bds-color_on-bg)`</td><td>Input text colour</td></tr>
+<tr><td>`--combobox_border`</td><td>`none`</td><td>Input border</td></tr>
+<tr><td>`--combobox_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Input corner radius</td></tr>
+<tr><td>`--combobox_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Input box shadow</td></tr>
+<tr><td>`--combobox_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Dropdown list text colour</td></tr>
+<tr><td>`--combobox_listbox-border`</td><td>`none`</td><td>Dropdown list border</td></tr>
+<tr><td>`--combobox_listbox-radius`</td><td>`var(--bdc-outline_radius)`</td><td>Dropdown list corner radius</td></tr>
+<tr><td>`--combobox_listbox-shadow`</td><td>`var(--bds-shadow_m)`</td><td>Dropdown list box shadow</td></tr>
+</tbody>
+</table>
+
+
 ## Accessibility
 
 - Input uses `role="combobox"` with `aria-autocomplete="list"` and `aria-controls`

package/src/components/interaction/form/Combobox/Combobox.module.css

@@ -12,7 +12,7 @@
 
   .input {
     appearance: none;
-    width: 100%;
+    inline-size: 100%;
     font-family: var(--bds-font_family--body);
     font-size: var(--bds-font_size--body);
     padding: var(--bds-space_s);
@@ -59,18 +59,17 @@
   }
 
   .chevron svg {
-    width: 1rem;
-    height: 1rem;
+    inline-size: 1rem;
+    block-size: 1rem;
   }
 
   .listbox {
     position: absolute;
-    top: calc(100% + var(--bds-space_xxs));
-    left: 0;
-    right: 0;
+    inset-block-start: calc(100% + var(--bds-space_xxs));
+    inset-inline: 0;
     z-index: var(--bds-z-index_dropdown);
-    max-height: 15rem;
-    overflow-y: auto;
+    max-block-size: 15rem;
+    overflow-block: auto;
     list-style: none;
     margin: 0;
     padding: var(--bds-space_xxs) 0;
@@ -98,7 +97,7 @@
 
   .option.--highlighted {
     background-color: var(--bds-color_bg--subtle);
-    color: var(--bds-color_interactive);
+    color: var(--bds-color_interactive_on-bg);
   }
 
   .option.--selected {

package/src/components/interaction/form/Combobox/Combobox.stories.tsx

@@ -12,7 +12,7 @@ const options = [
 ];
 
 const meta = {
-  title: 'Form/Combobox',
+  title: 'React/Form/Combobox',
   component: Combobox,
 } satisfies Meta<typeof Combobox>;
 

package/src/components/interaction/form/Combobox/Combobox.tsx

@@ -13,6 +13,7 @@ import { cn } from '@boostdev/design-system-foundation';
 import { InputContainer } from '../atoms/InputContainer';
 import { Label } from '../atoms/Label';
 import { Message } from '../atoms/Message';
+import type { WithClassName } from '../../../../types';
 
 export interface ComboboxOption {
   value: string;
@@ -20,7 +21,7 @@ export interface ComboboxOption {
   disabled?: boolean;
 }
 
-interface ComboboxProps {
+interface ComboboxProps extends WithClassName {
   label: ReactNode;
   name: string;
   options: ComboboxOption[];
@@ -30,7 +31,6 @@ interface ComboboxProps {
   disabled?: boolean;
   error?: string;
   hint?: string;
-  className?: string;
 }
 
 export function Combobox({

package/src/components/interaction/form/FileInput/FileInput.mdx

@@ -31,6 +31,20 @@ File upload input with styled trigger button, hint, and error support.
 
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--fileInput_color`</td><td>`var(--bds-color_on-bg)`</td><td>Text colour</td></tr>
+<tr><td>`--fileInput_border-color`</td><td>`currentcolor`</td><td>Drop zone border colour</td></tr>
+</tbody>
+</table>
+
+
 ## Accessibility
 
 - Native `<input type="file">` — opens the OS file picker

package/src/components/interaction/form/FileInput/FileInput.module.css

@@ -48,8 +48,8 @@
   }
 
   .icon {
-    width: 2rem;
-    height: 2rem;
+    inline-size: 2rem;
+    block-size: 2rem;
     flex-shrink: 0;
   }
 
@@ -59,7 +59,7 @@
   }
 
   .prompt strong {
-    color: var(--bds-color_interactive);
+    color: var(--bds-color_interactive_on-bg);
     font-weight: var(--bds-font_weight--semibold);
   }
 
@@ -70,8 +70,8 @@
 
   .hiddenInput {
     position: absolute;
-    width: 1px;
-    height: 1px;
+    inline-size: 1px;
+    block-size: 1px;
     overflow: hidden;
     clip: rect(0, 0, 0, 0);
     white-space: nowrap;

package/src/components/interaction/form/FileInput/FileInput.stories.tsx

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

package/src/components/interaction/form/FileInput/FileInput.tsx

@@ -3,8 +3,9 @@ import css from './FileInput.module.css';
 import { Message } from '../atoms/Message';
 import { InputContainer } from '../atoms/InputContainer';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../../types';
 
-interface FileInputProps {
+interface FileInputProps extends WithClassName {
   label: string;
   name: string;
   accept?: string;
@@ -14,7 +15,6 @@ interface FileInputProps {
   error?: string;
   hint?: string;
   onChange?: (files: FileList | null) => void;
-  className?: string;
 }
 
 export function FileInput({

package/src/components/interaction/form/FormInput/FormInput.stories.tsx

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

package/src/components/interaction/form/FormInput/FormInput.tsx

@@ -4,15 +4,15 @@ import { Label } from '../atoms/Label';
 import { Message } from '../atoms/Message';
 import { cn } from '@boostdev/design-system-foundation';
 import { InputContainer } from '../atoms/InputContainer';
+import type { WithClassName } from '../../../../types';
 
-interface FormInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
+interface FormInputProps extends WithClassName, Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
   label: ReactNode;
   name: string;
   type?: Exclude<HTMLInputTypeAttribute, 'checkbox' | 'radio' | 'file'>;
   ariaLabel?: string;
   error?: string;
   hint?: string;
-  className?: string;
 }
 
 export function FormInput({