@datalayer/primer-addons 1.0.9 → 1.0.11

package/lib/theme/themeRegistry.js

@@ -0,0 +1,288 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { datalayerTheme, datalayerThemeStyles } from './themes/datalayerTheme';
+import { spatialTheme, spatialThemeStyles } from './themes/spatialTheme';
+import { lovelyTheme, lovelyThemeStyles } from './themes/lovelyTheme';
+import { matrixTheme, matrixThemeStyles } from './themes/matrixTheme';
+import { datalayerColors } from './colors/datalayerColors';
+import { spatialColors } from './colors/spatialColors';
+import { lovelyColors } from './colors/lovelyColors';
+import { matrixColors } from './colors/matrixColors';
+/* ─── Registry ────────────────────────────────────────────────────────── */
+export const themeConfigs = {
+    datalayer: {
+        label: 'Datalayer',
+        description: 'Default green palette — the classic Datalayer look.',
+        brandColor: datalayerColors.greenBrand,
+        defaultColorMode: 'auto',
+        primerTheme: datalayerTheme,
+        themeStyles: datalayerThemeStyles,
+        cardGradient: {
+            light: { from: datalayerColors.greenBrand, to: datalayerColors.greenText }, // #16A085 → #117A65
+            dark: { from: datalayerColors.greenAccent, to: datalayerColors.greenBrand }, // #1ABC9C → #16A085
+        },
+        brightPalette: {
+            glow: datalayerColors.brightGlow, // #00D68F — vivid emerald
+            onGlow: '#1b1f24', // dark text on bright green
+            pop: datalayerColors.brightPop, // #00E5FF — electric cyan
+            spark: datalayerColors.brightSpark, // #76FF03 — lime neon
+            blaze: datalayerColors.brightBlaze, // #FF1744 — vivid red
+            surge: datalayerColors.brightSurge, // #2979FF — electric blue
+            flame: datalayerColors.brightFlame, // #FF6D00 — vivid orange
+            gold: datalayerColors.brightGold, // #FFD600 — vivid yellow
+        },
+        brightPaletteLight: {
+            glow: datalayerColors.brightLightGlow, // #00BFA5 — vivid aqua-green
+            onGlow: '#1b1f24', // dark text on aqua-green
+            pop: datalayerColors.brightLightPop, // #00B0FF — vivid sky blue
+            spark: datalayerColors.brightLightSpark, // #64DD17 — vivid chartreuse
+            blaze: datalayerColors.brightLightBlaze, // #FF1744 — vivid red
+            surge: datalayerColors.brightLightSurge, // #2979FF — electric blue
+            flame: datalayerColors.brightLightFlame, // #FF6D00 — vivid orange
+            gold: datalayerColors.brightLightGold, // #FFAB00 — vivid amber
+        },
+    },
+    spatial: {
+        label: 'Spatial',
+        description: 'Cosmic indigo & deep blues — inspired by space.',
+        brandColor: spatialColors.indigoBrand,
+        defaultColorMode: 'auto',
+        primerTheme: spatialTheme,
+        themeStyles: spatialThemeStyles,
+        cardGradient: {
+            light: { from: spatialColors.indigoBrand, to: spatialColors.indigoText }, // #4F46E5 → #3730A3
+            dark: { from: spatialColors.indigoAccent, to: spatialColors.indigoBrand }, // #6366F1 → #4F46E5
+        },
+        brightPalette: {
+            glow: spatialColors.brightGlow, // #7C4DFF — electric violet
+            onGlow: '#ffffff', // white text on violet
+            pop: spatialColors.brightPop, // #448AFF — neon blue
+            spark: spatialColors.brightSpark, // #E040FB — vivid magenta
+            blaze: spatialColors.brightBlaze, // #FF5252 — neon red
+            surge: spatialColors.brightSurge, // #00B0FF — deep sky blue
+            flame: spatialColors.brightFlame, // #FF9100 — amber orange
+            gold: spatialColors.brightGold, // #FFEA00 — electric yellow
+        },
+        brightPaletteLight: {
+            glow: spatialColors.brightLightGlow, // #7C4DFF — electric violet
+            onGlow: '#ffffff', // white text on violet
+            pop: spatialColors.brightLightPop, // #448AFF — neon blue
+            spark: spatialColors.brightLightSpark, // #D500F9 — vivid purple
+            blaze: spatialColors.brightLightBlaze, // #FF5252 — neon red
+            surge: spatialColors.brightLightSurge, // #00B0FF — vivid sky blue
+            flame: spatialColors.brightLightFlame, // #FF9100 — vivid amber orange
+            gold: spatialColors.brightLightGold, // #FFC400 — vivid gold
+        },
+    },
+    lovely: {
+        label: 'Lovely',
+        description: 'Warm rose & magenta — soft and inviting.',
+        brandColor: lovelyColors.roseBrand,
+        defaultColorMode: 'auto',
+        primerTheme: lovelyTheme,
+        themeStyles: lovelyThemeStyles,
+        cardGradient: {
+            light: { from: lovelyColors.roseBrand, to: lovelyColors.roseText }, // #DB2777 → #9D174D
+            dark: { from: lovelyColors.roseAccent, to: lovelyColors.roseBrand }, // #EC4899 → #DB2777
+        },
+        brightPalette: {
+            glow: lovelyColors.brightGlow, // #FF4081 — hot pink
+            onGlow: '#ffffff', // white text on hot pink
+            pop: lovelyColors.brightPop, // #FF6E40 — vivid coral
+            spark: lovelyColors.brightSpark, // #EA80FC — electric fuchsia
+            blaze: lovelyColors.brightBlaze, // #FF1744 — vivid crimson
+            surge: lovelyColors.brightSurge, // #536DFE — indigo blue
+            flame: lovelyColors.brightFlame, // #FF6E40 — coral orange
+            gold: lovelyColors.brightGold, // #FFD740 — amber gold
+        },
+        brightPaletteLight: {
+            glow: lovelyColors.brightLightGlow, // #FF4081 — hot pink
+            onGlow: '#ffffff', // white text on hot pink
+            pop: lovelyColors.brightLightPop, // #FF6E40 — vivid coral
+            spark: lovelyColors.brightLightSpark, // #EA80FC — electric fuchsia
+            blaze: lovelyColors.brightLightBlaze, // #FF1744 — vivid crimson
+            surge: lovelyColors.brightLightSurge, // #536DFE — vivid indigo
+            flame: lovelyColors.brightLightFlame, // #FF6E40 — vivid coral orange
+            gold: lovelyColors.brightLightGold, // #FFD740 — vivid amber gold
+        },
+    },
+    matrix: {
+        label: 'Matrix',
+        description: 'Phosphor green on black — CRT terminal aesthetic.',
+        brandColor: matrixColors.greenPhosphor,
+        defaultColorMode: 'dark',
+        primerTheme: matrixTheme,
+        themeStyles: matrixThemeStyles,
+        cardGradient: {
+            light: { from: matrixColors.greenBrand, to: matrixColors.greenText }, // #16A085 → #117A65
+            dark: { from: matrixColors.greenGlow, to: matrixColors.greenHover }, // #39FF14 → #0E6655
+        },
+        brightPalette: {
+            glow: matrixColors.brightGlow, // #39FF14 — neon green
+            onGlow: '#1b1f24', // dark text on neon green
+            pop: matrixColors.brightPop, // #00FF88 — phosphor cyan
+            spark: matrixColors.brightSpark, // #CCFF00 — acid lime
+            blaze: matrixColors.brightBlaze, // #FF0040 — matrix red pill
+            surge: matrixColors.brightSurge, // #00E5FF — electric blue
+            flame: matrixColors.brightFlame, // #FF6D00 — electric orange
+            gold: matrixColors.brightGold, // #FFEA00 — glitch yellow
+        },
+        brightPaletteLight: {
+            glow: matrixColors.brightLightGlow, // #00E676 — vivid green
+            onGlow: '#1b1f24', // dark text on vivid green
+            pop: matrixColors.brightLightPop, // #1DE9B6 — vivid teal-mint
+            spark: matrixColors.brightLightSpark, // #AEEA00 — vivid lime
+            blaze: matrixColors.brightLightBlaze, // #FF1744 — vivid red
+            surge: matrixColors.brightLightSurge, // #00B0FF — vivid sky blue
+            flame: matrixColors.brightLightFlame, // #FF6D00 — vivid orange
+            gold: matrixColors.brightLightGold, // #FFAB00 — vivid amber
+        },
+    },
+};
+/** All available theme variants in display order. */
+export const themeVariants = ['datalayer', 'spatial', 'lovely', 'matrix'];
+/** Look up a theme config by variant name. */
+export function getThemeConfig(variant) {
+    return themeConfigs[variant];
+}
+/**
+ * Resolve the card gradient for a given theme variant and colour mode.
+ * Falls back to `datalayer` / `light` when values are missing.
+ */
+export function getCardGradient(variant = 'datalayer', colorMode = 'light') {
+    const mode = colorMode === 'auto' ? 'light' : colorMode;
+    return themeConfigs[variant]?.cardGradient?.[mode] ?? themeConfigs.datalayer.cardGradient.light;
+}
+/**
+ * Get the bright (vivid / OpenAI-blog-style) palette for a given theme variant.
+ *
+ * When `colorMode` is `'light'` the vivid / saturated light-background palette
+ * is returned — these are punchy, high-saturation colours designed to keep SVG
+ * illustrations vibrant and energetic on near-white surfaces.
+ * When `colorMode` is `'auto'`, the OS preference is queried via
+ * `prefers-color-scheme` so palettes always match the effective background.
+ * Defaults to the dark-optimised neon palette for backward compatibility.
+ */
+export function getBrightPalette(variant = 'datalayer', colorMode) {
+    const cfg = themeConfigs[variant] ?? themeConfigs.datalayer;
+    let resolvedMode;
+    if (colorMode === 'auto') {
+        resolvedMode =
+            typeof window !== 'undefined' &&
+                window.matchMedia('(prefers-color-scheme: dark)').matches
+                ? 'dark'
+                : 'light';
+    }
+    else if (colorMode === 'light') {
+        resolvedMode = 'light';
+    }
+    else {
+        resolvedMode = 'dark';
+    }
+    if (resolvedMode === 'light') {
+        return cfg.brightPaletteLight ?? cfg.brightPalette;
+    }
+    return cfg.brightPalette;
+}
+/**
+ * Avatar colour palettes per theme × colour mode.
+ *
+ * Each palette is a 5-colour array tuned for the `boring-avatars` library.
+ * The colours are picked from each theme's brand + bright palette so the
+ * avatar always feels native to the current theme.
+ *
+ * - **Light mode** uses the deeper / accessible colour variants so the
+ *   avatar is legible on light backgrounds.
+ * - **Dark mode** uses the brighter / glowing variants so the avatar
+ *   pops against dark surfaces.
+ */
+const avatarColorPalettes = {
+    datalayer: {
+        light: [
+            datalayerColors.greenText, // #117A65 — deep green
+            datalayerColors.greenBrand, // #16A085 — brand green
+            datalayerColors.brightLightPop, // #00B0FF — sky blue
+            datalayerColors.brightLightGold, // #FFAB00 — amber
+            datalayerColors.gray, // #59595C — neutral
+        ],
+        dark: [
+            datalayerColors.greenAccent, // #1ABC9C — bright teal
+            datalayerColors.greenBright, // #2ECC71 — bright green
+            datalayerColors.brightPop, // #00E5FF — electric cyan
+            datalayerColors.brightGold, // #FFD600 — vivid yellow
+            datalayerColors.brightFlame, // #FF6D00 — vivid orange
+        ],
+    },
+    spatial: {
+        light: [
+            spatialColors.indigoText, // #3730A3 — deep indigo
+            spatialColors.indigoBrand, // #4F46E5 — brand indigo
+            spatialColors.brightLightSpark, // #D500F9 — vivid purple
+            spatialColors.brightLightGold, // #FFC400 — vivid gold
+            spatialColors.gray, // #8892B0 — nebula gray
+        ],
+        dark: [
+            spatialColors.indigoAccent, // #6366F1 — bright indigo
+            spatialColors.indigoBright, // #818CF8 — light indigo
+            spatialColors.brightPop, // #448AFF — neon blue
+            spatialColors.brightSpark, // #E040FB — vivid magenta
+            spatialColors.brightGold, // #FFEA00 — electric yellow
+        ],
+    },
+    lovely: {
+        light: [
+            lovelyColors.roseText, // #9D174D — deep rose
+            lovelyColors.roseBrand, // #DB2777 — brand pink
+            lovelyColors.brightLightSurge, // #536DFE — vivid indigo
+            lovelyColors.brightLightGold, // #FFD740 — amber gold
+            lovelyColors.gray, // #9D7A8F — mauve gray
+        ],
+        dark: [
+            lovelyColors.roseAccent, // #EC4899 — bright pink
+            lovelyColors.roseBright, // #F472B6 — light pink
+            lovelyColors.brightPop, // #FF6E40 — vivid coral
+            lovelyColors.brightSpark, // #EA80FC — electric fuchsia
+            lovelyColors.brightGold, // #FFD740 — amber gold
+        ],
+    },
+    matrix: {
+        light: [
+            matrixColors.greenText, // #117A65 — deep green
+            matrixColors.greenBrand, // #16A085 — brand green
+            matrixColors.brightLightPop, // #1DE9B6 — vivid teal
+            matrixColors.brightLightGold, // #FFAB00 — vivid amber
+            matrixColors.gray, // #4A7856 — dim green-gray
+        ],
+        dark: [
+            matrixColors.greenPhosphor, // #00FF41 — Matrix green
+            matrixColors.greenGlow, // #39FF14 — neon phosphor
+            matrixColors.brightPop, // #00FF88 — phosphor cyan
+            matrixColors.brightSpark, // #CCFF00 — acid lime
+            matrixColors.brightSurge, // #00E5FF — electric blue
+        ],
+    },
+};
+/**
+ * Get a 5-colour avatar palette for the given theme variant and colour mode.
+ *
+ * Designed for use with the `boring-avatars` library's `colors` prop.
+ * When `colorMode` is `'auto'`, the OS preference is queried via
+ * `prefers-color-scheme` so avatars always match the effective background.
+ * Falls back to `datalayer` / `light` when values are missing.
+ */
+export function getAvatarColors(variant = 'datalayer', colorMode = 'light') {
+    let mode;
+    if (colorMode === 'auto') {
+        mode =
+            typeof window !== 'undefined' &&
+                window.matchMedia('(prefers-color-scheme: dark)').matches
+                ? 'dark'
+                : 'light';
+    }
+    else {
+        mode = colorMode;
+    }
+    return avatarColorPalettes[variant]?.[mode] ?? avatarColorPalettes.datalayer.light;
+}

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

