@flipdish/ui-library 0.7.1 → 0.7.3

package/dist/providers/PortalContainer/index.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var reactAria = require('react-aria');
+
+/**
+ * Redirects React Aria overlay portals into a specific DOM container instead of
+ * `document.body`. Use for micro-frontends and embedded apps with scoped CSS.
+ *
+ * @summary redirects React Aria overlay portals into a scoped DOM container
+ */
+const PortalContainer = ({ getContainer, children }) => {
+    if (!getContainer) {
+        return jsxRuntime.jsx(jsxRuntime.Fragment, { children: children });
+    }
+    return jsxRuntime.jsx(reactAria.UNSAFE_PortalProvider, { getContainer: getContainer, children: children });
+};
+
+exports.PortalContainer = PortalContainer;
+//# sourceMappingURL=index.cjs.map

package/dist/providers/PortalContainer/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../../../src/providers/PortalContainer/index.tsx"],"sourcesContent":[null],"names":["_jsx","_Fragment","UNSAFE_PortalProvider"],"mappings":";;;;;AA+BA;;;;;AAKG;AACI,MAAM,eAAe,GAAG,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAwB,KAAI;IAClF,IAAI,CAAC,YAAY,EAAE;QACjB,OAAOA,cAAA,CAAAC,mBAAA,EAAA,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAI;IACxB;IAEA,OAAOD,cAAA,CAACE,+BAAqB,EAAA,EAAC,YAAY,EAAE,YAAY,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAyB;AAC9F;;;;"}

package/dist/providers/PortalContainer/index.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+export interface PortalContainerProps {
+    /**
+     * Callback that returns the DOM element where React Aria overlays (Modal, Popover,
+     * Select, Tooltip, Toast) should portal into. Use this in micro-frontends or
+     * embedded apps whose CSS is scoped to a mount subtree (e.g. via
+     * `postcss-prefix-selector`) — overlays that portal to `document.body` would land
+     * outside the scoped subtree and render unstyled.
+     *
+     * A callback (rather than an element ref) is required because the container may not
+     * exist at module-evaluation time.
+     *
+     * **Note on the `UNSAFE_` prefix:** Under the hood this wraps React Aria's
+     * `UNSAFE_PortalProvider`. The prefix is React Aria's naming convention for escape
+     * hatches that override tested defaults — it signals "you are opting out of a
+     * default we test against", not a stability or production-readiness warning. It is
+     * safe to use in production for light-DOM scoped subtrees. Shadow DOM has a
+     * {@link https://github.com/adobe/react-spectrum/issues/8675 known interaction issue}
+     * and is out of scope.
+     *
+     * @example
+     * <PortalContainer getContainer={() => document.getElementById('flipdish-micro-frontend')}>
+     *   <App />
+     * </PortalContainer>
+     */
+    getContainer: (() => HTMLElement | null) | null;
+    children: ReactNode;
+}
+/**
+ * Redirects React Aria overlay portals into a specific DOM container instead of
+ * `document.body`. Use for micro-frontends and embedded apps with scoped CSS.
+ *
+ * @summary redirects React Aria overlay portals into a scoped DOM container
+ */
+export declare const PortalContainer: ({ getContainer, children }: PortalContainerProps) => import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/PortalContainer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/PortalContainer/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,YAAY,EAAE,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAChD,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,4BAA4B,oBAAoB,gCAM/E,CAAC"}

package/dist/providers/PortalContainer/index.js

@@ -0,0 +1,18 @@
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { UNSAFE_PortalProvider } from 'react-aria';
+
+/**
+ * Redirects React Aria overlay portals into a specific DOM container instead of
+ * `document.body`. Use for micro-frontends and embedded apps with scoped CSS.
+ *
+ * @summary redirects React Aria overlay portals into a scoped DOM container
+ */
+const PortalContainer = ({ getContainer, children }) => {
+    if (!getContainer) {
+        return jsx(Fragment, { children: children });
+    }
+    return jsx(UNSAFE_PortalProvider, { getContainer: getContainer, children: children });
+};
+
+export { PortalContainer };
+//# sourceMappingURL=index.js.map

package/dist/providers/PortalContainer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/providers/PortalContainer/index.tsx"],"sourcesContent":[null],"names":["_jsx","_Fragment"],"mappings":";;;AA+BA;;;;;AAKG;AACI,MAAM,eAAe,GAAG,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAwB,KAAI;IAClF,IAAI,CAAC,YAAY,EAAE;QACjB,OAAOA,GAAA,CAAAC,QAAA,EAAA,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAI;IACxB;IAEA,OAAOD,GAAA,CAAC,qBAAqB,EAAA,EAAC,YAAY,EAAE,YAAY,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAyB;AAC9F;;;;"}

package/dist/providers/ThemeProvider/index.cjs

@@ -11,8 +11,13 @@ const useTheme = () => {
     }
     return context;
 };
