@jobber/components-native 0.113.3 → 0.113.4-implement--97f86be.3

package/dist/types/src/AtlantisThemeContext/AtlantisThemeContext.d.ts

@@ -1,4 +1,4 @@
 import React from "react";
 import type { AtlantisThemeContextProviderProps, AtlantisThemeContextValue } from "./types";
-export declare function AtlantisThemeContextProvider({ children, dangerouslyOverrideTheme, }: AtlantisThemeContextProviderProps): React.JSX.Element;
+export declare function AtlantisThemeContextProvider({ children, theme, onThemeChange, dangerouslyOverrideTheme, }: AtlantisThemeContextProviderProps): React.JSX.Element;
 export declare function useAtlantisTheme(): AtlantisThemeContextValue;

package/dist/types/src/AtlantisThemeContext/index.d.ts

@@ -1,3 +1,3 @@
 export { AtlantisThemeContextProvider, useAtlantisTheme, } from "./AtlantisThemeContext";
-export type { Theme, AtlantisThemeContextProviderProps, AtlantisThemeContextValue, } from "./types";
+export type { EffectiveTheme, Theme, AtlantisThemeContextProviderProps, AtlantisThemeContextValue, } from "./types";
 export { buildThemedStyles } from "./buildThemedStyles";

package/dist/types/src/AtlantisThemeContext/types.d.ts

@@ -1,9 +1,13 @@
 import type { iosTokens } from "@jobber/design";
 export interface AtlantisThemeContextValue {
     /**
-     * The active theme.
+     * The selected theme.
      */
     readonly theme: Theme;
+    /**
+     * The resolved theme used to select tokens.
+     */
+    readonly effectiveTheme: EffectiveTheme;
     /**
      * The design tokens for the current theme.
      */
@@ -18,10 +22,21 @@ export interface AtlantisThemeContextProviderProps {
      * The children to render.
      */
     readonly children: React.ReactNode;
+    /**
+     * Control the selected theme for this provider.
+     */
+    readonly theme?: Theme;
+    /**
+     * Called when children request a selected theme change through setTheme.
+     */
+    readonly onThemeChange?: (theme: Theme) => void;
     /**
      * Force the theme for this provider to always be the same as the provided theme. Useful for sections that should remain the same theme regardless of the rest of the application's theme.
-     * This is dangerous because the children in this provider will not be able to change the theme.
+     * This is dangerous because it forces the subtree's rendered tokens while preserving the selected
+     * theme semantics from the nearest non-forced provider. Calls to setTheme inside the forced subtree
+     * still update the selected theme upstream.
      */
-    readonly dangerouslyOverrideTheme?: Theme;
+    readonly dangerouslyOverrideTheme?: EffectiveTheme;
 }
-export type Theme = "light" | "dark";
+export type Theme = "system" | EffectiveTheme;
+export type EffectiveTheme = "light" | "dark";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jobber/components-native",
-  "version": "0.113.3",
+  "version": "0.113.4-implement--97f86be.3+97f86be1",
   "license": "MIT",
   "description": "React Native implementation of Atlantis",
   "repository": {
@@ -124,5 +124,5 @@
     "react-native-screens": ">=4.18.0",
     "react-native-svg": ">=12.0.0"
   },
-  "gitHead": "895ad886700e1a7e11927702a0e5f49cb554c4e3"
+  "gitHead": "97f86be1230044c71581dea90ac836ab6a65f580"
 }

package/src/AtlantisThemeContext/AtlantisThemeContext.guide.md

