matterviz 0.3.1 → 0.3.3

package/dist/spectral/Bands.svelte.d.ts

@@ -1,6 +1,6 @@
 import ScatterPlot from '../plot/ScatterPlot.svelte';
 import type { AxisConfig } from '../plot/types';
-import type { BandStructureType, BaseBandStructure, LineKwargs, PathMode, RibbonConfig } from './types';
+import type { BandsSpinMode, BandStructureType, BaseBandStructure, FrequencyUnit, LineKwargs, PathMode, RibbonConfig } from './types';
 import type { ComponentProps } from 'svelte';
 type $$ComponentProps = ComponentProps<typeof ScatterPlot> & {
     band_structs: BaseBandStructure | Record<string, BaseBandStructure>;
@@ -14,7 +14,27 @@ type $$ComponentProps = ComponentProps<typeof ScatterPlot> & {
     reference_frequency?: number | null;
     ribbon_config?: RibbonConfig | Record<string, RibbonConfig>;
     fermi_level?: number;
+    units?: FrequencyUnit;
+    band_spin_mode?: BandsSpinMode;
+    highlight_regions?: {
+        y_min: number;
+        y_max: number;
+        color?: string;
+        opacity?: number;
+        label?: string;
+    }[];
+    shade_imaginary_modes?: boolean;
+    show_gap_annotation?: boolean;
+    show_controls?: boolean;
+    show_path_mode_control?: boolean;
+    show_units_control?: boolean;
+    show_spin_control?: boolean;
+    show_annotation_controls?: boolean;
+    id?: string;
+    class?: string;
+    style?: string;
+    'data-testid'?: string;
 };
-declare const Bands: import("svelte").Component<$$ComponentProps, {}, "y_axis" | "x_positions">;
+declare const Bands: import("svelte").Component<$$ComponentProps, {}, "y_axis" | "units" | "x_positions" | "band_spin_mode">;
 type Bands = ReturnType<typeof Bands>;
 export default Bands;

package/dist/spectral/BandsAndDos.svelte

@@ -1,62 +1,103 @@
-<script lang="ts">import { untrack } from 'svelte';
-import Bands from './Bands.svelte';
-import Dos from './Dos.svelte';
-import { compute_frequency_range, detect_zoom_change, extract_efermi, is_valid_range, ranges_equal, } from './helpers';
-let { band_structs, doses, bands_props = {}, dos_props = {}, shared_y_axis = true, sync_y_zoom = true, children, ...rest } = $props();
-let shared_frequency_range = $derived(shared_y_axis ? compute_frequency_range(band_structs, doses) : undefined);
-let fermi_level = $derived(extract_efermi(band_structs) ?? extract_efermi(doses));
-// Synced zoom state (null = use auto-computed range)
-let synced_zoom_range = $state(null);
-let bands_y_axis = $state({});
-let dos_y_axis = $state({ label: `` });
-// Detect zoom changes and sync between components (runs first to capture child updates)
-$effect(() => {
-    if (!sync_y_zoom || !shared_frequency_range)
-        return;
-    const result = detect_zoom_change(bands_y_axis.range, dos_y_axis.range, shared_frequency_range, untrack(() => synced_zoom_range));
-    if (result !== undefined)
-        synced_zoom_range = result;
-});
-// Propagate synced range to bands y-axis (untrack current to avoid overwriting child zoom)
-$effect(() => {
-    const base_range = synced_zoom_range ?? shared_frequency_range;
-    const current_range = untrack(() => bands_y_axis.range);
+<script lang="ts">
+  import type { Vec2 } from '../math'
+  import type { AxisConfig } from '../plot/types'
+  import type { ComponentProps, Snippet } from 'svelte'
+  import { untrack } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import Bands from './Bands.svelte'
+  import Dos from './Dos.svelte'
+  import {
+    compute_frequency_range,
+    detect_zoom_change,
+    extract_efermi,
+    is_valid_range,
+    ranges_equal,
+  } from './helpers'
+  import type { BaseBandStructure, DosInput, HoveredData } from './types'
+
+  let {
+    band_structs,
+    doses,
+    bands_props = {},
+    dos_props = {},
+    shared_y_axis = true,
+    sync_y_zoom = true,
+    children,
+    ...rest
+  }: HTMLAttributes<HTMLDivElement> & {
+    band_structs: BaseBandStructure | Record<string, BaseBandStructure>
+    doses: DosInput | Record<string, DosInput>
+    bands_props?: Partial<ComponentProps<typeof Bands>>
+    dos_props?: Partial<ComponentProps<typeof Dos>>
+    shared_y_axis?: boolean
+    sync_y_zoom?: boolean
+    class?: string
+    children?: Snippet<[HoveredData]>
+  } = $props()
+
+  let shared_frequency_range = $derived(
+    shared_y_axis ? compute_frequency_range(band_structs, doses) : undefined,
+  )
+  let fermi_level = $derived(extract_efermi(band_structs) ?? extract_efermi(doses))
+
+  // Synced zoom state (null = use auto-computed range)
+  let synced_zoom_range = $state<Vec2 | null>(null)
+  let bands_y_axis = $state<AxisConfig>({})
+  let dos_y_axis = $state<AxisConfig>({ label: `` })
+
+  // Detect zoom changes and sync between components (runs first to capture child updates)
+  $effect(() => {
+    if (!sync_y_zoom || !shared_frequency_range) return
+    const result = detect_zoom_change(
+      bands_y_axis.range,
+      dos_y_axis.range,
+      shared_frequency_range,
+      untrack(() => synced_zoom_range),
+    )
+    if (result !== undefined) synced_zoom_range = result
+  })
+
+  // Propagate synced range to bands y-axis (untrack current to avoid overwriting child zoom)
+  $effect(() => {
+    const base_range = synced_zoom_range ?? shared_frequency_range
+    const current_range = untrack(() => bands_y_axis.range) as Vec2 | undefined
     // Skip if current range already matches base, or is valid but differs (child zoom in progress)
-    if (ranges_equal(current_range, base_range))
-        return;
+    if (ranges_equal(current_range, base_range)) return
     if (is_valid_range(current_range) && !ranges_equal(current_range, base_range)) {
-        return;
+      return
     }
     // Only include range if it's valid (don't override child's auto-range with undefined)
     bands_y_axis = shared_y_axis
-        ? {
-            ...(bands_props.y_axis ?? {}),
-            ...(is_valid_range(base_range) && { range: base_range }),
-        }
-        : { ...(bands_props.y_axis ?? {}) };
-});
-// Propagate synced range to DOS y-axis (untrack current to avoid overwriting child zoom)
-$effect(() => {
-    const base_range = synced_zoom_range ?? shared_frequency_range;
-    const current_range = untrack(() => dos_y_axis.range);
+      ? {
+        ...(bands_props.y_axis ?? {}),
+        ...(is_valid_range(base_range) && { range: base_range }),
+      }
+      : { ...(bands_props.y_axis ?? {}) }
+  })
+
+  // Propagate synced range to DOS y-axis (untrack current to avoid overwriting child zoom)
+  $effect(() => {
+    const base_range = synced_zoom_range ?? shared_frequency_range
+    const current_range = untrack(() => dos_y_axis.range) as Vec2 | undefined
     // Skip if current range already matches base, or is valid but differs (child zoom in progress)
-    if (ranges_equal(current_range, base_range))
-        return;
+    if (ranges_equal(current_range, base_range)) return
     if (is_valid_range(current_range) && !ranges_equal(current_range, base_range)) {
-        return;
+      return
     }
     // Only include range if it's valid (don't override child's auto-range with undefined)
     dos_y_axis = shared_y_axis
-        ? {
-            label: ``,
-            ...(dos_props.y_axis ?? {}),
-            ...(is_valid_range(base_range) && { range: base_range }),
-        }
-        : { label: ``, ...(dos_props.y_axis ?? {}) };
-});
-let hovered_frequency = $state(null);
-// Ensure both plots use identical top/bottom padding for aligned y_scale_fn
-const shared_tb_padding = { t: 20, b: 50 };
+      ? {
+        label: ``,
+        ...(dos_props.y_axis ?? {}),
+        ...(is_valid_range(base_range) && { range: base_range }),
+      }
+      : { label: ``, ...(dos_props.y_axis ?? {}) }
+  })
+
+  let hovered_frequency = $state<number | null>(null)
+
+  // Ensure both plots use identical top/bottom padding for aligned y_scale_fn
+  const shared_tb_padding = { t: 20, b: 50 }
 </script>
 
 <div

package/dist/spectral/BrillouinBandsDos.svelte

@@ -1,104 +1,162 @@
-<script lang="ts">import { BrillouinZone, reciprocal_lattice } from '../brillouin';
-import { untrack } from 'svelte';
-import Bands from './Bands.svelte';
-import Dos from './Dos.svelte';
-import * as helpers from './helpers';
-let { structure, band_structs, doses, bands_props = {}, dos_props = {}, bz_props = {}, sync_y_zoom = true, children, ...rest } = $props();
-// Get the first normalized band structure for path calculations
-// Support both qpoints (phonon) and kpoints (electronic) to detect single vs dict
-let first_band_struct = $derived(helpers.normalize_band_structure(`qpoints` in band_structs || `kpoints` in band_structs
-    ? band_structs
-    : Object.values(band_structs)[0]));
-// Compute shared frequency/energy range from both bands and DOS data
-let shared_frequency_range = $derived(helpers.compute_frequency_range(band_structs, doses));
-// Extract Fermi level from electronic band structure or DOS data
-let fermi_level = $derived.by(() => {
-    // Check band structures for efermi
-    const bs_source = `efermi` in band_structs
+<script lang="ts">
+  import { BrillouinZone, reciprocal_lattice } from '../brillouin'
+  import type { Vec2, Vec3 } from '../math'
+  import type { InternalPoint } from '../plot'
+  import type { AxisConfig } from '../plot/types'
+  import type { Crystal } from '../structure'
+  import type { ComponentProps, Snippet } from 'svelte'
+  import { untrack } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import Bands from './Bands.svelte'
+  import Dos from './Dos.svelte'
+  import * as helpers from './helpers'
+  import type { BaseBandStructure, DosData, HoveredData } from './types'
+
+  let {
+    structure,
+    band_structs,
+    doses,
+    bands_props = {},
+    dos_props = {},
+    bz_props = {},
+    sync_y_zoom = true,
+    children,
+    ...rest
+  }: HTMLAttributes<HTMLDivElement> & {
+    structure: Crystal
+    band_structs: BaseBandStructure | Record<string, BaseBandStructure>
+    doses: DosData | Record<string, DosData>
+    bands_props?: Partial<ComponentProps<typeof Bands>>
+    dos_props?: Partial<ComponentProps<typeof Dos>>
+    bz_props?: Partial<ComponentProps<typeof BrillouinZone>>
+    sync_y_zoom?: boolean // Sync frequency/energy axis zoom between plots (default: true)
+    children?: Snippet<[HoveredData]>
+  } = $props()
+
+  // Get the first normalized band structure for path calculations
+  // Support both qpoints (phonon) and kpoints (electronic) to detect single vs dict
+  let first_band_struct = $derived(
+    helpers.normalize_band_structure(
+      `qpoints` in (band_structs as object) || `kpoints` in (band_structs as object)
         ? band_structs
-        : Object.values(band_structs)[0];
-    const bs_efermi = bs_source?.efermi;
-    if (typeof bs_efermi === `number`)
-        return bs_efermi;
+        : Object.values(band_structs)[0],
+    ),
+  ) as BaseBandStructure | null
+
+  // Compute shared frequency/energy range from both bands and DOS data
+  let shared_frequency_range = $derived(
+    helpers.compute_frequency_range(band_structs, doses),
+  )
+
+  // Extract Fermi level from electronic band structure or DOS data
+  let fermi_level = $derived.by((): number | undefined => {
+    // Check band structures for efermi
+    const bs_source = `efermi` in (band_structs as object)
+      ? band_structs
+      : Object.values(band_structs)[0]
+    const bs_efermi = (bs_source as Record<string, unknown>)?.efermi
+    if (typeof bs_efermi === `number`) return bs_efermi
+
     // Check DOS for efermi
-    const dos_source = `efermi` in doses ? doses : Object.values(doses)[0];
-    const dos_efermi = dos_source?.efermi;
-    return typeof dos_efermi === `number` ? dos_efermi : undefined;
-});
-// Convert fractional k-point coordinates to Cartesian reciprocal space
-// using the structure's reciprocal lattice (consistent with BZ computation)
-let k_path_points = $derived.by(() => {
-    if (!first_band_struct?.qpoints || !structure?.lattice?.matrix)
-        return [];
-    const k_lattice = reciprocal_lattice(structure.lattice.matrix);
-    return helpers.extract_k_path_points(first_band_struct, k_lattice);
-});
-let hovered_band_point = $state(null);
-let bands_x_positions = $state({});
-let hovered_qpoint_index = $derived(hovered_band_point && first_band_struct &&
-    Object.keys(bands_x_positions).length > 0
-    ? helpers.find_qpoint_at_rescaled_x(first_band_struct, hovered_band_point.x, bands_x_positions)
-    : null);
-let hovered_k_point = $derived(hovered_qpoint_index !== null
-    ? k_path_points[hovered_qpoint_index]
-    : null);
-const [desktop_width, tablet_width] = [1200, 600];
-let clientWidth = $state(desktop_width);
-let is_desktop = $derived(clientWidth >= desktop_width);
-let is_mobile = $derived(clientWidth < tablet_width);
-let screen_class = $derived(clientWidth >= desktop_width
-    ? `desktop`
-    : clientWidth >= tablet_width
-        ? `tablet`
-        : `phone`);
-// Synced zoom state (null = use auto-computed range)
-let synced_zoom_range = $state(null);
-let bands_y_axis = $state({});
-let dos_y_axis = $state({});
-// Detect zoom changes and sync between components (runs first to capture child updates)
-$effect(() => {
-    if (!sync_y_zoom || !shared_frequency_range)
-        return;
-    const result = helpers.detect_zoom_change(bands_y_axis.range, dos_y_axis.range, shared_frequency_range, untrack(() => synced_zoom_range), is_desktop);
-    if (result !== undefined)
-        synced_zoom_range = result;
-});
-// Propagate synced range to bands y-axis (untrack current to avoid overwriting child zoom)
-$effect(() => {
-    const base_range = synced_zoom_range ?? shared_frequency_range;
-    const current_range = untrack(() => bands_y_axis.range);
+    const dos_source = `efermi` in (doses as object) ? doses : Object.values(doses)[0]
+    const dos_efermi = (dos_source as Record<string, unknown>)?.efermi
+    return typeof dos_efermi === `number` ? dos_efermi : undefined
+  })
+
+  // Convert fractional k-point coordinates to Cartesian reciprocal space
+  // using the structure's reciprocal lattice (consistent with BZ computation)
+  let k_path_points = $derived.by(() => {
+    if (!first_band_struct?.qpoints || !structure?.lattice?.matrix) return []
+
+    const k_lattice = reciprocal_lattice(structure.lattice.matrix)
+    return helpers.extract_k_path_points(first_band_struct, k_lattice)
+  })
+
+  let hovered_band_point = $state<InternalPoint | null>(null)
+  let bands_x_positions = $state<Record<string, [number, number]>>({})
+  let hovered_qpoint_index = $derived(
+    hovered_band_point && first_band_struct &&
+      Object.keys(bands_x_positions).length > 0
+      ? helpers.find_qpoint_at_rescaled_x(
+        first_band_struct,
+        hovered_band_point.x,
+        bands_x_positions,
+      )
+      : null,
+  )
+  let hovered_k_point = $derived(
+    hovered_qpoint_index !== null
+      ? (k_path_points[hovered_qpoint_index] as Vec3)
+      : null,
+  )
+  const [desktop_width, tablet_width] = [1200, 600]
+  let clientWidth = $state(desktop_width)
+  let is_desktop = $derived(clientWidth >= desktop_width)
+  let is_mobile = $derived(clientWidth < tablet_width)
+  let screen_class = $derived(
+    clientWidth >= desktop_width
+      ? `desktop`
+      : clientWidth >= tablet_width
+      ? `tablet`
+      : `phone`,
+  )
+
+  // Synced zoom state (null = use auto-computed range)
+  let synced_zoom_range = $state<Vec2 | null>(null)
+  let bands_y_axis = $state<AxisConfig>({})
+  let dos_y_axis = $state<AxisConfig>({})
+
+  // Detect zoom changes and sync between components (runs first to capture child updates)
+  $effect(() => {
+    if (!sync_y_zoom || !shared_frequency_range) return
+    const result = helpers.detect_zoom_change(
+      bands_y_axis.range,
+      dos_y_axis.range,
+      shared_frequency_range,
+      untrack(() => synced_zoom_range),
+      is_desktop, // DOS sync only enabled on desktop
+    )
+    if (result !== undefined) synced_zoom_range = result
+  })
+
+  // Propagate synced range to bands y-axis (untrack current to avoid overwriting child zoom)
+  $effect(() => {
+    const base_range = synced_zoom_range ?? shared_frequency_range
+    const current_range = untrack(() => bands_y_axis.range) as Vec2 | undefined
     // Skip if current range already matches base, or is valid but differs (child zoom in progress)
-    if (helpers.ranges_equal(current_range, base_range))
-        return;
-    if (helpers.is_valid_range(current_range) &&
-        !helpers.ranges_equal(current_range, base_range))
-        return;
+    if (helpers.ranges_equal(current_range, base_range)) return
+    if (
+      helpers.is_valid_range(current_range) &&
+      !helpers.ranges_equal(current_range, base_range)
+    ) return
     // Only include range if it's valid (don't override child's auto-range with undefined)
     bands_y_axis = {
-        ...(bands_props.y_axis ?? {}),
-        ...(helpers.is_valid_range(base_range) && { range: base_range }),
-    };
-});
-// Propagate synced range to DOS y-axis (untrack current to avoid overwriting child zoom)
-$effect(() => {
-    const base_range = synced_zoom_range ?? shared_frequency_range;
-    const current_range = untrack(() => dos_y_axis.range);
+      ...(bands_props.y_axis ?? {}),
+      ...(helpers.is_valid_range(base_range) && { range: base_range }),
+    }
+  })
+
+  // Propagate synced range to DOS y-axis (untrack current to avoid overwriting child zoom)
+  $effect(() => {
+    const base_range = synced_zoom_range ?? shared_frequency_range
+    const current_range = untrack(() => dos_y_axis.range) as Vec2 | undefined
     // Skip if current range already matches base, or is valid but differs (child zoom in progress)
-    if (helpers.ranges_equal(current_range, base_range))
-        return;
-    if (helpers.is_valid_range(current_range) &&
-        !helpers.ranges_equal(current_range, base_range))
-        return;
+    if (helpers.ranges_equal(current_range, base_range)) return
+    if (
+      helpers.is_valid_range(current_range) &&
+      !helpers.ranges_equal(current_range, base_range)
+    ) return
     // Only include range if it's valid (don't override child's auto-range with undefined)
     dos_y_axis = is_desktop
-        ? {
-            label: ``,
-            ...(dos_props.y_axis ?? {}),
-            ...(helpers.is_valid_range(base_range) && { range: base_range }),
-        }
-        : { ...(dos_props.y_axis ?? {}) };
-});
-let hovered_frequency = $state(null);
+      ? {
+        label: ``,
+        ...(dos_props.y_axis ?? {}),
+        ...(helpers.is_valid_range(base_range) && { range: base_range }),
+      }
+      : { ...(dos_props.y_axis ?? {}) }
+  })
+
+  let hovered_frequency = $state<number | null>(null)
 </script>
 
 <div