@fibery/ui-kit 1.40.3 → 1.41.0

package/src/theme-provider.test.tsx

@@ -0,0 +1,820 @@
+/* eslint-disable max-lines, no-console */
+import {render, screen} from "@testing-library/react";
+import {
+  MenuThemeProvider,
+  RootThemeProvider,
+  ThemeProvider,
+  useTheme,
+  useThemeMenuPreference,
+  useThemeMode,
+  useThemePreference,
+  useThemeStyles,
+} from "./theme-provider";
+import {defaultDarkTheme, defaultLightTheme, defaultLightThemeStyles} from "./theme-styles";
+import {createInlineStyles, getThemeColors, themeVars} from "./design-system";
+import {makeDefaultPalette} from "./palette-generator";
+
+const palette = makeDefaultPalette();
+
+function ThemeDisplay({testId = "theme-display"}: {testId?: string}) {
+  const theme = useTheme();
+  const mode = useThemeMode();
+  return (
+    <div data-testid={testId} data-mode={mode} data-primary={theme.primary}>
+      {theme.key}
+    </div>
+  );
+}
+
+describe("ThemeProvider", () => {
+  describe("basic rendering", () => {
+    it("renders children", () => {
+      render(
+        <ThemeProvider theme={defaultLightTheme}>
+          <div data-testid="child">Hello</div>
+        </ThemeProvider>
+      );
+      expect(screen.getByTestId("child")).toHaveTextContent("Hello");
+    });
+
+    it("provides theme via useTheme", () => {
+      render(
+        <ThemeProvider theme={defaultLightTheme}>
+          <ThemeDisplay />
+        </ThemeProvider>
+      );
+      expect(screen.getByTestId("theme-display")).toHaveAttribute("data-mode", "light");
+    });
+
+    it("provides dark theme correctly", () => {
+      render(
+        <ThemeProvider theme={defaultDarkTheme}>
+          <ThemeDisplay />
+        </ThemeProvider>
+      );
+      expect(screen.getByTestId("theme-display")).toHaveAttribute("data-mode", "dark");
+    });
+  });
+
+  describe("diff behavior", () => {
+    it("when theme equals parent, applies no styles", () => {
+      const {container} = render(
+        <ThemeProvider theme={defaultLightTheme}>
+          <ThemeProvider theme={defaultLightTheme}>
+            <ThemeDisplay />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const innerDiv = container.querySelectorAll("[style]")[1];
+      const style = innerDiv?.getAttribute("style") || "";
+      expect(style).toBe("");
+    });
+
+    it("nested provider only sets properties that differ from parent", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      // Compare full inline themes to verify they differ
+      const lightStyles = createInlineStyles(lightTheme);
+      const darkStyles = createInlineStyles(darkTheme);
+
+      // Count how many properties differ between light and dark
+      let diffCount = 0;
+      for (const key in darkStyles) {
+        if (darkStyles[key] !== lightStyles[key]) {
+          diffCount++;
+        }
+      }
+
+      // Dark and light themes should have differences
+      expect(diffCount).toBeGreaterThan(0);
+
+      // When nesting dark inside light, the inner provider should only set the diff
+      const {container} = render(
+        <ThemeProvider theme={lightTheme}>
+          <ThemeProvider theme={darkTheme}>
+            <ThemeDisplay />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      // Get all divs (ThemeProvider creates divs with display:contents)
+      const allDivs = container.querySelectorAll("div");
+      // Find divs with style attribute
+      const styledDivs = Array.from(allDivs).filter((d) => d.hasAttribute("style"));
+
+      // Inner provider's div should have styles (the diff)
+      expect(styledDivs.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it("deeply nested providers accumulate only diffs", () => {
+      const theme1 = getThemeColors(null, "light", palette);
+      const theme2 = getThemeColors(null, "dark", palette);
+      const theme3 = getThemeColors(null, "light", palette); // back to light
+
+      // Verify themes differ
+      const styles1 = createInlineStyles(theme1);
+      const styles2 = createInlineStyles(theme2);
+
+      let diffCount = 0;
+      for (const key in styles2) {
+        if (styles2[key] !== styles1[key]) {
+          diffCount++;
+        }
+      }
+      expect(diffCount).toBeGreaterThan(0);
+
+      const {container} = render(
+        <ThemeProvider theme={theme1}>
+          <ThemeProvider theme={theme2}>
+            <ThemeProvider theme={theme3}>
+              <ThemeDisplay />
+            </ThemeProvider>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      // Get styled divs
+      const allDivs = container.querySelectorAll("div");
+      const styledDivs = Array.from(allDivs).filter((d) => d.hasAttribute("style"));
+
+      // At least the middle one (dark) should have styles since it differs from light
+      // The innermost (light again) should also have styles since it differs from dark
+      expect(styledDivs.length).toBeGreaterThanOrEqual(2);
+    });
+  });
+
+  describe("context-based diff", () => {
+    it("diffs against parent context value", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+
+      // When parent context has same theme, diff should be empty
+      const {container} = render(
+        <ThemeProvider theme={lightTheme}>
+          <ThemeProvider theme={lightTheme}>
+            <ThemeDisplay />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      // Find the inner ThemeProvider's div
+      const divs = Array.from(container.querySelectorAll("div"));
+      const styledDivs = divs.filter((d) => d.hasAttribute("style"));
+
+      // Inner should have empty style (same theme as parent)
+      if (styledDivs.length >= 2) {
+        const innerStyle = styledDivs[1]?.getAttribute("style") || "";
+        expect(innerStyle).toBe("");
+      }
+    });
+
+    it("setting context before ThemeProvider controls diff base", () => {
+      // Outer ThemeProvider sets context to dark theme
+      // Inner ThemeProvider with same theme should have empty diff
+      const {container} = render(
+        <ThemeProvider theme={defaultDarkTheme}>
+          <ThemeProvider theme={defaultDarkTheme}>
+            <ThemeDisplay />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const divs = Array.from(container.querySelectorAll("div"));
+      const styledDivs = divs.filter((d) => d.hasAttribute("style"));
+
+      // Inner should have empty style (same as parent context)
+      if (styledDivs.length >= 2) {
+        const innerStyle = styledDivs[1]?.getAttribute("style") || "";
+        expect(innerStyle).toBe("");
+      }
+    });
+  });
+
+  describe("rejectKeys", () => {
+    it("by default, all properties are included in diff", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      const lightStyles = createInlineStyles(lightTheme);
+      const darkStyles = createInlineStyles(darkTheme);
+
+      let diffCount = 0;
+      for (const key in darkStyles) {
+        if (darkStyles[key] !== lightStyles[key]) {
+          diffCount++;
+        }
+      }
+
+      // Should have differences (dark differs from light)
+      expect(diffCount).toBeGreaterThan(0);
+
+      // Render and verify the diff is applied
+      const {container} = render(
+        <ThemeProvider theme={lightTheme}>
+          <ThemeProvider theme={darkTheme}>
+            <ThemeDisplay />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      // At least one div should have styles
+      const styledDivs = Array.from(container.querySelectorAll("div")).filter((d) => d.hasAttribute("style"));
+      expect(styledDivs.length).toBeGreaterThan(0);
+    });
+
+    it("without rejectKeys, uses default reject keys (fewer properties)", () => {
+      const theme = getThemeColors(null, "dark", palette);
+
+      const {container: withEmptyReject} = render(
+        <ThemeProvider theme={defaultLightTheme}>
+          <ThemeProvider theme={theme}>
+            <ThemeDisplay testId="with-empty" />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const {container: withDefaultReject} = render(
+        <ThemeProvider theme={defaultLightTheme}>
+          <ThemeProvider theme={theme}>
+            <ThemeDisplay testId="with-default" />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const divsEmpty = Array.from(withEmptyReject.querySelectorAll("div")).filter((d) => d.hasAttribute("style"));
+      const divsDefault = Array.from(withDefaultReject.querySelectorAll("div")).filter((d) => d.hasAttribute("style"));
+
+      const styleWithEmpty = divsEmpty[1]?.getAttribute("style") || "";
+      const styleWithDefault = divsDefault[1]?.getAttribute("style") || "";
+
+      const countEmpty = styleWithEmpty.split(";").filter((s) => s.includes(":")).length;
+      const countDefault = styleWithDefault.split(";").filter((s) => s.includes(":")).length;
+
+      // Default rejectKeys should result in fewer or equal properties
+      expect(countDefault).toBeLessThanOrEqual(countEmpty);
+    });
+  });
+
+  describe("useTheme and useThemeMode", () => {
+    it("useTheme returns current theme in nested context", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      render(
+        <ThemeProvider theme={lightTheme}>
+          <ThemeDisplay testId="outer" />
+          <ThemeProvider theme={darkTheme}>
+            <ThemeDisplay testId="inner" />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      expect(screen.getByTestId("outer")).toHaveAttribute("data-mode", "light");
+      expect(screen.getByTestId("inner")).toHaveAttribute("data-mode", "dark");
+    });
+
+    it("useThemeMode returns correct mode for each nesting level", () => {
+      render(
+        <ThemeProvider mode="light">
+          <ThemeDisplay testId="level1" />
+          <ThemeProvider mode="dark">
+            <ThemeDisplay testId="level2" />
+            <ThemeProvider mode="light">
+              <ThemeDisplay testId="level3" />
+            </ThemeProvider>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      expect(screen.getByTestId("level1")).toHaveAttribute("data-mode", "light");
+      expect(screen.getByTestId("level2")).toHaveAttribute("data-mode", "dark");
+      expect(screen.getByTestId("level3")).toHaveAttribute("data-mode", "light");
+    });
+  });
+
+  describe("color prop", () => {
+    it("generates theme with specified color", () => {
+      const customColor = "#FF0000";
+
+      render(
+        <ThemeProvider color={customColor} mode="light">
+          <ThemeDisplay />
+        </ThemeProvider>
+      );
+
+      // Theme should be generated with the custom color
+      expect(screen.getByTestId("theme-display")).toBeInTheDocument();
+    });
+
+    it("color={var(--...)} is a no-op (same theme as parent)", () => {
+      const {container} = render(
+        <ThemeProvider mode="light">
+          <ThemeProvider color={themeVars.accentTextColor}>
+            <ThemeDisplay />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const divs = Array.from(container.querySelectorAll("div")).filter((d) => !d.hasAttribute("data-testid"));
+      const innerDiv = divs[divs.length - 1];
+      const style = innerDiv?.getAttribute("style") || "";
+      expect(style).toBe("");
+    });
+  });
+
+  describe("style optimization verification", () => {
+    it("same theme nested produces no inline styles", () => {
+      const theme = getThemeColors(null, "light", palette);
+
+      const {container} = render(
+        <ThemeProvider theme={theme}>
+          <div data-testid="outer-content">
+            <ThemeProvider theme={theme}>
+              <div data-testid="inner-content">content</div>
+            </ThemeProvider>
+          </div>
+        </ThemeProvider>
+      );
+
+      // Find the inner ThemeProvider's div (second div with display:contents behavior)
+      const divs = Array.from(container.querySelectorAll("div"));
+      const themeProviderDivs = divs.filter(
+        (d) => !d.hasAttribute("data-testid") && d.textContent?.includes("content")
+      );
+
+      // The innermost ThemeProvider div should have empty or no style
+      const innerProviderDiv = themeProviderDivs.find((d) => {
+        const style = d.getAttribute("style");
+        return style === "" || style === null;
+      });
+
+      expect(innerProviderDiv).toBeTruthy();
+    });
+
+    it("switching light→dark→light produces symmetric diffs", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      const lightStyles = createInlineStyles(lightTheme);
+      const darkStyles = createInlineStyles(darkTheme);
+
+      // Calculate light→dark diff
+      const lightToDarkDiff: Record<string, string> = {};
+      for (const key in darkStyles) {
+        if (darkStyles[key] !== lightStyles[key]) {
+          lightToDarkDiff[key] = darkStyles[key];
+        }
+      }
+
+      // Calculate dark→light diff
+      const darkToLightDiff: Record<string, string> = {};
+      for (const key in lightStyles) {
+        if (lightStyles[key] !== darkStyles[key]) {
+          darkToLightDiff[key] = lightStyles[key];
+        }
+      }
+
+      // Both diffs should have the same keys (symmetric)
+      expect(Object.keys(lightToDarkDiff).sort()).toEqual(Object.keys(darkToLightDiff).sort());
+    });
+
+    it("diff count is significantly less than full theme count", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      const fullStyles = createInlineStyles(darkTheme);
+      const fullCount = Object.keys(fullStyles).length;
+
+      // Calculate diff
+      const lightStyles = createInlineStyles(lightTheme);
+      let diffCount = 0;
+      for (const key in fullStyles) {
+        if (fullStyles[key] !== lightStyles[key]) {
+          diffCount++;
+        }
+      }
+
+      // Diff should be smaller than full (many colors are the same between themes)
+      expect(diffCount).toBeLessThan(fullCount);
+      // But diff should still have meaningful changes
+      expect(diffCount).toBeGreaterThan(10);
+    });
+  });
+
+  describe("style helpers verification", () => {
+    it("getStyleCount returns correct number of CSS properties", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      // Same theme nested = inner div has no style attribute (empty diff)
+      const {container: sameContainer} = render(
+        <ThemeProvider theme={lightTheme}>
+          <ThemeProvider theme={lightTheme}>
+            <span>light</span>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      // Different theme nested = more styled divs
+      const {container: diffContainer} = render(
+        <ThemeProvider theme={lightTheme}>
+          <ThemeProvider theme={darkTheme}>
+            <span>dark</span>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const sameStyledDivCount = Array.from(sameContainer.querySelectorAll("div")).filter((d) =>
+        d.hasAttribute("style")
+      ).length;
+      const diffStyledDivCount = Array.from(diffContainer.querySelectorAll("div")).filter((d) =>
+        d.hasAttribute("style")
+      ).length;
+
+      // When themes are same, only outer has styles (inner diff is empty)
+      // When themes differ, both have styles
+      // So diff case should have >= same case
+      expect(diffStyledDivCount).toBeGreaterThanOrEqual(sameStyledDivCount);
+    });
+
+    it("getStyleObject returns parseable CSS properties", () => {
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      const {container} = render(
+        <ThemeProvider theme={defaultLightTheme}>
+          <ThemeProvider theme={darkTheme}>
+            <span>content</span>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      // Get the inner provider's div
+      const divs = Array.from(container.querySelectorAll("div")).filter((d) => d.hasAttribute("style"));
+      const innerDiv = divs[1];
+
+      if (innerDiv) {
+        const style = innerDiv.getAttribute("style") || "";
+        const styleObj: Record<string, string> = {};
+        style.split(";").forEach((s) => {
+          const [key, value] = s.split(":").map((x) => x.trim());
+          if (key && value) {
+            styleObj[key] = value;
+          }
+        });
+
+        const keys = Object.keys(styleObj);
+        expect(keys.length).toBeGreaterThan(0);
+
+        // All keys should be CSS custom properties starting with --
+        const cssVarKeys = keys.filter((k) => k.startsWith("--"));
+        expect(cssVarKeys.length).toBe(keys.length);
+      }
+    });
+
+    it("nested providers have decreasing style counts", () => {
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      // Outer: diff from context default
+      // Inner: only diff from outer (which should be 0 since same theme)
+      const {container} = render(
+        <ThemeProvider theme={darkTheme}>
+          <ThemeProvider theme={darkTheme}>
+            <span>nested same</span>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const styledDivs = Array.from(container.querySelectorAll("div")).filter((d) => d.hasAttribute("style"));
+
+      if (styledDivs.length >= 2) {
+        const outerStyle = styledDivs[0].getAttribute("style") || "";
+        const innerStyle = styledDivs[1].getAttribute("style") || "";
+
+        const outerCount = outerStyle.split(";").filter((s) => s.includes(":")).length;
+        const innerCount = innerStyle.split(";").filter((s) => s.includes(":")).length;
+
+        // Inner (same theme as parent) should have 0 styles
+        expect(innerCount).toBe(0);
+        // Outer should have styles (diff from context default)
+        expect(outerCount).toBeGreaterThanOrEqual(0);
+      }
+    });
+
+    it("getStyleObject can verify specific CSS variable values", () => {
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      const {container} = render(
+        <ThemeProvider theme={defaultLightTheme}>
+          <ThemeProvider theme={darkTheme}>
+            <span>content</span>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      // Get inner provider's style
+      const divs = Array.from(container.querySelectorAll("div")).filter((d) => d.hasAttribute("style"));
+      const innerDiv = divs[1];
+
+      if (innerDiv) {
+        const style = innerDiv.getAttribute("style") || "";
+        const values = style
+          .split(";")
+          .map((s) => s.split(":")[1]?.trim())
+          .filter(Boolean);
+
+        const colorValues = values.filter(
+          (v) => v.includes("rgb") || v.includes("hsl") || v.includes("#") || v.includes("oklch")
+        );
+
+        // Most theme values should be colors
+        expect(colorValues.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe("useThemeStyles", () => {
+    function StylesDisplay({testId = "styles"}: {testId?: string}) {
+      const styles = useThemeStyles();
+      return <div data-testid={testId} data-style-count={Object.keys(styles).length} />;
+    }
+
+    it("returns computed styles from context", () => {
+      render(
+        <ThemeProvider theme={defaultLightTheme}>
+          <StylesDisplay />
+        </ThemeProvider>
+      );
+      const count = Number(screen.getByTestId("styles").getAttribute("data-style-count"));
+      expect(count).toBeGreaterThan(0);
+    });
+
+    it("returns default styles outside ThemeProvider", () => {
+      render(<StylesDisplay />);
+      const count = Number(screen.getByTestId("styles").getAttribute("data-style-count"));
+      expect(count).toBe(Object.keys(defaultLightThemeStyles).length);
+    });
+
+    it("nested provider updates styles context", () => {
+      render(
+        <ThemeProvider theme={defaultLightTheme}>
+          <StylesDisplay testId="outer" />
+          <ThemeProvider theme={defaultDarkTheme}>
+            <StylesDisplay testId="inner" />
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+      const outerCount = Number(screen.getByTestId("outer").getAttribute("data-style-count"));
+      const innerCount = Number(screen.getByTestId("inner").getAttribute("data-style-count"));
+      expect(outerCount).toBe(innerCount);
+    });
+  });
+
+  describe("MenuThemeProvider", () => {
+    it("provides dark mode for light2 parent", () => {
+      render(
+        <ThemeProvider mode="light2">
+          <MenuThemeProvider>
+            <ThemeDisplay />
+          </MenuThemeProvider>
+        </ThemeProvider>
+      );
+      expect(screen.getByTestId("theme-display")).toHaveAttribute("data-mode", "dark");
+    });
+
+    it("provides light mode for light parent", () => {
+      render(
+        <ThemeProvider mode="light">
+          <MenuThemeProvider>
+            <ThemeDisplay />
+          </MenuThemeProvider>
+        </ThemeProvider>
+      );
+      expect(screen.getByTestId("theme-display")).toHaveAttribute("data-mode", "light");
+    });
+
+    it("provides dark mode for dark parent", () => {
+      render(
+        <ThemeProvider mode="dark">
+          <MenuThemeProvider>
+            <ThemeDisplay />
+          </MenuThemeProvider>
+        </ThemeProvider>
+      );
+      expect(screen.getByTestId("theme-display")).toHaveAttribute("data-mode", "dark");
+    });
+  });
+
+  describe("portal mode", () => {
+    function getStyleCount(el: Element) {
+      const style = el.getAttribute("style") || "";
+      return style.split(";").filter((s) => s.includes(":")).length;
+    }
+
+    function getThemeProviderDivs(container: HTMLElement) {
+      return Array.from(container.querySelectorAll("div")).filter((d) => !d.hasAttribute("data-testid"));
+    }
+
+    function renderWithRoot(children: React.ReactNode, mode: "light" | "dark" = "light") {
+      return render(
+        <RootThemeProvider initialThemeMode={mode} initialPreference={mode} initialMenuPreference={"auto"}>
+          {children}
+        </RootThemeProvider>
+      );
+    }
+
+    it("diffs against root styles, not parent context", () => {
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      // Non-portal dark inside dark parent: diffs against parent (same) → 0 styles
+      const {container: normalContainer} = renderWithRoot(
+        <ThemeProvider theme={darkTheme}>
+          <ThemeProvider theme={darkTheme}>
+            <span>normal</span>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      // Portal dark inside dark parent: diffs against root (light) → many styles
+      const {container: portalContainer} = renderWithRoot(
+        <ThemeProvider theme={darkTheme}>
+          <ThemeProvider theme={darkTheme} portal>
+            <span>portal</span>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const normalDivs = getThemeProviderDivs(normalContainer);
+      const portalDivs = getThemeProviderDivs(portalContainer);
+
+      const normalInner = normalDivs[normalDivs.length - 1];
+      const portalInner = portalDivs[portalDivs.length - 1];
+
+      const normalCount = getStyleCount(normalInner);
+      const portalCount = getStyleCount(portalInner);
+
+      // Non-portal: same theme as parent → 0 diff
+      expect(normalCount).toBe(0);
+      // Portal: dark vs light root → many overrides
+      expect(portalCount).toBeGreaterThan(0);
+    });
+
+    it("when theme matches root, produces no inline styles", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+
+      const {container} = renderWithRoot(
+        <ThemeProvider theme={lightTheme} portal>
+          <span>portal same as root</span>
+        </ThemeProvider>
+      );
+
+      // The portal ThemeProvider div is after the root one
+      const divs = getThemeProviderDivs(container);
+      const portalDiv = divs[divs.length - 1];
+      expect(getStyleCount(portalDiv)).toBe(0);
+    });
+
+    it("when theme differs from root, emits diff against root", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      const lightStyles = createInlineStyles(lightTheme);
+      const darkStyles = createInlineStyles(darkTheme);
+      let expectedDiffCount = 0;
+      for (const key in darkStyles) {
+        if (darkStyles[key] !== lightStyles[key]) {
+          expectedDiffCount++;
+        }
+      }
+
+      const {container} = renderWithRoot(
+        <ThemeProvider theme={darkTheme} portal>
+          <span>portal dark</span>
+        </ThemeProvider>
+      );
+
+      const divs = getThemeProviderDivs(container);
+      const portalDiv = divs[divs.length - 1];
+      expect(getStyleCount(portalDiv)).toBe(expectedDiffCount);
+    });
+
+    it("portal ignores intermediate parent overrides for diff base", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      // root(light) > dark > portal(light)
+      // Portal diffs against root(light), not dark parent
+      // Since portal theme === root theme, diff should be empty
+      const {container} = renderWithRoot(
+        <ThemeProvider theme={darkTheme}>
+          <ThemeProvider theme={lightTheme} portal>
+            <span>portal</span>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const divs = getThemeProviderDivs(container);
+      const portalDiv = divs[divs.length - 1];
+      expect(getStyleCount(portalDiv)).toBe(0);
+    });
+
+    it("portal with dark mode emits overrides vs light root", () => {
+      const lightTheme = getThemeColors(null, "light", palette);
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      const lightStyles = createInlineStyles(lightTheme);
+      const darkStyles = createInlineStyles(darkTheme);
+      let expectedDiffCount = 0;
+      for (const key in darkStyles) {
+        if (darkStyles[key] !== lightStyles[key]) {
+          expectedDiffCount++;
+        }
+      }
+      expect(expectedDiffCount).toBeGreaterThan(0);
+
+      const {container} = renderWithRoot(
+        <ThemeProvider theme={darkTheme} portal>
+          <span>portal dark</span>
+        </ThemeProvider>
+      );
+
+      const divs = getThemeProviderDivs(container);
+      const portalDiv = divs[divs.length - 1];
+      expect(getStyleCount(portalDiv)).toBe(expectedDiffCount);
+    });
+
+    it("non-portal still diffs against parent context", () => {
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      // Non-portal nested with same theme as parent: empty diff
+      const {container} = renderWithRoot(
+        <ThemeProvider theme={darkTheme}>
+          <ThemeProvider theme={darkTheme}>
+            <span>same</span>
+          </ThemeProvider>
+        </ThemeProvider>
+      );
+
+      const divs = getThemeProviderDivs(container);
+      const innerDiv = divs[divs.length - 1];
+      expect(getStyleCount(innerDiv)).toBe(0);
+    });
+
+    it("provides correct theme context regardless of portal flag", () => {
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      renderWithRoot(
+        <ThemeProvider theme={darkTheme} portal>
+          <ThemeDisplay testId="portal-child" />
+        </ThemeProvider>
+      );
+
+      expect(screen.getByTestId("portal-child")).toHaveAttribute("data-mode", "dark");
+    });
+
+    it("provides correct ThemeStylesContext inside portal", () => {
+      const darkTheme = getThemeColors(null, "dark", palette);
+
+      function StylesCheck() {
+        const styles = useThemeStyles();
+        const expected = createInlineStyles(darkTheme);
+        const match = Object.keys(expected).every((k) => styles[k] === expected[k]);
+        return <div data-testid="styles-match" data-match={String(match)} />;
+      }
+
+      renderWithRoot(
+        <ThemeProvider theme={darkTheme} portal>
+          <StylesCheck />
+        </ThemeProvider>
+      );
+
+      expect(screen.getByTestId("styles-match")).toHaveAttribute("data-match", "true");
+    });
+  });
+
+  describe("error handling", () => {
+    const originalError = console.error;
+    beforeAll(() => {
+      console.error = jest.fn();
+    });
+    afterAll(() => {
+      console.error = originalError;
+    });
+
+    it("useThemePreference throws outside RootThemeProvider", () => {
+      function BadComponent() {
+        useThemePreference();
+        return null;
+      }
+      expect(() => render(<BadComponent />)).toThrow(/RootThemeProvider/);
+    });
+
+    it("useThemeMenuPreference throws outside RootThemeProvider", () => {
+      function BadComponent() {
+        useThemeMenuPreference();
+        return null;
+      }
+      expect(() => render(<BadComponent />)).toThrow(/RootThemeProvider/);
+    });
+  });
+});