@compsych/mobile-ui 1.0.10 → 1.0.13

package/src/theme/__tests__/ThemeProvider.test.tsx

@@ -0,0 +1,101 @@
+import React, { useContext } from 'react';
+
+import { Text } from 'react-native';
+
+import { render } from '@testing-library/react-native';
+
+import { sys } from '../../tokens';
+import { ThemeContext } from '../ThemeContext';
+import { ThemeProvider } from '../ThemeProvider';
+
+function ThemeConsumer() {
+  const theme = useContext(ThemeContext);
+  return (
+    <Text testID="primary-color">
+      {theme.colorRoles.accent.primary.sysPrimary}
+    </Text>
+  );
+}
+
+describe('ThemeProvider', () => {
+  it('renders children', () => {
+    const { getByText } = render(
+      <ThemeProvider>
+        <Text>hello</Text>
+      </ThemeProvider>,
+    );
+    expect(getByText('hello')).toBeTruthy();
+  });
+
+  it('provides the GuidanceNow default theme when no override is given', () => {
+    const { getByTestId } = render(
+      <ThemeProvider>
+        <ThemeConsumer />
+      </ThemeProvider>,
+    );
+    expect(getByTestId('primary-color').props.children).toBe(
+      sys.colorRoles.accent.primary.sysPrimary,
+    );
+  });
+
+  it('provides the merged custom theme when an override is supplied', () => {
+    const { getByTestId } = render(
+      <ThemeProvider
+        theme={{
+          colorRoles: { accent: { primary: { sysPrimary: '#c00000' } } },
+        }}
+      >
+        <ThemeConsumer />
+      </ThemeProvider>,
+    );
+    expect(getByTestId('primary-color').props.children).toBe('#c00000');
+  });
+
+  it('keeps default values for tokens not included in the override', () => {
+    function ErrorColorConsumer() {
+      const theme = useContext(ThemeContext);
+      return (
+        <Text testID="error-color">{theme.colorRoles.error.sysError}</Text>
+      );
+    }
+
+    const { getByTestId } = render(
+      <ThemeProvider
+        theme={{
+          colorRoles: { accent: { primary: { sysPrimary: '#c00000' } } },
+        }}
+      >
+        <ErrorColorConsumer />
+      </ThemeProvider>,
+    );
+    expect(getByTestId('error-color').props.children).toBe(
+      sys.colorRoles.error.sysError,
+    );
+  });
+
+  it('works correctly when nested — inner provider wins', () => {
+    function Consumer() {
+      const theme = useContext(ThemeContext);
+      return (
+        <Text testID="color">{theme.colorRoles.accent.primary.sysPrimary}</Text>
+      );
+    }
+
+    const { getByTestId } = render(
+      <ThemeProvider
+        theme={{
+          colorRoles: { accent: { primary: { sysPrimary: '#aaaaaa' } } },
+        }}
+      >
+        <ThemeProvider
+          theme={{
+            colorRoles: { accent: { primary: { sysPrimary: '#bbbbbb' } } },
+          }}
+        >
+          <Consumer />
+        </ThemeProvider>
+      </ThemeProvider>,
+    );
+    expect(getByTestId('color').props.children).toBe('#bbbbbb');
+  });
+});

package/src/theme/__tests__/defaultTheme.test.ts

@@ -0,0 +1,36 @@
+import { sys } from '../../tokens';
+import { defaultTheme } from '../defaultTheme';
+
+describe('defaultTheme', () => {
+  it('equals the GuidanceNow default token values', () => {
+    expect(defaultTheme).toEqual(sys);
+  });
+
+  it('exposes colorRoles tokens at the correct paths', () => {
+    expect(defaultTheme.colorRoles.accent.primary.sysPrimary).toBe(
+      sys.colorRoles.accent.primary.sysPrimary,
+    );
+    expect(defaultTheme.colorRoles.error.sysError).toBe(
+      sys.colorRoles.error.sysError,
+    );
+  });
+
+  it('exposes dimension tokens at the correct paths', () => {
+    expect(defaultTheme.dimensions.borderRadius.sysRadiusMd).toBe(
+      sys.dimensions.borderRadius.sysRadiusMd,
+    );
+  });
+
+  it('exposes typeScale tokens at the correct paths', () => {
+    expect(defaultTheme.typeScale.bodyMedium.sysFontSize).toBe(
+      sys.typeScale.bodyMedium.sysFontSize,
+    );
+  });
+
+  it('is typed as Theme — readable without a ThemeProvider in scope', () => {
+    // This is a compile-time check: accessing a property on the widened Theme type
+    // (not the narrow `as const` literal type) must not require a type cast.
+    const primary: string = defaultTheme.colorRoles.accent.primary.sysPrimary;
+    expect(typeof primary).toBe('string');
+  });
+});