@@ -0,0 +1,53 @@
+# AtlantisThemeContext
+
+## What this owns
+
+`AtlantisThemeContext` is the native Atlantis boundary for theme semantics and
+token resolution.
+
+It owns:
+
+- the selected theme (`"system" | "light" | "dark"`)
+- the effective theme used to resolve tokens (`"light" | "dark"`)
+- mapping the selected theme to the current platform token set
+- subtree overrides for Atlantis-owned surfaces that need fixed visual tokens
+
+It does **not** own:
+
+- preference persistence
+- settings UI
+- product rollout or split configuration
+
+Those concerns belong to the consuming app.
+
+## Selected theme vs effective theme
+
+The `theme` value represents the user's selected preference. It may be
+`"system"`, which means "follow the OS setting".
+
+The `effectiveTheme` value is the resolved runtime theme Atlantis uses to choose
+tokens. This is always `"light"` or `"dark"`.
+
+Consumers that need to persist or display the user's choice should use `theme`.
+Consumers that need to style non-Atlantis surfaces should usually use
+`effectiveTheme`.
+
+## Controlled vs uncontrolled usage
+
+`AtlantisThemeContextProvider` supports both controlled and uncontrolled usage.
+
+- Use `theme` and `onThemeChange` when the app owns the selected theme state.
+- Omit `theme` when the provider should manage theme locally.
+
+App-level providers should generally be controlled so the selected preference
+can be stored outside Atlantis.
+
+## Forced theme subtrees
+
+`dangerouslyOverrideTheme` forces the subtree to render with a specific
+effective theme. This is useful for portals, overlays, or any Atlantis-owned
+surface that visually leaves the normal React subtree.
+
+Important: a forced subtree preserves the selected theme semantics from the
+nearest non-forced provider. Calling `setTheme` inside the forced subtree still
+updates the upstream selected theme; only the rendered tokens stay forced.

package/src/AtlantisThemeContext/AtlantisThemeContext.test.tsx

@@ -2,21 +2,43 @@ import React from "react";
 import { act, renderHook } from "@testing-library/react-native";
 import { darkTokens, iosTokens } from "@jobber/design";
 import merge from "lodash/merge";
+import { type ColorSchemeName, useColorScheme } from "react-native";
 import {
   AtlantisThemeContextProvider,
   useAtlantisTheme,
 } from "./AtlantisThemeContext";
-import type { AtlantisThemeContextProviderProps, Theme } from "./types";
+import type {
+  AtlantisThemeContextProviderProps,
+  EffectiveTheme,
+} from "./types";
+
+jest.mock("react-native", () => {
+  const actual = jest.requireActual("react-native");
+
+  Object.defineProperty(actual, "useColorScheme", {
+    configurable: true,
+    value: jest.fn(),
+  });
+
+  return actual;
+});
 
 const expectedDarkTokens = merge({}, iosTokens, darkTokens);
 const expectedLightTokens = iosTokens;