+const resolveSystemPreference = () => {
+    if (typeof window === 'undefined')
+        return 'light';
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+};
 /**
- * @summary app-wide light/dark/system theme provider that syncs the root `data-theme` attribute
+ * @summary app-wide light/dark/system theme provider that renders a themed `display: contents` wrapper carrying `data-theme`
  */
 const ThemeProvider = ({ children, defaultTheme = 'system', storageKey = 'ui-theme', themeModeOverride }) => {
     const [theme, setTheme] = React.useState(() => {
@@ -22,37 +27,28 @@ const ThemeProvider = ({ children, defaultTheme = 'system', storageKey = 'ui-the
         }
         return defaultTheme;
     });
+    const [systemPreference, setSystemPreference] = React.useState(resolveSystemPreference);
+    const [themeRoot, setThemeRoot] = React.useState(null);
     const activeTheme = themeModeOverride ?? theme;
+    const resolvedMode = activeTheme === 'system' ? systemPreference : activeTheme;
     React.useEffect(() => {
-        const resolveTheme = (value) => value === 'system' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : value;
-        const applyTheme = () => {
-            const root = window.document.documentElement;
-            // The token layer + Tailwind `dark:` variant cascade on `[data-theme="dark"]`
-            // (see @flipdish/ui-tokens + src/styles.css), so drive that attribute here.
-            root.setAttribute('data-theme', resolveTheme(activeTheme));
-            // Controlled usage (e.g. Storybook) is ephemeral — don't touch persisted state.
-            if (themeModeOverride) {
-                return;
-            }
+        document.documentElement.setAttribute('data-theme', resolvedMode);
+        // Only persist the theme if it's not overridden
+        if (!themeModeOverride) {
             if (activeTheme === 'system') {
                 localStorage.removeItem(storageKey);
             }
             else {
                 localStorage.setItem(storageKey, activeTheme);
             }
-        };
-        applyTheme();
-        // Listen for system theme changes
+        }
         const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
-        const handleChange = () => {
-            if (activeTheme === 'system') {
-                applyTheme();
-            }
-        };
+        const handleChange = () => setSystemPreference(mediaQuery.matches ? 'dark' : 'light');
         mediaQuery.addEventListener('change', handleChange);
         return () => mediaQuery.removeEventListener('change', handleChange);
-    }, [activeTheme, themeModeOverride, storageKey]);
-    return jsxRuntime.jsx(ThemeContext.Provider, { value: { theme: activeTheme, setTheme }, children: children });
+    }, [resolvedMode, activeTheme, themeModeOverride, storageKey]);
+    const contextValue = React.useMemo(() => ({ theme: activeTheme, setTheme, themeRoot, resolvedMode }), [activeTheme, themeRoot, resolvedMode]);
+    return (jsxRuntime.jsx(ThemeContext.Provider, { value: contextValue, children: jsxRuntime.jsx("div", { ref: setThemeRoot, "data-theme": resolvedMode, style: { display: 'contents' }, children: children }) }));
 };
 
 exports.ThemeProvider = ThemeProvider;

