@datalayer/primer-addons 1.0.14 → 1.0.17

package/lib/components/logo/AI.d.ts

@@ -0,0 +1,17 @@
+import { type SVGProps } from 'react';
+import { type ThemeVariant } from '../../theme';
+export interface AIProps extends Omit<SVGProps<SVGSVGElement>, 'ref'> {
+    size?: number;
+    variant?: ThemeVariant;
+    colorMode?: 'light' | 'dark' | 'auto';
+    /** Colour of the "I" glyph. */
+    primaryColor?: string;
+    /** Colour of the "A" glyph. */
+    secondaryColor?: string;
+}
+/**
+ * AI glyph mark from the official brand source SVG.
+ * Defaults to themed logo colors and supports explicit overrides.
+ */
+export declare const AI: import("react").ForwardRefExoticComponent<AIProps & import("react").RefAttributes<SVGSVGElement>>;
+export default AI;

package/lib/components/logo/AI.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { forwardRef } from 'react';
+import { getLogoColors } from './DatalayerLogo';
+/**
+ * AI glyph mark from the official brand source SVG.
+ * Defaults to themed logo colors and supports explicit overrides.
+ */
+export const AI = forwardRef(function AI({ size = 24, variant = 'datalayer', colorMode = 'light', primaryColor, secondaryColor, ...svgProps }, ref) {
+    const themed = getLogoColors(variant, colorMode);
+    const resolvedPrimary = primaryColor ?? themed.primary;
+    const resolvedSecondary = secondaryColor ?? themed.textColor;
+    return (_jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", fill: "none", viewBox: "0 0 24 24", width: size, height: size, role: "img", "aria-label": "AI", ref: ref, ...svgProps, children: [_jsx("path", { d: "m13.788825 3.932 6.43325 16.136075h3.5279L17.316725 3.932H13.788825Z", fill: resolvedPrimary, strokeWidth: 0.25 }), _jsx("path", { d: "m6.325375 13.682775 2.20125 -5.67065 2.201275 5.67065H6.325375ZM6.68225 3.932 0.25 20.068075h3.596525l1.3155 -3.3886h6.729425l1.315275 3.3886h3.59655L10.371 3.932H6.68225Z", fill: resolvedSecondary, fillRule: "evenodd", clipRule: "evenodd", strokeWidth: 0.25 })] }));
+});
+export default AI;

package/lib/components/logo/DatalayerTextAI.d.ts

@@ -0,0 +1,25 @@
+import { type SVGProps } from 'react';
+import { type ThemeVariant } from '../../theme';
+export interface DatalayerTextAIProps extends Omit<SVGProps<SVGSVGElement>, 'ref'> {
+    size?: number;
+    scale?: number;
+    colorMode?: 'light' | 'dark' | 'auto';
+    variant?: ThemeVariant;
+    /** Colour for the "LAYER" part of the wordmark. */
+    primaryColor?: string;
+    /** Secondary accent colour used by the AI glyph. */
+    secondaryColor?: string;
+    /** Colour for the "DATA" part of the wordmark. */
+    textColor?: string;
+    textSizeMultiplier?: number;
+    aiPrimaryColor?: string;
+    aiSecondaryColor?: string;
+    /** Gap between wordmark and AI glyph in viewBox units. */
+    aiGap?: number;
+}
+/**
+ * Datalayer wordmark followed by AI glyph on one line.
+ * Both elements are aligned to the same 25-unit cap height.
+ */
+export declare const DatalayerTextAI: import("react").ForwardRefExoticComponent<DatalayerTextAIProps & import("react").RefAttributes<SVGSVGElement>>;
+export default DatalayerTextAI;

package/lib/components/logo/DatalayerTextAI.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { forwardRef } from 'react';
+import { AI } from './AI';
+import { DatalayerText } from './DatalayerText';
+import { getLogoColors } from './DatalayerLogo';
+const TEXT_LEFT_TRIM = 12;
+const TEXT_END_X = 136.672 - TEXT_LEFT_TRIM;
+const AI_SIZE = 24;
+const AI_VISIBLE_TOP = 3.932;
+const AI_VISIBLE_LEFT = 0.25;
+const AI_VISIBLE_HEIGHT = 16.136075;
+const AI_SCALE_TO_TEXT_HEIGHT = 25 / AI_VISIBLE_HEIGHT;
+const AI_RENDER_SIZE = AI_SIZE * AI_SCALE_TO_TEXT_HEIGHT;
+const AI_X_TRIM = AI_VISIBLE_LEFT * AI_SCALE_TO_TEXT_HEIGHT;
+const AI_Y_TRIM = AI_VISIBLE_TOP * AI_SCALE_TO_TEXT_HEIGHT;
+/**
+ * Datalayer wordmark followed by AI glyph on one line.
+ * Both elements are aligned to the same 25-unit cap height.
+ */
+export const DatalayerTextAI = forwardRef(function DatalayerTextAI({ size = 25, scale = 1, colorMode = 'light', variant = 'datalayer', primaryColor, secondaryColor, textColor, 
+// 2.380655 ~= 25 / (0.7 * 15.00187)
+textSizeMultiplier = 2.380655, aiPrimaryColor, aiSecondaryColor, aiGap = 6, ...svgProps }, ref) {
+    const themed = getLogoColors(variant, colorMode);
+    const layerColor = primaryColor ?? themed.primary;
+    const accentColor = secondaryColor ?? themed.secondary;
+    const dataTextColor = textColor ?? themed.textColor;
+    const resolvedAiPrimary = aiPrimaryColor ?? layerColor;
+    const resolvedAiSecondary = aiSecondaryColor ?? accentColor;
+    const viewBoxWidth = TEXT_END_X + aiGap + AI_RENDER_SIZE - AI_X_TRIM;
+    const baseHeight = size;
+    const baseWidth = (viewBoxWidth / 25) * size;
+    const height = baseHeight * scale;
+    const width = baseWidth * scale;
+    return (_jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: `0 0 ${viewBoxWidth} 25`, width: width, height: height, role: "img", "aria-label": "Datalayer AI", ref: ref, ...svgProps, children: [_jsx(DatalayerText, { primaryColor: layerColor, secondaryColor: dataTextColor, sizeMultiplier: textSizeMultiplier, x: -TEXT_LEFT_TRIM }), _jsx(AI, { size: AI_RENDER_SIZE, x: TEXT_END_X + aiGap - AI_X_TRIM, y: -AI_Y_TRIM, variant: variant, colorMode: colorMode, primaryColor: resolvedAiPrimary, secondaryColor: resolvedAiSecondary })] }));
+});
+export default DatalayerTextAI;

