matterviz 0.3.6 → 0.4.0

package/dist/chempot-diagram/index.d.ts

@@ -0,0 +1,6 @@
+export { default as ChemPotDiagram } from './ChemPotDiagram.svelte';
+export { default as ChemPotDiagram2D } from './ChemPotDiagram2D.svelte';
+export { default as ChemPotDiagram3D } from './ChemPotDiagram3D.svelte';
+export { compute_chempot_async } from './async-compute.svelte';
+export { compute_chempot_diagram, get_ternary_combinations } from './compute';
+export * from './types';

package/dist/chempot-diagram/index.js

@@ -0,0 +1,6 @@
+export { default as ChemPotDiagram } from './ChemPotDiagram.svelte';
+export { default as ChemPotDiagram2D } from './ChemPotDiagram2D.svelte';
+export { default as ChemPotDiagram3D } from './ChemPotDiagram3D.svelte';
+export { compute_chempot_async } from './async-compute.svelte';
+export { compute_chempot_diagram, get_ternary_combinations } from './compute';
+export * from './types';

package/dist/chempot-diagram/pointer.d.ts

@@ -0,0 +1,16 @@
+export declare function get_pointer_coords(raw_event: unknown): {
+    clientX: number;
+    clientY: number;
+} | null;
+/** Convert pointer event to container-relative coords for tooltip placement. */
+export declare function get_hover_pointer(raw_event: unknown, container_rect: DOMRect | null | undefined): {
+    x: number;
+    y: number;
+} | null;
+/** Add hover pointer to an info object for tooltip placement. */
+export declare function with_hover_pointer<T extends {
+    pointer?: {
+        x: number;
+        y: number;
+    };
+}>(info: Omit<T, `pointer`>, raw_event: unknown, container_rect: DOMRect | null | undefined): T;

package/dist/chempot-diagram/pointer.js

@@ -0,0 +1,40 @@
+// Event/pointer normalization for hover tooltips.
+// Handles DOM events and Threlte/Three.js event wrappers (nativeEvent, srcEvent).
+const is_pointer_like_event = (event_val) => (typeof PointerEvent !== `undefined` && event_val instanceof PointerEvent) ||
+    (typeof MouseEvent !== `undefined` && event_val instanceof MouseEvent);
+export function get_pointer_coords(raw_event) {
+    if (is_pointer_like_event(raw_event)) {
+        return raw_event;
+    }
+    if (!raw_event || typeof raw_event !== `object`)
+        return null;
+    const event_obj = raw_event;
+    if (is_pointer_like_event(event_obj.nativeEvent)) {
+        return event_obj.nativeEvent;
+    }
+    if (is_pointer_like_event(event_obj.srcEvent)) {
+        return event_obj.srcEvent;
+    }
+    const client_x = event_obj.clientX;
+    const client_y = event_obj.clientY;
+    if (typeof client_x === `number` && typeof client_y === `number`) {
+        return { clientX: client_x, clientY: client_y };
+    }
+    return null;
+}
+/** Convert pointer event to container-relative coords for tooltip placement. */
+export function get_hover_pointer(raw_event, container_rect) {
+    const pointer_event = get_pointer_coords(raw_event);
+    if (!pointer_event)
+        return null;
+    const offset_x = container_rect?.left ?? 0;
+    const offset_y = container_rect?.top ?? 0;
+    const x = pointer_event.clientX - offset_x + 4;
+    const y = pointer_event.clientY - offset_y + 4;
+    return { x, y };
+}
+/** Add hover pointer to an info object for tooltip placement. */
+export function with_hover_pointer(info, raw_event, container_rect) {
+    const pointer = get_hover_pointer(raw_event, container_rect);
+    return { ...info, pointer: pointer ?? undefined };
+}

package/dist/chempot-diagram/temperature.d.ts

