@boostdev/design-system-react-native 0.1.0 → 0.2.1

package/src/native/ReactNavigationTheme.mdx

@@ -0,0 +1,140 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Theming/React Navigation" />
+
+# Theming
+
+`@boostdev/design-system-react-native` is designed to work two ways:
+
+1. **Standalone** — wrap in `ThemeProvider` and use components directly. No other dependencies.
+2. **Alongside React Navigation** — opt into a bridge that produces a React Navigation–compatible `Theme` from the same foundation tokens.
+
+Both paths share the same source of truth: tokens from `@boostdev/design-system-foundation`. The mapping from those tokens to React Navigation's `Theme` shape lives in this repo, not the foundation.
+
+---
+
+## Standalone
+
+```tsx
+import { ThemeProvider, useTheme, Button } from '@boostdev/design-system-react-native';
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      <Button onPress={() => {}}>Press me</Button>
+    </ThemeProvider>
+  );
+}
+```
+
+`ThemeProvider` auto-detects the system color scheme via React Native's `useColorScheme`. Force a scheme with `colorScheme="light" | "dark"`.
+
+Inside the tree:
+
+```tsx
+const { colors, isDark } = useTheme();
+```
+
+`colors` is the full foundation token palette (`colorBg`, `colorOnBg`, `colorInteractive`, …) — a superset of what React Navigation expects.
+
+---
+
+## React Navigation bridge
+
+`@react-navigation/native` is an **optional** peer dependency. You only need to install it if you use the bridge.
+
+### `useReactNavigationTheme()` — when wrapped in `ThemeProvider`
+
+```tsx
+import { NavigationContainer } from '@react-navigation/native';
+import { ThemeProvider, useReactNavigationTheme } from '@boostdev/design-system-react-native';
+
+function NavRoot({ children }) {
+  const theme = useReactNavigationTheme();
+  return <NavigationContainer theme={theme}>{children}</NavigationContainer>;
+}
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      <NavRoot>{/* screens */}</NavRoot>
+    </ThemeProvider>
+  );
+}
+```
+
+Reflects light/dark switches automatically. Accepts optional `{ colors, fonts }` overrides.
+
+### `createReactNavigationTheme()` — pure builder
+
+```tsx
+import { createReactNavigationTheme } from '@boostdev/design-system-react-native';
+
+const lightTheme = createReactNavigationTheme({ dark: false });
+const darkTheme = createReactNavigationTheme({ dark: true });
+
+const branded = createReactNavigationTheme({
+  dark: false,
+  colors: { primary: '#ff5500' },
+});
+```
+
+Use this when you do not wrap in `ThemeProvider`, or when you need a theme outside React (tests, navigators created at module scope, etc.).
+
+### Options
+
+| Option   | Type                                  | Description                                                              |
+| -------- | ------------------------------------- | ------------------------------------------------------------------------ |
+| `dark`   | `boolean`                             | Selects the dark token set. Default `false`.                             |
+| `tokens` | foundation `colors.light` shape       | Bring your own token set. Defaults to the foundation's built-in palette. |
+| `colors` | `Partial<ReactNavigationThemeColors>` | Override individual Navigation colors.                                   |
+| `fonts`  | `Partial<ReactNavigationThemeFonts>`  | Override individual Navigation font styles.                              |
+
+### Token mapping
+
+The bridge maps foundation tokens to React Navigation's six-color palette:
+
+| React Navigation | Foundation token                                |
+| ---------------- | ----------------------------------------------- |
+| `primary`        | `colorInteractive`                              |
+| `background`     | `colorBg`                                       |
+| `card`           | `colorBgSubtle`                                 |
+| `text`           | `colorOnBg`                                     |
+| `border`         | `palette.grey200` (light) / `grey700` (dark)    |
+| `notification`   | `colorError`                                    |
+
+Fonts use `font.family.body` with weights from `font.weight` (`body`, `medium`, `bold`, `heading`).
+
+---
+
+## Custom themes
+
+Author a token set matching the foundation's `colors.light` / `colors.dark` shape, then pass it through the bridge:
+
+```tsx
+import { createReactNavigationTheme } from '@boostdev/design-system-react-native';
+import { colors } from '@boostdev/design-system-foundation/native';
+
+const myTokens = { ...colors.light, colorInteractive: '#ff5500' };
+const theme = createReactNavigationTheme({ tokens: myTokens, dark: false });
+```
+
+The foundation package stays untouched — all theme assembly lives in this repo.
+
+### Brand overrides flow through automatically
+
+`useReactNavigationTheme()` reads the colors from `ThemeProvider`, so any `tokens`
+overrides you pass there (e.g. a brand `colorInteractive`) are reflected in the
+navigation theme's `primary`, `background`, `card`, `text` and `notification`
+colors without extra wiring. With expo-router, pass the result to
+`ThemeProvider` from `@react-navigation/native` in your root layout:
+
+```tsx
+import { ThemeProvider as NavThemeProvider } from '@react-navigation/native';
+import { useReactNavigationTheme } from '@boostdev/design-system-react-native';
+
+function RootNavigationTheme({ children }: { children: React.ReactNode }) {
+  const navTheme = useReactNavigationTheme();
+  return <NavThemeProvider value={navTheme}>{children}</NavThemeProvider>;
+}
+```

