@datalayer/primer-addons 1.0.9 → 1.0.11

package/lib/story-helpers.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+import { ArgTypes } from '@storybook/react';
+import { Icon } from '@primer/octicons-react';
+type StoryContext = Record<string, unknown> & {
+    globals: {
+        colorScheme: string;
+    };
+    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 toolbarTypes: {
+    colorScheme: {
+        name: string;
+        description: string;
+        defaultValue: string;
+        toolbar: {
+            icon: string;
+            items: string[];
+            title: string;
+        };
+    };
+};
+export declare const inputWrapperArgTypes: ArgTypes;
+export declare const getTextInputArgTypes: (category?: string) => Record<string, unknown>;
+export declare const OcticonArgType: (iconList: Icon[]) => {
+    options: string[];
+    control: string;
+    mapping: Record<string, Icon>;
+};
+export {};

package/lib/story-helpers.js

@@ -0,0 +1,105 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createGlobalStyle } from 'styled-components';
+import { ThemeProvider, themeGet, BaseStyles, theme } from '@primer/react';
+// set global theme styles for each story
+const GlobalStyle = createGlobalStyle `
+  body,
+  .docs-story {
+    background-color: ${themeGet('colors.canvas.default')};
+    color: ${themeGet('colors.fg.default')};
+  }
+`;
+export const colormodeFromScheme = (colorScheme) => {
+    return colorScheme.startsWith('light') ? 'light' : 'dark';
+};
+export const withThemeProvider = (Story, context) => {
+    // used for testing ThemeProvider.stories.tsx
+    if (context.parameters.disableThemeDecorator)
+        return Story(context);
+    const { colorScheme } = context.globals;
+    return (_jsxs(ThemeProvider, { theme: theme, colorMode: colormodeFromScheme(colorScheme), dayScheme: colorScheme, nightScheme: colorScheme, children: [colorScheme.startsWith('light') ? (_jsx(GlobalStyle, { "$lightTheme": true })) : (_jsx(GlobalStyle, {})), _jsx(BaseStyles, { children: _jsx("div", { id: "html-addon-root", children: Story(context) }) })] }));
+};
+export const toolbarTypes = {
+    colorScheme: {
+        name: 'Color Scheme',
+        description: 'Switch color scheme',
+        defaultValue: 'light',
+        toolbar: {
+            icon: 'photo',
+            items: [...Object.keys(theme.colorSchemes)],
+            title: 'Color Scheme',
+        },
+    },
+};
+export const inputWrapperArgTypes = {
+    block: {
+        defaultValue: false,
+        control: 'boolean',
+    },
+    contrast: {
+        defaultValue: false,
+        control: 'boolean',
+    },
+    disabled: {
+        defaultValue: false,
+        control: 'boolean',
+    },
+    placeholder: {
+        defaultValue: '',
+        control: 'text',
+    },
+    size: {
+        name: 'size (input)', // TODO: remove '(input)'
+        defaultValue: 'medium',
+        options: ['small', 'medium', 'large'],
+        control: 'radio',
+    },
+    validationStatus: {
+        defaultValue: undefined,
+        options: ['error', 'success', undefined],
+        control: 'radio',
+    },
+};
+const textInputArgTypesUnsorted = {
+    ...inputWrapperArgTypes,
+    loading: {
+        defaultValue: false,
+        control: 'boolean',
+    },
+    loaderPosition: {
+        defaultValue: 'auto',
+        options: ['auto', 'leading', 'trailing'],
+        control: 'radio',
+    },
+    monospace: {
+        defaultValue: false,
+        control: 'boolean',
+    },
+};
+// Alphabetize and optionally categorize the props
+export const getTextInputArgTypes = (category) => Object.keys(textInputArgTypesUnsorted)
+    .sort()
+    .reduce((obj, key) => {
+    obj[key] = category
+        ? {
+            // have to do weird type casting so we can spread the object
+            ...textInputArgTypesUnsorted[key],
+            table: {
+                category,
+            },
+        }
+        : textInputArgTypesUnsorted[key];
+    return obj;
+}, {});
+// Use this function for icon options in the controls. Desired icons are passed in as an array of Octicons
+export const OcticonArgType = (iconList) => {
+    const icons = iconList.reduce((obj, icon) => {
+        obj[icon.displayName || 'Icon'] = icon;
+        return obj;
+    }, {});
+    return {
+        options: Object.keys(icons),
+        control: 'select',
+        mapping: icons,
+    };
+};