@@ -0,0 +1,15 @@
+import type { PhaseData } from '../convex-hull/types';
+import type { ChemPotDiagramConfig } from './types';
+interface TempFilterProps {
+    interpolate_temperature?: boolean;
+    max_interpolation_gap?: number;
+}
+export interface TempFilterPayload {
+    has_temp_data: boolean;
+    available_temperatures: number[];
+    temp_filtered_entries: PhaseData[];
+}
+export declare const get_projection_source_entries: (entries: PhaseData[], temp_filtered_entries: PhaseData[]) => PhaseData[];
+export declare function get_temp_filter_payload(entries: PhaseData[], temperature: number | undefined, config: ChemPotDiagramConfig, props: TempFilterProps): TempFilterPayload;
+export declare function get_valid_temperature(temperature: number | undefined, has_temp_data: boolean, available_temperatures: number[]): number | undefined;
+export {};

package/dist/chempot-diagram/temperature.js

@@ -0,0 +1,34 @@
+import { analyze_temperature_data, filter_entries_at_temperature, } from '../convex-hull/helpers';
+import { CHEMPOT_DEFAULTS } from './types';
+export const get_projection_source_entries = (entries, temp_filtered_entries) => (temp_filtered_entries.length > 0 ? temp_filtered_entries : entries);
+const resolve_temp_filter_options = (config, props) => ({
+    interpolate: config.interpolate_temperature ??
+        props.interpolate_temperature ??
+        CHEMPOT_DEFAULTS.interpolate_temperature,
+    max_interpolation_gap: config.max_interpolation_gap ??
+        props.max_interpolation_gap ??
+        CHEMPOT_DEFAULTS.max_interpolation_gap,
+});
+export function get_temp_filter_payload(entries, temperature, config, props) {
+    const { has_temp_data, available_temperatures } = analyze_temperature_data(entries);
+    if (!has_temp_data || temperature === undefined) {
+        return { has_temp_data, available_temperatures, temp_filtered_entries: entries };
+    }
+    const filter_options = resolve_temp_filter_options(config, props);
+    const temp_filtered_entries = filter_entries_at_temperature(entries, temperature, filter_options);
+    return { has_temp_data, available_temperatures, temp_filtered_entries };
+}
+export function get_valid_temperature(temperature, has_temp_data, available_temperatures) {
+    if (!has_temp_data || available_temperatures.length === 0)
+        return temperature;
+    const min_temperature = available_temperatures[0];
+    const max_temperature = available_temperatures.at(-1) ?? min_temperature;
+    if (temperature === undefined)
+        return min_temperature;
+    if (available_temperatures.includes(temperature))
+        return temperature;
+    if (temperature >= min_temperature && temperature <= max_temperature) {
+        return temperature;
+    }
+    return min_temperature;
+}

package/dist/chempot-diagram/types.d.ts