package/dist/providers/ThemeProvider/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../../../src/providers/ThemeProvider/index.tsx"],"sourcesContent":[null],"names":["createContext","useContext","useState","useEffect","_jsx"],"mappings":";;;;;AAUA,MAAM,YAAY,GAAGA,mBAAa,CAA+B,SAAS,CAAC;AAEpE,MAAM,QAAQ,GAAG,MAAuB;AAC7C,IAAA,MAAM,OAAO,GAAGC,gBAAU,CAAC,YAAY,CAAC;AAExC,IAAA,IAAI,OAAO,KAAK,SAAS,EAAE;AACzB,QAAA,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC;IACjE;AAEA,IAAA,OAAO,OAAO;AAChB;AAqBA;;AAEG;AACI,MAAM,aAAa,GAAG,CAAC,EAAE,QAAQ,EAAE,YAAY,GAAG,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,iBAAiB,EAAsB,KAAI;IACrI,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAGC,cAAQ,CAAQ,MAAK;AAC7C,QAAA,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE;YACjC,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,UAAU,CAAiB;YACnE,OAAO,UAAU,IAAI,YAAY;QACnC;AACA,QAAA,OAAO,YAAY;AACrB,IAAA,CAAC,CAAC;AAEF,IAAA,MAAM,WAAW,GAAU,iBAAiB,IAAI,KAAK;IAErDC,eAAS,CAAC,MAAK;AACb,QAAA,MAAM,YAAY,GAAG,CAAC,KAAY,KAChC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO,IAAI,KAAK;QAE7G,MAAM,UAAU,GAAG,MAAK;AACtB,YAAA,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,eAAe;;;YAI5C,IAAI,CAAC,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;;YAG1D,IAAI,iBAAiB,EAAE;gBACrB;YACF;AAEA,YAAA,IAAI,WAAW,KAAK,QAAQ,EAAE;AAC5B,gBAAA,YAAY,CAAC,UAAU,CAAC,UAAU,CAAC;YACrC;iBAAO;AACL,gBAAA,YAAY,CAAC,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC;YAC/C;AACF,QAAA,CAAC;AAED,QAAA,UAAU,EAAE;;QAGZ,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC;QAEpE,MAAM,YAAY,GAAG,MAAK;AACxB,YAAA,IAAI,WAAW,KAAK,QAAQ,EAAE;AAC5B,gBAAA,UAAU,EAAE;YACd;AACF,QAAA,CAAC;AAED,QAAA,UAAU,CAAC,gBAAgB,CAAC,QAAQ,EAAE,YAAY,CAAC;QACnD,OAAO,MAAM,UAAU,CAAC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,CAAC;IACrE,CAAC,EAAE,CAAC,WAAW,EAAE,iBAAiB,EAAE,UAAU,CAAC,CAAC;AAEhD,IAAA,OAAOC,eAAC,YAAY,CAAC,QAAQ,EAAA,EAAC,KAAK,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAA,QAAA,EAAG,QAAQ,GAAyB;AAC3G;;;;;"}
+{"version":3,"file":"index.cjs","sources":["../../../src/providers/ThemeProvider/index.tsx"],"sourcesContent":[null],"names":["createContext","useContext","useState","useEffect","useMemo","_jsx"],"mappings":";;;;;AAYA,MAAM,YAAY,GAAGA,mBAAa,CAA+B,SAAS,CAAC;AAEpE,MAAM,QAAQ,GAAG,MAAuB;AAC7C,IAAA,MAAM,OAAO,GAAGC,gBAAU,CAAC,YAAY,CAAC;AAExC,IAAA,IAAI,OAAO,KAAK,SAAS,EAAE;AACzB,QAAA,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC;IACjE;AAEA,IAAA,OAAO,OAAO;AAChB;AAEA,MAAM,uBAAuB,GAAG,MAAuB;IACrD,IAAI,OAAO,MAAM,KAAK,WAAW;AAAE,QAAA,OAAO,OAAO;AACjD,IAAA,OAAO,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO;AACrF,CAAC;AAqBD;;AAEG;AACI,MAAM,aAAa,GAAG,CAAC,EAAE,QAAQ,EAAE,YAAY,GAAG,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,iBAAiB,EAAsB,KAAI;IACrI,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAGC,cAAQ,CAAQ,MAAK;AAC7C,QAAA,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE;YACjC,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,UAAU,CAAiB;YACnE,OAAO,UAAU,IAAI,YAAY;QACnC;AACA,QAAA,OAAO,YAAY;AACrB,IAAA,CAAC,CAAC;IAEF,MAAM,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,GAAGA,cAAQ,CAAmB,uBAAuB,CAAC;IACnG,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAGA,cAAQ,CAAqB,IAAI,CAAC;AAEpE,IAAA,MAAM,WAAW,GAAU,iBAAiB,IAAI,KAAK;AACrD,IAAA,MAAM,YAAY,GAAqB,WAAW,KAAK,QAAQ,GAAG,gBAAgB,GAAG,WAAW;IAEhGC,eAAS,CAAC,MAAK;QACb,QAAQ,CAAC,eAAe,CAAC,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC;;QAGjE,IAAI,CAAC,iBAAiB,EAAE;AACtB,YAAA,IAAI,WAAW,KAAK,QAAQ,EAAE;AAC5B,gBAAA,YAAY,CAAC,UAAU,CAAC,UAAU,CAAC;YACrC;iBAAO;AACL,gBAAA,YAAY,CAAC,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC;YAC/C;QACF;QAEA,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC;AACpE,QAAA,MAAM,YAAY,GAAG,MAAM,mBAAmB,CAAC,UAAU,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AACrF,QAAA,UAAU,CAAC,gBAAgB,CAAC,QAAQ,EAAE,YAAY,CAAC;QACnD,OAAO,MAAM,UAAU,CAAC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,CAAC;IACrE,CAAC,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,UAAU,CAAC,CAAC;AAE9D,IAAA,MAAM,YAAY,GAAGC,aAAO,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;AAEvI,IAAA,QACEC,cAAA,CAAC,YAAY,CAAC,QAAQ,EAAA,EAAC,KAAK,EAAE,YAAY,EAAA,QAAA,EACxCA,cAAA,CAAA,KAAA,EAAA,EAAK,GAAG,EAAE,YAAY,EAAA,YAAA,EAAc,YAAY,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,EAAA,QAAA,EAC7E,QAAQ,EAAA,CACL,EAAA,CACgB;AAE5B;;;;;"}

package/dist/providers/ThemeProvider/index.d.ts