package/lib/theme/DatalayerThemeProvider.js

@@ -1,17 +1,90 @@
 import { jsx as _jsx } 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';
+/**
+ * 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
  * letter-spacing on headings, crisp body text).
+ *
+ * Primer components like `Blankslate` use the CSS `font` shorthand
+ * through `--text-title-shorthand-*` / `--text-body-shorthand-*`.
+ * Those shorthand variables reference `--fontStack-sansSerif` (and
+ * `--fontStack-sansSerifDisplay`).  If the `@primer/primitives`
+ * typography CSS isn't loaded, the shorthand vars are undefined and
+ * components fall back to a hardcoded system font stack baked into
+ * their CSS.  We define the full set here so **every** theme gets
+ * correct font inheritance — no primitives CSS import required.
  */
 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,
+    /* ── 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',
+    /* ── 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',
+    /* ── 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',
+    /* ── 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',
+    /* ── 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
+     * `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}`,
+    /* ── Custom overrides ──────────────────────────────────────────── */
     '--text-body-lineHeight': '1.7',
     '--text-title-lineHeight': '1.2',
     '--text-title-letterSpacing': '-0.02em',
-    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"',
+    fontFamily: SYSTEM_FONT,
     WebkitFontSmoothing: 'antialiased',
     MozOsxFontSmoothing: 'grayscale',
     textRendering: 'optimizeLegibility',
@@ -25,6 +98,21 @@ export function DatalayerThemeProvider(props) {
     const resolvedTheme = theme ?? datalayerTheme;
     const styles = themeStyles ?? datalayerThemeStyles;
     const resolvedStyles = isDark ? styles.dark : styles.light;
+    // The full set of styles that <BaseStyles> receives — we also push
+    // these to document.body so Primer portal content inherits theme
+    // tokens, fonts, and colors.
+    const portalStyles = useMemo(() => ({
+        ...typographyVars,
+        ...resolvedStyles,
+        ...baseStyles,
+    }), [resolvedStyles, baseStyles]);
+    // 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).
+    useEffect(() => {
+        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',

package/lib/theme/ThemeSwitcher.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ThemeSwitcher – Themed colour circles + light/dark/auto segmented control.
+ *
+ * The component requires an external Zustand `ThemeState` store (created
+ * with `createThemeStore`).  Consumers pass the `useStore` hook as a prop
+ * so the switcher is completely decoupled from any specific app's store.
+ *
+ * @module theme/ThemeSwitcher
+ */
+import React from 'react';
+import type { ThemeState } from './useThemeStore';
+import type { UseBoundStore, StoreApi } from 'zustand';
+export interface ThemeSwitcherProps {
+    /** A Zustand store hook created via `createThemeStore()`. */
+    useStore: UseBoundStore<StoreApi<ThemeState>>;
+}
+export declare const ThemeSwitcher: React.FC<ThemeSwitcherProps>;

package/lib/theme/ThemeSwitcher.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, IconButton, SegmentedControl, Tooltip } from '@primer/react';
+import { SunIcon, MoonIcon, DeviceDesktopIcon, CircleIcon, } from '@primer/octicons-react';
+import { themeConfigs, themeVariants } from './themeRegistry';
+export const ThemeSwitcher = ({ useStore }) => {
+    const { colorMode, theme: themeVariant } = useStore();
+    return (_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 3 }, children: [_jsx(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1 }, children: themeVariants.map(variant => {
+                    const tcfg = themeConfigs[variant];
+                    const isSelected = themeVariant === variant;
+                    return (_jsx(Tooltip, { text: tcfg.label, direction: "s", children: _jsx(IconButton, { "aria-label": tcfg.label, "aria-pressed": isSelected, icon: () => _jsx(CircleIcon, { size: 16, fill: tcfg.brandColor }), size: "small", variant: isSelected ? 'default' : 'invisible', onClick: () => useStore.getState().setTheme(variant, false), sx: {
+                                border: isSelected ? '2px solid' : '1px solid',
+                                borderColor: isSelected ? 'accent.fg' : 'border.muted',
+                                borderRadius: '50%',
+                            } }) }, variant));
+                }) }), _jsxs(SegmentedControl, { "aria-label": "Color mode", size: "small", onChange: (index) => {
+                    const modes = ['light', 'dark', 'auto'];
+                    useStore.getState().setColorMode(modes[index]);
+                }, children: [_jsx(SegmentedControl.IconButton, { selected: colorMode === 'light', icon: SunIcon, "aria-label": "Light" }), _jsx(SegmentedControl.IconButton, { selected: colorMode === 'dark', icon: MoonIcon, "aria-label": "Dark" }), _jsx(SegmentedControl.IconButton, { selected: colorMode === 'auto', icon: DeviceDesktopIcon, "aria-label": "Auto" })] })] }));
+};

