@datalayer/primer-addons 1.0.21 → 1.0.23

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

@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `@datalayer/primer-page-layout` — the page layout, as a reactor plugin.
+ *
+ * A host lists this plugin and renders one slot, `main` by default; the
+ * plugin fills it with {@link PageLayout} and opens four slots of its own for
+ * the other plugins to fill: `page` for what lies on the sheet, `page-band`
+ * for the band docked above it (a composer, a toolbar), `page-panel` for the
+ * side panel, `page-chips` for the chips under the band. A button that opens
+ * and closes the panel goes in the header — only while something fills the
+ * panel slot, so a host with no panel gets no dead button.
+ *
+ * This is the Loop's page layout with the Loop taken out: there the chat
+ * view hands the layout its parts directly through a contribution point of
+ * its own, and the Loop keeps that adapter. Here the parts are slots, which
+ * is what a plain Reactor host has.
+ *
+ * @module reactor/page-layout/PageLayoutPlugin
+ */
+import { createElement } from "react";
+import { definePlugin } from "@datalayer/reactor";
+import { SlotPageLayout, SlotPanelToggle } from "./SlotPageLayout";
+import { pageLayoutPanelOpen } from "./panelState";
+export const PAGE_LAYOUT_PLUGIN_NAME = "@datalayer/primer-page-layout";
+/** The slots the plugin opens, by their default names. */
+export const PageLayoutSlots = {
+    page: "page",
+    band: "page-band",
+    panel: "page-panel",
+    chips: "page-chips",
+};
+export const PageLayoutPlugin = definePlugin({
+    name: PAGE_LAYOUT_PLUGIN_NAME,
+    displayName: "Page layout",
+    description: "The page on a centred sheet, a band docked above it at the same width or floating over it, and a side panel that opens from the header.",
+    octicon: "file",
+    emoji: "\u{1F4C4}",
+    config: {
+        slot: "main",
+        order: 0,
+        headerSlot: "header",
+        toggleOrder: 50,
+        panelName: "panel",
+        toggleIcon: undefined,
+        pageSlot: PageLayoutSlots.page,
+        bandSlot: PageLayoutSlots.band,
+        panelSlot: PageLayoutSlots.panel,
+        chipsSlot: PageLayoutSlots.chips,
+        band: "docked",
+        panel: "docked",
+        panelSide: "right",
+        panelOpen: false,
+        sheetWidth: undefined,
+        pageSize: undefined,
+        panelWidth: undefined,
+    },
+    build: ({ config }) => {
+        // A host whose panel is a navigation sidebar wants it open on arrival,
+        // not behind the header's toggle. Set once, at build: after that the
+        // signal is the reader's.
+        if (config.panelOpen) {
+            pageLayoutPanelOpen.value = true;
+        }
+        return {
+            components: [
+                {
+                    id: "page-layout",
+                    slot: config.slot,
+                    order: config.order,
+                    Component: (context) => createElement(SlotPageLayout, {
+                        pageSlot: config.pageSlot,
+                        bandSlot: config.bandSlot,
+                        panelSlot: config.panelSlot,
+                        chipsSlot: config.chipsSlot,
+                        bandMode: config.band,
+                        panelMode: config.panel,
+                        panelSide: config.panelSide,
+                        sheetWidth: config.sheetWidth,
+                        pageSize: config.pageSize,
+                        panelWidth: config.panelWidth,
+                        context,
+                    }),
+                },
+                ...(config.headerSlot
+                    ? [
+                        {
+                            id: "page-layout-panel-toggle",
+                            slot: config.headerSlot,
+                            order: config.toggleOrder,
+                            Component: () => createElement(SlotPanelToggle, {
+                                panelSlot: config.panelSlot,
+                                panelName: config.panelName,
+                                icon: config.toggleIcon,
+                            }),
+                        },
+                    ]
+                    : []),
+            ],
+        };
+    },
+});
+export default PageLayoutPlugin;

package/lib/reactor/page-layout/PagePanelToggle.d.ts

@@ -0,0 +1,21 @@
+import type { JSX } from "react";
+import { type SxProp } from "@primer/react";
+import { type Icon } from "@primer/octicons-react";
+export type PagePanelToggleProps = {
+    /** What the panel holds, for the label: "Show the conversation". */
+    panelName?: string;
+    /** The button's glyph. */
+    icon?: Icon;
+    /** Extra styles — an `order` among a header's items, say. */
+    sx?: SxProp["sx"];
+};
+/**
+ * The header button that opens and closes the page layout's side panel.
+ *
+ * It shares the layout's signals, so a host that opens the panel itself —
+ * `openPagePanel()` when something lands in it — sees the button follow.
+ * With the panel's content on the sheet there is nothing to open, and the
+ * button draws nothing.
+ */
+export declare function PagePanelToggle({ panelName, icon, sx, }: PagePanelToggleProps): JSX.Element | null;
+export default PagePanelToggle;

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

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { IconButton } from "@primer/react";
+import { SidebarExpandIcon } from "@primer/octicons-react";
+import { useSignalValue } from "@datalayer/reactor/react";
+import { openPagePanel, pageLayoutPanelOpen, pageLayoutSheet, } from "./panelState";
+/**
+ * The header button that opens and closes the page layout's side panel.
+ *
+ * It shares the layout's signals, so a host that opens the panel itself —
+ * `openPagePanel()` when something lands in it — sees the button follow.
+ * With the panel's content on the sheet there is nothing to open, and the
+ * button draws nothing.
+ */
+export function PagePanelToggle({ panelName = "panel", icon = SidebarExpandIcon, sx, }) {
+    const open = useSignalValue(pageLayoutPanelOpen);
+    const sheet = useSignalValue(pageLayoutSheet);
+    if (sheet === "panel") {
+        return null;
+    }
+    return (_jsx(IconButton, { icon: icon, size: "small", variant: open ? "default" : "invisible", "aria-label": open ? `Hide the ${panelName}` : `Show the ${panelName}`, "aria-pressed": open, onClick: () => {
+            if (open) {
+                pageLayoutPanelOpen.value = false;
+            }
+            else {
+                openPagePanel();
+            }
+        }, sx: { color: open ? "accent.fg" : "fg.muted", ...sx } }));
+}
+export default PagePanelToggle;

