@datalayer/primer-addons 1.0.20 → 1.0.22

package/lib/reactor/page-layout/panelState.js

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The page layout's shared state: whether the side panel is open, what the
+ * sheet holds, and what is happening in the page.
+ *
+ * Signals, in a module of their own so the layout, the header toggle, the
+ * panel's own contents and a host can all read and write them without any
+ * of them importing the others.
+ *
+ * @module reactor/page-layout/panelState
+ */
+import { signal } from "@datalayer/reactor";
+/**
+ * Whether the side panel is open.
+ *
+ * Closed to start: the page is what a reader came for, and a panel with
+ * nothing in it yet is a column of nothing.
+ */
+export const pageLayoutPanelOpen = signal(false);
+/**
+ * What lies on the sheet: the page, or — when there is no page to show — the
+ * panel's own content.
+ *
+ * Written by the layout as it renders, read by the parts that only make
+ * sense beside a page: the toggle would open a second copy of what is
+ * already on the sheet, and anything hung under a band to echo the panel
+ * would repeat it.
+ */
+export const pageLayoutSheet = signal("page");
+/**
+ * What is happening in the page, in a short line — "Analyst is adding a
+ * cell…" — or nothing. The layout pins it to the top of the sheet while it
+ * is set. A host or another plugin writes it; a layout given an `activity`
+ * prop shows that instead.
+ */
+export const pageLayoutActivity = signal(undefined);
+/** Open the panel — for a host that wants its content seen the moment it lands. */
+export function openPagePanel() {
+    pageLayoutPanelOpen.value = true;
+}
+export function closePagePanel() {
+    pageLayoutPanelOpen.value = false;
+}
+export function togglePagePanel() {
+    pageLayoutPanelOpen.value = !pageLayoutPanelOpen.value;
+}

package/lib/story-helpers.d.ts

@@ -7,8 +7,8 @@ type StoryContext = Record<string, unknown> & {
     };
     parameters: Record<string, unknown>;
 };
