matterviz 0.3.2 → 0.3.3

package/dist/fermi-surface/FermiSurface.svelte

@@ -1,224 +1,364 @@
-<script lang="ts">import { compute_brillouin_zone, reciprocal_lattice } from '../brillouin';
-import { normalize_show_controls } from '../controls';
-import EmptyState from '../EmptyState.svelte';
-import { StatusMessage } from '../feedback';
-import Spinner from '../feedback/Spinner.svelte';
-import Icon from '../Icon.svelte';
-import { create_file_drop_handler, load_from_url } from '../io';
-import { set_fullscreen_bg, toggle_fullscreen } from '../layout';
-import { PlotTooltip } from '../plot';
-import { DEFAULTS } from '../settings';
-import { Canvas } from '@threlte/core';
-import { untrack } from 'svelte';
-import { tooltip } from 'svelte-multiselect/attachments';
-import { detect_irreducible_bz, extract_fermi_surface } from './compute';
-import FermiSurfaceControls from './FermiSurfaceControls.svelte';
-import FermiSurfaceScene from './FermiSurfaceScene.svelte';
-import FermiSurfaceTooltip from './FermiSurfaceTooltip.svelte';
-import { parse_fermi_file } from './parse';
-let { fermi_data = $bindable(), band_data = $bindable(), structure, bz_data = $bindable(), mu = $bindable(0), controls_open = $bindable(false), color_property = $bindable(`band`), color_scale = $bindable(`interpolateViridis`), custom_property_label, representation = $bindable(`solid`), surface_opacity = $bindable(0.8), selected_bands = $bindable(), show_bz = $bindable(true), bz_opacity = $bindable(0.1), show_vectors = $bindable(true), tile_bz = $bindable(false), 
-// Clipping plane
-clip_enabled = $bindable(false), clip_axis = $bindable(`z`), clip_position = $bindable(0), clip_flip = $bindable(false), 
-// Interpolation
-interpolation_factor = $bindable(1), camera_projection = $bindable(`perspective`), show_controls, fullscreen = $bindable(false), wrapper = $bindable(), width = $bindable(0), height = $bindable(0), hovered = $bindable(false), dragover = $bindable(false), allow_file_drop = true, fullscreen_toggle = DEFAULTS.structure.fullscreen_toggle, data_url, spinner_props = {}, loading = $bindable(false), error_msg = $bindable(), children, tooltip_config, on_file_drop, on_file_load, on_error, on_fullscreen_change, on_mu_change, on_hover, ...rest } = $props();
-let scene = $state(undefined);
-let camera = $state(undefined);
-let current_filename = $state(undefined);
-let recompute_job_id = 0; // monotonic counter to track latest recompute call
-let hover_data = $state(null);
-// Call on_hover callback when hover_data changes
-$effect(() => {
-    on_hover?.(hover_data);
-});
-let controls_config = $derived(normalize_show_controls(show_controls));
-// Yield to browser so spinner can render before heavy computation
-const tick = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => r())));
-// Parse and load Fermi surface from content (async for UI responsiveness)
-async function parse_fermi_content(content, filename) {
+<script lang="ts">
+  import type { BrillouinZoneData } from '../brillouin'
+  import { compute_brillouin_zone, reciprocal_lattice } from '../brillouin'
+  import type { ShowControlsProp } from '../controls'
+  import { normalize_show_controls } from '../controls'
+  import EmptyState from '../EmptyState.svelte'
+  import { StatusMessage } from '../feedback'
+  import Spinner from '../feedback/Spinner.svelte'
+  import Icon from '../Icon.svelte'
+  import { create_file_drop_handler, load_from_url } from '../io'
+  import { set_fullscreen_bg, toggle_fullscreen } from '../layout'
+  import { PlotTooltip } from '../plot'
+  import type { CameraProjection } from '../settings'
+  import { DEFAULTS } from '../settings'
+  import type { Crystal } from '../structure'
+  import { Canvas } from '@threlte/core'
+  import type { ComponentProps, Snippet } from 'svelte'
+  import { untrack } from 'svelte'
+  import { tooltip } from 'svelte-multiselect/attachments'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import type { Camera, Scene } from 'three'
+  import { detect_irreducible_bz, extract_fermi_surface } from './compute'
+  import FermiSurfaceControls from './FermiSurfaceControls.svelte'
+  import FermiSurfaceScene from './FermiSurfaceScene.svelte'
+  import FermiSurfaceTooltip from './FermiSurfaceTooltip.svelte'
+  import { parse_fermi_file } from './parse'
+  import type {
+    BandGridData,
+    ColorProperty,
+    FermiErrorData,
+    FermiFileLoadData,
+    FermiHoverData,
+    FermiSurfaceData,
+    FermiTooltipConfig,
+    RepresentationMode,
+  } from './types'
+
+  type FermiHandlerData = {
+    fermi_data?: FermiSurfaceData
+    band_data?: BandGridData
+    bz_data?: BrillouinZoneData
+    filename?: string
+    file_size?: number
+    error_msg?: string
+    fullscreen?: boolean
+  }
+
+  let {
+    fermi_data = $bindable(),
+    band_data = $bindable(),
+    structure,
+    bz_data = $bindable(),
+    mu = $bindable(0),
+    controls_open = $bindable(false),
+    color_property = $bindable(`band`),
+    color_scale = $bindable(`interpolateViridis`),
+    custom_property_label,
+    representation = $bindable(`solid`),
+    surface_opacity = $bindable(0.8),
+    selected_bands = $bindable(),
+    show_bz = $bindable(true),
+    bz_opacity = $bindable(0.1),
+    show_vectors = $bindable(true),
+    tile_bz = $bindable(false),
+    // Clipping plane
+    clip_enabled = $bindable(false),
+    clip_axis = $bindable(`z`),
+    clip_position = $bindable(0),
+    clip_flip = $bindable(false),
+    // Interpolation
+    interpolation_factor = $bindable(1),
+    camera_projection = $bindable(`perspective`),
+    show_controls,
+    fullscreen = $bindable(false),
+    wrapper = $bindable(),
+    width = $bindable(0),
+    height = $bindable(0),
+    hovered = $bindable(false),
+    dragover = $bindable(false),
+    allow_file_drop = true,
+    fullscreen_toggle = DEFAULTS.structure.fullscreen_toggle,
+    data_url,
+    spinner_props = {},
+    loading = $bindable(false),
+    error_msg = $bindable(),
+    children,
+    tooltip_config,
+    on_file_drop,
+    on_file_load,
+    on_error,
+    on_fullscreen_change,
+    on_mu_change,
+    on_hover,
+    ...rest
+  }: {
+    fermi_data?: FermiSurfaceData
+    band_data?: BandGridData
+    structure?: Crystal
+    bz_data?: BrillouinZoneData
+    mu?: number
+    controls_open?: boolean
+    color_property?: ColorProperty
+    color_scale?: string
+    // Label for custom property coloring (e.g. "λ(k)", "DOS", etc.)
+    custom_property_label?: string
+    representation?: RepresentationMode
+    surface_opacity?: number
+    selected_bands?: number[]
+    show_bz?: boolean
+    bz_opacity?: number
+    show_vectors?: boolean
+    tile_bz?: boolean
+    clip_enabled?: boolean
+    clip_axis?: `x` | `y` | `z`
+    clip_position?: number
+    clip_flip?: boolean
+    interpolation_factor?: number
+    camera_projection?: CameraProjection
+    /**
+     * Controls visibility configuration.
+     * - 'always': controls always visible
+     * - 'hover': controls visible on component hover (default)
+     * - 'never': controls never visible
+     * - object: { mode, hidden, style } for fine-grained control
+     *
+     * Control names: 'filename', 'fullscreen', 'controls'
+     */
+    show_controls?: ShowControlsProp
+    fullscreen?: boolean
+    width?: number
+    height?: number
+    wrapper?: HTMLDivElement
+    hovered?: boolean
+    dragover?: boolean
+    allow_file_drop?: boolean
+    fullscreen_toggle?: Snippet<[{ fullscreen: boolean }]> | boolean
+    data_url?: string
+    spinner_props?: ComponentProps<typeof Spinner>
+    loading?: boolean
+    error_msg?: string
+    children?: Snippet<
+      [{ fermi_data?: FermiSurfaceData; bz_data?: BrillouinZoneData }]
+    >
+    on_file_drop?: (filename: string) => void
+    on_file_load?: (data: FermiFileLoadData) => void
+    on_error?: (data: FermiErrorData) => void
+    on_fullscreen_change?: (data: FermiHandlerData) => void
+    on_mu_change?: (mu: number) => void
+    tooltip_config?: Snippet<[{ hover_data: FermiHoverData }]> | FermiTooltipConfig
+    on_hover?: (data: FermiHoverData | null) => void
+  } & HTMLAttributes<HTMLDivElement> = $props()
+
+  let scene = $state<Scene | undefined>(undefined)
+  let camera = $state<Camera | undefined>(undefined)
+  let current_filename = $state<string | undefined>(undefined)
+  let recompute_job_id = 0 // monotonic counter to track latest recompute call
+  let hover_data = $state<FermiHoverData | null>(null)
+
+  // Call on_hover callback when hover_data changes
+  $effect(() => {
+    on_hover?.(hover_data)
+  })
+
+  let controls_config = $derived(normalize_show_controls(show_controls))
+
+  // Yield to browser so spinner can render before heavy computation
+  const tick = () =>
+    new Promise<void>((r) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => r()))
+    )
+
+  // Parse and load Fermi surface from content (async for UI responsiveness)
+  async function parse_fermi_content(
+    content: string | ArrayBuffer,
+    filename: string,
+  ) {
     const text = content instanceof ArrayBuffer
-        ? new TextDecoder().decode(content)
-        : content;
-    const parsed = parse_fermi_file(text, filename);
-    if (!parsed)
-        throw new Error(`Failed to parse Fermi surface from ${filename}`);
-    const file_size = new Blob([content]).size;
-    current_filename = filename;
+      ? new TextDecoder().decode(content)
+      : content
+
+    const parsed = parse_fermi_file(text, filename)
+    if (!parsed) throw new Error(`Failed to parse Fermi surface from ${filename}`)
+
+    const file_size = new Blob([content]).size
+    current_filename = filename
+
     // Check if it's already FermiSurfaceData or BandGridData
     if (`isosurfaces` in parsed) {
-        fermi_data = parsed;
-        band_data = undefined;
-    }
-    else {
-        band_data = parsed;
-        fermi_data = extract_fermi_surface(band_data, { mu, wigner_seitz: true });
+      fermi_data = parsed as FermiSurfaceData
+      band_data = undefined
+    } else {
+      band_data = parsed as BandGridData
+      fermi_data = extract_fermi_surface(band_data, { mu, wigner_seitz: true })
     }
-    on_file_load?.({ fermi_data, band_data, filename, file_size });
-}
-// Load with error handling
-async function safe_parse(content, filename) {
+
+    on_file_load?.({ fermi_data, band_data, filename, file_size })
+  }
+
+  // Load with error handling
+  async function safe_parse(content: string | ArrayBuffer, filename: string) {
     try {
-        await parse_fermi_content(content, filename);
-    }
-    catch (err) {
-        error_msg = `Failed to parse ${filename}: ${err instanceof Error ? err.message : err}`;
-        on_error?.({ error_msg, filename });
+      await parse_fermi_content(content, filename)
+    } catch (err) {
+      error_msg = `Failed to parse ${filename}: ${
+        err instanceof Error ? err.message : err
+      }`
+      on_error?.({ error_msg, filename })
     }
-}
-// Re-extract Fermi surface from band data with current settings
-async function recompute_fermi_surface() {
-    if (!band_data)
-        return;
-    const job_id = ++recompute_job_id; // capture this job's ID
-    await tick(); // yield to check for newer jobs before committing to work
+  }
+
+  // Re-extract Fermi surface from band data with current settings
+  async function recompute_fermi_surface() {
+    if (!band_data) return
+    const job_id = ++recompute_job_id // capture this job's ID
+    await tick() // yield to check for newer jobs before committing to work
     // Check if this job is still the latest before proceeding
     // If stale, return without setting loading - the superseding job handles it
-    if (job_id !== recompute_job_id)
-        return;
+    if (job_id !== recompute_job_id) return
     // Only set loading after stale check to avoid orphaned loading states
-    loading = true;
+    loading = true
     try {
-        const result = extract_fermi_surface(band_data, {
-            mu,
-            wigner_seitz: true,
-            interpolation_factor,
-        });
-        // Only update state if this is still the latest job
-        if (job_id === recompute_job_id) {
-            fermi_data = result;
-        }
-    }
-    catch (err) {
-        console.error(`Failed to re-extract Fermi surface:`, err);
+      const result = extract_fermi_surface(band_data, {
+        mu,
+        wigner_seitz: true,
+        interpolation_factor,
+      })
+      // Only update state if this is still the latest job
+      if (job_id === recompute_job_id) {
+        fermi_data = result
+      }
+    } catch (err) {
+      console.error(`Failed to re-extract Fermi surface:`, err)
+    } finally {
+      // Only clear loading if this is still the latest job
+      if (job_id === recompute_job_id) loading = false
     }
-    finally {
-        // Only clear loading if this is still the latest job
-        if (job_id === recompute_job_id)
-            loading = false;
-    }
-}
-// Debounce recompute to avoid excessive re-computation during rapid slider drags
-let recompute_timeout;
-function handle_mu_change(new_mu) {
-    mu = new_mu;
-    clearTimeout(recompute_timeout);
-    recompute_timeout = setTimeout(() => void recompute_fermi_surface(), 150);
-    on_mu_change?.(new_mu);
-}
-function handle_interpolation_change(new_factor) {
-    interpolation_factor = new_factor;
-    clearTimeout(recompute_timeout);
-    recompute_timeout = setTimeout(() => void recompute_fermi_surface(), 150);
-}
-// Export Fermi surface to various formats
-async function handle_export(format) {
+  }
+
+  // Debounce recompute to avoid excessive re-computation during rapid slider drags
+  let recompute_timeout: ReturnType<typeof setTimeout>
+
+  function handle_mu_change(new_mu: number) {
+    mu = new_mu
+    clearTimeout(recompute_timeout)
+    recompute_timeout = setTimeout(() => void recompute_fermi_surface(), 150)
+    on_mu_change?.(new_mu)
+  }
+
+  function handle_interpolation_change(new_factor: number) {
+    interpolation_factor = new_factor
+    clearTimeout(recompute_timeout)
+    recompute_timeout = setTimeout(() => void recompute_fermi_surface(), 150)
+  }
+
+  // Export Fermi surface to various formats
+  async function handle_export(format: `stl` | `obj` | `gltf`) {
     if (!scene) {
-        console.error(`No scene available for export`);
-        return;
+      console.error(`No scene available for export`)
+      return
     }
     try {
-        const { export_scene } = await import(`./export`);
-        await export_scene(scene, format, current_filename || `fermi-surface`);
+      const { export_scene } = await import(`./export`)
+      await export_scene(scene, format, current_filename || `fermi-surface`)
+    } catch (err) {
+      console.error(`Export failed:`, err)
+      error_msg = `Export failed: ${err instanceof Error ? err.message : err}`
     }
-    catch (err) {
-        console.error(`Export failed:`, err);
-        error_msg = `Export failed: ${err instanceof Error ? err.message : err}`;
-    }
-}
-// Compute BZ when structure or fermi_data changes
-$effect(() => {
+  }
+
+  // Compute BZ when structure or fermi_data changes
+  $effect(() => {
     // Get k_lattice from available sources (priority order)
     const k_lattice = fermi_data?.k_lattice ??
-        band_data?.k_lattice ??
-        (structure?.lattice?.matrix
-            ? reciprocal_lattice(structure.lattice.matrix)
-            : null);
+      band_data?.k_lattice ??
+      (structure?.lattice?.matrix
+        ? reciprocal_lattice(structure.lattice.matrix)
+        : null)
+
     if (!k_lattice) {
-        bz_data = undefined;
-        return;
+      bz_data = undefined
+      return
     }
+
     try {
-        bz_data = compute_brillouin_zone(k_lattice, 1);
+      bz_data = compute_brillouin_zone(k_lattice, 1)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      console.warn(`BZ computation failed:`, msg)
+      bz_data = undefined
+      // Only report error for structure-derived lattice (user-provided data)
+      if (structure?.lattice?.matrix) {
+        const err_msg = `BZ computation failed: ${msg}`
+        error_msg = err_msg
+        untrack(() => on_error?.({ error_msg: err_msg }))
+      }
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`BZ computation failed:`, msg);
-        bz_data = undefined;
-        // Only report error for structure-derived lattice (user-provided data)
-        if (structure?.lattice?.matrix) {
-            const err_msg = `BZ computation failed: ${msg}`;
-            error_msg = err_msg;
-            untrack(() => on_error?.({ error_msg: err_msg }));
-        }
-    }
-});
-// Auto-enable BZ tiling when irreducible data is detected
-$effect(() => {
+  })
+
+  // Auto-enable BZ tiling when irreducible data is detected
+  $effect(() => {
     if (fermi_data && detect_irreducible_bz(fermi_data)) {
-        tile_bz = true;
+      tile_bz = true
     }
-});
-// Load from URL (with race condition protection for rapid URL changes)
-let load_id = 0;
-$effect(() => {
+  })
+
+  // Load from URL (with race condition protection for rapid URL changes)
+  let load_id = 0
+  $effect(() => {
     if (data_url && !fermi_data && !band_data) {
-        const current_load_id = ++load_id;
-        loading = true;
-        error_msg = undefined;
-        load_from_url(data_url, safe_parse)
-            .catch((err) => {
-            if (current_load_id !== load_id)
-                return; // stale request
-            error_msg = err instanceof Error ? err.message : String(err);
-            on_error?.({ error_msg, filename: data_url });
+      const current_load_id = ++load_id
+      loading = true
+      error_msg = undefined
+      load_from_url(data_url, safe_parse)
+        .catch((err) => {
+          if (current_load_id !== load_id) return // stale request
+          error_msg = err instanceof Error ? err.message : String(err)
+          on_error?.({ error_msg, filename: data_url })
+        })
+        .finally(() => {
+          if (current_load_id === load_id) loading = false
         })
-            .finally(() => {
-            if (current_load_id === load_id)
-                loading = false;
-        });
     }
-});
-const handle_file_drop = create_file_drop_handler({
+  })
+
+  const handle_file_drop = create_file_drop_handler({
     allow: () => allow_file_drop,
     on_drop: async (content, filename) => {
-        on_file_drop?.(filename);
-        await safe_parse(content, filename);
+      on_file_drop?.(filename)
+      await safe_parse(content, filename)
     },
     on_error: (msg) => {
-        error_msg = msg;
-        on_error?.({ error_msg: msg });
+      error_msg = msg
+      on_error?.({ error_msg: msg })
     },
     set_loading: (val) => {
-        loading = val;
-        if (val)
-            [error_msg, dragover] = [undefined, false];
+      loading = val
+      if (val) [error_msg, dragover] = [undefined, false]
     },
-});
-function handle_keydown(event) {
-    const target = event.target;
-    if ([`INPUT`, `TEXTAREA`].includes(target.tagName))
-        return;
+  })
+
+  function handle_keydown(event: KeyboardEvent) {
+    const target = event.target as HTMLElement
+    if ([`INPUT`, `TEXTAREA`].includes(target.tagName)) return
     // Only handle shortcuts when component is focused/hovered or contains focus
-    if (!wrapper?.contains(document.activeElement) && !hovered)
-        return;
-    if (event.key === `f` && fullscreen_toggle)
-        toggle_fullscreen(wrapper);
-    else if (event.key === `Escape`)
-        controls_open = false;
-}
-$effect(() => {
-    if (typeof window === `undefined`)
-        return;
-    const fs_el = document.fullscreenElement;
+    if (!wrapper?.contains(document.activeElement) && !hovered) return
+
+    if (event.key === `f` && fullscreen_toggle) toggle_fullscreen(wrapper)
+    else if (event.key === `Escape`) controls_open = false
+  }
+
+  $effect(() => {
+    if (typeof window === `undefined`) return
+    const fs_el = document.fullscreenElement
     if (fullscreen && fs_el !== wrapper && wrapper) {
-        wrapper.requestFullscreen().catch((err) => {
-            console.error(err);
-            fullscreen = false;
-        });
-    }
-    else if (!fullscreen && fs_el === wrapper)
-        document.exitFullscreen();
-    set_fullscreen_bg(wrapper, fullscreen, `--fermi-bg-fullscreen`);
-});
+      wrapper.requestFullscreen().catch((err) => {
+        console.error(err)
+        fullscreen = false
+      })
+    } else if (!fullscreen && fs_el === wrapper) document.exitFullscreen()
+    set_fullscreen_bg(wrapper, fullscreen, `--fermi-bg-fullscreen`)
+  })
 </script>
 
 <svelte:window onkeydown={handle_keydown} />