package/src/theme/__tests__/mergeTheme.test.ts

@@ -0,0 +1,94 @@
+import { sys } from '../../tokens';
+import { mergeTheme } from '../mergeTheme';
+
+describe('mergeTheme', () => {
+  it('returns the default GuidanceNow theme when no override is provided', () => {
+    expect(mergeTheme()).toEqual(sys);
+  });
+
+  it('returns the default theme when override is undefined', () => {
+    expect(mergeTheme(undefined)).toEqual(sys);
+  });
+
+  it('overrides a single top-level color token', () => {
+    const result = mergeTheme({
+      colorRoles: { accent: { primary: { sysPrimary: '#c00000' } } },
+    });
+
+    expect(result.colorRoles.accent.primary.sysPrimary).toBe('#c00000');
+  });
+
+  it('preserves all non-overridden default values', () => {
+    const result = mergeTheme({
+      colorRoles: { accent: { primary: { sysPrimary: '#c00000' } } },
+    });
+
+    expect(result.colorRoles.accent.primary.sysOnPrimary).toBe(
+      sys.colorRoles.accent.primary.sysOnPrimary,
+    );
+    expect(result.colorRoles.error.sysError).toBe(
+      sys.colorRoles.error.sysError,
+    );
+    expect(result.dimensions.borderRadius.sysRadiusMd).toBe(
+      sys.dimensions.borderRadius.sysRadiusMd,
+    );
+    expect(result.typeScale.bodyMedium.sysFontSize).toBe(
+      sys.typeScale.bodyMedium.sysFontSize,
+    );
+  });
+
+  it('overrides a numeric dimension token', () => {
+    const result = mergeTheme({
+      dimensions: { borderRadius: { sysRadiusMd: 99 } },
+    });
+
+    expect(result.dimensions.borderRadius.sysRadiusMd).toBe(99);
+    expect(result.dimensions.borderRadius.sysRadiusSm).toBe(
+      sys.dimensions.borderRadius.sysRadiusSm,
+    );
+  });
+
+  it('overrides a typeScale token', () => {
+    const result = mergeTheme({
+      typeScale: { bodyMedium: { sysFontSize: 18 } },
+    });
+
+    expect(result.typeScale.bodyMedium.sysFontSize).toBe(18);
+    expect(result.typeScale.bodyMedium.sysLineHeight).toBe(
+      sys.typeScale.bodyMedium.sysLineHeight,
+    );
+  });
+
+  it('ignores null override values and keeps defaults', () => {
+    const result = mergeTheme({
+      colorRoles: {
+        accent: { primary: { sysPrimary: null as unknown as string } },
+      },
+    });
+
+    expect(result.colorRoles.accent.primary.sysPrimary).toBe(
+      sys.colorRoles.accent.primary.sysPrimary,
+    );
+  });
+
+  it('handles an empty override object without changing anything', () => {
+    const result = mergeTheme({});
+    expect(result).toEqual(sys);
+  });
+
+  it('handles deeply partial overrides spanning multiple branches', () => {
+    const result = mergeTheme({
+      colorRoles: { accent: { primary: { sysPrimary: '#aabbcc' } } },
+      dimensions: { borderRadius: { sysRadiusFull: 500 } },
+    });
+
+    expect(result.colorRoles.accent.primary.sysPrimary).toBe('#aabbcc');
+    expect(result.dimensions.borderRadius.sysRadiusFull).toBe(500);
+    expect(result.colorRoles.error.sysError).toBe(
+      sys.colorRoles.error.sysError,
+    );
+    expect(result.dimensions.borderRadius.sysRadiusMd).toBe(
+      sys.dimensions.borderRadius.sysRadiusMd,
+    );
+  });
+});