package/lib/theme/ThemedProvider.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ThemedProvider – Drop-in theme provider that reads theme / color-mode
+ * from a Zustand `ThemeState` store and forwards them to
+ * `DatalayerThemeProvider`.
+ *
+ * Consumers pass the `useStore` hook as a prop, so the provider is
+ * completely decoupled from any specific application's store instance.
+ *
+ * @module theme/ThemedProvider
+ */
+import React from 'react';
+import { type IDatalayerThemeProviderProps } from './DatalayerThemeProvider';
+import type { ThemeState } from './useThemeStore';
+import type { UseBoundStore, StoreApi } from 'zustand';
+export interface ThemedProviderProps extends Omit<IDatalayerThemeProviderProps, 'ref'> {
+    /** A Zustand store hook created via `createThemeStore()`. */
+    useStore: UseBoundStore<StoreApi<ThemeState>>;
+}
+/**
+ * Drop-in replacement for `<DatalayerThemeProvider>`.
+ * Reads theme / colorMode from the supplied store and forwards them to
+ * the real provider.  Any explicit props (colorMode, theme, themeStyles)
+ * are still respected as overrides.
+ */
+export declare const ThemedProvider: React.FC<React.PropsWithChildren<ThemedProviderProps>>;

package/lib/theme/ThemedProvider.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { DatalayerThemeProvider, } from './DatalayerThemeProvider';
+import { themeConfigs } from './themeRegistry';
+/**
+ * Drop-in replacement for `<DatalayerThemeProvider>`.
+ * Reads theme / colorMode from the supplied store and forwards them to
+ * the real provider.  Any explicit props (colorMode, theme, themeStyles)
+ * are still respected as overrides.
+ */
+export const ThemedProvider = ({ children, useStore, ...rest }) => {
+    const { colorMode, theme: themeVariant } = useStore();
+    const cfg = themeConfigs[themeVariant];
+    return (_jsx(DatalayerThemeProvider, { colorMode: rest.colorMode ?? colorMode, theme: rest.theme ?? cfg.primerTheme, themeStyles: rest.themeStyles ?? cfg.themeStyles, ...rest, children: children }));
+};

package/lib/theme/colors/datalayerColors.d.ts

@@ -12,4 +12,18 @@ export declare const datalayerColors: {
     greenTint: string;
     greenBright: string;
     greenHover: string;
+    brightGlow: string;
+    brightPop: string;
+    brightSpark: string;
+    brightBlaze: string;
+    brightSurge: string;
+    brightFlame: string;
+    brightGold: string;
+    brightLightGlow: string;
+    brightLightPop: string;
+    brightLightSpark: string;
+    brightLightBlaze: string;
+    brightLightSurge: string;
+    brightLightFlame: string;
+    brightLightGold: string;
 };

package/lib/theme/colors/datalayerColors.js