-export declare const colormodeFromScheme: (colorScheme: string) => "dark" | "light";
-export declare const withThemeProvider: (Story: React.FC<React.PropsWithChildren<StoryContext>>, context: StoryContext) => string | number | boolean | Iterable<React.ReactNode> | import("react/jsx-runtime").JSX.Element | null | undefined;
+export declare const colormodeFromScheme: (colorScheme: string) => "light" | "dark";
+export declare const withThemeProvider: (Story: React.FC<React.PropsWithChildren<StoryContext>>, context: StoryContext) => string | number | bigint | boolean | Iterable<React.ReactNode> | React.JSX.Element | Promise<React.ReactNode> | null | undefined;
 export declare const toolbarTypes: {
     colorScheme: {
         name: string;

package/lib/theme/DatalayerBrandThemeProvider.d.ts

@@ -38,4 +38,4 @@ export interface IDatalayerBrandThemeProviderProps {
  * </DatalayerBrandThemeProvider>
  * ```
  */
-export declare function DatalayerBrandThemeProvider({ colorMode, brandTheme, style, children, }: IDatalayerBrandThemeProviderProps): JSX.Element;
+export declare function DatalayerBrandThemeProvider({ colorMode, brandTheme, style, children, }: IDatalayerBrandThemeProviderProps): React.JSX.Element;

package/lib/theme/DatalayerThemeProvider.d.ts

@@ -1,13 +1,13 @@
-import { type CSSProperties } from 'react';
-import { ThemeProviderProps } from '@primer/react';
-export interface IDatalayerThemeProviderProps extends Omit<ThemeProviderProps, 'theme' | 'colorMode'> {
+import { type CSSProperties } from "react";
+import { ThemeProviderProps } from "@primer/react";
+export interface IDatalayerThemeProviderProps extends Omit<ThemeProviderProps, "theme" | "colorMode"> {
     /**
      * Color mode to use.
      * - `'light'` / `'dark'` — explicit override
      * - `'auto'` — follow the operating system preference (prefers-color-scheme)
      * - Primer's `'day'` / `'night'` are still accepted.
      */
-    colorMode?: 'light' | 'dark' | 'auto' | 'day' | 'night';
+    colorMode?: "light" | "dark" | "auto" | "day" | "night";
     /**
      * Additional base styles merged on top of theme defaults.
      */
@@ -33,4 +33,4 @@ export interface IDatalayerThemeProviderProps extends Omit<ThemeProviderProps, '
         dark: CSSProperties;
     };
 }
-export declare function DatalayerThemeProvider(props: React.PropsWithChildren<IDatalayerThemeProviderProps>): JSX.Element;
+export declare function DatalayerThemeProvider(props: React.PropsWithChildren<IDatalayerThemeProviderProps>): React.JSX.Element;

package/lib/theme/DatalayerThemeProvider.js

@@ -1,20 +1,20 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /*
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { useEffect, useMemo } from 'react';
-import { BaseStyles, ThemeProvider } from '@primer/react';
-import { useSystemColorMode } from './useSystemColorMode';
-import { datalayerTheme, datalayerThemeStyles } from './themes/datalayerTheme';
-import { setupPrimerPortals, syncPortalThemeStyles } from '../utils/Portals';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { BaseStyles, ThemeProvider } from "@primer/react";
+import { useSystemColorMode } from "./useSystemColorMode";
+import { datalayerTheme, datalayerThemeStyles } from "./themes/datalayerTheme";
+import { systemFontStack } from "./fontStacks";
+import { setupPrimerPortals, syncPortalThemeStyles } from "../utils/Portals";
 /**
  * System sans-serif font stack — shared between `fontFamily` and
  * the Primer `--fontStack-*` CSS custom properties so that
  * components using the CSS `font` shorthand (e.g. `Blankslate`)
  * also pick up the themed typeface.
  */
-const SYSTEM_FONT = '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"';
 /**
  * Shared typographic rhythm — clean, spacious feel inspired by
  * modern developer-blog aesthetics (generous line-height, open
@@ -31,70 +31,114 @@ const SYSTEM_FONT = '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, A
  */
 const typographyVars = {
     /* ── Font stacks ───────────────────────────────────────────────── */
-    '--fontStack-monospace': 'ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace',
-    '--fontStack-sansSerif': SYSTEM_FONT,
-    '--fontStack-sansSerifDisplay': SYSTEM_FONT,
-    '--fontStack-system': SYSTEM_FONT,
+    "--fontStack-monospace": "ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace",
+    "--fontStack-sansSerif": systemFontStack,
+    "--fontStack-sansSerifDisplay": systemFontStack,
+    "--fontStack-system": systemFontStack,
     /* ── Base text weights (from @primer/primitives) ───────────────── */
-    '--base-text-weight-light': '300',
-    '--base-text-weight-normal': '400',
-    '--base-text-weight-medium': '500',
-    '--base-text-weight-semibold': '600',
+    "--base-text-weight-light": "300",
+    "--base-text-weight-normal": "400",
+    "--base-text-weight-medium": "500",
+    "--base-text-weight-semibold": "600",
     /* ── Body sizing ───────────────────────────────────────────────── */
-    '--text-body-size-large': '1rem',
-    '--text-body-size-medium': '0.875rem',
-    '--text-body-size-small': '0.75rem',
-    '--text-body-lineHeight-large': '1.5',
-    '--text-body-lineHeight-medium': '1.4285',
-    '--text-body-lineHeight-small': '1.6666',
+    "--text-body-size-large": "1rem",
+    "--text-body-size-medium": "0.875rem",
+    "--text-body-size-small": "0.75rem",
+    "--text-body-lineHeight-large": "1.5",
+    "--text-body-lineHeight-medium": "1.4285",
+    "--text-body-lineHeight-small": "1.6666",
     /* ── Title sizing ──────────────────────────────────────────────── */
-    '--text-title-size-large': '2rem',
-    '--text-title-size-medium': '1.25rem',
-    '--text-title-size-small': '1rem',
-    '--text-title-lineHeight-large': '1.5',
-    '--text-title-lineHeight-medium': '1.6',
-    '--text-title-lineHeight-small': '1.5',
+    "--text-title-size-large": "2rem",
+    "--text-title-size-medium": "1.25rem",
+    "--text-title-size-small": "1rem",
+    "--text-title-lineHeight-large": "1.5",
+    "--text-title-lineHeight-medium": "1.6",
+    "--text-title-lineHeight-small": "1.5",
     /* ── Caption / subtitle / display ──────────────────────────────── */
-    '--text-caption-size': '0.75rem',
-    '--text-caption-lineHeight': '1.3333',
-    '--text-subtitle-size': '1.25rem',
-    '--text-subtitle-lineHeight': '1.6',
-    '--text-display-size': '2.5rem',
-    '--text-display-lineHeight': '1.4',
+    "--text-caption-size": "0.75rem",
+    "--text-caption-lineHeight": "1.3333",
+    "--text-subtitle-size": "1.25rem",
+    "--text-subtitle-lineHeight": "1.6",
+    "--text-display-size": "2.5rem",
+    "--text-display-lineHeight": "1.4",
     /* ── Font shorthand tokens ─────────────────────────────────────── *
      * These are the tokens consumed by Primer components (Blankslate,
      * etc.) via `font: var(--text-title-shorthand-medium, <fallback>)`.
      * Defining them here prevents the hard-coded fallback from firing.
      * Each one references `var(--fontStack-sansSerif)` or
-     * `SYSTEM_FONT` directly (no nested `var()`) so that the CSS
+     * the system font stack directly (no nested `var()`) so that the CSS
      * `font` shorthand parses reliably.  Themes that override fonts
      * (e.g. Matrix monospace) replace these shorthand tokens via
      * `buildThemeStyles({ fontFamily })` in their `themeStyles`.
      * ─────────────────────────────────────────────────────────────── */
-    '--text-body-shorthand-large': `400 1rem/1.5 ${SYSTEM_FONT}`,
-    '--text-body-shorthand-medium': `400 0.875rem/1.4285 ${SYSTEM_FONT}`,
-    '--text-body-shorthand-small': `400 0.75rem/1.6666 ${SYSTEM_FONT}`,
-    '--text-title-shorthand-large': `600 2rem/1.5 ${SYSTEM_FONT}`,
-    '--text-title-shorthand-medium': `600 1.25rem/1.6 ${SYSTEM_FONT}`,
-    '--text-title-shorthand-small': `600 1rem/1.5 ${SYSTEM_FONT}`,
-    '--text-caption-shorthand': `400 0.75rem/1.3333 ${SYSTEM_FONT}`,
-    '--text-subtitle-shorthand': `400 1.25rem/1.6 ${SYSTEM_FONT}`,
-    '--text-display-shorthand': `500 2.5rem/1.4 ${SYSTEM_FONT}`,
+    "--text-body-shorthand-large": `400 1rem/1.5 ${systemFontStack}`,
+    "--text-body-shorthand-medium": `400 0.875rem/1.4285 ${systemFontStack}`,
+    "--text-body-shorthand-small": `400 0.75rem/1.6666 ${systemFontStack}`,
+    "--text-title-shorthand-large": `600 2rem/1.5 ${systemFontStack}`,
+    "--text-title-shorthand-medium": `600 1.25rem/1.6 ${systemFontStack}`,
+    "--text-title-shorthand-small": `600 1rem/1.5 ${systemFontStack}`,
+    "--text-caption-shorthand": `400 0.75rem/1.3333 ${systemFontStack}`,
+    "--text-subtitle-shorthand": `400 1.25rem/1.6 ${systemFontStack}`,
+    "--text-display-shorthand": `500 2.5rem/1.4 ${systemFontStack}`,
     /* ── Custom overrides ──────────────────────────────────────────── */
-    '--text-body-lineHeight': '1.7',
-    '--text-title-lineHeight': '1.2',
-    '--text-title-letterSpacing': '-0.02em',
-    fontFamily: SYSTEM_FONT,
-    WebkitFontSmoothing: 'antialiased',
-    MozOsxFontSmoothing: 'grayscale',
-    textRendering: 'optimizeLegibility',
+    "--text-body-lineHeight": "1.7",
+    "--text-title-lineHeight": "1.2",
+    "--text-title-letterSpacing": "-0.02em",
+    fontFamily: systemFontStack,
+    WebkitFontSmoothing: "antialiased",
+    MozOsxFontSmoothing: "grayscale",
+    textRendering: "optimizeLegibility",
 };
 export function DatalayerThemeProvider(props) {
     const { children, colorMode, baseStyles, theme, themeStyles, ...rest } = props;
     // Resolve 'auto' → actual system preference ('light' or 'dark').
     const systemMode = useSystemColorMode();
-    const resolvedColorMode = colorMode === 'auto' ? systemMode : (colorMode ?? 'light');
-    const isDark = resolvedColorMode === 'dark' || resolvedColorMode === 'night';
+    /*
+     * Whether this provider sits inside another themed element, and if so what
+     * that element says.
+     *
+     * The portal root is one element shared by the whole page, and every
+     * provider used to restamp it from its own mode — so a provider nested in
+     * the page (a deck in its own theme, a widget rendered into a notebook cell
+     * as a React root of its own) wrote its mode over the application's
+     * whenever it mounted, and the next overlay came up in the wrong colour.
+     * Nested providers leave the portal root alone. And a nested provider given
+     * no `colorMode` wears the mode above it rather than a default of light: a
+     * widget inside a dark page has no business being light. Read from the DOM
+     * rather than from React context, because those widget roots are separate
+     * React trees; what they share with the application is the document.
+     */
+    const sentinel = useRef(null);
+    const [themedAncestor, setThemedAncestor] = useState(null);
+    const [ancestorMode, setAncestorMode] = useState(null);
+    useLayoutEffect(() => {
+        // The sentinel's parent is this provider's own element; anything themed
+        // above *that* is another provider's.
+        const own = sentinel.current?.parentElement;
+        const ancestor = own?.parentElement?.closest("[data-color-mode]") ?? null;
+        setThemedAncestor(ancestor);
+        if (!ancestor) {
+            setAncestorMode(null);
+            return undefined;
+        }
+        const read = () => {
+            const mode = ancestor.getAttribute("data-color-mode");
+            setAncestorMode(mode === "dark" || mode === "night" ? "dark" : "light");
+        };
+        read();
+        // Rewritten on every toggle; follow it.
+        const observer = new MutationObserver(read);
+        observer.observe(ancestor, {
+            attributes: true,
+            attributeFilter: ["data-color-mode"],
+        });
+        return () => observer.disconnect();
+    }, []);
+    const nested = themedAncestor !== null;
+    const resolvedColorMode = colorMode === "auto"
+        ? systemMode
+        : (colorMode ?? (nested ? (ancestorMode ?? "light") : "light"));
+    const isDark = resolvedColorMode === "dark" || resolvedColorMode === "night";
     const resolvedTheme = theme ?? datalayerTheme;
     const styles = themeStyles ?? datalayerThemeStyles;
     const resolvedStyles = isDark ? styles.dark : styles.light;
@@ -109,15 +153,32 @@ export function DatalayerThemeProvider(props) {
     // Keep document.body portal-root attributes AND theme styles in sync
     // so that Primer portals (modals, dialogs, overlays) inherit the
     // correct color mode **and** theme tokens (fonts, colors, CSS vars).
+    //
+    // Only the outermost provider does this. The portal root is one element
+    // shared by the whole page, and every provider used to restamp it from its
+    // own mode — so a provider nested in the page (a deck in its own theme, a
+    // widget jupyter-react renders into a notebook cell as a React root of its
+    // own) wrote its mode over the application's whenever it mounted, and the
+    // next overlay came up in the wrong colour. Nesting is read from the DOM
+    // rather than from React context, because those widget roots are separate
+    // React trees: what they share with the application is the document.
     useEffect(() => {
-        setupPrimerPortals(resolvedColorMode === 'night' ? 'dark' : resolvedColorMode === 'day' ? 'light' : resolvedColorMode);
+        if (nested) {
+            // Another provider owns the page's portal root; see above.
+            return;
+        }
+        setupPrimerPortals(resolvedColorMode === "night"
+            ? "dark"
+            : resolvedColorMode === "day"
+                ? "light"
+                : resolvedColorMode);
         syncPortalThemeStyles(portalStyles);
-    }, [resolvedColorMode, portalStyles]);
-    return (_jsx(ThemeProvider, { colorMode: resolvedColorMode, theme: resolvedTheme, ...rest, children: _jsx(BaseStyles, { style: {
-                lineHeight: '1.7',
-                transition: 'background-color 0.25s ease, color 0.25s ease',
+    }, [nested, resolvedColorMode, portalStyles]);
+    return (_jsx(ThemeProvider, { colorMode: resolvedColorMode, theme: resolvedTheme, ...rest, children: _jsxs(BaseStyles, { style: {
+                lineHeight: "1.7",
+                transition: "background-color 0.25s ease, color 0.25s ease",
                 ...typographyVars,
                 ...resolvedStyles,
                 ...baseStyles,
-            }, children: children }) }));
+            }, children: [_jsx("span", { ref: sentinel, hidden: true, "data-datalayer-theme-root": "" }), children] }) }));
 }

package/lib/theme/css/createThemeCSSVars.d.ts

@@ -135,6 +135,7 @@ export interface ThemeColorDefs {
  * | Background       | `--bgColor-default`                    |
  * | Foreground       | `--fgColor-default`                    |
  * | Border           | `--borderColor-default`                |
+ * | Field (rest)     | `--control-borderColor-rest`           |
  * | Link             | `--fgColor-link`                       |
  * | Accent / Success | `--bgColor-accent-emphasis`            |
  * | Default button   | `--button-default-bgColor-rest`        |

package/lib/theme/css/createThemeCSSVars.js

@@ -19,6 +19,7 @@
  * | Background       | `--bgColor-default`                    |
  * | Foreground       | `--fgColor-default`                    |
  * | Border           | `--borderColor-default`                |
+ * | Field (rest)     | `--control-borderColor-rest`           |
  * | Link             | `--fgColor-link`                       |
  * | Accent / Success | `--bgColor-accent-emphasis`            |
  * | Default button   | `--button-default-bgColor-rest`        |
@@ -219,6 +220,14 @@ export function colorDefsToCSS(defs, mode = 'light') {
         '--control-transparent-bgColor-selected': defs.btn.selectedBg,
         '--control-transparent-borderColor-hover': 'transparent',
         '--control-transparent-borderColor-active': 'transparent',
+        /* ── Fields (rest state) ──────────────────────────────────────
+         * `TextInput` / `Textarea` / `Select` paint their inactive border
+         * with `var(--control-borderColor-rest, var(--color-btn-border))`
+         * — both legacy fallbacks apps that skip @primer/primitives CSS
+         * never get — so without this the border shorthand is invalid and
+         * the field shows no border at all until it is focused. */
+        '--control-borderColor-rest': defs.border?.default ?? defs.btn.border,
+        '--control-fgColor-rest': defs.fg.default,
         /* ── Disabled controls / fields ─────────────────────────────── */
         '--control-bgColor-disabled': defs.canvas.subtle ?? defs.btn.bg,
         '--control-borderColor-disabled': defs.border?.default ?? defs.btn.border,

package/lib/theme/fontStacks.d.ts

@@ -0,0 +1,2 @@
+/** Default typeface used when a Datalayer theme does not override typography. */
+export declare const systemFontStack = "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Helvetica, Arial, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\"";

package/lib/theme/fontStacks.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Default typeface used when a Datalayer theme does not override typography. */
+export const systemFontStack = '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"';

package/lib/theme/index.d.ts

@@ -13,6 +13,8 @@ export * from './themes/ivoryTheme';
 export * from './themes/sunTheme';
 export * from './themes-brand/spatialBrandTheme';
 export * from './themeRegistry';
+export * from './portableTheme';
+export * from './fontStacks';
 export * from './palettes';
 export * from './useSystemColorMode';
 export * from './useThemeStore';

package/lib/theme/index.js

@@ -17,6 +17,8 @@ export * from './themes/ivoryTheme';
 export * from './themes/sunTheme';
 export * from './themes-brand/spatialBrandTheme';
 export * from './themeRegistry';
+export * from './portableTheme';
+export * from './fontStacks';
 export * from './palettes';
 export * from './useSystemColorMode';
 export * from './useThemeStore';

package/lib/theme/palettes/ColorPalette.d.ts

@@ -21,12 +21,12 @@ export declare function getColorPalette(theme?: ThemeVariant, colorMode?: 'light
 export declare function useColorPalette(): ColorPalette;
 /** @deprecated Use `useColorPalette` instead. */
 export declare const useBlogColorPalette: typeof useColorPalette;
-export declare const LightBoostFilter: () => import("react/jsx-runtime").JSX.Element;
+export declare const LightBoostFilter: () => import("react").JSX.Element;
 export declare const SharedDefs: ({ p }: {
     p: ColorPalette;
-}) => import("react/jsx-runtime").JSX.Element;
+}) => import("react").JSX.Element;
 export declare const svgLightFilter: (p: ColorPalette) => "url(#svgLightBoost)" | undefined;
 export declare const BgGrid: ({ w, h }: {
     w?: number;
     h?: number;
-}) => import("react/jsx-runtime").JSX.Element;
+}) => import("react").JSX.Element;

package/lib/theme/portableTheme.d.ts

@@ -0,0 +1,32 @@
+import { type ColorMode } from './DatalayerBrandThemeProvider';
+import { type ThemeVariant } from './themeRegistry';
+/** A valid CSS custom-property name. */
+export type CssVariableName = `--${string}`;
+/**
+ * A JSON-safe CSS-variable map.
+ *
+ * Theme values retain Primer's canonical functional and component token names
+ * (`--bgColor-*`, `--fgColor-*`, `--button-*`, and so on), allowing consumers
+ * to use the map without depending on React, styled-components, or Primer.
+ */
+export type CssVariableMap = Record<CssVariableName, string>;
+/** A portable theme with explicit light and dark CSS-variable modes. */
+export interface PortableTheme {
+    id: ThemeVariant;
+    label: string;
+    description: string;
+    defaultColorMode: ColorMode;
+    modes: {
+        light: CssVariableMap;
+        dark: CssVariableMap;
+    };
+}
+/**
+ * Export a Primer Addons theme as a framework-neutral, JSON-safe token map.
+ *
+ * Framework adapters should consume these canonical CSS variables directly
+ * instead of translating them into framework-specific color names.
+ */
+export declare function exportPortableTheme(variant: ThemeVariant): PortableTheme;
+/** Serialize a trusted portable map for a CSS declaration block. */
+export declare function cssVariableDeclarations(tokens: CssVariableMap): string;

package/lib/theme/portableTheme.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { systemFontStack } from './fontStacks';
+import { themeConfigs } from './themeRegistry';
+function cssVariables(styles) {
+    const variables = Object.fromEntries(Object.entries(styles)
+        .filter(([name, value]) => name.startsWith('--') && value !== undefined && value !== null)
+        .map(([name, value]) => [name, String(value)]));
+    const fontFamily = variables['--fontStack-sansSerif'] ??
+        styles.fontFamily ??
+        systemFontStack;
+    return {
+        '--fontStack-sansSerif': fontFamily,
+        '--fontStack-sansSerifDisplay': fontFamily,
+        '--fontStack-system': fontFamily,
+        ...variables,
+    };
+}
+/**
+ * Export a Primer Addons theme as a framework-neutral, JSON-safe token map.
+ *
+ * Framework adapters should consume these canonical CSS variables directly
+ * instead of translating them into framework-specific color names.
+ */
+export function exportPortableTheme(variant) {
+    const config = themeConfigs[variant];
+    return {
+        id: variant,
+        label: config.label,
+        description: config.description,
+        defaultColorMode: config.defaultColorMode,
+        modes: {
+            light: cssVariables(config.themeStyles.light),
+            dark: cssVariables(config.themeStyles.dark),
+        },
+    };
+}
+/** Serialize a trusted portable map for a CSS declaration block. */
+export function cssVariableDeclarations(tokens) {
+    return Object.entries(tokens)
+        .map(([name, value]) => `${name}:${value}`)
+        .join(';');
+}

package/lib/utils/Helper.d.ts

@@ -6,12 +6,12 @@ import type { AnimateProps } from '@primer/react-brand';
 export declare const Container: ({ children, style, }: {
     children: React.ReactElement[] | React.ReactElement;
     style?: React.CSSProperties;
-}) => import("react/jsx-runtime").JSX.Element;
+}) => React.JSX.Element;
 type RedlineBackgroundProps = {
     height?: number;
     hasBorder?: boolean;
 };
-export declare function RedlineBackground({ height, hasBorder, ...rest }: PropsWithChildren<RedlineBackgroundProps>): import("react/jsx-runtime").JSX.Element;
+export declare function RedlineBackground({ height, hasBorder, ...rest }: PropsWithChildren<RedlineBackgroundProps>): React.JSX.Element;
 /**
  * Base Types
  *

package/lib/utils/Portals.d.ts

@@ -1,4 +1,12 @@
 import { type CSSProperties } from 'react';
+/**
+ * Id of the element Primer portals render under.
+ *
+ * Exported because a host may need to mark that element as its own — the
+ * JupyterLab theming of jupyter-react adds `jp-ThemedContainer` to it, so
+ * the rules JupyterLab scopes to that class reach portaled content too.
+ */
+export declare const PRIMER_PORTAL_ROOT_ID = "__primerPortalRoot__";
 type Colormode = 'light' | 'dark' | 'auto';
 /**
  * Ensure we define a root for Primer portal root.
@@ -11,6 +19,13 @@ type Colormode = 'light' | 'dark' | 'auto';
  *  @see https://github.com/primer/react/blob/030fe020b48b7f12c2994c6614e5d4191fe764ee/src/Portal/Portal.tsx#L33
  */
 export declare const setupPrimerPortals: (colormode?: Colormode) => void;
+/**
+ * The element Primer portals render under, when it has been set up.
+ *
+ * `setupPrimerPortals` creates it; before that call there is none, and this
+ * answers `null` rather than inventing one.
+ */
+export declare const getPrimerPortalRoot: () => HTMLElement | null;
 /**
  * Sync a set of CSS properties (including CSS custom properties) to
  * `document.body` so that Primer portal content — which is a DOM child