matterviz 0.3.7 → 0.4.0

package/dist/spectral/helpers.d.ts

@@ -1,10 +1,11 @@
 import type { Matrix3x3, Vec2, Vec3 } from '../math';
-import type { AxisConfig } from '../plot/types';
+import type { AxisConfig } from '../plot/core/types';
 import type * as types from './types';
 import type { RibbonConfig } from './types';
 export declare const is_valid_range: (range: unknown) => range is Vec2;
 export declare const ranges_equal: (a: Vec2 | undefined | null, b: Vec2 | undefined | null, tol?: number) => boolean;
 export declare const axis_with_range: (axis: AxisConfig | undefined, range: Vec2 | undefined, label?: string) => AxisConfig;
+export declare function sync_axis_range(axis: AxisConfig, range: unknown): AxisConfig;
 export declare function detect_zoom_change(bands_range: unknown, dos_range: unknown, shared_range: Vec2, current_synced: Vec2 | null, dos_enabled?: boolean): Vec2 | null | undefined;
 export declare const IMAGINARY_MODE_NOISE_THRESHOLD = 0.005;
 export declare function pretty_sym_point(symbol: string): string;
@@ -29,6 +30,7 @@ export declare function extract_k_path_points(band_struct: types.BaseBandStructu
     wrap_to_bz?: boolean;
 }): Vec3[];
 export declare function find_qpoint_at_distance(band_struct: types.BaseBandStructure, target: number): number | null;