@@ -18,4 +18,21 @@ export const datalayerColors = {
     greenTint: '#E9F7F1', // Soft background for success / callouts
     greenBright: '#2ECC71', // Highlights and glow on dark backgrounds
     greenHover: '#0E6655', // Primary button hover
+    // Bright / vivid colours for SVG illustrations (OpenAI-blog style)
+    brightGlow: '#00D68F', // Ultra-vivid emerald — primary glow
+    brightPop: '#00E5FF', // Electric cyan — contrasting accent
+    brightSpark: '#76FF03', // Lime neon — sparkle / tertiary
+    brightBlaze: '#FF1744', // Vivid red — warm accent
+    brightSurge: '#2979FF', // Electric blue — cool accent
+    // Warm vivid colours — yellow & orange accents for SVG illustrations
+    brightFlame: '#FF6D00', // Vivid orange — warm energy accent
+    brightGold: '#FFD600', // Vivid yellow — golden highlight
+    // Vivid brights for light backgrounds — punchy, saturated, OpenAI-blog vibrancy
+    brightLightGlow: '#00BFA5', // Vivid aqua-green
+    brightLightPop: '#00B0FF', // Vivid sky blue
+    brightLightSpark: '#64DD17', // Vivid chartreuse
+    brightLightBlaze: '#FF1744', // Vivid red
+    brightLightSurge: '#2979FF', // Electric blue
+    brightLightFlame: '#FF6D00', // Vivid orange
+    brightLightGold: '#FFAB00', // Vivid amber
 };

package/lib/theme/colors/lovelyColors.d.ts

@@ -12,4 +12,18 @@ export declare const lovelyColors: {
     roseTint: string;
     roseBright: string;
     roseHover: string;
+    brightGlow: string;
+    brightPop: string;
+    brightSpark: string;
+    brightBlaze: string;
+    brightSurge: string;
+    brightFlame: string;
+    brightGold: string;
+    brightLightGlow: string;
+    brightLightPop: string;
+    brightLightSpark: string;
+    brightLightBlaze: string;
+    brightLightSurge: string;
+    brightLightFlame: string;
+    brightLightGold: string;
 };

package/lib/theme/colors/lovelyColors.js

@@ -18,4 +18,21 @@ export const lovelyColors = {
     roseTint: '#FDF2F8', // Soft background for callouts
     roseBright: '#F472B6', // Highlights & glow on dark
     roseHover: '#831843', // Primary button hover
+    // Bright / vivid colours for SVG illustrations (OpenAI-blog style)
+    brightGlow: '#FF4081', // Hot pink — primary glow
+    brightPop: '#FF6E40', // Vivid coral — contrasting accent
+    brightSpark: '#EA80FC', // Electric fuchsia — sparkle / tertiary
+    brightBlaze: '#FF1744', // Vivid crimson — warm accent
+    brightSurge: '#536DFE', // Indigo blue — cool accent
+    // Warm vivid colours — yellow & orange accents for SVG illustrations
+    brightFlame: '#FF6E40', // Coral orange — warm blush accent
+    brightGold: '#FFD740', // Amber gold — golden warmth
+    // Vivid brights for light backgrounds — punchy, saturated, OpenAI-blog vibrancy
+    brightLightGlow: '#FF4081', // Hot pink
+    brightLightPop: '#FF6E40', // Vivid coral
+    brightLightSpark: '#EA80FC', // Electric fuchsia
+    brightLightBlaze: '#FF1744', // Vivid crimson
+    brightLightSurge: '#536DFE', // Vivid indigo
+    brightLightFlame: '#FF6E40', // Vivid coral orange
+    brightLightGold: '#FFD740', // Vivid amber gold
 };

package/lib/theme/colors/matrixColors.d.ts

@@ -17,4 +17,18 @@ export declare const matrixColors: {
     greenGlow: string;
     greenHover: string;
     greenTerminal: string;
+    brightGlow: string;
+    brightPop: string;
+    brightSpark: string;
+    brightBlaze: string;
+    brightSurge: string;
+    brightFlame: string;
+    brightGold: string;
+    brightLightGlow: string;
+    brightLightPop: string;
+    brightLightSpark: string;
+    brightLightBlaze: string;
+    brightLightSurge: string;
+    brightLightFlame: string;
+    brightLightGold: string;
 };

package/lib/theme/colors/matrixColors.js

