matterviz 0.4.1 → 0.4.3

package/dist/theme/embedded.js

@@ -0,0 +1,206 @@
+// Theme Detection for Embedded MatterViz Views
+import { luminance } from '../colors';
+import { COLOR_THEMES } from './';
+// oxlint-disable-next-line import/no-unassigned-import -- registers built-in themes
+import './themes.mjs';
+// Per-element watcher (callback + last-seen theme for dedup + the element's own
+// Shadow-host observer). Widgets can mount in different roots with different
+// themes, so each is tracked and torn down independently.
+const element_watchers = new Map();
+// Shared document observer + media-query listener, created with the first widget
+// and disconnected with the last (counted via element_watchers.size).
+let doc_observer = null;
+let media_query_listener = null;
+// Pending debounce timer shared across all mutation sources; cleared before each
+// reschedule so bursts of mutations collapse into a single notify_theme_change.
+let notify_timer = null;
+const observe_opts = { attributes: true, attributeFilter: [`class`, `data-theme`] };
+export function detect_parent_theme(target_element) {
+    try {
+        // Check Shadow DOM context
+        if (target_element) {
+            const root_node = target_element.getRootNode();
+            if (root_node !== document && root_node instanceof ShadowRoot) {
+                const theme = check_element_hierarchy(root_node.host);
+                if (theme)
+                    return theme;
+            }
+        }
+        // Check document theme indicators
+        const theme_classes = [
+            `dark-theme`,
+            `light-theme`,
+            `vscode-dark`,
+            `vscode-light`,
+            `dark`,
+            `light`,
+        ];
+        for (const cls of theme_classes) {
+            if (document.body.classList.contains(cls)) {
+                return cls.includes(`dark`) ? `dark` : `light`;
+            }
+        }
+        // System preference
+        if (globalThis.matchMedia) {
+            if (globalThis.matchMedia(`(prefers-color-scheme: dark)`).matches)
+                return `dark`;
+            if (globalThis.matchMedia(`(prefers-color-scheme: light)`).matches)
+                return `light`;
+        }
+        // Jupyter Lab theme API
+        const jupyter_theme = globalThis.jupyterlab?.application?.shell?.dataset?.theme;
+        if (jupyter_theme) {
+            return jupyter_theme.includes(`dark`) ? `dark` : `light`;
+        }
+        // Jupyter CSS custom properties
+        const jp_bg = getComputedStyle(document.documentElement).getPropertyValue(`--jp-layout-color0`);
+        if (jp_bg) {
+            const is_dark = is_dark_color(jp_bg);
+            if (is_dark !== null)
+                return is_dark ? `dark` : `light`;
+        }
+        // Analyze background colors
+        const backgrounds = [
+            getComputedStyle(document.body).backgroundColor,
+            getComputedStyle(document.documentElement).backgroundColor,
+        ];
+        for (const bg of backgrounds) {
+            const is_dark = is_dark_color(bg);
+            if (is_dark !== null)
+                return is_dark ? `dark` : `light`;
+        }
+        return `light`;
+    }
+    catch (error) {
+        console.warn(`Theme detection failed, defaulting to light:`, error);
+        return `light`;
+    }
+}
+function check_element_hierarchy(element) {
+    let current_element = element;
+    while (current_element) {
+        // Check classes
+        const class_list = current_element.classList;
+        if (class_list.contains(`dark-theme`) ||
+            class_list.contains(`vscode-dark`) ||
+            class_list.contains(`dark`))
+            return `dark`;
+        if (class_list.contains(`light-theme`) ||
+            class_list.contains(`vscode-light`) ||
+            class_list.contains(`light`))
+            return `light`;
+        // Check data attributes
+        const data_theme = current_element.getAttribute(`data-theme`);
+        if (data_theme === `dark`)
+            return `dark`;
+        if (data_theme === `light`)
+            return `light`;
+        // Check computed styles
+        const computed_style = getComputedStyle(current_element);
+        const bg_color = computed_style.backgroundColor;
+        const text_color = computed_style.color;
+        const is_dark = is_dark_color(bg_color);
+        if (is_dark !== null)
+            return is_dark ? `dark` : `light`;
+        const text_is_dark = is_dark_color(text_color);
+        if (text_is_dark !== null)
+            return text_is_dark ? `light` : `dark`;
+        current_element = current_element.parentElement;
+    }
+    return null;
+}
+function is_dark_color(color) {
+    if (!color || [`transparent`, `rgba(0, 0, 0, 0)`, `initial`, `inherit`].includes(color)) {
+        return null;
+    }
+    return luminance(color) < 0.5;
+}
+function notify_theme_change() {
+    notify_timer = null;
+    // Re-detect every element's theme; notify only those whose theme changed.
+    for (const [element, watcher] of element_watchers) {
+        const new_theme = detect_parent_theme(element);
+        if (new_theme !== watcher.theme) {
+            watcher.theme = new_theme;
+            watcher.callback(new_theme);
+        }
+    }
+}
+const schedule_notify = () => {
+    // Debounce: cancel any pending notify so only the latest mutation burst fires.
+    if (notify_timer)
+        clearTimeout(notify_timer);
+    notify_timer = setTimeout(notify_theme_change, 10);
+};
+function on_dom_mutation(mutations) {
+    if (mutations.some((mut) => mut.type === `attributes` &&
+        (mut.attributeName === `class` || mut.attributeName === `data-theme`)))
+        schedule_notify();
+}
+// Register a widget element + its theme-change callback. Returns a disposer that
+// removes this element's subscriber and Shadow-host observer and, once the last
+// widget is gone, disconnects the shared document/media-query watchers (fixing a
+// leak where observers stayed attached for the page's lifetime).
+export function watch_theme(target_element, callback) {
+    try {
+        // Shared document-level + system-preference watchers (created once for all).
+        if (!doc_observer) {
+            doc_observer = new MutationObserver(on_dom_mutation);
+            doc_observer.observe(document.documentElement, observe_opts);
+            if (document.body)
+                doc_observer.observe(document.body, observe_opts);
+        }
+        if (!media_query_listener && globalThis.matchMedia) {
+            media_query_listener = globalThis.matchMedia(`(prefers-color-scheme: dark)`);
+            media_query_listener.addEventListener(`change`, schedule_notify);
+        }
+        // Shadow DOM hosts (e.g. marimo cells) carry the theme class/data-theme but
+        // aren't reachable from document, so observe each widget's host individually
+        // (not just the first widget's).
+        let shadow_observer = null;
+        const root_node = target_element.getRootNode();
+        if (root_node instanceof ShadowRoot) {
+            shadow_observer = new MutationObserver(on_dom_mutation);
+            shadow_observer.observe(root_node.host, observe_opts);
+        }
+        element_watchers.set(target_element, {
+            callback,
+            theme: detect_parent_theme(target_element),
+            shadow_observer,
+        });
+    }
+    catch (error) {
+        console.warn(`Failed to setup theme watchers:`, error);
+    }
+    return () => {
+        element_watchers.get(target_element)?.shadow_observer?.disconnect();
+        element_watchers.delete(target_element);
+        if (element_watchers.size > 0)
+            return; // other widgets still need shared watchers
+        if (notify_timer) {
+            clearTimeout(notify_timer); // drop a pending notify; no widgets left to update
+            notify_timer = null;
+        }
+        doc_observer?.disconnect();
+        doc_observer = null;
+        media_query_listener?.removeEventListener(`change`, schedule_notify);
+        media_query_listener = null;
+    };
+}
+export function get_theme_css(theme_type, is_shadow_dom = false) {
+    const theme_name = COLOR_THEMES[theme_type];
+    // Get theme data (matterviz/themes.js sets this)
+    const theme = globalThis.MATTERVIZ_THEMES?.[theme_name];
+    const css_map = globalThis.MATTERVIZ_CSS_MAP;
+    if (!theme || !css_map) {
+        console.warn(`Theme data not available, skipping theme application`);
+        return ``;
+    }
+    const css_vars = Object.entries(theme)
+        .map(([key, value]) => (css_map[key] ? `${css_map[key]}: ${value};` : ``))
+        .filter(Boolean)
+        .join(`\n\t`);
+    // Use :host for Shadow DOM, :root for regular DOM
+    const selector = is_shadow_dom ? `:host` : `:root`;
+    return `${selector} {\n\t${css_vars}\n}`;
+}