package/src/theme/defaultTheme.ts

@@ -0,0 +1,15 @@
+import { sys } from '../tokens';
+import type { Theme } from './types';
+
+/**
+ * The GuidanceNow default theme — the full resolved token tree typed as `Theme`
+ * (widened, mutable types) so consumers can read individual values without a
+ * ThemeProvider in scope.
+ *
+ * @example
+ * import { defaultTheme } from '@compsych/mobile-ui';
+ *
+ * const primaryColor = defaultTheme.colorRoles.accent.primary.sysPrimary;
+ * const bodyFont = defaultTheme.typeScale.body.md.fontFamily;
+ */
+export const defaultTheme: Theme = sys as unknown as Theme;

package/src/theme/index.ts

@@ -0,0 +1,8 @@
+export { ThemeProvider } from './ThemeProvider';
+export type { ThemeProviderProps } from './ThemeProvider';
+
+export { useTheme } from './useTheme';
+
+export type { Theme, ThemeOverride } from './types';
+
+export { defaultTheme } from './defaultTheme';

package/src/theme/mergeTheme.ts

@@ -0,0 +1,47 @@
+import { sys } from '../tokens';
+import type { Theme, ThemeOverride } from './types';
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function deepMerge(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...base };
+
+  for (const key of Object.keys(override)) {
+    const overrideVal = override[key];
+    const baseVal = base[key];
+
+    if (overrideVal === undefined || overrideVal === null) {
+      // Ignore nullish overrides — preserve the default
+      continue;
+    }
+
+    if (isPlainObject(baseVal) && isPlainObject(overrideVal)) {
+      result[key] = deepMerge(baseVal, overrideVal);
+    } else {
+      result[key] = overrideVal;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Deep-merges a partial ThemeOverride on top of the GuidanceNow defaults.
+ * Any key omitted from the override keeps its default value, so missing or
+ * invalid overrides can never break the UI.
+ */
+export function mergeTheme(override?: ThemeOverride): Theme {
+  if (!override) {
+    return sys as unknown as Theme;
+  }
+
+  return deepMerge(
+    sys as unknown as Record<string, unknown>,
+    override as Record<string, unknown>,
+  ) as Theme;
+}

package/src/theme/types.ts

@@ -0,0 +1,39 @@
+import { sys } from '../tokens';
+
+// Strip `as const` readonly modifiers and widen literal types to their
+// primitive base (string, number, boolean) so consumers can supply any valid
+// CSS color or numeric value in a ThemeOverride — not just the exact GuidanceNow
+// hex literals.
+type DeepWritable<T> = {
+  -readonly [P in keyof T]: DeepWritable<T[P]>;
+};
+
+type WidenLiterals<T> = T extends string
+  ? string
+  : T extends number
+    ? number
+    : T extends boolean
+      ? boolean
+      : T extends object
+        ? { [K in keyof T]: WidenLiterals<T[K]> }
+        : T;
+
+/** The full resolved theme object consumed by every component via useTheme(). */
+export type Theme = WidenLiterals<DeepWritable<typeof sys>>;
+
+type DeepPartial<T> = T extends object
+  ? { [P in keyof T]?: DeepPartial<T[P]> }
+  : T;
+
+/**
+ * A partial theme override — any subset of the token tree.
+ * Missing keys fall back to the GuidanceNow defaults.
+ *
+ * @example
+ * const brandTheme: ThemeOverride = {
+ *   colorRoles: {
+ *     accent: { primary: { sysPrimary: '#c00000' } },
+ *   },
+ * };
+ */
+export type ThemeOverride = DeepPartial<Theme>;

package/src/theme/useTheme.ts

@@ -0,0 +1,16 @@
+import { useContext } from 'react';
+
+import { ThemeContext } from './ThemeContext';
+import type { Theme } from './types';
+
+/**
+ * Returns the active resolved theme. Components use this hook to read token
+ * values at render time so they automatically reflect any ThemeProvider
+ * override in the tree.
+ *
+ * Falls back to the GuidanceNow default theme when called outside a
+ * ThemeProvider.
+ */
+export function useTheme(): Theme {
+  return useContext(ThemeContext);
+}