feat(styles): add theme extension support and improve nested theme composition

- Add support for extending FusionTheme with custom properties using generics
- Enhance createTheme to accept optional baseTheme parameter for nested themes
- Improve deep merging to properly handle StyleProperty instances and Record types
- Export ThemeProviderProps and StylesProviderProps interfaces for better TypeScript support
- Add explicit exports for createTheme, FusionTheme, and StyleDefinition
- Update tests to use createTheme instead of plain objects
- Fix theme merging in nested ThemeProvider scenarios

All changes are backward compatible.

Signed-off-by: Odin Thomas Rochmann <odin.rochmann@gmail.com>

Author: odinr

.changeset/react-styles-theme-extensions.md

@@ -0,0 +1,33 @@
+---
+"@equinor/fusion-react-styles": minor
+---
+
+Enhanced theme system with support for extending `FusionTheme` with custom properties and improved nested theme composition.
+
+### Added
+
+- **Theme Extension Support**: `FusionTheme` now supports extending with custom properties using generics:
+  ```typescript
+  type MyTheme = FusionTheme<{ colors: { primary: ColorStyleProperty } }>;
+  ```
+- **Custom Base Theme Merging**: `createTheme` now accepts an optional `baseTheme` parameter for merging with custom base themes:
+  ```typescript
+  const extendedTheme = createTheme(
+    { colors: { ui: { background__danger: newColor } } },
+    outerTheme
+  );
+  ```
+- **Deep Merging Improvements**: Enhanced `deepMerge` function properly handles nested theme properties, `Record` types, and `StyleProperty` instances
+- **Type Exports**: Explicitly exported `ThemeProviderProps`, `StylesProviderProps`, `FusionTheme`, `StyleDefinition`, and `createTheme` for better TypeScript support
+
+### Changed
+
+- `createTheme` signature now accepts optional `baseTheme` parameter (backward compatible)
+- Improved type inference for extended themes in `ThemeProvider`, `useTheme`, and `makeStyles`
+- Better handling of nested theme composition when using theme functions in nested `ThemeProvider` components
+
+### Technical Details
+
+- Deep merging now correctly handles `StyleProperty` instances (replaces instead of merging)
+- Theme composition works correctly with nested `ThemeProvider` components
+- All types are properly exported and documented

packages/styles/src/ThemeProvider.tsx

@@ -2,6 +2,7 @@ import { useContext, useMemo, type ReactNode } from 'react';
 import type { ReactElement } from 'react';
 import { styles as defaultTheme } from '@equinor/fusion-web-theme';
 import { ThemeContext } from './utils/contexts';
+import type { FusionTheme } from './theme';
 
 import '@equinor/fusion-wc-theme';
 import type ThemeElement from '@equinor/fusion-wc-theme';