package/lib/reactor/page-layout/SlotPageLayout.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The page layout fed from slots, for a host whose parts arrive as plugins.
+ *
+ * The layout component takes elements; a Reactor host has slot components.
+ * This reads four slots — the page, the band, the panel, the chips — and
+ * hands each to the layout as a `ReactorSlot`, or as nothing when no plugin
+ * filled it, so an empty band draws no band and an empty panel offers no
+ * toggle. Whatever the host passed to the layout's own slot goes on to every
+ * sub-slot, the way a slot's props always reach its components.
+ *
+ * @module reactor/page-layout/SlotPageLayout
+ */
+import type { JSX } from "react";
+import type { Icon } from "@primer/octicons-react";
+import { type PageLayoutProps } from "./PageLayout";
+export type SlotPageLayoutProps = Pick<PageLayoutProps, "bandMode" | "panelMode" | "panelSide" | "sheetWidth" | "pageSize" | "panelWidth"> & {
+    pageSlot: string;
+    bandSlot: string;
+    panelSlot: string;
+    chipsSlot: string;
+    /** What the host handed the layout's slot; passed on to every sub-slot. */
+    context?: Record<string, unknown>;
+};
+export declare function SlotPageLayout({ pageSlot, bandSlot, panelSlot, chipsSlot, context, ...layout }: SlotPageLayoutProps): JSX.Element;
+/**
+ * The panel toggle, drawn only while some plugin fills the panel slot.
+ *
+ * Its place in the header is the slot component's `order`, which the slot
+ * applies; nothing here sets a CSS order, which would reshuffle the row.
+ */
+export declare function SlotPanelToggle({ panelSlot, panelName, icon, }: {
+    panelSlot: string;
+    panelName?: string;
+    icon?: Icon;
+}): JSX.Element | null;
+export default SlotPageLayout;

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

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ReactorSlot, useOptionalSlotComponents, } from "@datalayer/reactor/react";
+import { PageLayout } from "./PageLayout";
+import { PagePanelToggle } from "./PagePanelToggle";
+export function SlotPageLayout({ pageSlot, bandSlot, panelSlot, chipsSlot, context, ...layout }) {
+    const hasPage = useOptionalSlotComponents(pageSlot).length > 0;
+    const hasBand = useOptionalSlotComponents(bandSlot).length > 0;
+    const hasPanel = useOptionalSlotComponents(panelSlot).length > 0;
+    const hasChips = useOptionalSlotComponents(chipsSlot).length > 0;
+    return (_jsx(PageLayout, { ...layout, page: hasPage ? _jsx(ReactorSlot, { slot: pageSlot, props: context }) : null, hasPage: hasPage, band: hasBand ? _jsx(ReactorSlot, { slot: bandSlot, props: context }) : null, panel: hasPanel ? _jsx(ReactorSlot, { slot: panelSlot, props: context }) : null, chips: hasChips ? _jsx(ReactorSlot, { slot: chipsSlot, props: context }) : null }));
+}
+/**
+ * The panel toggle, drawn only while some plugin fills the panel slot.
+ *
+ * Its place in the header is the slot component's `order`, which the slot
+ * applies; nothing here sets a CSS order, which would reshuffle the row.
+ */
+export function SlotPanelToggle({ panelSlot, panelName, icon, }) {
+    const hasPanel = useOptionalSlotComponents(panelSlot).length > 0;
+    if (!hasPanel) {
+        return null;
+    }
+    return _jsx(PagePanelToggle, { panelName: panelName, icon: icon });
+}
+export default SlotPageLayout;

package/lib/reactor/page-layout/panelState.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare const pageLayoutPanelOpen: import("@datalayer/reactor").Signal<boolean>;
+/**
+ * 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 declare const pageLayoutSheet: import("@datalayer/reactor").Signal<"page" | "panel">;
+/**
+ * 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 declare const pageLayoutActivity: import("@datalayer/reactor").Signal<string | undefined>;
+/** Open the panel — for a host that wants its content seen the moment it lands. */
+export declare function openPagePanel(): void;
+export declare function closePagePanel(): void;
+export declare function togglePagePanel(): void;

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> | Promise<React.ReactNode> | React.JSX.Element | 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';