@@ -3,6 +3,8 @@ type Theme = 'light' | 'dark' | 'system';
 interface ThemeContextType {
     theme: Theme;
     setTheme: (theme: Theme) => void;
+    themeRoot: HTMLElement | null;
+    resolvedMode: 'light' | 'dark';
 }
 export declare const useTheme: () => ThemeContextType;
 interface ThemeProviderProps {
@@ -19,12 +21,12 @@ interface ThemeProviderProps {
     storageKey?: string;
     /**
      * Controlled theme override. When set, the provider mirrors this value instead of its
-     * internal state and skips localStorage persistence — useful for Storybook toolbars or tests.
+     * internal state and skips localStorage persistence — useful for controlled MFE's or tests.
      */
     themeModeOverride?: 'light' | 'dark';
 }
 /**
- * @summary app-wide light/dark/system theme provider that syncs the root `data-theme` attribute
+ * @summary app-wide light/dark/system theme provider that renders a themed `display: contents` wrapper carrying `data-theme`
  */
 export declare const ThemeProvider: ({ children, defaultTheme, storageKey, themeModeOverride }: ThemeProviderProps) => import("react").JSX.Element;
 export {};

package/dist/providers/ThemeProvider/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/ThemeProvider/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,KAAK,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEzC,UAAU,gBAAgB;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAID,eAAO,MAAM,QAAQ,QAAO,gBAQ3B,CAAC;AAEF,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,2DAAmF,kBAAkB,gCAkDlI,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/ThemeProvider/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,KAAK,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEzC,UAAU,gBAAgB;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,OAAO,GAAG,MAAM,CAAC;CAChC;AAID,eAAO,MAAM,QAAQ,QAAO,gBAQ3B,CAAC;AAOF,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,2DAAmF,kBAAkB,gCA0ClI,CAAC"}

package/dist/providers/ThemeProvider/index.js

@@ -1,5 +1,5 @@
 import { jsx } from 'react/jsx-runtime';
-import { createContext, useState, useEffect, useContext } from 'react';
+import { createContext, useState, useEffect, useMemo, useContext } from 'react';
 
 const ThemeContext = createContext(undefined);
 const useTheme = () => {
@@ -9,8 +9,13 @@ const useTheme = () => {
     }
     return context;
 };
+const resolveSystemPreference = () => {
+    if (typeof window === 'undefined')
+        return 'light';
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+};
 /**
- * @summary app-wide light/dark/system theme provider that syncs the root `data-theme` attribute
+ * @summary app-wide light/dark/system theme provider that renders a themed `display: contents` wrapper carrying `data-theme`
  */
 const ThemeProvider = ({ children, defaultTheme = 'system', storageKey = 'ui-theme', themeModeOverride }) => {
     const [theme, setTheme] = useState(() => {
@@ -20,37 +25,28 @@ const ThemeProvider = ({ children, defaultTheme = 'system', storageKey = 'ui-the
         }
         return defaultTheme;
     });
+    const [systemPreference, setSystemPreference] = useState(resolveSystemPreference);
+    const [themeRoot, setThemeRoot] = useState(null);
     const activeTheme = themeModeOverride ?? theme;
+    const resolvedMode = activeTheme === 'system' ? systemPreference : activeTheme;
     useEffect(() => {
-        const resolveTheme = (value) => value === 'system' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : value;
-        const applyTheme = () => {
-            const root = window.document.documentElement;
-            // The token layer + Tailwind `dark:` variant cascade on `[data-theme="dark"]`
-            // (see @flipdish/ui-tokens + src/styles.css), so drive that attribute here.
-            root.setAttribute('data-theme', resolveTheme(activeTheme));
-            // Controlled usage (e.g. Storybook) is ephemeral — don't touch persisted state.
-            if (themeModeOverride) {
-                return;
-            }
+        document.documentElement.setAttribute('data-theme', resolvedMode);
+        // Only persist the theme if it's not overridden
+        if (!themeModeOverride) {
             if (activeTheme === 'system') {
                 localStorage.removeItem(storageKey);
             }
             else {
                 localStorage.setItem(storageKey, activeTheme);
             }
-        };
-        applyTheme();
-        // Listen for system theme changes
+        }
         const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
-        const handleChange = () => {
-            if (activeTheme === 'system') {
-                applyTheme();
-            }
-        };
+        const handleChange = () => setSystemPreference(mediaQuery.matches ? 'dark' : 'light');
         mediaQuery.addEventListener('change', handleChange);
         return () => mediaQuery.removeEventListener('change', handleChange);
-    }, [activeTheme, themeModeOverride, storageKey]);
-    return jsx(ThemeContext.Provider, { value: { theme: activeTheme, setTheme }, children: children });
+    }, [resolvedMode, activeTheme, themeModeOverride, storageKey]);
+    const contextValue = useMemo(() => ({ theme: activeTheme, setTheme, themeRoot, resolvedMode }), [activeTheme, themeRoot, resolvedMode]);
+    return (jsx(ThemeContext.Provider, { value: contextValue, children: jsx("div", { ref: setThemeRoot, "data-theme": resolvedMode, style: { display: 'contents' }, children: children }) }));
 };
 
 export { ThemeProvider, useTheme };