package/lib/components/logo/index.d.ts

@@ -1,3 +1,5 @@
+export * from './AI';
 export * from './DatalayerLogo';
 export * from './DatalayerLogoText';
 export * from './DatalayerText';
+export * from './DatalayerTextAI';

package/lib/components/logo/index.js

@@ -1,3 +1,5 @@
+export * from './AI';
 export * from './DatalayerLogo';
 export * from './DatalayerLogoText';
 export * from './DatalayerText';
+export * from './DatalayerTextAI';

package/lib/theme/DatalayerThemeProvider.d.ts

@@ -25,7 +25,7 @@ export interface IDatalayerThemeProviderProps extends Omit<ThemeProviderProps, '
      * When provided, these replace the built-in datalayer styles entirely.
      * The `baseStyles` prop is still merged on top.
      *
-     * Use the `buildThemeStyles` helper from `./themes/createThemeCSSVars`
+     * Use the `buildThemeStyles` helper from `./css/createThemeCSSVars`
      * to generate comprehensive overrides from a `ThemeColorDefs` pair.
      */
     themeStyles?: {

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

@@ -3,7 +3,6 @@ export { spatialColors } from './spatialColors';
 export { lovelyColors } from './lovelyColors';
 export { matrixColors } from './matrixColors';
 export { earthColors } from './earthColors';
-export { indicatorColors, defaultIndicatorColors, type IndicatorColors, } from './indicatorColors';
 import type { ThemeVariant } from '../themeRegistry';
 /**
  * Themed color palettes — maps each `ThemeVariant` to its corresponding

package/lib/theme/colors/index.js

@@ -7,7 +7,6 @@ export { spatialColors } from './spatialColors';
 export { lovelyColors } from './lovelyColors';
 export { matrixColors } from './matrixColors';
 export { earthColors } from './earthColors';
-export { indicatorColors, defaultIndicatorColors, } from './indicatorColors';
 import { datalayerColors } from './datalayerColors';
 import { spatialColors } from './spatialColors';
 import { lovelyColors } from './lovelyColors';

package/lib/theme/{themes → css}/createThemeCSSVars.js

@@ -174,6 +174,7 @@ export function colorDefsToCSS(defs) {
         /* ── Datalayer brand tokens (consumed by custom components) ─── */
         '--brand-color-canvas-default': defs.canvas.default,
         '--brand-color-text-default': defs.fg.default,
+        '--datalayer-icon-fg': defs.accent.fg,
     };
 }
 /**

package/lib/theme/index.d.ts

@@ -1,5 +1,6 @@
 export * from './colors';
-export * from './themes/createThemeCSSVars';
+export * from './indicators';
+export * from './css/createThemeCSSVars';
 export * from './themes/datalayerTheme';
 export * from './DatalayerThemeProvider';
 export * from './DatalayerBrandThemeProvider';

package/lib/theme/index.js

@@ -3,7 +3,8 @@
  * Distributed under the terms of the Modified BSD License.
  */
 export * from './colors';
