refactor(ui-react): make the colorScheme (previously mode) on the ThemeProvider controlled (#537)

* refactor(ui-react): make the colorScheme (previously mode) on the ThemeProvider controlled

Signed-off-by: Simon Bruneaud <simon.bruneaud@ledger.fr>

* nx versions

Signed-off-by: Simon Bruneaud <simon.bruneaud@ledger.fr>

* refactor: update the sandbox react app

Signed-off-by: Simon Bruneaud <simon.bruneaud@ledger.fr>

* nx plan

Signed-off-by: Simon Bruneaud <simon.bruneaud@ledger.fr>

---------

Signed-off-by: Simon Bruneaud <simon.bruneaud@ledger.fr>

Author: gamegee

.nx/version-plans/version-plan-1772548561527.md

@@ -0,0 +1,7 @@
+---
+'@ledgerhq/lumen-ui-react': patch
+---
+
+refactor(ui-react): make the colorScheme (previously mode) on the ThemeProvider controlled
+BREAKING_CHANGE(ui-react): rename ThemeProvider mode to colorScheme
+BREAKING_CHANGE(ui-react): remove useTheme hook

apps/app-sandbox-react/src/app/app.tsx

@@ -1,25 +1,19 @@
-import {
-  Button,
-  ThemeProvider,
-  Switch,
-  useTheme,
-} from '@ledgerhq/lumen-ui-react';
-
-const ToggleThemeButton = () => {
-  const { mode, toggleMode } = useTheme();
-  return (
-    <div className='flex flex-row gap-8 text-muted'>
-      Dark mode
-      <Switch selected={mode === 'dark'} onChange={toggleMode} />
-    </div>
-  );
-};
+import { Button, ThemeProvider } from '@ledgerhq/lumen-ui-react';
+import { useState } from 'react';
 
 export function App() {
+  const [colorScheme, setColorScheme] = useState<'light' | 'dark'>('light');
+
   return (
-    <ThemeProvider defaultMode='system'>
+    <ThemeProvider colorScheme='system'>
       <div className='flex h-screen w-screen flex-col items-center justify-center bg-muted'>
-        <ToggleThemeButton />
+        <Button
+          onClick={() =>
+            setColorScheme(colorScheme === 'light' ? 'dark' : 'light')
+          }
+        >
+          Toggle theme
+        </Button>
         <div className='mt-32 flex flex-row gap-2'>
           <Button appearance='accent'>Button</Button>
           <Button appearance='base'>Button</Button>

apps/app-sandbox-react/tests/treeShaking/main.treeshaking.tsx

@@ -9,7 +9,7 @@ const root = document.getElementById('root');
 if (root) {
   createRoot(root).render(
     <StrictMode>
-      <ThemeProvider defaultMode='light'>
+      <ThemeProvider colorScheme='light'>
         <div className='flex h-screen w-screen flex-col items-center justify-center gap-16 bg-base'>
           <Incognito size={48} />
           <Button appearance='accent'>Tree Shaking Test</Button>

libs/ui-react/.storybook/Decorator.tsx

@@ -1,6 +1,9 @@
 import type { Decorator } from '@storybook/react-vite';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { ThemeMode, ThemeProvider } from '../src/lib/Components/ThemeProvider';
+import {
+  ColorSchemeName,
+  ThemeProvider,
+} from '../src/lib/Components/ThemeProvider';
 
 const queryClient = new QueryClient({
   defaultOptions: { queries: { retry: false } },
@@ -22,7 +25,7 @@ const createThemeDecorator = (
 
     return (
       <QueryClientProvider client={queryClient}>
-        <ThemeProvider defaultMode={context.globals.mode as ThemeMode}>
+        <ThemeProvider colorScheme={context.globals.mode as ColorSchemeName}>
           <Story />
         </ThemeProvider>
       </QueryClientProvider>

libs/ui-react/.storybook/docs/ThemeProvider.mdx

@@ -3,52 +3,58 @@ import { Meta } from '@storybook/addon-docs/blocks';
 <Meta title="Getting Started/Theme Provider" />
 
 ## Ledger Design System Theme Provider
-The ThemeProvider from @ledgerhq/lumen-ui-react manages the app’s visual theme (light or dark mode) using React Context.
+
+The ThemeProvider from @ledgerhq/lumen-ui-react manages the app's visual theme (light, dark, or system) and locale.
 Define the `ThemeProvider` at the top-level of your app.
 
+### Color Scheme
+
+The `colorScheme` prop is fully controlled. It accepts `"light"`, `"dark"`, or `"system"` (default).
+When set to `"system"`, the theme automatically follows the user's OS preference via `prefers-color-scheme`.
+
 ```tsx
 import { ThemeProvider } from '@ledgerhq/lumen-ui-react';
 
 function AppProviders() {
   return (
-    <ThemeProvider defaultMode="dark">
+    <ThemeProvider colorScheme="dark">
       <App />
     </ThemeProvider>
   );
 }
 ```
 
-Updates the mode using the `useTheme` context hook.
-```tsx
-import { ThemeProvider, useTheme } from '@ledgerhq/lumen-ui-react';
+To let users toggle the theme, manage the state in your app and pass it down:
 
-const UpdateThemeModeButton = () => {
-  const { mode, toggleMode, setMode } = useTheme();
-  return (
-    <Button onClick={toggleMode}>
-      {mode}
-    </Button>
-  );
-};
+```tsx
+import { useState } from 'react';
+import { ThemeProvider, type ColorSchemeName } from '@ledgerhq/lumen-ui-react';
 
 function AppProviders() {
+  const [colorScheme, setColorScheme] = useState<ColorSchemeName>('system');
+
   return (
-    <ThemeProvider mode="dark">
-      <UpdateThemeModeButton />
+    <ThemeProvider colorScheme={colorScheme}>
+      <Button onClick={() => setColorScheme(prev => prev === 'dark' ? 'light' : 'dark')}>
+        Toggle theme
+      </Button>
     </ThemeProvider>
   );
 }
 ```
 
-## Internationalization
-The ThemeProvider also manages the app’s locale using React Context.  
-You can just pass the locale to the `ThemeProvider` and the translations will be lazy-loaded automatically.
+### Internationalization
+
+The ThemeProvider also manages the app's locale.
+Pass the `locale` prop and translations will be lazy-loaded automatically.
 
 ```tsx
+import { useState } from 'react';
 import { ThemeProvider, type SupportedLocale, Languages } from '@ledgerhq/lumen-ui-react';
 
 function AppProviders() {
   const [locale, setLocale] = useState<SupportedLocale>(Languages.en.id);
+
   return (
     <ThemeProvider locale={locale}>
       <App />

libs/ui-react/src/lib/Components/Button/Button.stories.tsx

@@ -135,19 +135,21 @@ export const ContentTypesShowcase: Story = {
 };
 
 export const SizesShowcase: Story = {
-  render: () => (
-    <div className='flex items-center gap-4'>
-      <Button appearance='base' size='sm'>
-        Small
-      </Button>
-      <Button appearance='base' size='md'>
-        Medium
-      </Button>
-      <Button appearance='base' size='lg' icon={Settings}>
-        Large
-      </Button>
-    </div>
-  ),
+  render: () => {
+    return (
+      <div className='flex items-center gap-4'>
+        <Button appearance='base' size='sm'>
+          Small
+        </Button>
+        <Button appearance='base' size='md'>
+          Medium
+        </Button>
+        <Button appearance='base' size='lg' icon={Settings}>
+          Large
+        </Button>
+      </div>
+    );
+  },
 };
 
 export const StatesShowcase: Story = {

libs/ui-react/src/lib/Components/ThemeProvider/ThemeProvider.test.tsx

@@ -1,8 +1,8 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { render } from '@testing-library/react';
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import '@testing-library/jest-dom';
 
-import { ThemeProvider, useTheme } from './ThemeProvider';
+import { ThemeProvider } from './ThemeProvider';
 
 const root = document.documentElement;
 
@@ -33,7 +33,7 @@ afterEach(() => {
 describe('ThemeProvider', () => {
   it('applies light class when theme is light', () => {
     render(
-      <ThemeProvider defaultMode='light'>
+      <ThemeProvider colorScheme='light'>
         <div data-testid='child' />
       </ThemeProvider>,
     );
@@ -44,7 +44,7 @@ describe('ThemeProvider', () => {
 
   it('applies dark class when theme is dark', () => {
     render(
-      <ThemeProvider defaultMode='dark'>
+      <ThemeProvider colorScheme='dark'>
         <div data-testid='child' />
       </ThemeProvider>,
     );
@@ -57,7 +57,7 @@ describe('ThemeProvider', () => {
     setupMatchMedia(true);
 
     render(
-      <ThemeProvider defaultMode='system'>
+      <ThemeProvider colorScheme='system'>
         <div data-testid='child' />
       </ThemeProvider>,
     );
@@ -70,35 +70,12 @@ describe('ThemeProvider', () => {
     setupMatchMedia(false);
 
     render(
-      <ThemeProvider defaultMode='system'>
+      <ThemeProvider colorScheme='system'>
         <div data-testid='child' />
       </ThemeProvider>,
     );
 
     expect(root).toHaveClass('light');
     expect(root).not.toHaveClass('dark');
   });
-
-  it('updates class using useTheme context', () => {
-    const Consumer = () => {
-      const { mode, setMode } = useTheme();
-      return (
-        <div data-testid='theme-value' onClick={() => setMode('light')}>
-          {mode}
-        </div>
-      );
-    };
-
-    render(
-      <ThemeProvider defaultMode='dark'>
-        <Consumer />
-      </ThemeProvider>,
-    );
-
-    expect(screen.getByTestId('theme-value')).toHaveTextContent('dark');
-    fireEvent.click(screen.getByTestId('theme-value'));
-    expect(screen.getByTestId('theme-value')).toHaveTextContent('light');
-    expect(root).toHaveClass('light');
-    expect(root).not.toHaveClass('dark');
-  });
 });

libs/ui-react/src/lib/Components/ThemeProvider/ThemeProvider.tsx

@@ -1,39 +1,29 @@
 import { createSafeContext } from '@ledgerhq/lumen-utils-shared';
-import { FC, useMemo, useState } from 'react';
+import { FC, useMemo } from 'react';
 import { I18nProvider } from '../../../i18n';
-import { ThemeMode, ThemeProviderProps } from './ThemeProvider.types';
-import {
-  DARK_MODE,
-  LIGHT_MODE,
-  SYSTEM_MODE,
-  useRootColorModeSideEffect,
-} from './useRootColorModeSideEffect';
+import { COLOR_SCHEMES, ThemeProviderProps } from './ThemeProvider.types';
+import { useRootColorModeSideEffect } from './useRootColorModeSideEffect';
 
 type ThemeProviderState = {
-  mode: ThemeMode;
-  setMode: (mode: ThemeMode) => void;
   locale: ThemeProviderProps['locale'];
 };
 
-const [ThemeProviderContext, useThemeContext] =
+const [ThemeProviderContext] =
   createSafeContext<ThemeProviderState>('ThemeProvider');
 
-const ThemeProvider: FC<ThemeProviderProps> = ({
+export const ThemeProvider: FC<ThemeProviderProps> = ({
   children,
-  defaultMode = SYSTEM_MODE,
+  colorScheme = COLOR_SCHEMES.system,
   locale,
 }) => {
-  const [mode, setMode] = useState(defaultMode);
-
-  useRootColorModeSideEffect({ mode });
+  useRootColorModeSideEffect({ colorScheme });
 
   const value = useMemo(
     () => ({
-      mode,
-      setMode,
+      colorScheme,
       locale,
     }),
-    [mode, locale],
+    [colorScheme, locale],
   );
 
   return (
@@ -42,17 +32,3 @@ const ThemeProvider: FC<ThemeProviderProps> = ({
     </ThemeProviderContext>
   );
 };
-
-const useTheme = () => {
-  const context = useThemeContext({
-    consumerName: 'useTheme',
-    contextRequired: true,
-  });
-  return {
-    ...context,
-    toggleMode: () =>
-      context.setMode(context.mode === DARK_MODE ? LIGHT_MODE : DARK_MODE),
-  };
-};
-
-export { ThemeProvider, useTheme };

libs/ui-react/src/lib/Components/ThemeProvider/ThemeProvider.types.ts

@@ -1,14 +1,22 @@
 import { PropsWithChildren } from 'react';
 import { type SupportedLocale } from '../../../i18n';
 
-export type ThemeMode = 'dark' | 'light' | 'system';
+export const COLOR_SCHEMES = {
+  light: 'light',
+  dark: 'dark',
+  system: 'system',
+} as const;
+
+export type ColorSchemeName =
+  (typeof COLOR_SCHEMES)[keyof typeof COLOR_SCHEMES];
 
 export type ThemeProviderProps = PropsWithChildren & {
   /**
-   * The default mode of the theme.
+   * The color scheme of the theme.
+   * system will follow the user's OS preference via `prefers-color-scheme`.
    * @default 'system'
    */
-  defaultMode?: ThemeMode;
+  colorScheme?: ColorSchemeName;
   /**
    * The locale to use for translations.
    * When changed, translations will be lazy-loaded automatically.