package/dist/providers/ThemeProvider/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/providers/ThemeProvider/index.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;AAUA,MAAM,YAAY,GAAG,aAAa,CAA+B,SAAS,CAAC;AAEpE,MAAM,QAAQ,GAAG,MAAuB;AAC7C,IAAA,MAAM,OAAO,GAAG,UAAU,CAAC,YAAY,CAAC;AAExC,IAAA,IAAI,OAAO,KAAK,SAAS,EAAE;AACzB,QAAA,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC;IACjE;AAEA,IAAA,OAAO,OAAO;AAChB;AAqBA;;AAEG;AACI,MAAM,aAAa,GAAG,CAAC,EAAE,QAAQ,EAAE,YAAY,GAAG,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,iBAAiB,EAAsB,KAAI;IACrI,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAQ,MAAK;AAC7C,QAAA,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE;YACjC,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,UAAU,CAAiB;YACnE,OAAO,UAAU,IAAI,YAAY;QACnC;AACA,QAAA,OAAO,YAAY;AACrB,IAAA,CAAC,CAAC;AAEF,IAAA,MAAM,WAAW,GAAU,iBAAiB,IAAI,KAAK;IAErD,SAAS,CAAC,MAAK;AACb,QAAA,MAAM,YAAY,GAAG,CAAC,KAAY,KAChC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO,IAAI,KAAK;QAE7G,MAAM,UAAU,GAAG,MAAK;AACtB,YAAA,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,eAAe;;;YAI5C,IAAI,CAAC,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;;YAG1D,IAAI,iBAAiB,EAAE;gBACrB;YACF;AAEA,YAAA,IAAI,WAAW,KAAK,QAAQ,EAAE;AAC5B,gBAAA,YAAY,CAAC,UAAU,CAAC,UAAU,CAAC;YACrC;iBAAO;AACL,gBAAA,YAAY,CAAC,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC;YAC/C;AACF,QAAA,CAAC;AAED,QAAA,UAAU,EAAE;;QAGZ,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC;QAEpE,MAAM,YAAY,GAAG,MAAK;AACxB,YAAA,IAAI,WAAW,KAAK,QAAQ,EAAE;AAC5B,gBAAA,UAAU,EAAE;YACd;AACF,QAAA,CAAC;AAED,QAAA,UAAU,CAAC,gBAAgB,CAAC,QAAQ,EAAE,YAAY,CAAC;QACnD,OAAO,MAAM,UAAU,CAAC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,CAAC;IACrE,CAAC,EAAE,CAAC,WAAW,EAAE,iBAAiB,EAAE,UAAU,CAAC,CAAC;AAEhD,IAAA,OAAOA,IAAC,YAAY,CAAC,QAAQ,EAAA,EAAC,KAAK,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAA,QAAA,EAAG,QAAQ,GAAyB;AAC3G;;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/providers/ThemeProvider/index.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;AAYA,MAAM,YAAY,GAAG,aAAa,CAA+B,SAAS,CAAC;AAEpE,MAAM,QAAQ,GAAG,MAAuB;AAC7C,IAAA,MAAM,OAAO,GAAG,UAAU,CAAC,YAAY,CAAC;AAExC,IAAA,IAAI,OAAO,KAAK,SAAS,EAAE;AACzB,QAAA,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC;IACjE;AAEA,IAAA,OAAO,OAAO;AAChB;AAEA,MAAM,uBAAuB,GAAG,MAAuB;IACrD,IAAI,OAAO,MAAM,KAAK,WAAW;AAAE,QAAA,OAAO,OAAO;AACjD,IAAA,OAAO,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO;AACrF,CAAC;AAqBD;;AAEG;AACI,MAAM,aAAa,GAAG,CAAC,EAAE,QAAQ,EAAE,YAAY,GAAG,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,iBAAiB,EAAsB,KAAI;IACrI,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAQ,MAAK;AAC7C,QAAA,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE;YACjC,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,UAAU,CAAiB;YACnE,OAAO,UAAU,IAAI,YAAY;QACnC;AACA,QAAA,OAAO,YAAY;AACrB,IAAA,CAAC,CAAC;IAEF,MAAM,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,GAAG,QAAQ,CAAmB,uBAAuB,CAAC;IACnG,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAqB,IAAI,CAAC;AAEpE,IAAA,MAAM,WAAW,GAAU,iBAAiB,IAAI,KAAK;AACrD,IAAA,MAAM,YAAY,GAAqB,WAAW,KAAK,QAAQ,GAAG,gBAAgB,GAAG,WAAW;IAEhG,SAAS,CAAC,MAAK;QACb,QAAQ,CAAC,eAAe,CAAC,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC;;QAGjE,IAAI,CAAC,iBAAiB,EAAE;AACtB,YAAA,IAAI,WAAW,KAAK,QAAQ,EAAE;AAC5B,gBAAA,YAAY,CAAC,UAAU,CAAC,UAAU,CAAC;YACrC;iBAAO;AACL,gBAAA,YAAY,CAAC,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC;YAC/C;QACF;QAEA,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC;AACpE,QAAA,MAAM,YAAY,GAAG,MAAM,mBAAmB,CAAC,UAAU,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AACrF,QAAA,UAAU,CAAC,gBAAgB,CAAC,QAAQ,EAAE,YAAY,CAAC;QACnD,OAAO,MAAM,UAAU,CAAC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,CAAC;IACrE,CAAC,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,UAAU,CAAC,CAAC;AAE9D,IAAA,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;AAEvI,IAAA,QACEA,GAAA,CAAC,YAAY,CAAC,QAAQ,EAAA,EAAC,KAAK,EAAE,YAAY,EAAA,QAAA,EACxCA,GAAA,CAAA,KAAA,EAAA,EAAK,GAAG,EAAE,YAAY,EAAA,YAAA,EAAc,YAAY,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,EAAA,QAAA,EAC7E,QAAQ,EAAA,CACL,EAAA,CACgB;AAE5B;;;;"}

package/dist/providers/UIProvider/index.cjs

@@ -2,19 +2,59 @@
 
 var jsxRuntime = require('react/jsx-runtime');
 var ErrorBoundary = require('@flipdish/ui-library/providers/ErrorBoundary');
+var PortalContainer = require('@flipdish/ui-library/providers/PortalContainer');
 var RouteProvider = require('@flipdish/ui-library/providers/RouteProvider');
 var ThemeProvider = require('@flipdish/ui-library/providers/ThemeProvider');
+var React = require('react');
 var reactRouter = require('react-router');
 
+const UIProviderInner = ({ children, baseUrl, errorBoundary, portalContainer }) => {
+    const { themeRoot, resolvedMode } = ThemeProvider.useTheme();
+    const portalAnchorRef = React.useRef(null);
+    const resolvedContainerRef = React.useRef(null);
+    // Create a themed, layout-invisible anchor inside the portalContainer so
+    // React Aria overlays inherit scoped CSS and the active data-theme.
+    // Compares resolved DOM nodes (not callback identity) to avoid tearing
+    // down the anchor when an inline callback like `() => getElementById(...)` is passed.
+    React.useEffect(() => {
+        const container = portalContainer?.() ?? null;
+        if (container === resolvedContainerRef.current) {
+            return;
+        }
+        portalAnchorRef.current?.remove();
+        portalAnchorRef.current = null;
+        resolvedContainerRef.current = container;
+        if (!container) {
+            return;
+        }
+        const anchor = document.createElement('div');
+        anchor.style.display = 'contents';
+        anchor.setAttribute('data-theme', resolvedMode);
+        container.appendChild(anchor);
+        portalAnchorRef.current = anchor;
+    });
+    // Clean up the anchor on unmount.
+    React.useEffect(() => () => {
+        portalAnchorRef.current?.remove();
+        portalAnchorRef.current = null;
+    }, []);
+    // Keep the anchor's data-theme in sync when the resolved mode changes.
+    React.useEffect(() => {
+        portalAnchorRef.current?.setAttribute('data-theme', resolvedMode);
+    }, [resolvedMode]);
+    // Fall back to ThemeProvider's themed wrapper when no portalContainer is provided.
+    const getContainer = React.useCallback(() => portalAnchorRef.current ?? themeRoot, [themeRoot]);
+    return (jsxRuntime.jsx(reactRouter.BrowserRouter, { basename: baseUrl, children: jsxRuntime.jsx(RouteProvider.RouteProvider, { children: jsxRuntime.jsx(ErrorBoundary.ErrorBoundary, { ...errorBoundary, children: jsxRuntime.jsx(PortalContainer.PortalContainer, { getContainer: getContainer, children: children }) }) }) }));
+};
 /**
  * @summary single entry-point provider that composes theme, routing, and an error boundary for consuming apps
  */