@@ -0,0 +1,81 @@
+import type { D3InterpolateName } from '../colors';
+import type { PhaseData } from '../convex-hull/types';
+import type { Point2D } from '../math';
+export type ChemPotLimits = Partial<Record<string, [number, number]>>;
+export type ChemPotColorMode = `none` | `energy` | `formation_energy` | `arity` | `entries`;
+export type ChemPotProjectionMode = `single` | `grid`;
+export interface ChemPotDiagramConfig {
+    formal_chempots?: boolean;
+    default_min_limit?: number;
+    element_padding?: number;
+    label_stable?: boolean;
+    elements?: string[];
+    limits?: ChemPotLimits;
+    formulas_to_draw?: string[];
+    draw_formula_meshes?: boolean;
+    draw_formula_lines?: boolean;
+    formula_colors?: string[];
+    show_tooltip?: boolean;
+    tooltip_detail_level?: `compact` | `detailed`;
+    color_mode?: ChemPotColorMode;
+    color_scale?: D3InterpolateName;
+    reverse_color_scale?: boolean;
+    interpolate_temperature?: boolean;
+    max_interpolation_gap?: number;
+    projection_mode?: ChemPotProjectionMode;
+}
+export interface ChemPotDiagramData {
+    domains: Record<string, number[][]>;
+    elements: string[];
+    el_refs: Record<string, PhaseData>;
+    min_entries: PhaseData[];
+    hyperplanes: number[][];
+    hyperplane_entries: PhaseData[];
+    lims: [number, number][];
+}
+export interface ChemPotHoverInfoBase {
+    formula: string;
+    view: `2d` | `3d`;
+    pointer?: Point2D;
+    n_points: number;
+    axis_ranges: AxisRangeData[];
+}
+export interface AxisRangeData {
+    element: string;
+    min_val: number;
+    max_val: number;
+}
+export interface ChemPotHoverInfo2D extends ChemPotHoverInfoBase {
+    view: `2d`;
+}
+export interface ChemPotHoverInfo3D extends ChemPotHoverInfoBase {
+    view: `3d`;
+    n_vertices: number;
+    n_edges: number;
+    ann_loc: number[];
+    touches_limits: string[];
+    is_elemental: boolean;
+    is_draw_formula: boolean;
+    matching_entry_count: number;
+    min_energy_per_atom: number | null;
+    max_energy_per_atom: number | null;
+    neighbors: string[];
+}
+export type ChemPotHoverInfo = ChemPotHoverInfo2D | ChemPotHoverInfo3D;
+export declare const CHEMPOT_DEFAULTS: {
+    readonly formal_chempots: true;
+    readonly default_min_limit: -50;
+    readonly element_padding: 1;
+    readonly label_stable: true;
+    readonly draw_formula_meshes: true;
+    readonly draw_formula_lines: true;
+    readonly show_tooltip: true;
+    readonly tooltip_detail_level: "detailed";
+    readonly color_mode: ChemPotColorMode;
+    readonly color_scale: D3InterpolateName;
+    readonly reverse_color_scale: true;
+    readonly interpolate_temperature: true;
+    readonly max_interpolation_gap: 500;
+    readonly projection_mode: ChemPotProjectionMode;
+    readonly formula_colors: readonly ["#1b9e77", "#d95f02", "#7570b3", "#e7298a", "#66a61e", "#e6ab02", "#a6761d", "#666666"];
+};

package/dist/chempot-diagram/types.js

@@ -0,0 +1,28 @@
+// Default configuration values
+export const CHEMPOT_DEFAULTS = {
+    formal_chempots: true,
+    default_min_limit: -50,
+    element_padding: 1.0,
+    label_stable: true,
+    draw_formula_meshes: true,
+    draw_formula_lines: true,
+    show_tooltip: true,
+    tooltip_detail_level: `detailed`,
+    color_mode: `formation_energy`,
+    color_scale: `interpolateSpectral`,
+    reverse_color_scale: true,
+    interpolate_temperature: true,
+    max_interpolation_gap: 500,
+    projection_mode: `single`,
+    // Dark2 qualitative palette (same as pymatgen/plotly default)
+    formula_colors: [
+        `#1b9e77`,
+        `#d95f02`,
+        `#7570b3`,
+        `#e7298a`,
+        `#66a61e`,
+        `#e6ab02`,
+        `#a6761d`,
+        `#666666`,
+    ],
+};

package/dist/colors/index.d.ts

