@jobber/components-native 0.113.4-implement--94d34f8.2 → 0.113.4-implement--97f86be.3

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

@@ -32,7 +32,9 @@ export interface AtlantisThemeContextProviderProps {
     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?: EffectiveTheme;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jobber/components-native",
-  "version": "0.113.4-implement--94d34f8.2+94d34f81",
+  "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": "94d34f81c5579bf7aec109cd129a94ea91aadf56"
+  "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

@@ -166,18 +166,55 @@ describe("ThemeContext", () => {
   });
 
   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);
     });
@@ -219,7 +256,7 @@ 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

@@ -17,7 +17,7 @@ const lightTokens = Platform.select({
 
 const completeDarkTokens = merge({}, lightTokens, darkTokens);
 
-const AtlantisThemeContext = createContext<AtlantisThemeContextValue>({
+const defaultAtlantisThemeContextValue: AtlantisThemeContextValue = {
   theme: "light",
   effectiveTheme: "light",
   tokens: lightTokens,
@@ -26,7 +26,11 @@ const AtlantisThemeContext = createContext<AtlantisThemeContextValue>({
       "useAtlantisTheme accessed outside of AtlantisThemeContextProvider",
     );
   },
-});
+};
+
+const AtlantisThemeContext = createContext<
+  AtlantisThemeContextValue | undefined
+>(undefined);
 
 export function AtlantisThemeContextProvider({
   children,
@@ -34,22 +38,34 @@ export function AtlantisThemeContextProvider({
   onThemeChange,
   dangerouslyOverrideTheme,
 }: AtlantisThemeContextProviderProps) {
-  const [uncontrolledTheme, setUncontrolledTheme] = useState<Theme>("light");
+  const parentThemeContext = useContext(AtlantisThemeContext);
+  const [localTheme, setLocalTheme] = useState<Theme | undefined>(undefined);
   const colorScheme = useColorScheme();
 
   const setTheme = useCallback(
     (nextTheme: Theme) => {
       onThemeChange?.(nextTheme);
 
-      if (theme === undefined) {
-        setUncontrolledTheme(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;
       }
+
+      setLocalTheme(nextTheme);
     },
-    [onThemeChange, theme],
+    [dangerouslyOverrideTheme, onThemeChange, parentThemeContext, theme],
   );
 
-  const currentTheme = dangerouslyOverrideTheme ?? theme ?? uncontrolledTheme;
-  const effectiveTheme = resolveEffectiveTheme(currentTheme, colorScheme);
+  const currentTheme =
+    theme ?? localTheme ?? parentThemeContext?.theme ?? "light";
+  const effectiveTheme =
+    dangerouslyOverrideTheme ??
+    resolveEffectiveTheme(currentTheme, colorScheme);
   const currentTokens =
     effectiveTheme === "dark" ? completeDarkTokens : lightTokens;
 
@@ -68,7 +84,7 @@ export function AtlantisThemeContextProvider({
 }
 
 export function useAtlantisTheme() {
-  return useContext(AtlantisThemeContext);
+  return useContext(AtlantisThemeContext) ?? defaultAtlantisThemeContextValue;
 }
 
 function resolveEffectiveTheme(

package/src/AtlantisThemeContext/docs/AtlantisThemeContextBasicExample.tsx

@@ -24,6 +24,10 @@ function ChildrenComponent({
         <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")} />

package/src/AtlantisThemeContext/docs/AtlantisThemeContextForceThemeForProviderExample.tsx

@@ -33,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>
   );
@@ -49,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/types.ts

@@ -40,7 +40,9 @@ export interface AtlantisThemeContextProviderProps {
 
   /**
    * 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?: EffectiveTheme;
 }