@@ -23,4 +23,21 @@ export const matrixColors = {
     greenGlow: '#39FF14', // Neon phosphor glow — brightest accent on dark
     greenHover: '#0E6655', // Datalayer hover — primary button hover
     greenTerminal: '#003B00', // Deep terminal — dark mode subtle/canvas
+    // Bright / vivid colours for SVG illustrations (OpenAI-blog style)
+    brightGlow: '#39FF14', // Neon green — primary glow (re-stated for palette API)
+    brightPop: '#00FF88', // Phosphor cyan — contrasting accent
+    brightSpark: '#CCFF00', // Acid lime — sparkle / tertiary
+    brightBlaze: '#FF0040', // Matrix red pill — warm accent
+    brightSurge: '#00E5FF', // Electric blue — cool accent
+    // Warm vivid colours — yellow & orange accents for SVG illustrations
+    brightFlame: '#FF6D00', // Electric orange — glitch warm accent
+    brightGold: '#FFEA00', // Glitch yellow — phosphor highlight
+    // Vivid brights for light backgrounds — punchy, saturated, OpenAI-blog vibrancy
+    brightLightGlow: '#00E676', // Vivid green
+    brightLightPop: '#1DE9B6', // Vivid teal-mint
+    brightLightSpark: '#AEEA00', // Vivid lime
+    brightLightBlaze: '#FF1744', // Vivid red
+    brightLightSurge: '#00B0FF', // Vivid sky blue
+    brightLightFlame: '#FF6D00', // Vivid orange
+    brightLightGold: '#FFAB00', // Vivid amber
 };

package/lib/theme/colors/spatialColors.d.ts

@@ -12,4 +12,18 @@ export declare const spatialColors: {
     indigoTint: string;
     indigoBright: string;
     indigoHover: string;
+    brightGlow: string;
+    brightPop: string;
+    brightSpark: string;
+    brightBlaze: string;
+    brightSurge: string;
+    brightFlame: string;
+    brightGold: string;
+    brightLightGlow: string;
+    brightLightPop: string;
+    brightLightSpark: string;
+    brightLightBlaze: string;
+    brightLightSurge: string;
+    brightLightFlame: string;
+    brightLightGold: string;
 };

package/lib/theme/colors/spatialColors.js

@@ -18,4 +18,21 @@ export const spatialColors = {
     indigoTint: '#EEF2FF', // Soft background for callouts
     indigoBright: '#818CF8', // Highlights & glow on dark
     indigoHover: '#312E81', // Primary button hover
+    // Bright / vivid colours for SVG illustrations (OpenAI-blog style)
+    brightGlow: '#7C4DFF', // Electric violet — primary glow
+    brightPop: '#448AFF', // Neon blue — contrasting accent
+    brightSpark: '#E040FB', // Vivid magenta — sparkle / tertiary
+    brightBlaze: '#FF5252', // Neon red — warm accent
+    brightSurge: '#00B0FF', // Deep sky blue — cool accent
+    // Warm vivid colours — yellow & orange accents for SVG illustrations
+    brightFlame: '#FF9100', // Amber orange — warm cosmic accent
+    brightGold: '#FFEA00', // Electric yellow — star highlight
+    // Vivid brights for light backgrounds — punchy, saturated, OpenAI-blog vibrancy
+    brightLightGlow: '#7C4DFF', // Electric violet
+    brightLightPop: '#448AFF', // Neon blue
+    brightLightSpark: '#D500F9', // Vivid purple
+    brightLightBlaze: '#FF5252', // Neon red
+    brightLightSurge: '#00B0FF', // Vivid sky blue
+    brightLightFlame: '#FF9100', // Vivid amber orange
+    brightLightGold: '#FFC400', // Vivid gold
 };

package/lib/theme/index.d.ts

@@ -7,5 +7,9 @@ export * from './themes/spatialTheme';
 export * from './themes/lovelyTheme';
 export * from './themes/matrixTheme';
 export * from './themes-brand/spatialBrandTheme';
+export * from './themeRegistry';
 export * from './Palette';
 export * from './useSystemColorMode';
+export * from './useThemeStore';
+export * from './ThemeSwitcher';
+export * from './ThemedProvider';

package/lib/theme/index.js

@@ -11,5 +11,9 @@ export * from './themes/spatialTheme';
 export * from './themes/lovelyTheme';
 export * from './themes/matrixTheme';
 export * from './themes-brand/spatialBrandTheme';