@@ -0,0 +1,47 @@
+import * as d3_sc from 'd3-scale-chromatic';
+import type { Vec3 } from '../math';
+import type { ELEM_SYMBOLS } from '../labels';
+export type D3InterpolateName = keyof typeof d3_sc & `interpolate${string}`;
+export type D3ColorSchemeName = D3InterpolateName extends `interpolate${infer Name}` ? Name : never;
+export declare const get_d3_interpolator: (name: D3InterpolateName) => ((t: number) => string);
+export declare const COLOR_SCALE_TYPES: readonly ["continuous", "categorical"];
+export type ColorScaleType = (typeof COLOR_SCALE_TYPES)[number];
+export declare const DEFAULT_CATEGORY_COLORS: Record<string, string>;
+export declare const AXIS_COLORS: readonly [readonly ["x", "#d75555", "#e66666"], readonly ["y", "#55b855", "#66c966"], readonly ["z", "#5555d7", "#6666e6"]];
+export declare const NEG_AXIS_COLORS: readonly [readonly ["nx", "#b84444", "#cc5555"], readonly ["ny", "#44a044", "#55b155"], readonly ["nz", "#4444b8", "#5555c9"]];
+export type RGBColor = Vec3;
+export type ElementColorScheme = Record<(typeof ELEM_SYMBOLS)[number], RGBColor>;
+export declare const vesta_hex: Record<string, string>;
+export declare const jmol_hex: Record<string, string>;
+export declare const alloy_hex: Record<string, string>;
+export declare const pastel_hex: Record<string, string>;
+export declare const muted_hex: Record<string, string>;
+export declare const dark_mode_hex: Record<string, string>;
+export declare const ELEMENT_COLOR_SCHEMES: {
+    readonly Vesta: Record<string, string>;
+    readonly Jmol: Record<string, string>;
+    readonly Alloy: Record<string, string>;
+    readonly Pastel: Record<string, string>;
+    readonly Muted: Record<string, string>;
+    readonly 'Dark Mode': Record<string, string>;
+};
+export type ColorSchemeName = keyof typeof ELEMENT_COLOR_SCHEMES;
+export declare const default_element_colors: {
+    [x: string]: string;
+};
+export declare const is_color: (val: unknown) => val is string;
+export declare const PLOT_COLORS: readonly ["#63b3ed", "#68d391", "#fbd38d", "#fc8181", "#d6bcfa", "#4fd1c7", "#f687b3", "#fed7d7", "#bee3f8", "#c6f6d5"];
+export declare function luminance(clr: string): number;
+export declare function get_bg_color(elem: HTMLElement | null, bg_color?: string | null): string;
+export interface ContrastOptions {
+    bg_color?: string;
+    luminance_threshold?: number;
+    choices?: [string, string];
+}
+export declare function pick_contrast_color(options?: ContrastOptions): string;
+export declare const contrast_color: (options?: ContrastOptions) => (node: HTMLElement) => void;
+export declare function get_page_background(fallback_dark?: string, fallback_light?: string): string;
+export declare function is_dark_mode(): boolean;
+export declare function watch_dark_mode(on_change: (dark: boolean) => void): () => void;
+export declare function css_color_to_hex(color: string | undefined, fallback: string): string;
+export declare function add_alpha(color: string, alpha: number): string;

package/dist/colors/index.js

