@datalayer/primer-addons 1.0.10 → 1.0.12

package/lib/theme/themes/createThemeCSSVars.js

@@ -26,6 +26,10 @@
  * | Outline button   | `--button-outline-fgColor-rest`        |
  * | Danger button    | `--button-danger-bgColor-hover`        |
  * | Button counters  | `--buttonCounter-primary-bgColor-rest` |
+ * | Control track    | `--controlTrack-bgColor-rest`          |
+ * | Control checked  | `--control-checked-bgColor-rest`       |
+ * | Control knob     | `--controlKnob-bgColor-rest`           |
+ * | List hover       | `--control-transparent-bgColor-hover`  |
  * | Legacy aliases   | `--color-btn-primary-bg`               |
  * | Brand (custom)   | `--brand-color-canvas-default`         |
  */
@@ -34,12 +38,6 @@ export function colorDefsToCSS(defs) {
     if (defs.canvas.subtle) {
         optional['--bgColor-muted'] = defs.canvas.subtle;
     }
-    if (defs.accent.subtle) {
-        optional['--bgColor-accent-subtle'] = defs.accent.subtle;
-    }
-    if (defs.success.subtle) {
-        optional['--bgColor-success-subtle'] = defs.success.subtle;
-    }
     return {
         /* ── Canvas / Background ─────────────────────────────────────── */
         '--bgColor-default': defs.canvas.default,
@@ -54,13 +52,13 @@ export function colorDefsToCSS(defs) {
         /* ── Accent ──────────────────────────────────────────────────── */
         '--fgColor-accent': defs.accent.fg,
         '--bgColor-accent-emphasis': defs.accent.emphasis,
-        '--bgColor-accent-muted': defs.accent.muted,
+        '--bgColor-accent-muted': defs.accent.subtle ?? defs.accent.muted,
         '--borderColor-accent-emphasis': defs.accent.emphasis,
         '--borderColor-accent-muted': defs.accent.muted,
         /* ── Success ─────────────────────────────────────────────────── */
         '--fgColor-success': defs.success.fg,
         '--bgColor-success-emphasis': defs.success.emphasis,
-        '--bgColor-success-muted': defs.success.muted,
+        '--bgColor-success-muted': defs.success.subtle ?? defs.success.muted,
         '--borderColor-success-emphasis': defs.success.emphasis,
         '--borderColor-success-muted': defs.success.muted,
         /* ── Border (generic) ────────────────────────────────────────── */
@@ -141,6 +139,35 @@ export function colorDefsToCSS(defs) {
         '--button-invisible-iconColor-rest': defs.fg.muted,
         '--button-invisible-iconColor-hover': defs.fg.default,
         '--button-invisible-iconColor-disabled': defs.fg.muted,
+        /* ── Control track (unchecked toggle / switch) ────────────── */
+        '--controlTrack-bgColor-rest': defs.border?.muted ?? defs.btn.border,
+        '--controlTrack-bgColor-hover': defs.border?.default ?? defs.btn.border,
+        '--controlTrack-bgColor-active': defs.border?.default ?? defs.btn.hoverBorder,
+        '--controlTrack-bgColor-disabled': defs.fg.muted,
+        '--controlTrack-fgColor-rest': defs.fg.muted,
+        '--controlTrack-fgColor-disabled': defs.fg.onEmphasis,
+        '--controlTrack-borderColor-rest': 'transparent',
+        /* ── Control checked (checked toggle / switch track) ──────── */
+        '--control-checked-bgColor-rest': defs.accent.emphasis,
+        '--control-checked-bgColor-hover': defs.btn.primary.hoverBg,
+        '--control-checked-bgColor-active': defs.btn.primary.selectedBg,
+        '--control-checked-fgColor-rest': defs.btn.primary.text,
+        '--control-checked-fgColor-disabled': defs.btn.primary.text,
+        '--control-checked-borderColor-rest': 'transparent',
+        /* ── Control knob (toggle switch handle) ──────────────────── */
+        '--controlKnob-bgColor-rest': defs.canvas.default,
+        '--controlKnob-bgColor-checked': defs.canvas.default,
+        '--controlKnob-bgColor-disabled': defs.canvas.subtle ?? defs.canvas.default,
+        '--controlKnob-borderColor-rest': defs.border?.default ?? defs.btn.border,
+        '--controlKnob-borderColor-checked': defs.accent.emphasis,
+        /* ── Control transparent (action list / nav list hover) ───── */
+        '--control-transparent-bgColor-hover': defs.btn.hoverBg,
+        '--control-transparent-bgColor-active': defs.btn.activeBg,
+        '--control-transparent-bgColor-selected': defs.btn.selectedBg,
+        '--control-transparent-borderColor-hover': 'transparent',
+        '--control-transparent-borderColor-active': 'transparent',
+        /* ── Menu ────────────────────────────────────────────────────── */
+        '--menu-bgColor-active': defs.btn.hoverBg,
         /* ── Legacy / compat aliases ─────────────────────────────────── */
         '--color-btn-primary-bg': defs.btn.primary.bg,
         '--color-btn-primary-hover-bg': defs.btn.primary.hoverBg,
@@ -153,20 +180,54 @@ export function colorDefsToCSS(defs) {
  * Build a complete `ThemeStyles` object from light / dark
  * `ThemeColorDefs`.  The result is ready to pass straight to
  * `<DatalayerThemeProvider themeStyles={…}>`.
+ *
+ * @param options.fontFamily  When supplied, the Primer font-stack
+ *   CSS custom properties (`--fontStack-sansSerif`,
+ *   `--fontStack-sansSerifDisplay`) are overridden so that every
+ *   Primer component that uses the CSS `font` shorthand (e.g.
+ *   `Blankslate`) picks up the themed font instead of the
+ *   hard-coded system-font fallback.
  */
-export function buildThemeStyles(light, dark) {
+export function buildThemeStyles(light, dark, options) {
+    const fontVars = {};
+    if (options?.fontFamily) {
+        const f = options.fontFamily;
+        // Override the font-stack custom properties so that any consumer
+        // referencing `var(--fontStack-sansSerif)` picks up the theme font.
+        fontVars['--fontStack-sansSerif'] = f;
+        fontVars['--fontStack-sansSerifDisplay'] = f;
+        // Also override every font-shorthand token directly.  Primer
+        // components like Blankslate use
+        //   `font: var(--text-title-shorthand-medium, <hardcoded>)`
+        // and relying on nested `var()` resolution inside the CSS `font`
+        // shorthand is unreliable across browsers.  Inlining the font
+        // family here guarantees the themed typeface is applied.
+        fontVars['--text-body-shorthand-large'] = `400 1rem/1.5 ${f}`;
+        fontVars['--text-body-shorthand-medium'] = `400 0.875rem/1.4285 ${f}`;
+        fontVars['--text-body-shorthand-small'] = `400 0.75rem/1.6666 ${f}`;
+        fontVars['--text-title-shorthand-large'] = `600 2rem/1.5 ${f}`;
+        fontVars['--text-title-shorthand-medium'] = `600 1.25rem/1.6 ${f}`;
+        fontVars['--text-title-shorthand-small'] = `600 1rem/1.5 ${f}`;
+        fontVars['--text-caption-shorthand'] = `400 0.75rem/1.3333 ${f}`;
+        fontVars['--text-subtitle-shorthand'] = `400 1.25rem/1.6 ${f}`;
+        fontVars['--text-display-shorthand'] = `500 2.5rem/1.4 ${f}`;
+    }
     return {
         light: {
             backgroundColor: light.canvas.default,
             color: light.fg.default,
             fontSize: 'var(--text-body-size-medium)',
+            ...(options?.fontFamily ? { fontFamily: options.fontFamily } : {}),
             ...colorDefsToCSS(light),
+            ...fontVars,
         },
         dark: {
             backgroundColor: dark.canvas.default,
             color: dark.fg.default,
             fontSize: 'var(--text-body-size-medium)',
+            ...(options?.fontFamily ? { fontFamily: options.fontFamily } : {}),
             ...colorDefsToCSS(dark),
+            ...fontVars,
         },
     };
 }

package/lib/theme/themes/matrixTheme.d.ts

@@ -1089,8 +1089,5 @@ export declare const matrixTheme: {
     }>;
 };
 /** Comprehensive Primer CSS-variable overrides for light & dark mode. */
-export declare const matrixThemeStyles: {
-    light: import("react").CSSProperties;
-    dark: import("react").CSSProperties;
-};
+export declare const matrixThemeStyles: import("./createThemeCSSVars").ThemeStyles;
 export default matrixTheme;

package/lib/theme/themes/matrixTheme.js

@@ -27,11 +27,13 @@ const matrixLight = {
         fg: matrixColors.greenText,
         emphasis: matrixColors.greenBrand,
         muted: matrixColors.greenAccent,
+        subtle: matrixColors.greenTint,
     },
     success: {
         fg: matrixColors.greenText,
         emphasis: matrixColors.greenBrand,
         muted: matrixColors.greenAccent,
+        subtle: matrixColors.greenTint,
     },
     btn: {
         text: '#0A2E1A',
@@ -192,11 +194,5 @@ export const matrixTheme = primerTheme;
  */
 const matrixFontFamily = '"SF Mono", "Cascadia Code", "Fira Code", Menlo, Consolas, "Liberation Mono", "Courier New", monospace';
 /** Comprehensive Primer CSS-variable overrides for light & dark mode. */
-export const matrixThemeStyles = (() => {
-    const base = buildThemeStyles(matrixLight, matrixDark);
-    return {
-        light: { ...base.light, fontFamily: matrixFontFamily },
-        dark: { ...base.dark, fontFamily: matrixFontFamily },
-    };
-})();
+export const matrixThemeStyles = buildThemeStyles(matrixLight, matrixDark, { fontFamily: matrixFontFamily });
 export default matrixTheme;

package/lib/theme/useThemeStore.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Zustand store for theme preferences – reusable across Datalayer apps.
+ *
+ * Persists `colorMode` and `theme` to localStorage. The store key is
+ * configurable so that different apps can maintain independent prefs.
+ *
+ * @module theme/useThemeStore
+ */
+import { type StoreApi, type UseBoundStore } from 'zustand';
+import type { ThemeVariant } from './themeRegistry';
+import type { ColorMode } from './DatalayerBrandThemeProvider';
+export type { ThemeVariant, ColorMode };
+export interface ThemeState {
+    /** Current color mode (light, dark, or auto = follow OS). */
+    colorMode: ColorMode;
+    /** Current theme variant. */
+    theme: ThemeVariant;
+    /** Cycle through light → dark → auto. */
+    toggleColorMode: () => void;
+    /** Set a specific color mode. */
+    setColorMode: (mode: ColorMode) => void;
+    /**
+     * Set the active theme variant.
+     * @param applyDefaultColorMode When true (default), also switches the
+     *   color mode to the theme's configured default.
+     */
+    setTheme: (theme: ThemeVariant, applyDefaultColorMode?: boolean) => void;
+}
+/**
+ * Create a theme store bound to a specific localStorage key.
+ *
+ * Usage:
+ * ```ts
+ * export const useMyAppThemeStore = createThemeStore('my-app-theme');
+ * ```
+ *
+ * @param storageKey  localStorage key for persistence (e.g. `'otel-example-theme'`)
+ * @param defaults    Optional overrides for the initial colorMode / theme
+ */
+export declare function createThemeStore(storageKey: string, defaults?: {
+    colorMode?: ColorMode;
+    theme?: ThemeVariant;
+}): UseBoundStore<StoreApi<ThemeState>>;
+/**
+ * Default theme store for Datalayer applications.
+ *
+ * Persists to `localStorage` under the key `'datalayer-theme'`.
+ * Use `createThemeStore` if you need an app-specific key or defaults.
+ */
+export declare const useThemeStore: UseBoundStore<StoreApi<ThemeState>>;

package/lib/theme/useThemeStore.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Zustand store for theme preferences – reusable across Datalayer apps.
+ *
+ * Persists `colorMode` and `theme` to localStorage. The store key is
+ * configurable so that different apps can maintain independent prefs.
+ *
+ * @module theme/useThemeStore
+ */
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import { themeConfigs } from './themeRegistry';
+/**
+ * Create a theme store bound to a specific localStorage key.
+ *
+ * Usage:
+ * ```ts
+ * export const useMyAppThemeStore = createThemeStore('my-app-theme');
+ * ```
+ *
+ * @param storageKey  localStorage key for persistence (e.g. `'otel-example-theme'`)
+ * @param defaults    Optional overrides for the initial colorMode / theme
+ */
+export function createThemeStore(storageKey, defaults) {
+    return create()(persist(set => ({
+        colorMode: defaults?.colorMode ?? 'dark',
+        theme: defaults?.theme ?? 'matrix',
+        toggleColorMode: () => set(state => {
+            const cycle = {
+                light: 'dark',
+                dark: 'auto',
+                auto: 'light',
+            };
+            return { colorMode: cycle[state.colorMode] };
+        }),
+        setColorMode: (mode) => set({ colorMode: mode }),
+        setTheme: (theme, applyDefaultColorMode = true) => set(() => {
+            const next = { theme };
+            if (applyDefaultColorMode) {
+                next.colorMode = themeConfigs[theme].defaultColorMode;
+            }
+            return next;
+        }),
+    }), {
+        name: storageKey,
+        storage: createJSONStorage(() => localStorage),
+        partialize: state => ({
+            colorMode: state.colorMode,
+            theme: state.theme,
+        }),
+    }));
+}
+/**
+ * Default theme store for Datalayer applications.
+ *
+ * Persists to `localStorage` under the key `'datalayer-theme'`.
+ * Use `createThemeStore` if you need an app-specific key or defaults.
+ */
+export const useThemeStore = createThemeStore('datalayer-theme', {
+    colorMode: 'dark',
+    theme: 'matrix',
+});

package/lib/utils/Portals.d.ts

@@ -1,10 +1,29 @@
+import { type CSSProperties } from 'react';
 import '@primer/react-brand/lib/css/main.css';
 type Colormode = 'light' | 'dark' | 'auto';
 /**
  * Ensure we define a root for Primer portal root.
  *
+ * Creates a dedicated `<div>` appended to `<body>` with a high z-index
+ * so that portaled content (overlays, tooltips, action menus) renders
+ * above other positioned UI elements such as chat panels.
+ *
  *  @see https://github.com/primer/react/blob/main/packages/react/src/Portal/Portal.tsx#L23
  *  @see https://github.com/primer/react/blob/030fe020b48b7f12c2994c6614e5d4191fe764ee/src/Portal/Portal.tsx#L33
  */
 export declare const setupPrimerPortals: (colormode?: Colormode) => void;
+/**
+ * Sync a set of CSS properties (including CSS custom properties) to
+ * `document.body` so that Primer portal content — which is a DOM child
+ * of `<body>`, not of the React-tree `<BaseStyles>` element — inherits
+ * the same theme tokens and cascade properties (font, color, background)
+ * as the rest of the application.
+ *
+ * This function is **idempotent**: calling it again replaces the
+ * properties from the previous call and removes any stale ones.
+ *
+ * Typical usage: call from `DatalayerThemeProvider`'s `useEffect` so
+ * portals stay in sync whenever theme or color-mode changes.
+ */
+export declare function syncPortalThemeStyles(styles: CSSProperties): void;
 export default setupPrimerPortals;

package/lib/utils/Portals.js

@@ -5,6 +5,11 @@
 import { registerPortalRoot } from '@primer/react';
 import '@primer/react-brand/lib/css/main.css';
 const PRIMER_PORTAL_ROOT_ID = '__primerPortalRoot__';
+/**
+ * Key used on `document.body` to track the CSS-property names we
+ * previously applied so we can remove stale entries on theme switch.
+ */
+const PORTAL_THEME_KEYS = '__primerPortalThemeKeys__';
 /**
  * Resolve 'auto' colormode to the actual OS preference.
  */
@@ -14,20 +19,117 @@ const resolveColormode = (colormode) => {
     }
     return colormode;
 };
+/**
+ * Infer current app color mode from existing DOM theme markers.
+ *
+ * This avoids accidentally forcing light mode when callers invoke
+ * setupPrimerPortals() without passing an explicit mode.
+ */
+const inferCurrentColormode = () => {
+    const portalRoot = document.getElementById(PRIMER_PORTAL_ROOT_ID);
+    const portalMode = portalRoot?.getAttribute('data-color-mode');
+    if (portalMode === 'light' || portalMode === 'dark' || portalMode === 'auto') {
+        return portalMode;
+    }
+    const htmlMode = document.documentElement.getAttribute('data-color-mode');
+    if (htmlMode === 'light' || htmlMode === 'dark' || htmlMode === 'auto') {
+        return htmlMode;
+    }
+    const bodyMode = document.body.getAttribute('data-color-mode');
+    if (bodyMode === 'light' || bodyMode === 'dark' || bodyMode === 'auto') {
+        return bodyMode;
+    }
+    return 'auto';
+};
+/**
+ * Infer Primer light/dark theme names from existing DOM markers.
+ */
+const inferCurrentThemeNames = () => {
+    const portalRoot = document.getElementById(PRIMER_PORTAL_ROOT_ID);
+    const lightTheme = portalRoot?.getAttribute('data-light-theme') ||
+        document.documentElement.getAttribute('data-light-theme') ||
+        document.body.getAttribute('data-light-theme') ||
+        'light';
+    const darkTheme = portalRoot?.getAttribute('data-dark-theme') ||
+        document.documentElement.getAttribute('data-dark-theme') ||
+        document.body.getAttribute('data-dark-theme') ||
+        'dark';
+    return { lightTheme, darkTheme };
+};
 /**
  * Ensure we define a root for Primer portal root.
  *
+ * Creates a dedicated `<div>` appended to `<body>` with a high z-index
+ * so that portaled content (overlays, tooltips, action menus) renders
+ * above other positioned UI elements such as chat panels.
+ *
  *  @see https://github.com/primer/react/blob/main/packages/react/src/Portal/Portal.tsx#L23
  *  @see https://github.com/primer/react/blob/030fe020b48b7f12c2994c6614e5d4191fe764ee/src/Portal/Portal.tsx#L33
  */
-export const setupPrimerPortals = (colormode = 'light') => {
-    const resolved = resolveColormode(colormode);
-    const body = document.body;
-    body.dataset['portalRoot'] = 'true';
-    body.dataset['colorMode'] = resolved;
-    body.dataset['lightTheme'] = 'light';
-    body.dataset['darkTheme'] = 'dark';
-    body.id = PRIMER_PORTAL_ROOT_ID;
-    registerPortalRoot(body);
+export const setupPrimerPortals = (colormode) => {
+    const effectiveColormode = colormode ?? inferCurrentColormode();
+    const resolved = resolveColormode(effectiveColormode);
+    const { lightTheme, darkTheme } = inferCurrentThemeNames();
+    // Create or reuse a dedicated portal root div.
+    let portalRoot = document.getElementById(PRIMER_PORTAL_ROOT_ID);
+    if (!portalRoot) {
+        portalRoot = document.createElement('div');
+        portalRoot.id = PRIMER_PORTAL_ROOT_ID;
+        document.body.appendChild(portalRoot);
+    }
+    // Primer theme attributes — required for proper theming inside portals.
+    portalRoot.dataset['portalRoot'] = 'true';
+    portalRoot.dataset['colorMode'] = resolved;
+    portalRoot.dataset['lightTheme'] = lightTheme;
+    portalRoot.dataset['darkTheme'] = darkTheme;
+    // High z-index so overlays render above positioned UI (e.g. chat z-index 1001).
+    portalRoot.style.position = 'relative';
+    portalRoot.style.zIndex = '9999';
+    registerPortalRoot(portalRoot);
 };
+/* ─── camelCase → kebab-case ─────────────────────────────────────────── */
+const camelToKebab = (s) => s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+/**
+ * Sync a set of CSS properties (including CSS custom properties) to
+ * `document.body` so that Primer portal content — which is a DOM child
+ * of `<body>`, not of the React-tree `<BaseStyles>` element — inherits
+ * the same theme tokens and cascade properties (font, color, background)
+ * as the rest of the application.
+ *
+ * This function is **idempotent**: calling it again replaces the
+ * properties from the previous call and removes any stale ones.
+ *
+ * Typical usage: call from `DatalayerThemeProvider`'s `useEffect` so
+ * portals stay in sync whenever theme or color-mode changes.
+ */
+export function syncPortalThemeStyles(styles) {
+    const body = document.body;
+    // 1. Remove properties set by the previous invocation.
+    const prev = body[PORTAL_THEME_KEYS];
+    if (prev) {
+        for (const key of prev) {
+            body.style.removeProperty(key);
+        }
+    }
+    // 2. Apply the new properties.
+    const tracked = [];
+    for (const [key, value] of Object.entries(styles)) {
+        if (value == null)
+            continue;
+        const strVal = String(value);
+        if (key.startsWith('--')) {
+            // CSS custom property — must use setProperty
+            body.style.setProperty(key, strVal);
+            tracked.push(key);
+        }
+        else {
+            // Standard CSS property (camelCase → kebab-case)
+            const kebab = camelToKebab(key);
+            body.style.setProperty(kebab, strVal);
+            tracked.push(kebab);
+        }
+    }
+    // 3. Stash the list for the next cleanup.
+    body[PORTAL_THEME_KEYS] = tracked;
+}
 export default setupPrimerPortals;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalayer/primer-addons",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "license": "BSD-3-Clause",
   "scripts": {
     "build": "tsc && vite build",
@@ -33,7 +33,8 @@
     "react": "^18.3.1 || ^19.0.0",
     "react-dom": "^18.3.1 || ^19.0.0",
     "react-loading-skeleton": "^3.5.0",
-    "styled-components": "^5.3.10"
+    "styled-components": "^5.3.10",
+    "zustand": "^5.0.0"
   },
   "devDependencies": {
     "@storybook/addon-docs": "^9.0.15",