-const UIProvider = ({ children, themeModeOverride, baseUrl, errorBoundary }) => {
+const UIProvider = ({ children, themeModeOverride, ...rest }) => {
     // TODO(i18n): add an internal library translation context so ui-library components can
     // source their own copy (e.g. ErrorBoundary's "Something went wrong") without the
     // consuming app needing to pass text props. This is purely internal — consuming apps
     // own their own translation layer and wrap their content inside UIProvider as usual.
-    return (jsxRuntime.jsx(ThemeProvider.ThemeProvider, { themeModeOverride: themeModeOverride, children: jsxRuntime.jsx(reactRouter.BrowserRouter, { basename: baseUrl, children: jsxRuntime.jsx(RouteProvider.RouteProvider, { children: jsxRuntime.jsx(ErrorBoundary.ErrorBoundary, { ...errorBoundary, children: children }) }) }) }));
+    return (jsxRuntime.jsx(ThemeProvider.ThemeProvider, { themeModeOverride: themeModeOverride, children: jsxRuntime.jsx(UIProviderInner, { ...rest, children: children }) }));
 };
 
 exports.UIProvider = UIProvider;

package/dist/providers/UIProvider/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../../../src/providers/UIProvider/index.tsx"],"sourcesContent":[null],"names":["_jsx","ThemeProvider","BrowserRouter","RouteProvider","ErrorBoundary"],"mappings":";;;;;;;;AA4BA;;AAEG;AACI,MAAM,UAAU,GAAG,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,aAAa,EAAsC,KAAI;;;;;AAKxH,IAAA,QACEA,cAAA,CAACC,2BAAa,EAAA,EAAC,iBAAiB,EAAE,iBAAiB,EAAA,QAAA,EACjDD,cAAA,CAACE,yBAAa,EAAA,EAAC,QAAQ,EAAE,OAAO,EAAA,QAAA,EAC9BF,cAAA,CAACG,2BAAa,EAAA,EAAA,QAAA,EACZH,cAAA,CAACI,2BAAa,EAAA,EAAA,GAAK,aAAa,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAiB,EAAA,CAC9C,EAAA,CACF,EAAA,CACF;AAEpB;;;;"}
+{"version":3,"file":"index.cjs","sources":["../../../src/providers/UIProvider/index.tsx"],"sourcesContent":[null],"names":["useTheme","useRef","useEffect","useCallback","_jsx","BrowserRouter","RouteProvider","ErrorBoundary","PortalContainer","ThemeProvider"],"mappings":";;;;;;;;;;AAyCA,MAAM,eAAe,GAAG,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAiE,KAAI;IAC/I,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAGA,sBAAQ,EAAE;AAC9C,IAAA,MAAM,eAAe,GAAGC,YAAM,CAAwB,IAAI,CAAC;AAC3D,IAAA,MAAM,oBAAoB,GAAGA,YAAM,CAAqB,IAAI,CAAC;;;;;IAM7DC,eAAS,CAAC,MAAK;AACb,QAAA,MAAM,SAAS,GAAG,eAAe,IAAI,IAAI,IAAI;AAC7C,QAAA,IAAI,SAAS,KAAK,oBAAoB,CAAC,OAAO,EAAE;YAC9C;QACF;AAEA,QAAA,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE;AACjC,QAAA,eAAe,CAAC,OAAO,GAAG,IAAI;AAC9B,QAAA,oBAAoB,CAAC,OAAO,GAAG,SAAS;QAExC,IAAI,CAAC,SAAS,EAAE;YACd;QACF;QAEA,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC;AAC5C,QAAA,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,UAAU;AACjC,QAAA,MAAM,CAAC,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC;AAC/C,QAAA,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC;AAC7B,QAAA,eAAe,CAAC,OAAO,GAAG,MAAM;AAClC,IAAA,CAAC,CAAC;;AAGF,IAAAA,eAAS,CACP,MAAM,MAAK;AACT,QAAA,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE;AACjC,QAAA,eAAe,CAAC,OAAO,GAAG,IAAI;IAChC,CAAC,EACD,EAAE,CACH;;IAGDA,eAAS,CAAC,MAAK;QACb,eAAe,CAAC,OAAO,EAAE,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC;AACnE,IAAA,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC;;AAGlB,IAAA,MAAM,YAAY,GAAGC,iBAAW,CAAC,MAAM,eAAe,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,SAAS,CAAC,CAAC;AAEzF,IAAA,QACEC,cAAA,CAACC,yBAAa,EAAA,EAAC,QAAQ,EAAE,OAAO,EAAA,QAAA,EAC9BD,cAAA,CAACE,2BAAa,EAAA,EAAA,QAAA,EACZF,cAAA,CAACG,2BAAa,EAAA,EAAA,GAAK,aAAa,EAAA,QAAA,EAC9BH,cAAA,CAACI,+BAAe,EAAA,EAAC,YAAY,EAAE,YAAY,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAmB,EAAA,CAC3D,EAAA,CACF,EAAA,CACF;AAEpB,CAAC;AAED;;AAEG;AACI,MAAM,UAAU,GAAG,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,GAAG,IAAI,EAAsC,KAAI;;;;;AAKzG,IAAA,QACEJ,cAAA,CAACK,2BAAa,EAAA,EAAC,iBAAiB,EAAE,iBAAiB,EAAA,QAAA,EACjDL,cAAA,CAAC,eAAe,OAAK,IAAI,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAmB,EAAA,CACzC;AAEpB;;;;"}

package/dist/providers/UIProvider/index.d.ts

@@ -1,5 +1,5 @@
 import { type ErrorBoundaryProps } from '@flipdish/ui-library/providers/ErrorBoundary';
-import type { PropsWithChildren } from 'react';
+import { type PropsWithChildren } from 'react';
 export interface UIProviderProps {
     /**
      * Controlled theme override. When set, the tree renders in this mode and theme
@@ -20,9 +20,21 @@ export interface UIProviderProps {
      * errorBoundary={{ identifier: 'app', onError: datadogReporter }}
      */
     errorBoundary: Omit<ErrorBoundaryProps, 'children'>;
+    /**
+     * Callback that returns the DOM element where React Aria overlays (Modal, Popover,
+     * Select, Tooltip, Toast) should portal into. Passed to `PortalContainer`
+     * internally — see its docs for full details.
+     *
+     * Use this in micro-frontends or embedded apps whose CSS is scoped to a mount
+     * subtree. Omit to portal into ThemeProvider's themed root element.
+     *
+     * @example
+     * portalContainer={() => document.getElementById('flipdish-micro-frontend')}
+     */
+    portalContainer?: (() => HTMLElement | null) | null;
 }
 /**
  * @summary single entry-point provider that composes theme, routing, and an error boundary for consuming apps
  */
-export declare const UIProvider: ({ children, themeModeOverride, baseUrl, errorBoundary }: PropsWithChildren<UIProviderProps>) => import("react").JSX.Element;
+export declare const UIProvider: ({ children, themeModeOverride, ...rest }: PropsWithChildren<UIProviderProps>) => import("react").JSX.Element;
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/UIProvider/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/UIProvider/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAGtG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAG/C,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,aAAa,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,yDAAyD,iBAAiB,CAAC,eAAe,CAAC,gCAcrH,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/UIProvider/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAItG,OAAO,EAAE,KAAK,iBAAiB,EAAkC,MAAM,OAAO,CAAC;AAG/E,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,aAAa,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC;IACpD;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;CACrD;AA4DD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,0CAA0C,iBAAiB,CAAC,eAAe,CAAC,gCAUtG,CAAC"}

package/dist/providers/UIProvider/index.js

@@ -1,18 +1,58 @@
 import { jsx } from 'react/jsx-runtime';
 import { ErrorBoundary } from '@flipdish/ui-library/providers/ErrorBoundary';
+import { PortalContainer } from '@flipdish/ui-library/providers/PortalContainer';
 import { RouteProvider } from '@flipdish/ui-library/providers/RouteProvider';
-import { ThemeProvider } from '@flipdish/ui-library/providers/ThemeProvider';
+import { ThemeProvider, useTheme } from '@flipdish/ui-library/providers/ThemeProvider';
+import { useRef, useEffect, useCallback } from 'react';
 import { BrowserRouter } from 'react-router';
 
+const UIProviderInner = ({ children, baseUrl, errorBoundary, portalContainer }) => {
+    const { themeRoot, resolvedMode } = useTheme();
+    const portalAnchorRef = useRef(null);
+    const resolvedContainerRef = useRef(null);
+    // Create a themed, layout-invisible anchor inside the portalContainer so
+    // React Aria overlays inherit scoped CSS and the active data-theme.
+    // Compares resolved DOM nodes (not callback identity) to avoid tearing
+    // down the anchor when an inline callback like `() => getElementById(...)` is passed.
+    useEffect(() => {
+        const container = portalContainer?.() ?? null;
+        if (container === resolvedContainerRef.current) {
+            return;
+        }
+        portalAnchorRef.current?.remove();
+        portalAnchorRef.current = null;
+        resolvedContainerRef.current = container;
+        if (!container) {
+            return;
+        }
+        const anchor = document.createElement('div');
+        anchor.style.display = 'contents';
+        anchor.setAttribute('data-theme', resolvedMode);
+        container.appendChild(anchor);
+        portalAnchorRef.current = anchor;
+    });
+    // Clean up the anchor on unmount.
+    useEffect(() => () => {
+        portalAnchorRef.current?.remove();
+        portalAnchorRef.current = null;
+    }, []);
+    // Keep the anchor's data-theme in sync when the resolved mode changes.
+    useEffect(() => {
+        portalAnchorRef.current?.setAttribute('data-theme', resolvedMode);
+    }, [resolvedMode]);
+    // Fall back to ThemeProvider's themed wrapper when no portalContainer is provided.
+    const getContainer = useCallback(() => portalAnchorRef.current ?? themeRoot, [themeRoot]);
+    return (jsx(BrowserRouter, { basename: baseUrl, children: jsx(RouteProvider, { children: jsx(ErrorBoundary, { ...errorBoundary, children: jsx(PortalContainer, { getContainer: getContainer, children: children }) }) }) }));
+};
 /**
  * @summary single entry-point provider that composes theme, routing, and an error boundary for consuming apps
  */
-const UIProvider = ({ children, themeModeOverride, baseUrl, errorBoundary }) => {
+const UIProvider = ({ children, themeModeOverride, ...rest }) => {
     // TODO(i18n): add an internal library translation context so ui-library components can
     // source their own copy (e.g. ErrorBoundary's "Something went wrong") without the
     // consuming app needing to pass text props. This is purely internal — consuming apps
     // own their own translation layer and wrap their content inside UIProvider as usual.
-    return (jsx(ThemeProvider, { themeModeOverride: themeModeOverride, children: jsx(BrowserRouter, { basename: baseUrl, children: jsx(RouteProvider, { children: jsx(ErrorBoundary, { ...errorBoundary, children: children }) }) }) }));
+    return (jsx(ThemeProvider, { themeModeOverride: themeModeOverride, children: jsx(UIProviderInner, { ...rest, children: children }) }));
 };
 
 export { UIProvider };

package/dist/providers/UIProvider/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/providers/UIProvider/index.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;;;;AA4BA;;AAEG;AACI,MAAM,UAAU,GAAG,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,aAAa,EAAsC,KAAI;;;;;AAKxH,IAAA,QACEA,GAAA,CAAC,aAAa,EAAA,EAAC,iBAAiB,EAAE,iBAAiB,EAAA,QAAA,EACjDA,GAAA,CAAC,aAAa,EAAA,EAAC,QAAQ,EAAE,OAAO,EAAA,QAAA,EAC9BA,GAAA,CAAC,aAAa,EAAA,EAAA,QAAA,EACZA,GAAA,CAAC,aAAa,EAAA,EAAA,GAAK,aAAa,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAiB,EAAA,CAC9C,EAAA,CACF,EAAA,CACF;AAEpB;;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/providers/UIProvider/index.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;;;;;;AAyCA,MAAM,eAAe,GAAG,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAiE,KAAI;IAC/I,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,QAAQ,EAAE;AAC9C,IAAA,MAAM,eAAe,GAAG,MAAM,CAAwB,IAAI,CAAC;AAC3D,IAAA,MAAM,oBAAoB,GAAG,MAAM,CAAqB,IAAI,CAAC;;;;;IAM7D,SAAS,CAAC,MAAK;AACb,QAAA,MAAM,SAAS,GAAG,eAAe,IAAI,IAAI,IAAI;AAC7C,QAAA,IAAI,SAAS,KAAK,oBAAoB,CAAC,OAAO,EAAE;YAC9C;QACF;AAEA,QAAA,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE;AACjC,QAAA,eAAe,CAAC,OAAO,GAAG,IAAI;AAC9B,QAAA,oBAAoB,CAAC,OAAO,GAAG,SAAS;QAExC,IAAI,CAAC,SAAS,EAAE;YACd;QACF;QAEA,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC;AAC5C,QAAA,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,UAAU;AACjC,QAAA,MAAM,CAAC,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC;AAC/C,QAAA,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC;AAC7B,QAAA,eAAe,CAAC,OAAO,GAAG,MAAM;AAClC,IAAA,CAAC,CAAC;;AAGF,IAAA,SAAS,CACP,MAAM,MAAK;AACT,QAAA,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE;AACjC,QAAA,eAAe,CAAC,OAAO,GAAG,IAAI;IAChC,CAAC,EACD,EAAE,CACH;;IAGD,SAAS,CAAC,MAAK;QACb,eAAe,CAAC,OAAO,EAAE,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC;AACnE,IAAA,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC;;AAGlB,IAAA,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,eAAe,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,SAAS,CAAC,CAAC;AAEzF,IAAA,QACEA,GAAA,CAAC,aAAa,EAAA,EAAC,QAAQ,EAAE,OAAO,EAAA,QAAA,EAC9BA,GAAA,CAAC,aAAa,EAAA,EAAA,QAAA,EACZA,GAAA,CAAC,aAAa,EAAA,EAAA,GAAK,aAAa,EAAA,QAAA,EAC9BA,GAAA,CAAC,eAAe,EAAA,EAAC,YAAY,EAAE,YAAY,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAmB,EAAA,CAC3D,EAAA,CACF,EAAA,CACF;AAEpB,CAAC;AAED;;AAEG;AACI,MAAM,UAAU,GAAG,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,GAAG,IAAI,EAAsC,KAAI;;;;;AAKzG,IAAA,QACEA,GAAA,CAAC,aAAa,EAAA,EAAC,iBAAiB,EAAE,iBAAiB,EAAA,QAAA,EACjDA,GAAA,CAAC,eAAe,OAAK,IAAI,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAmB,EAAA,CACzC;AAEpB;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flipdish/ui-library",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Flipdish Design System — atomic-design component library (Tailwind v4 + UntitledUI + React Aria).",
   "type": "module",
   "sideEffects": [
@@ -88,6 +88,7 @@
     "postcss-prefix-selector": "^2.1.1",
     "qr-code-styling": "^1.9.2",
     "react": "^19.0.0",
+    "react-aria": "^3.49.0",
     "react-aria-components": "^1.18.0",
     "react-dom": "^19.0.0",
     "react-hotkeys-hook": "^5.3.2",
@@ -150,6 +151,9 @@
     "qr-code-styling": {
       "optional": true
     },
+    "react-aria": {
+      "optional": true
+    },
     "react-aria-components": {
       "optional": true
     },
@@ -198,6 +202,7 @@
     "motion": "^12.40.0",
     "qr-code-styling": "^1.9.2",
     "react": "^19.0.0",
+    "react-aria": "^3.49.0",
     "react-aria-components": "^1.18.0",
     "react-dom": "^19.0.0",
     "react-hotkeys-hook": "^5.3.2",