@@ -0,0 +1,204 @@
+import { color as d3_color, rgb } from 'd3-color';
+import * as d3_sc from 'd3-scale-chromatic';
+import alloy_colors from './alloy-colors.json' with { type: 'json' };
+import dark_mode_colors from './dark-mode-colors.json' with { type: 'json' };
+import jmol_colors from './jmol-colors.json' with { type: 'json' };
+import muted_colors from './muted-colors.json' with { type: 'json' };
+import pastel_colors from './pastel-colors.json' with { type: 'json' };
+import vesta_colors from './vesta-colors.json' with { type: 'json' };
+export const get_d3_interpolator = (name) => {
+    const candidate = d3_sc[name];
+    return typeof candidate === `function` ? candidate : d3_sc.interpolateViridis;
+};
+export const COLOR_SCALE_TYPES = [`continuous`, `categorical`];
+// color values have to be in hex format since that's the only format
+// <input type="color"> supports
+// https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color#value
+export const DEFAULT_CATEGORY_COLORS = {
+    'diatomic nonmetal': `#ff8c00`, // darkorange
+    'noble gas': `#9932cc`, // darkorchid
+    'alkali metal': `#006400`, // darkgreen
+    'alkaline earth metal': `#483d8b`, // darkslateblue
+    metalloid: `#b8860b`, // darkgoldenrod
+    'polyatomic nonmetal': `#a52a2a`, // brown
+    'transition metal': `#571e6c`,
+    'post-transition metal': `#938d4a`,
+    lanthanide: `#58748e`,
+    actinide: `#6495ed`, // cornflowerblue
+};
+export const AXIS_COLORS = [
+    // [axis name, color, hover color]
+    [`x`, `#d75555`, `#e66666`],
+    [`y`, `#55b855`, `#66c966`],
+    [`z`, `#5555d7`, `#6666e6`],
+];
+export const NEG_AXIS_COLORS = [
+    [`nx`, `#b84444`, `#cc5555`],
+    [`ny`, `#44a044`, `#55b155`],
+    [`nz`, `#4444b8`, `#5555c9`],
+];
+const rgb_scheme_to_hex = (obj) => Object.fromEntries(Object.entries(obj)
+    .filter(([, val]) => val.length >= 3)
+    .map(([key, val]) => [key, rgb(val[0], val[1], val[2]).formatHex()]));
+export const vesta_hex = rgb_scheme_to_hex(vesta_colors);
+export const jmol_hex = rgb_scheme_to_hex(jmol_colors);
+export const alloy_hex = rgb_scheme_to_hex(alloy_colors);
+export const pastel_hex = rgb_scheme_to_hex(pastel_colors);
+export const muted_hex = rgb_scheme_to_hex(muted_colors);
+export const dark_mode_hex = rgb_scheme_to_hex(dark_mode_colors);
+export const ELEMENT_COLOR_SCHEMES = {
+    Vesta: vesta_hex,
+    Jmol: jmol_hex,
+    Alloy: alloy_hex,
+    Pastel: pastel_hex,
+    Muted: muted_hex,
+    'Dark Mode': dark_mode_hex,
+};
+export const default_element_colors = { ...vesta_hex };
+// Detect if a value is a CSS color string. d3-color parses hex, rgb()/rgba(),
+// hsl()/hsla(), and named colors case-insensitively, rejecting arbitrary words like
+// `pending`. It doesn't parse var()/color()/currentcolor, so match those explicitly.
+export const is_color = (val) => {
+    if (typeof val !== `string`)
+        return false;
+    const trimmed = val.trim();
+    return /^(?:var|color)\([^)]+\)$|^currentcolor$/i.test(trimmed) || d3_color(trimmed) !== null;
+};
+export const PLOT_COLORS = [
+    // Color series for e.g. line plots
+    `#63b3ed`,
+    `#68d391`,
+    `#fbd38d`,
+    `#fc8181`,
+    `#d6bcfa`,
+    `#4fd1c7`,
+    `#f687b3`,
+    `#fed7d7`,
+    `#bee3f8`,
+    `#c6f6d5`,
+];
+// calculate human-perceived brightness from RGB color
+export function luminance(clr) {
+    const { r, g, b } = rgb(clr);
+    return (0.299 * r + 0.587 * g + 0.114 * b) / 255; // https://stackoverflow.com/a/596243
+}
+// get background color of passed DOM node, or recurse up the DOM tree if current node is transparent
+export function get_bg_color(elem, bg_color = null) {
+    if (bg_color)
+        return bg_color;
+    // recurse up the DOM tree to find the first non-transparent background color
+    const transparent = `rgba(0, 0, 0, 0)`;
+    if (!elem)
+        return transparent; // if no DOM node, return transparent
+    const bg = getComputedStyle(elem).backgroundColor; // get node background color
+    if (bg !== transparent)
+        return bg; // if not transparent, return it
+    return get_bg_color(elem.parentElement); // otherwise recurse up the DOM tree
+}
+export function pick_contrast_color(options = {}) {
+    const { bg_color, luminance_threshold = 0.7, choices = [`black`, `white`] } = options;
+    const light_bg = luminance(bg_color ?? `white`) > luminance_threshold;
+    return light_bg ? choices[0] : choices[1]; // dark text for light backgrounds, light for dark
+}
+// Svelte attachment that automatically picks dark or light text color to maximize contrast with node's background color
+export const contrast_color = (options = {}) => (node) => {
+    node.style.color = pick_contrast_color({ ...options, bg_color: get_bg_color(node) });
+};
+const is_valid_bg = (bg) => bg !== `` && bg !== `rgba(0, 0, 0, 0)` && bg !== `transparent`;
+// Detect and return the page background color from html/body elements or user preferences
+export function get_page_background(fallback_dark = `#1a1a1a`, fallback_light = `#ffffff`) {
+    if (typeof window === `undefined`)
+        return ``;
+    // Try to get background from html or body
+    const html_bg = getComputedStyle(document.documentElement).backgroundColor;
+    const body_bg = getComputedStyle(document.body).backgroundColor;
+    // Check if background is not transparent/unset
+    // Prefer body background as it's more likely to be styled by the theme
+    if (is_valid_bg(body_bg))
+        return body_bg;
+    if (is_valid_bg(html_bg))
+        return html_bg;
+    // Fall back to prefers-color-scheme
+    const prefers_dark = globalThis.matchMedia(`(prefers-color-scheme: dark)`).matches;
+    return prefers_dark ? fallback_dark : fallback_light;
+}
+// Detect dark mode: checks data-theme attribute, localStorage, then OS preference
+export function is_dark_mode() {
+    if (typeof document === `undefined`)
+        return false;
+    const data_theme = document.documentElement.dataset.theme;
+    if (data_theme === `dark` || data_theme === `light`)
+        return data_theme === `dark`;
+    try {
+        const stored = localStorage.getItem(`theme`);
+        if (stored === `dark` || stored === `light`)
+            return stored === `dark`;
+    }
+    catch {
+        /* localStorage throws in private browsing mode */
+    }
+    return globalThis.matchMedia?.(`(prefers-color-scheme: dark)`).matches ?? false;
+}
+// Watch for dark mode changes and call callback on each change. Returns cleanup function.
+export function watch_dark_mode(on_change) {
+    if (typeof document === `undefined`)
+        return () => { }; // No-op in SSR
+    const notify = () => on_change(is_dark_mode());
+    const observer = new MutationObserver(notify);
+    observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: [`data-theme`],
+    });
+    const on_storage = (ev) => {
+        if (ev.key === `theme`)
+            notify();
+    };
+    globalThis.addEventListener(`storage`, on_storage);
+    const media_query = globalThis.matchMedia?.(`(prefers-color-scheme: dark)`);
+    media_query?.addEventListener(`change`, notify);
+    return () => {
+        observer.disconnect();
+        globalThis.removeEventListener(`storage`, on_storage);
+        media_query?.removeEventListener(`change`, notify);
+    };
+}
+// Convert a CSS color string to hex format for use with <input type="color">.
+// Returns fallback for CSS variables, transparent, invalid colors, or undefined.
+// Uses d3-color for robust parsing of named colors, rgb(), hsl(), etc.
+export function css_color_to_hex(color, fallback) {
+    if (!color || color.startsWith(`var(`))
+        return fallback;
+    if (color === `transparent`)
+        return `#ffffff`;
+    const parsed = rgb(color);
+    return Number.isNaN(parsed.r) ? fallback : parsed.formatHex();
+}
+// Add or modify the alpha channel of a color.
+// Supports hex (#rgb, #rgba, #rrggbb, #rrggbbaa), rgb(), and rgba() formats.
+// Returns the color in rgba() format, or the original color if format is unsupported.
+export function add_alpha(color, alpha) {
+    // Clamp alpha to valid CSS range [0, 1]
+    const clamped_alpha = Math.max(0, Math.min(1, alpha));
+    // Handle hex colors (#rgb, #rgba, #rrggbb, #rrggbbaa)
+    if (color.startsWith(`#`)) {
+        const hex = color.slice(1);
+        // Guard against malformed hex (only 3, 4, 6, or 8 chars are valid)
+        if (![3, 4, 6, 8].includes(hex.length))
+            return color;
+        // Extract RGB, ignoring any existing alpha channel
+        const is_short = hex.length === 3 || hex.length === 4;
+        const red = parseInt(is_short ? hex[0] + hex[0] : hex.slice(0, 2), 16);
+        const green = parseInt(is_short ? hex[1] + hex[1] : hex.slice(2, 4), 16);
+        const blue = parseInt(is_short ? hex[2] + hex[2] : hex.slice(4, 6), 16);
+        return `rgba(${red}, ${green}, ${blue}, ${clamped_alpha})`;
+    }
+    // Handle rgb() colors
+    if (color.startsWith(`rgb(`)) {
+        return color.replace(`rgb(`, `rgba(`).replace(`)`, `, ${clamped_alpha})`);
+    }
+    // Handle rgba() - replace existing alpha (supports scientific notation like 1e-5)
+    if (color.startsWith(`rgba(`)) {
+        return color.replace(/,\s*[\d.eE\-+]+\)$/, `, ${clamped_alpha})`);
+    }
+    return color;
+}