-export * from './themes/createThemeCSSVars';
+export * from './indicators';
+export * from './css/createThemeCSSVars';
 export * from './themes/datalayerTheme';
 export * from './DatalayerThemeProvider';
 export * from './DatalayerBrandThemeProvider';

package/lib/theme/indicators/index.d.ts

@@ -0,0 +1 @@
+export { indicatorColors, defaultIndicatorColors, type IndicatorColors, } from './indicatorColors';

package/lib/theme/indicators/index.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export { indicatorColors, defaultIndicatorColors, } from './indicatorColors';

package/lib/theme/palettes/{SvgPalette.d.ts → ColorPalette.d.ts}

@@ -1,4 +1,5 @@
-export interface SvgPalette {
+import { type ThemeVariant } from '../themeRegistry';
+export interface ColorPalette {
     bg: string;
     bgPanel: string;
     bgAlt: string;
@@ -16,14 +17,15 @@ export interface SvgPalette {
     textMuted: string;
     isLight: boolean;
 }
-export declare function useSvgPalette(): SvgPalette;
-/** @deprecated Use `useSvgPalette` instead. */
-export declare const useBlogSvgPalette: typeof useSvgPalette;
+export declare function getColorPalette(theme?: ThemeVariant, colorMode?: 'light' | 'dark' | 'auto'): ColorPalette;
+export declare function useColorPalette(): ColorPalette;
+/** @deprecated Use `useColorPalette` instead. */
+export declare const useBlogColorPalette: typeof useColorPalette;
 export declare const LightBoostFilter: () => import("react/jsx-runtime").JSX.Element;
 export declare const SharedDefs: ({ p }: {
-    p: SvgPalette;
+    p: ColorPalette;
 }) => import("react/jsx-runtime").JSX.Element;
-export declare const svgLightFilter: (p: SvgPalette) => "url(#svgLightBoost)" | undefined;
+export declare const svgLightFilter: (p: ColorPalette) => "url(#svgLightBoost)" | undefined;
 export declare const BgGrid: ({ w, h }: {
     w?: number;
     h?: number;

package/lib/theme/palettes/{SvgPalette.js → ColorPalette.js}

@@ -5,8 +5,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Datalayer License
  */
 /**
- * Shared SVG palette types, theme-aware colour resolution, and reusable
- * gradient / grid definitions consumed by SVG illustrations.
+ * Shared palette types, theme-aware colour resolution, and reusable
+ * gradient / grid definitions.
  */
 import { datalayerColors, spatialColors, lovelyColors, matrixColors, earthColors, } from '../colors';
 import { getBrightPalette, } from '../themeRegistry';
@@ -213,8 +213,7 @@ const palettes = {
         },
     },
 };
-export function useSvgPalette() {
-    const { colorMode, theme } = useThemeStore();
+export function getColorPalette(theme = 'datalayer', colorMode = 'auto') {
     const mode = colorMode === 'auto'
         ? typeof window !== 'undefined' &&
             window.matchMedia('(prefers-color-scheme: dark)').matches
@@ -223,8 +222,12 @@ export function useSvgPalette() {
         : colorMode;
     return palettes[theme]?.[mode] ?? palettes.datalayer.dark;
 }
-/** @deprecated Use `useSvgPalette` instead. */
-export const useBlogSvgPalette = useSvgPalette;
+export function useColorPalette() {
+    const { colorMode, theme } = useThemeStore();
+    return getColorPalette(theme, colorMode);
+}
+/** @deprecated Use `useColorPalette` instead. */
+export const useBlogColorPalette = useColorPalette;
 export const LightBoostFilter = () => (_jsx("filter", { id: "svgLightBoost", colorInterpolationFilters: "sRGB", children: _jsx("feComponentTransfer", { children: _jsx("feFuncA", { type: "gamma", exponent: "0.45", amplitude: "1", offset: "0" }) }) }));
 export const SharedDefs = ({ p }) => (_jsxs("defs", { children: [_jsx(LightBoostFilter, {}), _jsxs("linearGradient", { id: "fadeGreen", x1: "0", y1: "0", x2: "1", y2: "1", children: [_jsx("stop", { offset: "0%", stopColor: p.primary, stopOpacity: "0.7" }), _jsx("stop", { offset: "100%", stopColor: p.secondary, stopOpacity: "0" })] }), _jsxs("linearGradient", { id: "fadeGreenH", x1: "0", y1: "0", x2: "1", y2: "0", children: [_jsx("stop", { offset: "0%", stopColor: p.primary, stopOpacity: "0.5" }), _jsx("stop", { offset: "50%", stopColor: p.secondary, stopOpacity: "0.25" }), _jsx("stop", { offset: "100%", stopColor: p.secondary, stopOpacity: "0" })] }), _jsxs("linearGradient", { id: "fadeBright", x1: "0", y1: "0", x2: "0", y2: "1", children: [_jsx("stop", { offset: "0%", stopColor: p.accent, stopOpacity: "0.4" }), _jsx("stop", { offset: "100%", stopColor: p.accent, stopOpacity: "0" })] }), _jsxs("linearGradient", { id: "fadeVivid", x1: "0", y1: "0", x2: "1", y2: "1", children: [_jsx("stop", { offset: "0%", stopColor: p.glow, stopOpacity: "0.8" }), _jsx("stop", { offset: "50%", stopColor: p.pop, stopOpacity: "0.5" }), _jsx("stop", { offset: "100%", stopColor: p.spark, stopOpacity: "0" })] }), _jsxs("linearGradient", { id: "fadeVividH", x1: "0", y1: "0", x2: "1", y2: "0", children: [_jsx("stop", { offset: "0%", stopColor: p.glow, stopOpacity: "0.6" }), _jsx("stop", { offset: "100%", stopColor: p.pop, stopOpacity: "0.15" })] }), _jsxs("radialGradient", { id: "glowGreen", children: [_jsx("stop", { offset: "0%", stopColor: p.primary, stopOpacity: "0.6" }), _jsx("stop", { offset: "100%", stopColor: p.primary, stopOpacity: "0" })] }), _jsxs("radialGradient", { id: "glowBright", children: [_jsx("stop", { offset: "0%", stopColor: p.accent, stopOpacity: "0.45" }), _jsx("stop", { offset: "100%", stopColor: p.accent, stopOpacity: "0" })] }), _jsxs("radialGradient", { id: "glowVivid", children: [_jsx("stop", { offset: "0%", stopColor: p.glow, stopOpacity: "0.7" }), _jsx("stop", { offset: "60%", stopColor: p.glow, stopOpacity: "0.2" }), _jsx("stop", { offset: "100%", stopColor: p.glow, stopOpacity: "0" })] }), _jsxs("radialGradient", { id: "glowPop", children: [_jsx("stop", { offset: "0%", stopColor: p.pop, stopOpacity: "0.65" }), _jsx("stop", { offset: "60%", stopColor: p.pop, stopOpacity: "0.15" }), _jsx("stop", { offset: "100%", stopColor: p.pop, stopOpacity: "0" })] }), _jsxs("radialGradient", { id: "glowSpark", children: [_jsx("stop", { offset: "0%", stopColor: p.spark, stopOpacity: "0.6" }), _jsx("stop", { offset: "60%", stopColor: p.spark, stopOpacity: "0.15" }), _jsx("stop", { offset: "100%", stopColor: p.spark, stopOpacity: "0" })] }), _jsxs("radialGradient", { id: "glowBlaze", children: [_jsx("stop", { offset: "0%", stopColor: p.blaze, stopOpacity: "0.7" }), _jsx("stop", { offset: "55%", stopColor: p.blaze, stopOpacity: "0.2" }), _jsx("stop", { offset: "100%", stopColor: p.blaze, stopOpacity: "0" })] }), _jsxs("radialGradient", { id: "glowSurge", children: [_jsx("stop", { offset: "0%", stopColor: p.surge, stopOpacity: "0.7" }), _jsx("stop", { offset: "55%", stopColor: p.surge, stopOpacity: "0.2" }), _jsx("stop", { offset: "100%", stopColor: p.surge, stopOpacity: "0" })] }), _jsxs("radialGradient", { id: "glowFlame", children: [_jsx("stop", { offset: "0%", stopColor: p.flame, stopOpacity: "0.7" }), _jsx("stop", { offset: "55%", stopColor: p.flame, stopOpacity: "0.2" }), _jsx("stop", { offset: "100%", stopColor: p.flame, stopOpacity: "0" })] }), _jsxs("radialGradient", { id: "glowGold", children: [_jsx("stop", { offset: "0%", stopColor: p.gold, stopOpacity: "0.7" }), _jsx("stop", { offset: "55%", stopColor: p.gold, stopOpacity: "0.2" }), _jsx("stop", { offset: "100%", stopColor: p.gold, stopOpacity: "0" })] }), _jsxs("linearGradient", { id: "fadeBlazeToSurge", x1: "0", y1: "0", x2: "1", y2: "0", children: [_jsx("stop", { offset: "0%", stopColor: p.blaze, stopOpacity: "0.7" }), _jsx("stop", { offset: "50%", stopColor: p.spark, stopOpacity: "0.3" }), _jsx("stop", { offset: "100%", stopColor: p.surge, stopOpacity: "0.7" })] }), _jsx("pattern", { id: "gridDots", width: "24", height: "24", patternUnits: "userSpaceOnUse", children: _jsx("circle", { cx: "1", cy: "1", r: "0.7", fill: p.primary, opacity: "0.06" }) })] }));
 export const svgLightFilter = (p) => p.isLight ? 'url(#svgLightBoost)' : undefined;

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

@@ -1 +1 @@
-export * from './SvgPalette';
+export * from './ColorPalette';

package/lib/theme/palettes/index.js

@@ -3,4 +3,4 @@
  *
  * Datalayer License
  */
-export * from './SvgPalette';
+export * from './ColorPalette';

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

@@ -1087,5 +1087,5 @@ export declare const datalayerTheme: {
     }>;
 };
 /** Comprehensive Primer CSS-variable overrides for light & dark mode. */
-export declare const datalayerThemeStyles: import("./createThemeCSSVars").ThemeStyles;
+export declare const datalayerThemeStyles: import("../css/createThemeCSSVars").ThemeStyles;
 export default datalayerTheme;

package/lib/theme/themes/datalayerTheme.js

@@ -11,7 +11,7 @@
  */
 import { theme as primerTheme } from '@primer/react';
 import { datalayerColors } from '../colors';
-import { buildThemeStyles } from './createThemeCSSVars';
+import { buildThemeStyles } from '../css/createThemeCSSVars';
 /* ── Light-mode colour definitions ───────────────────────────────────── */
 const datalayerLight = {
     canvas: {

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

@@ -1087,5 +1087,5 @@ export declare const earthTheme: {
     }>;
 };
 /** Comprehensive Primer CSS-variable overrides for light & dark mode. */
-export declare const earthThemeStyles: import("./createThemeCSSVars").ThemeStyles;
+export declare const earthThemeStyles: import("../css/createThemeCSSVars").ThemeStyles;
 export default earthTheme;

package/lib/theme/themes/earthTheme.js

@@ -11,7 +11,7 @@
  */
 import { theme as primerTheme } from '@primer/react';
 import { earthColors } from '../colors/earthColors';
-import { buildThemeStyles } from './createThemeCSSVars';
+import { buildThemeStyles } from '../css/createThemeCSSVars';
 /* ── Light-mode colour definitions ───────────────────────────────────── */
 const earthLight = {
     canvas: {

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

@@ -1087,5 +1087,5 @@ export declare const lovelyTheme: {
     }>;
 };
 /** Comprehensive Primer CSS-variable overrides for light & dark mode. */
-export declare const lovelyThemeStyles: import("./createThemeCSSVars").ThemeStyles;
+export declare const lovelyThemeStyles: import("../css/createThemeCSSVars").ThemeStyles;
 export default lovelyTheme;

package/lib/theme/themes/lovelyTheme.js

@@ -10,7 +10,7 @@
  */
 import { theme as primerTheme } from '@primer/react';
 import { lovelyColors } from '../colors';
-import { buildThemeStyles } from './createThemeCSSVars';
+import { buildThemeStyles } from '../css/createThemeCSSVars';
 /* ── Light-mode colour definitions ───────────────────────────────────── */
 const lovelyLight = {
     canvas: {

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

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

package/lib/theme/themes/matrixTheme.js

@@ -10,7 +10,7 @@
  */
 import { theme as primerTheme } from '@primer/react';
 import { matrixColors } from '../colors';
-import { buildThemeStyles } from './createThemeCSSVars';
+import { buildThemeStyles } from '../css/createThemeCSSVars';
 /* ── Light-mode colour definitions ───────────────────────────────────── */
 const matrixLight = {
     canvas: {

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

@@ -1087,5 +1087,5 @@ export declare const spatialTheme: {
     }>;
 };
 /** Comprehensive Primer CSS-variable overrides for light & dark mode. */
-export declare const spatialThemeStyles: import("./createThemeCSSVars").ThemeStyles;
+export declare const spatialThemeStyles: import("../css/createThemeCSSVars").ThemeStyles;
 export default spatialTheme;

package/lib/theme/themes/spatialTheme.js

@@ -10,7 +10,7 @@
  */
 import { theme as primerTheme } from '@primer/react';
 import { spatialColors } from '../colors';
-import { buildThemeStyles } from './createThemeCSSVars';
+import { buildThemeStyles } from '../css/createThemeCSSVars';
 /* ── Light-mode colour definitions ───────────────────────────────────── */
 const spatialLight = {
     canvas: {

package/lib/theme/useThemeStore.d.ts

@@ -1,14 +1,32 @@
 /**
  * Zustand store for theme preferences – reusable across Datalayer apps.
  *
- * Persists `colorMode` and `theme` to localStorage. The store key is
+ * Persists `colorMode` and `theme` to localStorage.  The store key is
  * configurable so that different apps can maintain independent prefs.
  *
+ * ## Variants
+ *
+ * A *variant* is a named set of theme/colorMode defaults (e.g. `anonymous`,
+ * `authenticated`).  When a variant is active, `setTheme`, `setColorMode`,
+ * and `toggleColorMode` automatically update the active variant's stored
+ * preferences.  Calling `setVariant(name)` switches theme/colorMode to
+ * that variant's prefs in one step.
+ *
+ * Variants can be registered at build time (via defaults) or at runtime
+ * (via `registerVariants`).  `registerVariants` only sets defaults for
+ * variants that don't already exist, preserving user-customised prefs
+ * across page loads.
+ *
  * @module theme/useThemeStore
  */
 import { type StoreApi, type UseBoundStore } from 'zustand';
 import type { ThemeVariant } from './themeRegistry';
 import type { ColorMode } from './DatalayerBrandThemeProvider';
+/** Per-variant theme + colorMode preferences. */
+export type VariantDefaults = Record<string, {
+    theme: ThemeVariant;
+    colorMode: ColorMode;
+}>;
 export interface ThemeState {
     /** Current color mode (light, dark, or auto = follow OS). */
     colorMode: ColorMode;
@@ -24,6 +42,21 @@ export interface ThemeState {
      *   color mode to the theme's configured default.
      */
     setTheme: (theme: ThemeVariant, applyDefaultColorMode?: boolean) => void;
+    /** The currently active variant (`null` when no variant is active). */
+    activeVariant: string | null;
+    /** Per-variant stored preferences. */
+    variants: VariantDefaults;
+    /**
+     * Register variant definitions.  Only sets defaults for variants that
+     * don't already exist — existing (possibly user-customised) variants
+     * are preserved.
+     */
+    registerVariants: (defs: VariantDefaults) => void;
+    /**
+     * Activate a named variant.  Sets `theme` / `colorMode` to the
+     * variant's stored prefs in one step.
+     */
+    setVariant: (variant: string) => void;
 }
 /**
  * Create a theme store bound to a specific localStorage key.
@@ -34,11 +67,12 @@ export interface ThemeState {
  * ```
  *
  * @param storageKey  localStorage key for persistence (e.g. `'otel-example-theme'`)
- * @param defaults    Optional overrides for the initial colorMode / theme
+ * @param defaults    Optional overrides for the initial colorMode / theme / variants
  */
 export declare function createThemeStore(storageKey: string, defaults?: {
     colorMode?: ColorMode;
     theme?: ThemeVariant;
+    variants?: VariantDefaults;
 }): UseBoundStore<StoreApi<ThemeState>>;
 /**
  * Default theme store for Datalayer applications.

package/lib/theme/useThemeStore.js

@@ -5,14 +5,33 @@
 /**
  * Zustand store for theme preferences – reusable across Datalayer apps.
  *
- * Persists `colorMode` and `theme` to localStorage. The store key is
+ * Persists `colorMode` and `theme` to localStorage.  The store key is
  * configurable so that different apps can maintain independent prefs.
  *
+ * ## Variants
+ *
+ * A *variant* is a named set of theme/colorMode defaults (e.g. `anonymous`,
+ * `authenticated`).  When a variant is active, `setTheme`, `setColorMode`,
+ * and `toggleColorMode` automatically update the active variant's stored
+ * preferences.  Calling `setVariant(name)` switches theme/colorMode to
+ * that variant's prefs in one step.
+ *
+ * Variants can be registered at build time (via defaults) or at runtime
+ * (via `registerVariants`).  `registerVariants` only sets defaults for
+ * variants that don't already exist, preserving user-customised prefs
+ * across page loads.
+ *
  * @module theme/useThemeStore
  */
 import { create } from 'zustand';
 import { persist, createJSONStorage } from 'zustand/middleware';
 import { themeConfigs } from './themeRegistry';
+/* ── Helpers ─────────────────────────────────────────────────────── */
+const colorModeCycle = {
+    light: 'dark',
+    dark: 'auto',
+    auto: 'light',
+};
 /**
  * Create a theme store bound to a specific localStorage key.
  *
@@ -22,35 +41,118 @@ import { themeConfigs } from './themeRegistry';
  * ```
  *
  * @param storageKey  localStorage key for persistence (e.g. `'otel-example-theme'`)
- * @param defaults    Optional overrides for the initial colorMode / theme
+ * @param defaults    Optional overrides for the initial colorMode / theme / variants
  */
 export function createThemeStore(storageKey, defaults) {
     return create()(persist(set => ({
         colorMode: defaults?.colorMode ?? 'dark',
         theme: defaults?.theme ?? 'matrix',
+        /* ── variant state ──────────────────────────────────── */
+        activeVariant: null,
+        variants: defaults?.variants ?? {},
+        /* ── actions ────────────────────────────────────────── */
         toggleColorMode: () => set(state => {
-            const cycle = {
-                light: 'dark',
-                dark: 'auto',
-                auto: 'light',
-            };
-            return { colorMode: cycle[state.colorMode] };
+            const next = colorModeCycle[state.colorMode];
+            if (state.activeVariant && state.variants[state.activeVariant]) {
+                return {
+                    colorMode: next,
+                    variants: {
+                        ...state.variants,
+                        [state.activeVariant]: { ...state.variants[state.activeVariant], colorMode: next },
+                    },
+                };
+            }
+            return { colorMode: next };
+        }),
+        setColorMode: (mode) => set(state => {
+            if (state.activeVariant && state.variants[state.activeVariant]) {
+                return {
+                    colorMode: mode,
+                    variants: {
+                        ...state.variants,
+                        [state.activeVariant]: { ...state.variants[state.activeVariant], colorMode: mode },
+                    },
+                };
+            }
+            return { colorMode: mode };
         }),
-        setColorMode: (mode) => set({ colorMode: mode }),
-        setTheme: (theme, applyDefaultColorMode = true) => set(() => {
-            const next = { theme };
-            if (applyDefaultColorMode) {
-                next.colorMode = themeConfigs[theme].defaultColorMode;
+        setTheme: (theme, applyDefaultColorMode = true) => set(state => {
+            const nextColorMode = applyDefaultColorMode
+                ? themeConfigs[theme].defaultColorMode
+                : state.colorMode;
+            if (state.activeVariant && state.variants[state.activeVariant]) {
+                return {
+                    theme,
+                    colorMode: nextColorMode,
+                    variants: {
+                        ...state.variants,
+                        [state.activeVariant]: { theme, colorMode: nextColorMode },
+                    },
+                };
             }
-            return next;
+            return { theme, colorMode: nextColorMode };
+        }),
+        registerVariants: (defs) => set(state => {
+            const merged = { ...state.variants };
+            for (const [key, val] of Object.entries(defs)) {
+                if (!merged[key]) {
+                    merged[key] = val;
+                }
+            }
+            return { variants: merged };
+        }),
+        setVariant: (variant) => set(state => {
+            const v = state.variants[variant];
+            if (!v) {
+                return { activeVariant: variant };
+            }
+            return {
+                activeVariant: variant,
+                theme: v.theme,
+                colorMode: v.colorMode,
+            };
         }),
     }), {
         name: storageKey,
+        version: 2,
         storage: createJSONStorage(() => localStorage),
         partialize: state => ({
             colorMode: state.colorMode,
             theme: state.theme,
+            activeVariant: state.activeVariant,
+            variants: state.variants,
         }),
+        /**
+         * Migration: when `version` is missing or differs from the current
+         * value the persisted state is discarded and the store starts fresh
+         * from code-defined defaults.
+         */
+        migrate: () => ({}),
+        /**
+         * Deep-merge variants during hydration so that:
+         *  - Code-defined variants (from defaults or registerVariants) are
+         *    always present even when localStorage has an older snapshot.
+         *  - Per-variant prefs that the user customised (persisted) win over
+         *    code defaults for each variant key.
+         */
+        merge: (persisted, current) => {
+            const p = (persisted ?? {});
+            // Build merged variants: start from code-defined, then overlay
+            // any persisted variant whose prefs differ (user customisations).
+            const mergedVariants = { ...current.variants };
+            if (p.variants) {
+                for (const [key, val] of Object.entries(p.variants)) {
+                    if (val && typeof val === 'object' && 'theme' in val) {
+                        mergedVariants[key] = val;
+                    }
+                }
+            }
+            return {
+                ...current,
+                ...p,
+                variants: mergedVariants,
+            };
+        },
     }));
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalayer/primer-addons",
-  "version": "1.0.14",
+  "version": "1.0.17",
   "license": "BSD-3-Clause",
   "scripts": {
     "build": "tsc && vite build",