package/dist/theme/index.d.ts

@@ -1,3 +1,8 @@
+declare global {
+    var MATTERVIZ_THEMES: Record<string, Record<string, string>> | undefined;
+    var MATTERVIZ_CSS_MAP: Record<string, string> | undefined;
+}
+export declare const THEME_STORAGE_KEY = "matterviz-theme";
 export declare const COLOR_THEMES: {
     readonly light: "light";
     readonly dark: "dark";
@@ -22,8 +27,3 @@ export declare const get_theme_preference: () => ThemeMode;
 export declare const save_theme_preference: (mode: ThemeMode) => void;
 export declare const get_system_mode: () => ThemeType;
 export declare const apply_theme_to_dom: (mode: ThemeMode) => void;
-export declare const light_theme: () => any;
-export declare const dark_theme: () => any;
-export declare const white_theme: () => any;
-export declare const black_theme: () => any;
-export declare const get_theme_by_name: (name: ThemeName) => any;

package/dist/theme/index.js

@@ -1,6 +1,6 @@
 // Theme System for MatterViz
 const is_browser = typeof window !== `undefined`;
-const storage_key = `matterviz-theme`;
+export const THEME_STORAGE_KEY = `matterviz-theme`;
 // Core theme constants
 export const COLOR_THEMES = {
     light: `light`,
@@ -32,7 +32,7 @@ export const get_theme_preference = () => {
     if (!is_browser)
         return AUTO_THEME;
     try {
-        const saved = localStorage[storage_key];
+        const saved = localStorage[THEME_STORAGE_KEY];
         return is_valid_theme_mode(saved ?? ``) ? saved : AUTO_THEME;
     }
     catch {
@@ -41,13 +41,13 @@ export const get_theme_preference = () => {
 };
 export const save_theme_preference = (mode) => {
     try {
-        localStorage[storage_key] = mode;
+        localStorage[THEME_STORAGE_KEY] = mode;
     }
     catch {
         // Silently fail if localStorage is unavailable
     }
 };
-export const get_system_mode = () => is_browser && matchMedia(`(prefers-color-scheme: dark)`).matches
+export const get_system_mode = () => is_browser && globalThis.matchMedia?.(`(prefers-color-scheme: dark)`)?.matches
     ? COLOR_THEMES.dark
     : COLOR_THEMES.light;
 export const apply_theme_to_dom = (mode) => {
@@ -68,12 +68,5 @@ export const apply_theme_to_dom = (mode) => {
     });
     root.setAttribute(`data-theme`, resolved);
     // Set color-scheme to ensure form elements respect the theme
-    const color_scheme = THEME_TYPE[resolved];
-    root.style.setProperty(`color-scheme`, color_scheme);
+    root.style.setProperty(`color-scheme`, THEME_TYPE[resolved]);
 };
-// Theme getters
-export const light_theme = () => globalThis.MATTERVIZ_THEMES?.[COLOR_THEMES.light] ?? {};
-export const dark_theme = () => globalThis.MATTERVIZ_THEMES?.[COLOR_THEMES.dark] ?? {};
-export const white_theme = () => globalThis.MATTERVIZ_THEMES?.[COLOR_THEMES.white] ?? {};
-export const black_theme = () => globalThis.MATTERVIZ_THEMES?.[COLOR_THEMES.black] ?? {};
-export const get_theme_by_name = (name) => globalThis.MATTERVIZ_THEMES?.[name] ?? {};

package/dist/theme/themes.mjs

@@ -2,23 +2,21 @@
 // Note: This file needs to be symlinked into static/ to be importable by app.html before initial page render to prevent flashing colors before client-side JS kicks in. It also needs to be in src/lib so it gets packaged and shipped to NPM for use by the anywidgets in pymatviz.
 // Can't use exports in this file as would then require type="module" in app.html to import which would defer until after HTML is ready (module files are always deferred).
 
-// Text colors
-const txt_light = `#374151` // Dark gray
-const txt_dark = `#eee` // Light gray
-const txt_white = `#000000` // Black
-const txt_black = `#f5f5f5` // Off-white
-
-// Page backgrounds
-const page_bg_light = `#f1f3f5` // Light gray
-const page_bg_dark = `#18171c` // Very dark blue
-const page_bg_white = `#ffffff` // Pure white
-const page_bg_black = `#000000` // Pure black
+// Text colors (also GitHub corner bg + plot legend item color)
+const txt = {
+  light: `#374151`, // Dark gray
+  dark: `#eee`, // Light gray
+  white: `#000000`, // Black
+  black: `#f5f5f5`, // Off-white
+}
 
-// Borders
-const border_light = `#d1d5db` // Gray border
-const border_dark = `#404040` // Dark gray border
-const border_white = `#d1d5db` // Light border
-const border_black = `#404040` // Dark border
+// Page backgrounds (also fullscreen structure bg + GitHub corner fg)
+const page_bg = {
+  light: `#f1f3f5`, // Light gray
+  dark: `#18171c`, // Very dark blue
+  white: `#ffffff`, // Pure white
+  black: `#000000`, // Pure black
+}
 
 // Accents
 const acc_light = `#4f46e5` // Indigo
@@ -26,7 +24,7 @@ const acc_dark = `cornflowerblue` // Light blue
 const acc_white = `#2563eb` // Blue
 const acc_black = `cornflowerblue`
 
-// Helper functions for common patterns
+// Helper for common button-like background patterns
 const btn_bg = (dark_op, light_op) => ({
   light: `rgba(0, 0, 0, ${light_op})`,
   dark: `rgba(255, 255, 255, ${dark_op})`,
@@ -34,22 +32,21 @@ const btn_bg = (dark_op, light_op) => ({
   black: `rgba(255, 255, 255, ${dark_op})`,
 })
 
-const tooltip_bg = (light_bg, dark_bg, light_op = 0.95, dark_op = 0.95) => ({
-  light: `rgba(${light_bg}, ${light_op})`,
-  dark: `rgba(${dark_bg}, ${dark_op})`,
-  white: `rgba(255, 255, 255, 0.98)`,
-  black: `rgba(20, 20, 20, 0.98)`,
-})
+// Slight contrast shading drawn behind plot SVGs and structure canvases so they read
+// as panels sitting on top of the page background. Shared so a plot and a structure
+// shown side by side (e.g. trajectory view) get an identical tint. Kept subtle; light
+// modes darken, dark modes lighten.
+const canvas_bg = {
+  light: `rgba(0, 0, 0, 0.03)`,
+  dark: `rgba(255, 255, 255, 0.07)`,
+  white: `rgba(0, 0, 0, 0.025)`,
+  black: `rgba(255, 255, 255, 0.1)`,
+}
 
 const themes = {
   // Core colors
-  'page-bg': {
-    light: page_bg_light,
-    dark: page_bg_dark,
-    white: page_bg_white,
-    black: page_bg_black,
-  },
-  'text-color': { light: txt_light, dark: txt_dark, white: txt_white, black: txt_black },
+  'page-bg': page_bg,
+  'text-color': txt,
   'surface-bg': {
     light: `rgb(237, 238, 239)`,
     dark: `rgb(33, 36, 43)`,
@@ -57,10 +54,10 @@ const themes = {
     black: `rgb(19, 19, 19)`,
   },
   'border-color': {
-    light: border_light,
-    dark: border_dark,
-    white: border_white,
-    black: border_black,
+    light: `#d1d5db`, // Gray border
+    dark: `#404040`, // Dark gray border
+    white: `#d1d5db`,
+    black: `#404040`,
   },
   'accent-color': {
     light: acc_light,
@@ -147,7 +144,12 @@ const themes = {
   'btn-disabled-bg': btn_bg(0.1, 0.05),
 
   // Tooltips
-  'tooltip-bg': tooltip_bg(`243, 244, 246`, `0, 40, 60`),
+  'tooltip-bg': {
+    light: `rgba(243, 244, 246, 0.95)`,
+    dark: `rgba(0, 40, 60, 0.95)`,
+    white: `rgba(255, 255, 255, 0.98)`,
+    black: `rgba(20, 20, 20, 0.98)`,
+  },
   'canvas-tooltip-bg': {
     light: `rgba(226, 232, 240, 0.96)`,
     dark: `rgba(15, 23, 42, 0.96)`,
@@ -167,19 +169,10 @@ const themes = {
     black: `1px solid rgba(255, 255, 255, 0.075)`,
   },
 
-  // Structure-specific
-  'struct-bg': {
-    light: `rgba(0, 0, 0, 0.02)`,
-    dark: `rgba(255, 255, 255, 0.07)`,
-    white: `rgba(0, 0, 0, 0.01)`,
-    black: `rgba(255, 255, 255, 0.1)`,
-  },
-  'struct-bg-fullscreen': {
-    light: page_bg_light,
-    dark: page_bg_dark,
-    white: page_bg_white,
-    black: page_bg_black,
-  },
+  // Plot & structure canvas backgrounds (shared subtle panel shading)
+  'plot-bg': canvas_bg,
+  'struct-bg': canvas_bg,
+  'struct-bg-fullscreen': page_bg,
 
   // Pane backgrounds (DraggablePane, etc.)
   'pane-bg': {
@@ -250,26 +243,11 @@ const themes = {
     white: `1px solid rgba(0, 0, 0, 0.1)`,
     black: `1px solid rgba(255, 255, 255, 0.1)`,
   },
-  'plot-legend-item-color': {
-    light: txt_light,
-    dark: txt_dark,
-    white: txt_white,
-    black: txt_black,
-  },
+  'plot-legend-item-color': txt,
   'plot-legend-item-hover-bg-color': btn_bg(0.1, 0.1),
 
-  'github-corner-color': {
-    light: page_bg_light,
-    dark: page_bg_dark,
-    white: page_bg_white,
-    black: page_bg_black,
-  },
-  'github-corner-bg': {
-    light: txt_light,
-    dark: txt_dark,
-    white: txt_white,
-    black: txt_black,
-  },
+  'github-corner-color': page_bg,
+  'github-corner-bg': txt,
   'github-corner-bg-hover': {
     light: `#1e40af`, // Darker, more modest blue for light mode
     dark: `#60a5fa`, // Lighter blue for dark mode

package/dist/tooltip/KCoords.svelte

@@ -3,7 +3,10 @@
   import { format_vec3 } from '../labels'
   import type { Vec3 } from '../math'
 
-  let { cartesian, fractional = null }: {
+  let {
+    cartesian,
+    fractional = null,
+  }: {
     cartesian: Vec3
     fractional?: Vec3 | null
   } = $props()

package/dist/tooltip/TooltipContent.svelte

@@ -4,8 +4,8 @@
   // - If tooltip is a config object, render prefix/suffix around the default content
   // - Otherwise, render just the default content
   import { sanitize_html } from '../sanitize'
+  import type { TooltipConfig } from './'
   import type { Snippet } from 'svelte'
-  import type { TooltipConfig } from './types'
 
   let {
     data,
@@ -20,9 +20,7 @@
   } = $props()
 
   const is_snippet = $derived(typeof tooltip === `function`)
-  const config = $derived(
-    !is_snippet && tooltip ? (tooltip as TooltipConfig<T>) : null,
-  )
+  const config = $derived(!is_snippet && tooltip ? (tooltip as TooltipConfig<T>) : null)
   const prefix = $derived(
     typeof config?.prefix === `function` ? config.prefix(data) : config?.prefix,
   )
@@ -47,8 +45,7 @@
   .tooltip-prefix {
     margin-bottom: 6px;
     padding-bottom: 6px;
-    border-bottom: 1px solid
-      var(--tooltip-border, var(--border, rgba(128, 128, 128, 0.3)));
+    border-bottom: 1px solid var(--tooltip-border, var(--border, rgba(128, 128, 128, 0.3)));
   }
   .tooltip-suffix {
     margin-top: 6px;

package/dist/tooltip/TooltipContent.svelte.d.ts

@@ -1,5 +1,5 @@
+import type { TooltipConfig } from './';
 import type { Snippet } from 'svelte';
-import type { TooltipConfig } from './types';
 declare function $$render<T, SnippetArg = T>(): {
     props: {
         data: T;

package/dist/tooltip/index.d.ts

@@ -1,3 +1,10 @@
+import type { Snippet } from 'svelte';
+export type TooltipConfig<T> = {
+    prefix?: string | ((data: T) => string);
+    suffix?: string | ((data: T) => string);
+};
+export type TooltipProp<T, SnippetArgs extends unknown[] = [{
+    hover_data: T;
+}]> = Snippet<SnippetArgs> | TooltipConfig<T>;
 export { default as KCoords } from './KCoords.svelte';
 export { default as TooltipContent } from './TooltipContent.svelte';
-export type * from './types';