package/src/native/ReactNavigationTheme.spec.tsx

@@ -0,0 +1,35 @@
+import { render, screen } from '@testing-library/react';
+import { Text } from 'react-native';
+import { colors } from './tokens';
+import { ThemeProvider } from './ThemeContext';
+import { createReactNavigationTheme, useReactNavigationTheme } from './ReactNavigationTheme';
+
+function NavProbe() {
+  const theme = useReactNavigationTheme();
+  return (
+    <>
+      <Text testID="primary">{theme.colors.primary}</Text>
+      <Text testID="dark">{String(theme.dark)}</Text>
+    </>
+  );
+}
+
+describe('useReactNavigationTheme', () => {
+  it('maps ThemeProvider token overrides into the nav theme primary color', () => {
+    render(
+      <ThemeProvider tokens={{ light: { colorInteractive: '#00c853' } }}>
+        <NavProbe />
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('primary')).toHaveTextContent('#00c853');
+    expect(screen.getByTestId('dark')).toHaveTextContent('false');
+  });
+});
+
+describe('createReactNavigationTheme', () => {
+  it('builds from foundation colors when no tokens passed', () => {
+    const theme = createReactNavigationTheme();
+    expect(theme.colors.primary).toBe(colors.light.colorInteractive);
+    expect(theme.dark).toBe(false);
+  });
+});

package/src/native/ReactNavigationTheme.ts

@@ -0,0 +1,102 @@
+import { palette, colors as foundationColors, font } from '@boostdev/design-system-foundation/native';
+import { useTheme, type ThemeColors } from './ThemeContext';
+
+export interface ReactNavigationFontStyle {
+  fontFamily: string;
+  fontWeight:
+    | 'normal'
+    | 'bold'
+    | '100'
+    | '200'
+    | '300'
+    | '400'
+    | '500'
+    | '600'
+    | '700'
+    | '800'
+    | '900';
+}
+
+export interface ReactNavigationThemeColors {
+  primary: string;
+  background: string;
+  card: string;
+  text: string;
+  border: string;
+  notification: string;
+}
+
+export interface ReactNavigationThemeFonts {
+  regular: ReactNavigationFontStyle;
+  medium: ReactNavigationFontStyle;
+  bold: ReactNavigationFontStyle;
+  heavy: ReactNavigationFontStyle;
+}
+
+export interface ReactNavigationTheme {
+  dark: boolean;
+  colors: ReactNavigationThemeColors;
+  fonts: ReactNavigationThemeFonts;
+}
+
+export interface CreateReactNavigationThemeOptions {
+  dark?: boolean;
+  tokens?: ThemeColors;
+  colors?: Partial<ReactNavigationThemeColors>;
+  fonts?: Partial<ReactNavigationThemeFonts>;
+}
+
+function mapColors(tokens: ThemeColors, dark: boolean): ReactNavigationThemeColors {
+  return {
+    primary: tokens.colorInteractive,
+    background: tokens.colorBg,
+    card: tokens.colorBgSubtle,
+    text: tokens.colorOnBg,
+    border: dark ? palette.grey700 : palette.grey200,
+    notification: tokens.colorError,
+  };
+}
+
+function mapFonts(): ReactNavigationThemeFonts {
+  const family = font.family.body;
+  return {
+    regular: { fontFamily: family, fontWeight: String(font.weight.body) as ReactNavigationFontStyle['fontWeight'] },
+    medium: { fontFamily: family, fontWeight: String(font.weight.medium) as ReactNavigationFontStyle['fontWeight'] },
+    bold: { fontFamily: family, fontWeight: String(font.weight.bold) as ReactNavigationFontStyle['fontWeight'] },
+    heavy: { fontFamily: family, fontWeight: String(font.weight.heading) as ReactNavigationFontStyle['fontWeight'] },
+  };
+}
+
+/**
+ * Pure builder. Produces a React Navigation–compatible theme from the design
+ * system foundation tokens. Use this when you are not wrapping in our
+ * `ThemeProvider`, or when you need a theme outside React.
+ */
+export function createReactNavigationTheme(
+  options: CreateReactNavigationThemeOptions = {},
+): ReactNavigationTheme {
+  const dark = options.dark ?? false;
+  const tokens = options.tokens ?? (dark ? foundationColors.dark : foundationColors.light);
+  return {
+    dark,
+    colors: { ...mapColors(tokens, dark), ...options.colors },
+    fonts: { ...mapFonts(), ...options.fonts },
+  };
+}
+
+/**
+ * Hook variant. Reads from the design system's `ThemeProvider` and returns a
+ * React Navigation–compatible theme. Pass the result directly to
+ * `<NavigationContainer theme={...} />`.
+ */
+export function useReactNavigationTheme(
+  overrides: Pick<CreateReactNavigationThemeOptions, 'colors' | 'fonts'> = {},
+): ReactNavigationTheme {
+  const { colors: tokens, isDark } = useTheme();
+  return createReactNavigationTheme({
+    dark: isDark,
+    tokens,
+    colors: overrides.colors,
+    fonts: overrides.fonts,
+  });
+}