+export * from './themeRegistry';
 export * from './Palette';
 export * from './useSystemColorMode';
+export * from './useThemeStore';
+export * from './ThemeSwitcher';
+export * from './ThemedProvider';

package/lib/theme/themeRegistry.d.ts

@@ -0,0 +1,105 @@
+import { type CSSProperties } from 'react';
+import { type ColorMode } from './DatalayerBrandThemeProvider';
+/** Available theme variants. */
+export type ThemeVariant = 'datalayer' | 'spatial' | 'lovely' | 'matrix';
+/** A pair of colours for a two-stop gradient. */
+export interface GradientPair {
+    /** Start colour (brighter / brand). */
+    from: string;
+    /** End colour (deeper / hover). */
+    to: string;
+}
+/**
+ * Vivid colour triplet for SVG illustrations.
+ *
+ * Inspired by OpenAI's blog — ultra-saturated, luminous hues designed
+ * to glow and pop against both light and dark backgrounds.
+ */
+export interface BrightPalette {
+    /** Primary vivid accent — the "star" glow colour. */
+    glow: string;
+    /** Optimal text colour for content rendered on a `glow` background. */
+    onGlow: string;
+    /** Contrasting vivid colour — analogous/complement. */
+    pop: string;
+    /** Third vivid colour — sparkle / small highlights. */
+    spark: string;
+    /** Vivid red / warm accent — energy, urgency, warmth. */
+    blaze: string;
+    /** Vivid blue / cool accent — depth, trust, electricity. */
+    surge: string;
+    /** Vivid orange — warm energy, fire, dynamism. */
+    flame: string;
+    /** Vivid yellow / gold — highlights, attention, optimism. */
+    gold: string;
+}
+/**
+ * Complete configuration for a theme, including the Primer theme object,
+ * display metadata, and CSS custom property overrides per color mode.
+ */
+export interface ThemeConfig {
+    /** Human-readable name for UI display. */
+    label: string;
+    /** Short description of the theme. */
+    description: string;
+    /** Brand color for the theme — used for colored swatch buttons. */
+    brandColor: string;
+    /** Recommended default color mode for this theme. */
+    defaultColorMode: ColorMode;
+    /** Primer theme object passed to `<ThemeProvider theme={…}>`. */
+    primerTheme: Record<string, any>;
+    /** Per-mode CSS-property overrides for `<DatalayerThemeProvider themeStyles={…}>`. */
+    themeStyles: {
+        light: CSSProperties;
+        dark: CSSProperties;
+    };
+    /**
+     * Per-mode gradient pair for card backgrounds, banners, and other
+     * decorative surfaces that need a themed two-colour gradient.
+     */
+    cardGradient: {
+        light: GradientPair;
+        dark: GradientPair;
+    };
+    /**
+     * Vivid colour triplet for SVG illustrations — ultra-saturated,
+     * luminous hues that glow and pop on dark backgrounds (OpenAI-blog style).
+     */
+    brightPalette: BrightPalette;
+    /**
+     * Deeper / richer bright palette for light backgrounds.
+     * Same hue families as `brightPalette` but with higher contrast on
+     * light surfaces so illustrations don't appear faded.
+     */
+    brightPaletteLight: BrightPalette;
+}
+export declare const themeConfigs: Record<ThemeVariant, ThemeConfig>;
+/** All available theme variants in display order. */
+export declare const themeVariants: ThemeVariant[];
+/** Look up a theme config by variant name. */
+export declare function getThemeConfig(variant: ThemeVariant): ThemeConfig;
+/**
+ * Resolve the card gradient for a given theme variant and colour mode.
+ * Falls back to `datalayer` / `light` when values are missing.
+ */
+export declare function getCardGradient(variant?: ThemeVariant, colorMode?: 'light' | 'dark' | 'auto'): GradientPair;
+/**
+ * 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 declare function getBrightPalette(variant?: ThemeVariant, colorMode?: 'light' | 'dark' | 'auto'): BrightPalette;
+/**
+ * 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 declare function getAvatarColors(variant?: ThemeVariant, colorMode?: 'light' | 'dark' | 'auto'): string[];