@@ -427,7 +567,8 @@ $effect(() => {
     pointer-events: auto;
   }
   /* Mode: hover - controls visible on component hover */
-  .fermi-surface:hover section.control-buttons.hover-visible {
+  .fermi-surface:hover section.control-buttons.hover-visible,
+  .fermi-surface:focus-within section.control-buttons.hover-visible {
     opacity: 1;
     pointer-events: auto;
   }

package/dist/fermi-surface/FermiSurface.svelte.d.ts

@@ -78,6 +78,6 @@ type $$ComponentProps = {
     }]> | FermiTooltipConfig;
     on_hover?: (data: FermiHoverData | null) => void;
 } & HTMLAttributes<HTMLDivElement>;
-declare const FermiSurface: import("svelte").Component<$$ComponentProps, {}, "height" | "width" | "dragover" | "color_scale" | "controls_open" | "loading" | "fullscreen" | "hovered" | "camera_projection" | "wrapper" | "error_msg" | "surface_opacity" | "show_vectors" | "bz_data" | "mu" | "selected_bands" | "interpolation_factor" | "fermi_data" | "band_data" | "color_property" | "representation" | "show_bz" | "bz_opacity" | "tile_bz" | "clip_enabled" | "clip_axis" | "clip_position" | "clip_flip">;
+declare const FermiSurface: import("svelte").Component<$$ComponentProps, {}, "height" | "width" | "dragover" | "fullscreen" | "hovered" | "controls_open" | "loading" | "camera_projection" | "color_scale" | "wrapper" | "error_msg" | "surface_opacity" | "show_vectors" | "bz_data" | "mu" | "selected_bands" | "interpolation_factor" | "fermi_data" | "band_data" | "color_property" | "representation" | "show_bz" | "bz_opacity" | "tile_bz" | "clip_enabled" | "clip_axis" | "clip_position" | "clip_flip">;
 type FermiSurface = ReturnType<typeof FermiSurface>;
 export default FermiSurface;