+export declare function qpoint_x_position(band_struct: types.BaseBandStructure, qpoint_index: number, x_positions: Record<string, [number, number]>): number | null;
 export declare function find_qpoint_at_rescaled_x(band_struct: types.BaseBandStructure, rescaled_x: number, x_positions: Record<string, [number, number]>): number | null;
 type SpinDensities = Record<string, number[]>;
 export interface PymatgenDos {

package/dist/spectral/helpers.js

@@ -1,6 +1,6 @@
 // Helper utilities for band structure and DOS data processing
 import { SUBSCRIPT_MAP } from '../labels';
-import { centered_frac, euclidean_dist } from '../math';
+import { euclidean_dist } from '../math';
 const is_subscript_key = (key) => key in SUBSCRIPT_MAP;
 // Check if range is a valid [min, max] tuple (strict 2-element array of finite numbers)
 export const is_valid_range = (range) => Array.isArray(range) &&
@@ -22,6 +22,22 @@ export const axis_with_range = (axis, range, label) => ({
     ...(label !== undefined && { label }),
     ...(is_valid_range(range) && { range }),
 });
+// Sync a ScatterPlot's internal y-axis range back onto a parent bindable axis.
+// Returns a new axis when the range changed (or became invalid and must be
+// cleared), otherwise the same reference so callers can skip reassignment and
+// avoid reactive churn (assign only when `result !== axis`).
+export function sync_axis_range(axis, range) {
+    if (is_valid_range(range)) {
+        if (axis.range?.[0] === range[0] && axis.range?.[1] === range[1])
+            return axis;
+        return { ...axis, range };
+    }
+    if (`range` in axis) {
+        const { range: _omit, ...rest } = axis;
+        return rest;
+    }
+    return axis;
+}
 // Detect which plot triggered a zoom change and return the new synced range.
 // Returns null to reset to shared range, undefined for no change, or Vec2 for new zoom.
 export function detect_zoom_change(bands_range, dos_range, shared_range, current_synced, dos_enabled = true) {
@@ -70,12 +86,12 @@ export function pretty_sym_point(symbol) {
     // Handle subscripts: convert S0 to S₀, K1 to K₁, Γ1 to Γ₁, etc.
     // Use \p{L} to match any Unicode letter (not just ASCII A-Z)
     return symbol
-        .replace(/_/g, ``)
-        .replace(/\\?GAMMA/gi, `Γ`)
-        .replace(/\\?DELTA/gi, `Δ`)
-        .replace(/\\?SIGMA/gi, `Σ`)
-        .replace(/\\?LAMBDA/gi, `Λ`)
-        .replace(/(\p{L})(\d+)/gu, (_, letter, num) => letter +
+        .replaceAll('_', ``)
+        .replaceAll(/\\?GAMMA/gi, `Γ`)
+        .replaceAll(/\\?DELTA/gi, `Δ`)
+        .replaceAll(/\\?SIGMA/gi, `Σ`)
+        .replaceAll(/\\?LAMBDA/gi, `Λ`)
+        .replaceAll(/(\p{L})(\d+)/gu, (_, letter, num) => letter +
         num
             .split(``)
             .map((digit) => (is_subscript_key(digit) ? SUBSCRIPT_MAP[digit] : digit))
@@ -133,7 +149,7 @@ export function get_ribbon_config(ribbon_config, label) {
 export function get_band_xaxis_ticks(band_struct, branches = []) {
     const ticks_x_pos = [];
     const tick_labels = [];
-    let prev_label = band_struct.qpoints[0]?.label || null;
+    let prev_label = band_struct.qpoints[0]?.label ?? null;
     let prev_branch = band_struct.branches[0]?.name || null;
     // Convert branches to Set for consistent handling
     const branches_set = Array.isArray(branches) ? new Set(branches) : branches;
@@ -148,7 +164,7 @@ export function get_band_xaxis_ticks(band_struct, branches = []) {
         const this_branch = branch_names[0] || null;
         if (point.label !== prev_label && prev_branch !== this_branch) {
             // Branch transition - combine labels
-            tick_labels[tick_labels.length - 1] = `${prev_label || ``}|${point.label}`;
+            tick_labels[tick_labels.length - 1] = `${prev_label ?? ``}|${point.label}`;
             ticks_x_pos[ticks_x_pos.length - 1] = band_struct.distance[idx];
         }
         else if (branches_set.size === 0 || (this_branch && branches_set.has(this_branch))) {
@@ -222,6 +238,7 @@ function fnv1a_hash(arr) {
         hash ^= int_view[1];
         hash = Math.imul(hash, 16777619);
     }
+    // oxlint-disable-next-line eslint-plugin-unicorn/prefer-math-trunc -- `>>> 0` is unsigned 32-bit coercion, not truncation
     return hash >>> 0; // Ensure unsigned
 }
 // Generate cache key using FNV-1a hash over full arrays (O(n), low collision risk)
@@ -291,7 +308,7 @@ export function clear_smearing_cache() {
 }
 // Type guards for pymatgen qpoint formats
 const is_vec3 = (val) => Array.isArray(val) && val.length >= 3 && val.slice(0, 3).every(Number.isFinite);
-const is_kpoint = (val) => !!val && typeof val === `object` && `frac_coords` in val && is_vec3(val.frac_coords);
+const is_kpoint = (val) => val !== null && typeof val === `object` && `frac_coords` in val && is_vec3(val.frac_coords);
 const is_pymatgen_format = (obj) => {
     // Check for explicit pymatgen markers
     if (typeof obj[`@class`] === `string` || typeof obj[`@module`] === `string`) {
@@ -313,8 +330,8 @@ const parse_qpoint = (qpt, labels_dict) => {
             : null;
     if (!frac_coords)
         return null;
-    const label = (is_kpoint(qpt) && typeof qpt.label === `string` && qpt.label) ||
-        Object.entries(labels_dict ?? {}).find(([, c]) => euclidean_dist(frac_coords, c) < 1e-4)?.[0] ||
+    const label = ((is_kpoint(qpt) && typeof qpt.label === `string` && qpt.label) ||
+        Object.entries(labels_dict ?? {}).find(([, c]) => euclidean_dist(frac_coords, c) < 1e-4)?.[0]) ??
         null;
     return { label, frac_coords };
 };
@@ -386,13 +403,13 @@ function convert_pymatgen_band_structure(pmg) {
     const unit = pmg.unit?.toLowerCase() ?? (has_frequencies_cm ? `cm-1` : `thz`);
     if (!Array.isArray(raw_qpts) ||
         !Array.isArray(raw_bands) ||
-        !raw_qpts.length ||
-        !raw_bands.length)
+        raw_qpts.length === 0 ||
+        raw_bands.length === 0)
         return null;
     const qpoints = raw_qpts
         .map((qpoint) => parse_qpoint(qpoint, labels_dict))
         .filter((qpoint) => qpoint !== null);
-    if (!qpoints.length)
+    if (qpoints.length === 0)
         return null;
     // Step distances and discontinuity detection (5x median threshold)
     const steps = qpoints
@@ -439,7 +456,7 @@ function convert_pymatgen_band_structure(pmg) {
         })
             .filter((branch) => branch.start_index <= branch.end_index);
     }
-    if (!branches.length) {
+    if (branches.length === 0) {
         branches.push({ start_index: 0, end_index: qpoints.length - 1, name: `path` });
     }
     // Convert bands to THz based on input unit
@@ -574,19 +591,44 @@ export function extract_k_path_points(band_struct, recip_lattice_matrix, options
         throw new Error(`reciprocal_lattice_matrix must be a 3×3 matrix`);
     const [[m00, m01, m02], [m10, m11, m12], [m20, m21, m22]] = recip_lattice_matrix;
     return band_struct.qpoints.map((qpoint) => {
-        let [x, y, z] = qpoint.frac_coords;
-        // Wrap to first BZ if enabled (handles [0,1] vs [-0.5,0.5] convention difference)
-        if (wrap_to_bz) {
-            x = centered_frac(x);
-            y = centered_frac(y);
-            z = centered_frac(z);
-        }
-        const kx = x * m00 + y * m10 + z * m20;
-        const ky = x * m01 + y * m11 + z * m21;
-        const kz = x * m02 + y * m12 + z * m22;
-        return [kx, ky, kz];
+        const [x, y, z] = qpoint.frac_coords;
+        const cart = [
+            x * m00 + y * m10 + z * m20,
+            x * m01 + y * m11 + z * m21,
+            x * m02 + y * m12 + z * m22,
+        ];
+        // Fold into the first (Wigner-Seitz) BZ so points stay inside the rendered zone.
+        // Folding in Cartesian space (vs per-axis on fractional coords, which only yields
+        // the parallelepiped cell) handles non-orthogonal lattices and preserves path
+        // continuity: points already inside the zone are left untouched.
+        return wrap_to_bz ? fold_to_first_bz(cart, recip_lattice_matrix) : cart;
     });
 }
+// Fold a Cartesian reciprocal-space point into the first (Wigner-Seitz) Brillouin zone
+// by choosing the periodic image with the smallest norm (minimum-image convention).
+// The ±1 search (27 images) suffices for typical reciprocal lattices; extremely skewed
+// cells could in principle need a wider search.
+function fold_to_first_bz(cart, recip) {
+    let best = cart;
+    let best_norm = cart[0] ** 2 + cart[1] ** 2 + cart[2] ** 2;
+    for (let n1 = -1; n1 <= 1; n1++) {
+        for (let n2 = -1; n2 <= 1; n2++) {
+            for (let n3 = -1; n3 <= 1; n3++) {
+                if (n1 === 0 && n2 === 0 && n3 === 0)
+                    continue;
+                const cand = [
+                    cart[0] + n1 * recip[0][0] + n2 * recip[1][0] + n3 * recip[2][0],
+                    cart[1] + n1 * recip[0][1] + n2 * recip[1][1] + n3 * recip[2][1],
+                    cart[2] + n1 * recip[0][2] + n2 * recip[1][2] + n3 * recip[2][2],
+                ];
+                const norm = cand[0] ** 2 + cand[1] ** 2 + cand[2] ** 2;
+                if (norm < best_norm - 1e-9)
+                    [best, best_norm] = [cand, norm];
+            }
+        }
+    }
+    return best;
+}
 // Find the q-point index closest to a given distance along the band structure path
 export function find_qpoint_at_distance(band_struct, target) {
     const { distance } = band_struct;
@@ -594,6 +636,30 @@ export function find_qpoint_at_distance(band_struct, target) {
         return null;
     return distance.reduce((closest, dist, idx) => Math.abs(dist - target) < Math.abs(distance[closest] - target) ? idx : closest, 0);
 }
+// Rescaled x-position of a q-point index along the band plot path. Inverse of
+// find_qpoint_at_rescaled_x, used to highlight a q-point hovered in the Brillouin zone.
+// Returns null if the index doesn't fall on a plotted (non-discontinuity) branch.
+export function qpoint_x_position(band_struct, qpoint_index, x_positions) {
+    if (!band_struct?.branches?.length || !x_positions)
+        return null;
+    for (const branch of band_struct.branches) {
+        if (qpoint_index < branch.start_index || qpoint_index > branch.end_index)
+            continue;
+        const start_label = band_struct.qpoints[branch.start_index]?.label ?? undefined;
+        const end_label = band_struct.qpoints[branch.end_index]?.label ?? undefined;
+        const range = x_positions[get_segment_key(start_label, end_label)];
+        if (!range)
+            continue;
+        const [x_start, x_end] = range;
+        const d_start = band_struct.distance[branch.start_index];
+        const d_end = band_struct.distance[branch.end_index];
+        if (d_end === d_start)
+            return x_start; // discontinuity / zero-length segment
+        const ratio = (band_struct.distance[qpoint_index] - d_start) / (d_end - d_start);
+        return x_start + ratio * (x_end - x_start);
+    }
+    return null;
+}
 // Find q-point index from rescaled x-coordinate (used in band structure plots)
 // This handles the case where the plot uses custom x-axis scaling per segment
 export function find_qpoint_at_rescaled_x(band_struct, rescaled_x, x_positions) {
@@ -934,12 +1000,12 @@ export function format_dos_tooltip(x_formatted, y_formatted, label, is_horizonta
     };
     const lines = is_horizontal
         ? [
-            format_tooltip_line(y_parsed.name || freq_defaults.name, y_formatted, y_parsed.unit || freq_defaults.unit),
+            format_tooltip_line(y_parsed.name || freq_defaults.name, y_formatted, y_parsed.unit ?? freq_defaults.unit),
             format_tooltip_line(x_parsed.name || `Density`, x_formatted),
         ]
         : [
             format_tooltip_line(y_parsed.name || `Density`, y_formatted),
-            format_tooltip_line(x_parsed.name || freq_defaults.name, x_formatted, x_parsed.unit || freq_defaults.unit),
+            format_tooltip_line(x_parsed.name || freq_defaults.name, x_formatted, x_parsed.unit ?? freq_defaults.unit),
         ];
     return { title: num_series > 1 && label ? label : undefined, lines };
 }

package/dist/structure/AtomLegend.svelte

@@ -128,8 +128,8 @@
       // Use unique_values instead of values to avoid undefined colors from duplicates
       property_colors?.unique_values?.flatMap((val) => {
         const idx = property_colors.values.indexOf(val)
-        return idx >= 0 ? [[val, property_colors.colors[idx]]] : []
-      }) ?? [],
+        return idx !== -1 ? [[val, property_colors.colors[idx]]] : []
+      }),
     ),
   )
 
@@ -324,6 +324,7 @@
 
 {#if show_element_legend}
   <div {...rest} class="atom-legend element-legend {rest.class ?? ``}">
+    {@render mode_selector_snippet()}
     {#each sorted_element_entries as [elem, amt], idx (elem)}
       {@const is_hidden = hidden_elements.has(elem as ElementSymbol)}
       {@const displayed_elem = element_mapping?.[elem as ElementSymbol] || elem}
@@ -465,7 +466,6 @@
       </div>
     {/each}
     {@render site_radius_control_snippet()}
-    {@render mode_selector_snippet()}
     {@render children?.({ mode_menu_open, structure })}
   </div>
 {:else if show_property_legend}
@@ -474,6 +474,7 @@
     class:categorical-legend={atom_color_config.scale_type === `categorical`}
     {...rest}
   >
+    {@render mode_selector_snippet()}
     {#if legend_title}
       <div class="legend-header">
         <h4>{legend_title}</h4>
@@ -533,7 +534,6 @@
       {/each}
     {/if}
     {@render site_radius_control_snippet()}
-    {@render mode_selector_snippet()}
     {@render children?.({ mode_menu_open, structure })}
   </div>
 {/if}
@@ -723,7 +723,8 @@
     position: relative;
     display: flex;
     align-items: center;
-    margin-left: calc(-0.5 * var(--struct-legend-gap, clamp(3pt, 2cqmin, 7pt)));
+    /* extra gap toward the color labels so the chevron groups with the cell-select control */
+    margin-right: calc(0.25 * var(--struct-legend-gap, clamp(3pt, 2cqmin, 7pt)));
   }
   .mode-toggle {
     background: transparent;
@@ -735,17 +736,15 @@
     font-size: 0.9em;
     opacity: 0;
     pointer-events: none;
+    transform: translateY(1px);
     transition: opacity 0.2s ease;
   }
   .mode-toggle :global(svg) {
     font-size: 1.15em;
   }
   .mode-toggle.visible {
-    opacity: 0.7;
-    pointer-events: auto;
-  }
-  .mode-toggle.visible:hover {
     opacity: 1;
+    pointer-events: auto;
   }
   .mode-dropdown {
     position: absolute;

package/dist/structure/CellSelect.svelte

@@ -296,8 +296,7 @@
     gap: 3px;
   }
   .preset-btn {
-    padding: 0 1px;
-    line-height: 1;
+    padding: 1px;
     background: var(--btn-bg, light-dark(rgba(0, 0, 0, 0.08), rgba(255, 255, 255, 0.1)));
     border: 1px solid var(--border-color);
     border-radius: var(--border-radius, 3pt);

package/dist/structure/Cylinder.svelte

@@ -1,14 +1,18 @@
 <script lang="ts">
   import type { Vec3 } from '../math'
   import { T } from '@threlte/core'
+  import type { ComponentProps } from 'svelte'
   import { Euler, Quaternion, Vector3 } from 'three'
 
-  let { from, to, color = `#808080`, thickness = 0.1 }: {
-    from: Vec3
-    to: Vec3
-    color?: string
-    thickness?: number
-  } = $props()
+  let { from, to, color = `#808080`, thickness = 0.1, opacity = 1, ...rest }:
+    & ComponentProps<typeof T.Mesh>
+    & {
+      from: Vec3
+      to: Vec3
+      color?: string
+      thickness?: number
+      opacity?: number // < 1 renders semi/fully transparent (e.g. invisible hover proxies)
+    } = $props()
 
   let from_vec = $derived(new Vector3(...from))
   let to_vec = $derived(new Vector3(...to))
@@ -39,7 +43,7 @@
   }
 </script>
 
-<T.Mesh {position} {rotation} scale={[thickness, height, thickness]}>
+<T.Mesh {...rest} {position} {rotation} scale={[thickness, height, thickness]}>
   <T.CylinderGeometry args={[thickness, thickness, 1, 8]} />
-  <T.MeshStandardMaterial {color} />
+  <T.MeshStandardMaterial {color} transparent={opacity < 1} {opacity} depthWrite={opacity >= 1} />
 </T.Mesh>

package/dist/structure/Cylinder.svelte.d.ts

@@ -1,9 +1,12 @@
 import type { Vec3 } from '../math';
-type $$ComponentProps = {
+import { T } from '@threlte/core';
+import type { ComponentProps } from 'svelte';
+type $$ComponentProps = ComponentProps<typeof T.Mesh> & {
     from: Vec3;
     to: Vec3;
     color?: string;
     thickness?: number;
+    opacity?: number;
 };
 declare const Cylinder: import("svelte").Component<$$ComponentProps, {}, "">;
 type Cylinder = ReturnType<typeof Cylinder>;