An open source design system that's fully customizable and agent ready
TypeScript
fix(theme): sync data-xds-theme to <html> for root provider; add LayerProvider to sandbox (#1587)
Cindy Zhang4c325c38b4b9
diff --git a/apps/sandbox/src/app/providers.tsx b/apps/sandbox/src/app/providers.tsxindex fb0b7d15e4..ab562b8080 100644--- a/apps/sandbox/src/app/providers.tsx+++ b/apps/sandbox/src/app/providers.tsx@@ -2,6 +2,7 @@import {useState, createContext, useContext, useEffect} from 'react';import {XDSTheme} from '@xds/core/theme';+import {XDSLayerProvider} from '@xds/core/Layer';import {defaultTheme} from '@xds/theme-default/built';import {neutralTheme} from '@xds/theme-neutral/built';import {brutalistTheme} from '@xds/theme-brutalist/built';@@ -47,7 +48,7 @@ export function Providers({children}: {children: React.ReactNode}) {return (<ThemeContext.Provider value={{themeName, setThemeName, mode, setMode}}><XDSTheme theme={theme} mode={mode}>- {children}+ <XDSLayerProvider>{children}</XDSLayerProvider></XDSTheme></ThemeContext.Provider>);diff --git a/packages/core/src/theme/XDSTheme.test.tsx b/packages/core/src/theme/XDSTheme.test.tsxindex 8402a7ec40..de18d8244c 100644--- a/packages/core/src/theme/XDSTheme.test.tsx+++ b/packages/core/src/theme/XDSTheme.test.tsx@@ -22,11 +22,13 @@ describe('XDSTheme', () => {beforeEach(() => {// Clean up documentElement state before each testdocument.documentElement.removeAttribute('data-theme');+ document.documentElement.removeAttribute('data-xds-theme');});afterEach(() => {cleanup();document.documentElement.removeAttribute('data-theme');+ document.documentElement.removeAttribute('data-xds-theme');});it('renders children', () => {@@ -91,10 +93,52 @@ describe('XDSTheme', () => {expect(document.documentElement.hasAttribute('data-theme')).toBe(false);});+ // =========================================================================+ // Root detection — data-xds-theme on <html>+ // =========================================================================++ it('syncs data-xds-theme to <html> for root provider', () => {+ render(+ <XDSTheme theme={testTheme} mode="light">+ <span>child</span>+ </XDSTheme>,+ );+ expect(document.documentElement.getAttribute('data-xds-theme')).toBe(+ 'test',+ );+ });++ it('removes data-xds-theme from <html> when root provider unmounts', () => {+ const {unmount} = render(+ <XDSTheme theme={testTheme} mode="light">+ <span>child</span>+ </XDSTheme>,+ );+ expect(document.documentElement.getAttribute('data-xds-theme')).toBe(+ 'test',+ );+ unmount();+ expect(document.documentElement.hasAttribute('data-xds-theme')).toBe(false);+ });+// =========================================================================// Nested themes — should NOT sync to <html>// =========================================================================+ it('does not let nested XDSTheme override <html> data-xds-theme', () => {+ render(+ <XDSTheme theme={testTheme} mode="dark">+ <XDSTheme theme={altTheme} mode="light">+ <span>nested</span>+ </XDSTheme>+ </XDSTheme>,+ );+ // Root is "test" — nested "alt" should NOT override+ expect(document.documentElement.getAttribute('data-xds-theme')).toBe(+ 'test',+ );+ });+it('does not let nested XDSTheme override <html> data-theme', () => {render(<XDSTheme theme={testTheme} mode="dark">diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsxindex dfa25d46d3..4b90a069fe 100644--- a/packages/core/src/theme/XDSTheme.tsx+++ b/packages/core/src/theme/XDSTheme.tsx@@ -9,9 +9,11 @@* - Component overrides scoped via @scope'd CSS selectors on .xds-* classes** Root detection: The first XDSTheme in the tree (no parent XDSTheme)- * automatically syncs `data-theme` to `document.documentElement`, which- * drives `color-scheme` via reset.css rules. This ensures browser chrome- * (scrollbars, native form controls, date pickers) reflects the active mode.+ * automatically syncs attributes to `document.documentElement`:+ * - `data-theme` — drives `color-scheme` via reset.css rules, ensuring browser+ * chrome (scrollbars, native form controls, date pickers) reflects the mode.+ * - `data-xds-theme` — enables @scope'd theme CSS to reach elements rendered+ * outside the XDSTheme wrapper (portals, toast fallback viewports).** For RSC / SSR, set `data-theme` on `<html>` in your root server layout* to avoid a flash of wrong theme before hydration:@@ -244,16 +246,23 @@ function useThemeFontLoading(theme: XDSDefinedTheme): void {// =============================================================================/**- * Hook to sync data-theme to document.documentElement for the root provider.+ * Hook to sync theme attributes to document.documentElement for the root provider.* Skipped for nested XDSTheme instances.*- * reset.css maps [data-theme] to color-scheme, which controls browser chrome- * (scrollbars, native form controls, date pickers).+ * Syncs two attributes:+ * - `data-theme` (light/dark) — reset.css maps this to color-scheme, controlling+ * browser chrome (scrollbars, native form controls, date pickers).+ * - `data-xds-theme` (theme name) — enables @scope'd theme CSS to reach elements+ * outside the XDSTheme wrapper (e.g. toast fallback viewports, portals).** - 'light' | 'dark' → sets data-theme="light" | "dark"* - 'system' → removes data-theme (reset.css defaults to color-scheme: light dark)*/-function useRootColorSchemeSync(isNested: boolean, mode: ThemeMode): void {+function useRootThemeSync(+ isNested: boolean,+ mode: ThemeMode,+ themeName: string,+): void {useLayoutEffect(() => {if (isNested) return;if (typeof document === 'undefined') return;@@ -265,10 +274,14 @@ function useRootColorSchemeSync(isNested: boolean, mode: ThemeMode): void {document.documentElement.removeAttribute('data-theme');}+ // Sync theme name so @scope rules reach portals/fallback viewports+ document.documentElement.setAttribute('data-xds-theme', themeName);+return () => {document.documentElement.removeAttribute('data-theme');+ document.documentElement.removeAttribute('data-xds-theme');};- }, [isNested, mode]);+ }, [isNested, mode, themeName]);}// =============================================================================@@ -283,8 +296,8 @@ function useRootColorSchemeSync(isNested: boolean, mode: ThemeMode): void {* components render with their .xds-* class and don't need context.** When this is the root XDSTheme (no parent XDSTheme in the tree),- * it syncs `data-theme` to `<html>` so browser chrome elements- * (scrollbars, form controls, date pickers) reflect the active mode.+ * it syncs `data-theme` and `data-xds-theme` to `<html>` so browser+ * chrome reflects the active mode and @scope'd CSS reaches portals.* Nested XDSTheme instances skip the sync.*/export function XDSTheme({@@ -296,7 +309,7 @@ export function XDSTheme({useThemeStyleInjection(theme);useThemeFontLoading(theme);- useRootColorSchemeSync(isNested, mode);+ useRootThemeSync(isNested, mode, theme.name);// Get color-scheme styleconst colorSchemeStyle =