@@ -15,12 +16,14 @@ declare module 'react' {
 
 /**
  * Props for the ThemeProvider component
+ *
+ * @template T - Extended theme type that extends FusionTheme
  */
-export interface ThemeProviderProps {
+export interface ThemeProviderProps<T extends FusionTheme = FusionTheme> {
   /** Child components that will receive the theme context */
   children?: ReactNode;
   /** Theme object or function that receives outer theme and returns new theme */
-  theme: unknown | ((outerTheme: unknown) => unknown);
+  theme?: T | Partial<T> | ((outerTheme: T | null) => T);
 }
 
 /**
@@ -30,6 +33,9 @@ export interface ThemeProviderProps {
  * When nested, the theme can be a function that receives the outer theme and returns
  * a merged or customized theme.
  *
+ * Supports extending FusionTheme with custom properties for application-specific themes.
+ *
+ * @template T - Extended theme type that extends FusionTheme
  * @param props - Theme provider configuration
  * @returns A React element that provides theme context to children
  *
@@ -49,20 +55,40 @@ export interface ThemeProviderProps {
  *   </ThemeProvider>
  * </ThemeProvider>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Extended theme with custom properties
+ * interface MyAppTheme extends FusionTheme {
+ *   customProperty: string;
+ * }
+ *
+ * const extendedTheme: MyAppTheme = {
+ *   ...theme,
+ *   customProperty: 'value'
+ * };
+ *
+ * <ThemeProvider<MyAppTheme> theme={extendedTheme}>
+ *   <App />
+ * </ThemeProvider>
+ * ```
  */
-export function ThemeProvider(props: ThemeProviderProps): ReactElement {
+export function ThemeProvider<T extends FusionTheme = FusionTheme>(
+  props: ThemeProviderProps<T>,
+): ReactElement {
   const { children, theme: localTheme } = props;
   // Get theme from parent ThemeProvider (if nested)
-  const outerTheme = useContext(ThemeContext);
+  const outerTheme = useContext(ThemeContext) as T | null;
 
   // Resolve theme: if function, call with outer theme; otherwise use directly or default
-  const theme = useMemo(() => {
+  const theme = useMemo((): T => {
     if (typeof localTheme === 'function') {
       // Theme function receives outer theme and returns new theme (enables theme composition)
       return localTheme(outerTheme);
     }
-    // Use provided theme or fall back to default
-    return localTheme ?? defaultTheme;
+    // Use provided theme as-is, or fall back to default theme
+    // Note: Partial themes will be merged at the type level, but runtime uses provided theme directly
+    return (localTheme ?? defaultTheme) as T;
   }, [localTheme, outerTheme]);
 
   return (
@@ -76,18 +102,34 @@ export function ThemeProvider(props: ThemeProviderProps): ReactElement {
 /**
  * Hook to access the current theme from ThemeProvider context
  *
- * @template Theme - The type of the theme (defaults to unknown)
+ * Supports extended themes that extend FusionTheme. When used with an extended theme,
+ * the generic type parameter should match the theme type used in ThemeProvider.
+ *
+ * @template Theme - The type of the theme (defaults to FusionTheme, but can be extended)
  * @returns The current theme value or null if no ThemeProvider is present
  *
  * @example
  * ```tsx
  * function Component() {
- *   const theme = useTheme<MyTheme>();
+ *   const theme = useTheme();
  *   return <div style={{ color: theme?.colors.primary }}>Hello</div>;
  * }
  * ```
+ *
+ * @example
+ * ```tsx
+ * // With extended theme type
+ * interface MyAppTheme extends FusionTheme {
+ *   customProperty: string;
+ * }
+ *
+ * function Component() {
+ *   const theme = useTheme<MyAppTheme>();
+ *   return <div>{theme?.customProperty}</div>;
+ * }
+ * ```
  */
-export function useTheme<Theme = unknown>(): Theme | null {
+export function useTheme<Theme extends FusionTheme = FusionTheme>(): Theme | null {
   const theme = useContext(ThemeContext);
   return theme as Theme | null;
 }

packages/styles/src/__tests__/StyleProvider.test.tsx

@@ -18,12 +18,13 @@ import { createGenerateClassName } from '../utils/class-name-generator';
 import { StylesContext } from '../utils/contexts';
 import { makeStyles } from '../make-styles';
 import { ThemeProvider } from '../ThemeProvider';
+import { createTheme } from '../theme';
 
-const mockTheme = {
+const mockTheme = createTheme({
   colors: {
     primary: 'blue',
   },
-};
+});
 
 beforeEach(() => {
   document.head.innerHTML = '';

packages/styles/src/__tests__/ThemeProvider.test.tsx

@@ -15,14 +15,19 @@ import { render, screen, renderHook } from '@testing-library/react';
 import { useContext } from 'react';
 import { ThemeProvider, useTheme } from '../ThemeProvider';
 import { ThemeContext } from '../utils/contexts';
+import type { FusionTheme } from '../theme';
+import { createTheme, theme } from '../theme';
+import { makeStyles } from '../make-styles';
+import { ColorStyleProperty } from '@equinor/fusion-web-theme/dist/styles/colors';
 
 // Mock theme - simulates Fusion design system theme
-const mockTheme = {
+// Using createTheme to extend FusionTheme with custom colors
+const mockTheme = createTheme({
   colors: {
     primary: 'blue',
     secondary: 'red',
   },
-};
+});
 
 describe('ThemeProvider - Theme distribution', () => {
   it('should render child components normally', () => {
@@ -83,16 +88,27 @@ describe('ThemeProvider - Theme distribution', () => {
     // WHY: Enables theme composition - extend or override parent theme
     // EXAMPLE: Parent provides base theme, child extends it with custom colors
 
-    const themeFunction = (outerTheme: unknown) => {
-      return { ...mockTheme, outer: outerTheme };
+    const themeFunction = (outerTheme: unknown): FusionTheme => {
+      return { ...mockTheme, outer: outerTheme } as unknown as FusionTheme;
     };
 
+    const useStyles = makeStyles(
+      (theme: FusionTheme) => {
+        // Verify theme function was called and theme is available
+        expect(theme).toBeDefined();
+        expect(theme.outer).toBeDefined();
+        return {
+          root: {
+            color: 'blue',
+          },
+        };
+      },
+      { name: 'ThemeFunctionTest' },
+    );
+
     const TestComponent = () => {
-      const theme = useContext(ThemeContext);
-      // Verify theme function was called and returned theme
-      expect(theme).toBeDefined();
-      expect((theme as { outer: unknown }).outer).toBeDefined();
-      return <div>Test</div>;
+      const classes = useStyles({});
+      return <div className={classes.root}>Test</div>;
     };
 
     render(
@@ -107,14 +123,49 @@ describe('ThemeProvider - Theme distribution', () => {
     // WHY: Enables theme composition - child themes can extend parent
     // EXAMPLE: App theme defines colors, module theme extends with module-specific colors
 
-    const outerTheme = { outer: 'theme' };
-    const themeFunction = (outer: unknown) => {
+    const background__danger = new ColorStyleProperty('background__danger', {
+      hex: '#000000',
+      hsla: 'hsla(0, 0%, 0%, 1)',
+      rgba: 'rgba(0, 0, 0, 1)',
+    });
+
+    const outerTheme = createTheme();
+
+    const themeFunction = (providedTheme: FusionTheme | null): FusionTheme => {
       // Verify outer theme is passed correctly
-      expect(outer).toBe(outerTheme);
-      return { ...mockTheme, outer };
+      expect(providedTheme).toBe(outerTheme);
+      expect(providedTheme?.colors.ui.background__danger.value.hex).toBe(
+        theme?.colors.ui.background__danger.value.hex,
+      );
+      expect(providedTheme?.colors.ui.background__danger.value.hsla).toBe(
+        theme?.colors.ui.background__danger.value.hsla,
+      );
+      expect(providedTheme?.colors.ui.background__danger.value.rgba).toBe(
+        theme?.colors.ui.background__danger.value.rgba,
+      );
+
+      // Child theme extends outer theme with additional colors
+      // Pass outer theme as baseTheme to merge with outer theme instead of default theme
+      return createTheme(
+        {
+          colors: {
+            ui: {
+              background__danger: background__danger,
+            },
+          },
+        },
+        providedTheme ?? undefined,
+      );
     };
 
     const TestComponent = () => {
+      const componentTheme = useTheme();
+      // Verify the merged theme is available
+      expect(componentTheme).toBeDefined();
+      // Verify the custom background__danger was merged correctly
+      expect(componentTheme?.colors.ui.background__danger.css).toBe(background__danger.css);
+      // Verify other UI colors from base theme are still present
+      expect(componentTheme?.colors.ui.background__default).toBeDefined();
       return <div>Test</div>;
     };
 
@@ -188,7 +239,12 @@ describe('useTheme hook - Accessing theme from components', () => {
     // WHY: Type safety when accessing theme properties
     // EXAMPLE: useTheme<MyTheme>() gives typed access to theme.colors.primary
 
-    type CustomTheme = typeof mockTheme;
+    type CustomTheme = FusionTheme & {
+      colors: {
+        primary: string;
+        secondary: string;
+      };
+    };
 
     const wrapper = ({ children }: { children: React.ReactNode }) => (
       <ThemeProvider theme={mockTheme}>{children}</ThemeProvider>
@@ -198,16 +254,21 @@ describe('useTheme hook - Accessing theme from components', () => {
 
     // Verify typed theme is returned
     expect(result.current).toBe(mockTheme);
-    // TypeScript now knows theme structure
-    expect(result.current?.colors.primary).toBe('blue');
+    // TypeScript now knows theme structure - cast to access test-specific properties
+    const theme = result.current as unknown as { colors?: { primary?: string } };
+    expect(theme.colors?.primary).toBe('blue');
   });
 
   it('should update when theme changes', () => {
     // WHAT: useTheme updates when ThemeProvider theme changes
     // WHY: Supports dynamic theming (e.g., switching light/dark mode)
     // EXAMPLE: User toggles theme, all components get new theme
 
-    const newTheme = { colors: { primary: 'green' } };
+    const newTheme = createTheme({
+      colors: {
+        primary: 'green',
+      },
+    });
 
     const wrapper = ({ children }: { children: React.ReactNode }) => (
       <ThemeProvider theme={newTheme}>{children}</ThemeProvider>

packages/styles/src/__tests__/make-styles.test.tsx

@@ -17,14 +17,28 @@ import { makeStyles } from '../make-styles';
 import { ThemeProvider } from '../ThemeProvider';
 import { StylesProvider } from '../StyleProvider';
 import type { Styles } from '../types';
+import { createTheme, type FusionTheme } from '../theme';
+import { ColorStyleProperty, type Color } from '@equinor/fusion-web-theme/dist/styles/colors';
 
 // Mock theme object - simulates the Fusion design system theme
-const mockTheme = {
+// Using createTheme to extend FusionTheme with custom colors.primary property
+const mockTheme = createTheme({
   colors: {
-    primary: 'blue',
-    secondary: 'red',
+    primary: new ColorStyleProperty('primary', {
+      hex: '#0000ff',
+      hsla: 'hsla(240, 100%, 50%, 1)',
+      rgba: 'rgba(0, 0, 255, 1)',
+    } satisfies Color),
   },
-};
+});
+
+// Type for theme with string colors (for simpler test cases)
+type StringColorTheme = FusionTheme<{
+  colors: {
+    primary: string;
+    secondary: string;
+  };
+}>;
 
 describe('makeStyles - Main styling API', () => {
   beforeEach(() => {
@@ -114,20 +128,29 @@ describe('makeStyles - Main styling API', () => {
     // EXAMPLE: Components that use theme.colors.primary instead of hardcoded colors
 
     // Styles can be a function that receives theme
-    const styles: Styles<typeof mockTheme, Record<string, unknown>> = (
-      theme: typeof mockTheme,
-    ) => ({
-      root: {
-        color: theme.colors.primary, // Uses theme value
-        backgroundColor: theme.colors.secondary,
+    // Create a theme with string colors for this test
+    const stringColorTheme = createTheme({
+      colors: {
+        primary: 'blue',
+        secondary: 'red',
       },
     });
 
+    const styles: Styles<StringColorTheme, Record<string, unknown>> = (theme: StringColorTheme) => {
+      const themeColors = theme.colors;
+      return {
+        root: {
+          color: themeColors.primary || 'blue', // Uses theme value
+          backgroundColor: themeColors.secondary || 'red',
+        },
+      };
+    };
+
     const useStyles = makeStyles(styles, { name: 'ThemeComponent' });
 
     const wrapper = ({ children }: { children: React.ReactNode }) => (
       <StylesProvider>
-        <ThemeProvider theme={mockTheme}>{children}</ThemeProvider>
+        <ThemeProvider theme={stringColorTheme}>{children}</ThemeProvider>
       </StylesProvider>
     );