+const mockUseColorScheme = useColorScheme as jest.MockedFunction<
+  typeof useColorScheme
+>;
 
 function Wrapper({
   children,
+  theme,
+  onThemeChange,
   dangerouslyOverrideTheme,
 }: AtlantisThemeContextProviderProps) {
   return (
     <AtlantisThemeContextProvider
+      theme={theme}
+      onThemeChange={onThemeChange}
       dangerouslyOverrideTheme={dangerouslyOverrideTheme}
     >
       {children}
@@ -40,6 +62,10 @@ function WrapperWithOverride({
 }
 
 describe("ThemeContext", () => {
+  beforeEach(() => {
+    mockUseColorScheme.mockReturnValue("light");
+  });
+
   it("defaults to the light theme", () => {
     const { result } = renderHook(useAtlantisTheme, {
       wrapper: (props: AtlantisThemeContextProviderProps) => (
@@ -48,6 +74,7 @@ describe("ThemeContext", () => {
     });
 
     expect(result.current.theme).toBe("light");
+    expect(result.current.effectiveTheme).toBe("light");
     expect(result.current.tokens).toEqual(expectedLightTokens);
   });
 
@@ -60,35 +87,166 @@ describe("ThemeContext", () => {
 
     await act(async () => result.current.setTheme("dark"));
     expect(result.current.theme).toBe("dark");
+    expect(result.current.effectiveTheme).toBe("dark");
     expect(result.current.tokens).toEqual(expectedDarkTokens);
 
     await act(async () => result.current.setTheme("light"));
     expect(result.current.theme).toBe("light");
+    expect(result.current.effectiveTheme).toBe("light");
+    expect(result.current.tokens).toEqual(expectedLightTokens);
+  });
+
+  it("resolves the system theme from the OS color scheme", async () => {
+    mockUseColorScheme.mockReturnValue("dark");
+
+    const { result, rerender } = renderHook(useAtlantisTheme, {
+      wrapper: (props: AtlantisThemeContextProviderProps) => (
+        <Wrapper {...props} />
+      ),
+    });
+
+    await act(async () => result.current.setTheme("system"));
+    expect(result.current.theme).toBe("system");
+    expect(result.current.effectiveTheme).toBe("dark");
+    expect(result.current.tokens).toEqual(expectedDarkTokens);
+
+    mockUseColorScheme.mockReturnValue("light");
+    rerender({});
+
+    expect(result.current.theme).toBe("system");
+    expect(result.current.effectiveTheme).toBe("light");
+    expect(result.current.tokens).toEqual(expectedLightTokens);
+  });
+
+  it("uses a controlled selected theme", () => {
+    mockUseColorScheme.mockReturnValue("dark");
+
+    const { result } = renderHook(useAtlantisTheme, {
+      wrapper: (props: AtlantisThemeContextProviderProps) => (
+        <Wrapper {...props} theme="system" />
+      ),
+    });
+
+    expect(result.current.theme).toBe("system");
+    expect(result.current.effectiveTheme).toBe("dark");
+    expect(result.current.tokens).toEqual(expectedDarkTokens);
+  });
+
+  it("reports selected theme changes from a controlled provider", async () => {
+    const onThemeChange = jest.fn();
+    const { result } = renderHook(useAtlantisTheme, {
+      wrapper: (props: AtlantisThemeContextProviderProps) => (
+        <Wrapper {...props} theme="light" onThemeChange={onThemeChange} />
+      ),
+    });
+
+    await act(async () => result.current.setTheme("system"));
+
+    expect(onThemeChange).toHaveBeenCalledWith("system");
+    expect(result.current.theme).toBe("light");
+    expect(result.current.effectiveTheme).toBe("light");
+    expect(result.current.tokens).toEqual(expectedLightTokens);
+  });
+
+  it("falls back to light when system color scheme is unavailable", async () => {
+    mockUseColorScheme.mockReturnValue(
+      null as unknown as ReturnType<typeof useColorScheme>,
+    );
+
+    const { result } = renderHook(useAtlantisTheme, {
+      wrapper: (props: AtlantisThemeContextProviderProps) => (
+        <Wrapper {...props} />
+      ),
+    });
+
+    await act(async () => result.current.setTheme("system"));
+    expect(result.current.theme).toBe("system");
+    expect(result.current.effectiveTheme).toBe("light");
     expect(result.current.tokens).toEqual(expectedLightTokens);
   });
 
   describe("when theme is forced for provider", () => {
-    it("ignores updates to the global theme", async () => {
+    it("preserves the forced effective theme when the selected theme changes", async () => {
       const { result } = renderHook(useAtlantisTheme, {
         wrapper: (props: AtlantisThemeContextProviderProps) => (
           <WrapperWithOverride {...props} dangerouslyOverrideTheme="light" />
         ),
       });
 
-      // Update the global theme
+      // Update the selected theme through the forced subtree.
       await act(async () => result.current.setTheme("dark"));
 
-      // This hook shouldn't be affected by it because it's set to the light theme
-      expect(result.current.theme).toBe("light");
+      expect(result.current.theme).toBe("dark");
+      expect(result.current.effectiveTheme).toBe("light");
+      expect(result.current.tokens).toEqual(expectedLightTokens);
+    });
+
+    it("preserves the parent selected theme while forcing the effective theme", () => {
+      mockUseColorScheme.mockReturnValue("dark");
+
+      const { result } = renderHook(useAtlantisTheme, {
+        wrapper: (props: AtlantisThemeContextProviderProps) => (
+          <Wrapper theme="system">
+            <AtlantisThemeContextProvider
+              dangerouslyOverrideTheme="light"
+              {...props}
+            />
+          </Wrapper>
+        ),
+      });
+
+      expect(result.current.theme).toBe("system");
+      expect(result.current.effectiveTheme).toBe("light");
+      expect(result.current.tokens).toEqual(expectedLightTokens);
+    });
+
+    it("forwards selected theme changes through a forced subtree", async () => {
+      const { result } = renderHook(useAtlantisTheme, {
+        wrapper: (props: AtlantisThemeContextProviderProps) => (
+          <Wrapper>
+            <AtlantisThemeContextProvider
+              dangerouslyOverrideTheme="light"
+              {...props}
+            />
+          </Wrapper>
+        ),
+      });
+
+      await act(async () => result.current.setTheme("dark"));
+
+      expect(result.current.theme).toBe("dark");
+      expect(result.current.effectiveTheme).toBe("light");
       expect(result.current.tokens).toEqual(expectedLightTokens);
     });
 
     it.each([
-      { defaultTheme: "light", expectedTokens: expectedLightTokens },
-      { defaultTheme: "dark", expectedTokens: expectedDarkTokens },
-    ] as { defaultTheme: Theme; expectedTokens: typeof iosTokens }[])(
+      {
+        defaultTheme: "light",
+        colorScheme: "dark",
+        expectedEffectiveTheme: "light",
+        expectedTokens: expectedLightTokens,
+      },
+      {
+        defaultTheme: "dark",
+        colorScheme: "light",
+        expectedEffectiveTheme: "dark",
+        expectedTokens: expectedDarkTokens,
+      },
+    ] as {
+      defaultTheme: EffectiveTheme;
+      colorScheme: ColorSchemeName;
+      expectedEffectiveTheme: EffectiveTheme;
+      expectedTokens: typeof iosTokens;
+    }[])(
       "provides the dangerouslyOverrideTheme $defaultTheme tokens",
-      ({ defaultTheme, expectedTokens }) => {
+      ({
+        defaultTheme,
+        colorScheme,
+        expectedEffectiveTheme,
+        expectedTokens,
+      }) => {
+        mockUseColorScheme.mockReturnValue(colorScheme);
+
         const { result } = renderHook(useAtlantisTheme, {
           wrapper: (props: AtlantisThemeContextProviderProps) => (
             <WrapperWithOverride
@@ -98,7 +256,8 @@ describe("ThemeContext", () => {
           ),
         });
 
-        expect(result.current.theme).toBe(defaultTheme);
+        expect(result.current.theme).toBe("light");
+        expect(result.current.effectiveTheme).toBe(expectedEffectiveTheme);
         expect(result.current.tokens).toEqual(expectedTokens);
       },
     );

package/src/AtlantisThemeContext/AtlantisThemeContext.tsx

@@ -1,10 +1,11 @@
 import { androidTokens, darkTokens, iosTokens } from "@jobber/design";
-import React, { createContext, useContext, useState } from "react";
+import React, { createContext, useCallback, useContext, useState } from "react";
 import merge from "lodash/merge";
-import { Platform } from "react-native";
+import { Platform, useColorScheme } from "react-native";
 import type {
   AtlantisThemeContextProviderProps,
   AtlantisThemeContextValue,
+  EffectiveTheme,
   Theme,
 } from "./types";
 
@@ -16,34 +17,65 @@ const lightTokens = Platform.select({
 
 const completeDarkTokens = merge({}, lightTokens, darkTokens);
 
-const AtlantisThemeContext = createContext<AtlantisThemeContextValue>({
+const defaultAtlantisThemeContextValue: AtlantisThemeContextValue = {
   theme: "light",
+  effectiveTheme: "light",
   tokens: lightTokens,
   setTheme: () => {
     console.error(
       "useAtlantisTheme accessed outside of AtlantisThemeContextProvider",
     );
   },
-});
+};
+
+const AtlantisThemeContext = createContext<
+  AtlantisThemeContextValue | undefined
+>(undefined);
 
 export function AtlantisThemeContextProvider({
   children,
+  theme,
+  onThemeChange,
   dangerouslyOverrideTheme,
 }: AtlantisThemeContextProviderProps) {
-  // TODO: check last saved theme from local/device storage
-  const initialTheme: Theme = "light";
-  const [globalTheme, setGlobalTheme] = useState<Theme>(initialTheme);
+  const parentThemeContext = useContext(AtlantisThemeContext);
+  const [localTheme, setLocalTheme] = useState<Theme | undefined>(undefined);
+  const colorScheme = useColorScheme();
+
+  const setTheme = useCallback(
+    (nextTheme: Theme) => {
+      onThemeChange?.(nextTheme);
+
+      if (theme !== undefined) return;
+
+      // A forced visual override should preserve the parent subtree's selected
+      // theme semantics while still rendering with the forced tokens.
+      if (dangerouslyOverrideTheme !== undefined && parentThemeContext) {
+        parentThemeContext.setTheme(nextTheme);
+
+        return;
+      }
 
-  const currentTheme = dangerouslyOverrideTheme ?? globalTheme;
+      setLocalTheme(nextTheme);
+    },
+    [dangerouslyOverrideTheme, onThemeChange, parentThemeContext, theme],
+  );
+
+  const currentTheme =
+    theme ?? localTheme ?? parentThemeContext?.theme ?? "light";
+  const effectiveTheme =
+    dangerouslyOverrideTheme ??
+    resolveEffectiveTheme(currentTheme, colorScheme);
   const currentTokens =
-    currentTheme === "dark" ? completeDarkTokens : lightTokens;
+    effectiveTheme === "dark" ? completeDarkTokens : lightTokens;
 
   return (
     <AtlantisThemeContext.Provider
       value={{
         theme: currentTheme,
+        effectiveTheme,
         tokens: currentTokens,
-        setTheme: setGlobalTheme,
+        setTheme,
       }}
     >
       {children}
@@ -52,5 +84,14 @@ export function AtlantisThemeContextProvider({
 }
 
 export function useAtlantisTheme() {
-  return useContext(AtlantisThemeContext);
+  return useContext(AtlantisThemeContext) ?? defaultAtlantisThemeContextValue;
+}
+
+function resolveEffectiveTheme(
+  theme: Theme,
+  colorScheme: ReturnType<typeof useColorScheme>,
+): EffectiveTheme {
+  if (theme !== "system") return theme;
+
+  return colorScheme === "dark" ? "dark" : "light";
 }

package/src/AtlantisThemeContext/docs/AtlantisThemeContextBasicExample.tsx

@@ -14,15 +14,21 @@ function ChildrenComponent({
 }: {
   readonly message?: string;
 }) {
-  const { theme, tokens, setTheme } = useAtlantisTheme();
+  const { theme, effectiveTheme, tokens, setTheme } = useAtlantisTheme();
 
   return (
     <View style={{ backgroundColor: tokens["color-surface"] }}>
       <Content>
         <Text>{message}</Text>
-        <Text>{`Current theme: ${theme}`}</Text>
+        <Text>{`Selected theme: ${theme}`}</Text>
+        <Text>{`Effective theme: ${effectiveTheme}`}</Text>
         <Text>Tokens can be accessed using tokens[token-name]</Text>
         <Text>{`For example color-surface: ${tokens["color-surface"]}`}</Text>
+        <Text>
+          Use the selected theme for preference UI and the effective theme for
+          non-Atlantis surfaces.
+        </Text>
+        <Button label="Set system theme" onPress={() => setTheme("system")} />
         <Button label="Set dark theme" onPress={() => setTheme("dark")} />
         <Button label="Set light theme" onPress={() => setTheme("light")} />
       </Content>

package/src/AtlantisThemeContext/docs/AtlantisThemeContextForceThemeForProviderExample.tsx

@@ -14,15 +14,17 @@ function ChildrenComponent({
 }: {
   readonly message?: string;
 }) {
-  const { theme, tokens, setTheme } = useAtlantisTheme();
+  const { theme, effectiveTheme, tokens, setTheme } = useAtlantisTheme();
 
   return (
     <View style={{ backgroundColor: tokens["color-surface"] }}>
       <Content>
         <Text>{message}</Text>
-        <Text>{`Current theme: ${theme}`}</Text>
+        <Text>{`Selected theme: ${theme}`}</Text>
+        <Text>{`Effective theme: ${effectiveTheme}`}</Text>
         <Text>Tokens can be accessed using tokens[token-name]</Text>
         <Text>{`For example color-surface: ${tokens["color-surface"]}`}</Text>
+        <Button label="Set system theme" onPress={() => setTheme("system")} />
         <Button label="Set dark theme" onPress={() => setTheme("dark")} />
         <Button label="Set light theme" onPress={() => setTheme("light")} />
       </Content>
@@ -31,12 +33,14 @@ function ChildrenComponent({
 }
 
 function ForcedDarkThemeComponent() {
-  const { tokens } = useAtlantisTheme();
+  const { effectiveTheme, theme, tokens } = useAtlantisTheme();
 
   return (
     <View style={{ backgroundColor: tokens["color-surface"] }}>
       <Content>
         <Text>This will always be a dark theme</Text>
+        <Text>{`Selected theme: ${theme}`}</Text>
+        <Text>{`Effective theme: ${effectiveTheme}`}</Text>
       </Content>
     </View>
   );
@@ -47,7 +51,7 @@ export function AtlantisThemeContextForceThemeForProviderExample(
 ) {
   return (
     <AtlantisThemeContextProvider {...props}>
-      <ChildrenComponent message="It is possible to have a provider ignore Theme Changes" />
+      <ChildrenComponent message="It is possible to force a subtree's rendered theme while preserving the selected theme semantics." />
       <AtlantisThemeContextProvider dangerouslyOverrideTheme="dark">
         <ForcedDarkThemeComponent />
       </AtlantisThemeContextProvider>

package/src/AtlantisThemeContext/index.ts

@@ -3,6 +3,7 @@ export {
   useAtlantisTheme,
 } from "./AtlantisThemeContext";
 export type {
+  EffectiveTheme,
   Theme,
   AtlantisThemeContextProviderProps,
   AtlantisThemeContextValue,

package/src/AtlantisThemeContext/types.ts

@@ -2,10 +2,15 @@ import type { iosTokens } from "@jobber/design";
 
 export interface AtlantisThemeContextValue {
   /**
-   * The active theme.
+   * The selected theme.
    */
   readonly theme: Theme;
 
+  /**
+   * The resolved theme used to select tokens.
+   */
+  readonly effectiveTheme: EffectiveTheme;
+
   /**
    * The design tokens for the current theme.
    */
@@ -23,11 +28,25 @@ export interface AtlantisThemeContextProviderProps {
    */
   readonly children: React.ReactNode;
 
+  /**
+   * Control the selected theme for this provider.
+   */
+  readonly theme?: Theme;
+
+  /**
+   * Called when children request a selected theme change through setTheme.
+   */
+  readonly onThemeChange?: (theme: Theme) => void;
+
   /**
    * Force the theme for this provider to always be the same as the provided theme. Useful for sections that should remain the same theme regardless of the rest of the application's theme.
-   * This is dangerous because the children in this provider will not be able to change the theme.
+   * This is dangerous because it forces the subtree's rendered tokens while preserving the selected
+   * theme semantics from the nearest non-forced provider. Calls to setTheme inside the forced subtree
+   * still update the selected theme upstream.
    */
-  readonly dangerouslyOverrideTheme?: Theme;
+  readonly dangerouslyOverrideTheme?: EffectiveTheme;
 }
 
-export type Theme = "light" | "dark";
+export type Theme = "system" | EffectiveTheme;
+
+export type EffectiveTheme = "light" | "dark";

package/src/ContentOverlay/ContentOverlay.tsx

@@ -99,7 +99,7 @@ export function ContentOverlay({
 
   const styles = useStyles();
   const { t } = useAtlantisI18n();
-  const { theme, tokens } = useAtlantisTheme();
+  const { effectiveTheme, tokens } = useAtlantisTheme();
   const isScreenReaderEnabled = useIsScreenReaderEnabled();
 
   const behavior = computeContentOverlayBehavior(
@@ -327,7 +327,7 @@ export function ContentOverlay({
         the active theme here so descendants (e.g. the header title) resolve the
         correct themed tokens.
       */}
-      <AtlantisThemeContextProvider dangerouslyOverrideTheme={theme}>
+      <AtlantisThemeContextProvider dangerouslyOverrideTheme={effectiveTheme}>
         <ContentOverlayKeyboardContext.Provider value={scrollEnabled}>
           {scrollEnabled ? (
             <BottomSheetKeyboardAwareScrollView