@@ -31,6 +31,10 @@ export interface ThemeColorDefs {
         muted: string;
         subtle?: string;
     };
+    border?: {
+        default: string;
+        muted: string;
+    };
     btn: {
         text: string;
         bg: string;
@@ -114,6 +118,10 @@ export interface ThemeColorDefs {
  * | 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`         |
  */
@@ -127,5 +135,14 @@ export interface ThemeStyles {
  * 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 declare function buildThemeStyles(light: ThemeColorDefs, dark: ThemeColorDefs): ThemeStyles;
+export declare function buildThemeStyles(light: ThemeColorDefs, dark: ThemeColorDefs, options?: {
+    fontFamily?: string;
+}): ThemeStyles;

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,18 +52,18 @@ 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) ────────────────────────────────────────── */
-        '--borderColor-default': defs.btn.border,
-        '--borderColor-muted': defs.btn.border,
+        '--borderColor-default': defs.border?.default ?? defs.btn.border,
+        '--borderColor-muted': defs.border?.muted ?? defs.btn.border,
         /* ── Default button ──────────────────────────────────────────── */
         '--button-default-fgColor-rest': defs.btn.text,
         '--button-default-bgColor-rest': defs.btn.bg,
@@ -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/datalayerTheme.js

@@ -34,6 +34,10 @@ const datalayerLight = {
         emphasis: datalayerColors.greenBrand,
         muted: datalayerColors.greenAccent,
     },
+    border: {
+        default: '#d1d9e0',
+        muted: '#e0e6eb',
+    },
     btn: {
         text: datalayerColors.black,
         bg: datalayerColors.white,

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',
@@ -185,6 +187,12 @@ const matrixDark = {
  * default Primer theme kept for backward compatibility.
  */
 export const matrixTheme = primerTheme;
+/**
+ * Monospace font stack for the Matrix terminal aesthetic.
+ * Uses fonts pre-installed across macOS / Windows / Linux so no
+ * web-font loading is required.
+ */
+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 = buildThemeStyles(matrixLight, matrixDark);
+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,3 +1,4 @@
+import { type CSSProperties } from 'react';
 import '@primer/react-brand/lib/css/main.css';
 type Colormode = 'light' | 'dark' | 'auto';
 /**
@@ -7,4 +8,18 @@ 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;
+/**
+ * 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;