package/src/native/ThemeContext.spec.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from '@testing-library/react';
+import { Text } from 'react-native';
+import { colors } from './tokens';
+import { ThemeProvider, useTheme } from './ThemeContext';
+
+function Probe() {
+  const { colors: themeColors, isDark } = useTheme();
+  return (
+    <>
+      <Text testID="interactive">{themeColors.colorInteractive}</Text>
+      <Text testID="bg">{themeColors.colorBg}</Text>
+      <Text testID="mode">{isDark ? 'dark' : 'light'}</Text>
+    </>
+  );
+}
+
+describe('ThemeProvider token overrides', () => {
+  it('provides foundation colors when no overrides given', () => {
+    render(
+      <ThemeProvider>
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('interactive')).toHaveTextContent(colors.light.colorInteractive);
+    expect(screen.getByTestId('bg')).toHaveTextContent(colors.light.colorBg);
+  });
+
+  it('merges light overrides over the foundation light colors', () => {
+    render(
+      <ThemeProvider tokens={{ light: { colorInteractive: '#00c853' } }}>
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('interactive')).toHaveTextContent('#00c853');
+    // untouched tokens keep their foundation values
+    expect(screen.getByTestId('bg')).toHaveTextContent(colors.light.colorBg);
+  });
+
+  it('applies dark overrides when colorScheme is dark', () => {
+    render(
+      <ThemeProvider colorScheme="dark" tokens={{ dark: { colorInteractive: '#00c853' } }}>
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('mode')).toHaveTextContent('dark');
+    expect(screen.getByTestId('interactive')).toHaveTextContent('#00c853');
+  });
+
+  it('does not apply light overrides in the dark scheme', () => {
+    render(
+      <ThemeProvider colorScheme="dark" tokens={{ light: { colorInteractive: '#00c853' } }}>
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('interactive')).toHaveTextContent(colors.dark.colorInteractive);
+  });
+});

package/src/native/ThemeContext.tsx

@@ -0,0 +1,48 @@
+import { createContext, ReactNode, useContext, useMemo } from 'react';
+import { useColorScheme } from 'react-native';
+import { colors } from './tokens';
+
+export type ThemeColorName = keyof typeof colors.light;
+
+/** Semantic theme colors, widened to `string` so brand overrides typecheck. */
+export type ThemeColors = Readonly<Record<ThemeColorName, string>>;
+
+/**
+ * Per-scheme token overrides, merged over the foundation colors.
+ * The React Native equivalent of overriding tokens in the web
+ * `boostdev.tokens.override` CSS layer.
+ */
+export interface ThemeTokenOverrides {
+  light?: Partial<Record<ThemeColorName, string>>;
+  dark?: Partial<Record<ThemeColorName, string>>;
+}
+
+interface ThemeContextValue {
+  colors: ThemeColors;
+  isDark: boolean;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+interface ThemeProviderProps {
+  children: ReactNode;
+  colorScheme?: 'light' | 'dark';
+  tokens?: ThemeTokenOverrides;
+}
+
+export function ThemeProvider({ children, colorScheme, tokens }: ThemeProviderProps) {
+  const systemScheme = useColorScheme();
+  const isDark = (colorScheme ?? systemScheme) === 'dark';
+  const value = useMemo<ThemeContextValue>(() => {
+    const base = isDark ? colors.dark : colors.light;
+    const overrides = isDark ? tokens?.dark : tokens?.light;
+    return { colors: { ...base, ...overrides }, isDark };
+  }, [isDark, tokens]);
+  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/test/setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';