matterviz 0.3.1 → 0.3.3

package/dist/brillouin/BrillouinZone.svelte

@@ -1,189 +1,317 @@
-<script lang="ts">import { toggle_fullscreen } from '../layout';
-import { normalize_show_controls } from '../controls';
-import EmptyState from '../EmptyState.svelte';
-import Spinner from '../feedback/Spinner.svelte';
-import Icon from '../Icon.svelte';
-import { decompress_file, handle_url_drop, load_from_url } from '../io';
-import { set_fullscreen_bg } from '../layout';
-import { DEFAULTS } from '../settings';
-import { parse_any_structure } from '../structure/parse';
-import { analyze_structure_symmetry } from '../symmetry';
-import { Canvas } from '@threlte/core';
-import { untrack } from 'svelte';
-import { tooltip } from 'svelte-multiselect/attachments';
-import { PlotTooltip } from '../plot';
-import BrillouinZoneControls from './BrillouinZoneControls.svelte';
-import BrillouinZoneExportPane from './BrillouinZoneExportPane.svelte';
-import BrillouinZoneInfoPane from './BrillouinZoneInfoPane.svelte';
-import BrillouinZoneScene from './BrillouinZoneScene.svelte';
-import BrillouinZoneTooltip from './BrillouinZoneTooltip.svelte';
-import { compute_brillouin_zone, compute_irreducible_bz, extract_point_group_from_operations, reciprocal_lattice, } from './compute';
-let { structure = $bindable(), bz_order = $bindable(1), bz_data = $bindable(), controls_open = $bindable(false), info_pane_open = $bindable(false), surface_color = $bindable(`#4488ff`), surface_opacity = $bindable(0.3), edge_color = $bindable(`#000000`), edge_width = $bindable(0.05), show_vectors = $bindable(true), vector_scale = $bindable(1.0), camera_projection = $bindable(`perspective`), 
-// Irreducible BZ options
-show_ibz = $bindable(false), ibz_color = $bindable(`#ff8844`), ibz_opacity = $bindable(0.5), ibz_data = $bindable(null), show_controls, fullscreen = $bindable(false), wrapper = $bindable(), width = $bindable(0), height = $bindable(0), hovered = $bindable(false), dragover = $bindable(false), allow_file_drop = true, png_dpi = $bindable(150), fullscreen_toggle = DEFAULTS.structure.fullscreen_toggle, data_url, structure_string, on_file_drop, spinner_props = {}, loading = $bindable(false), error_msg = $bindable(), k_path_points = [], k_path_labels = [], hovered_k_point = null, hovered_qpoint_index = null, children, tooltip_config, on_file_load, on_error, on_fullscreen_change, on_hover, ...rest } = $props();
-let scene = $state(undefined);
-let camera = $state(undefined);
-let export_pane_open = $state(false);
-let current_filename = $state(undefined);
-let hover_data = $state(null);
-// Call on_hover callback when hover_data changes
-$effect(() => {
-    on_hover?.(hover_data);
-});
-// Normalize show_controls prop into consistent config
-let controls_config = $derived(normalize_show_controls(show_controls));
-// Parse and load structure from content
-function parse_structure(content, filename) {
+<script lang="ts">
+  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 type { Vec3 } from '../math'
+  import { PlotTooltip } from '../plot'
+  import { type CameraProjection, DEFAULTS } from '../settings'
+  import type { Crystal } from '../structure'
+  import { parse_any_structure } from '../structure/parse'
+  import { analyze_structure_symmetry } from '../symmetry'
+  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 BrillouinZoneControls from './BrillouinZoneControls.svelte'
+  import BrillouinZoneExportPane from './BrillouinZoneExportPane.svelte'
+  import BrillouinZoneInfoPane from './BrillouinZoneInfoPane.svelte'
+  import BrillouinZoneScene from './BrillouinZoneScene.svelte'
+  import BrillouinZoneTooltip from './BrillouinZoneTooltip.svelte'
+  import {
+    compute_brillouin_zone,
+    compute_irreducible_bz,
+    extract_point_group_from_operations,
+    reciprocal_lattice,
+  } from './compute'
+  import type {
+    BrillouinZoneData,
+    BZHoverData,
+    BZTooltipProp,
+    IrreducibleBZData,
+  } from './types'
+
+  type BZHandlerData = {
+    structure?: Crystal
+    bz_data?: BrillouinZoneData
+    bz_order?: number
+    filename?: string
+    file_size?: number
+    error_msg?: string
+    fullscreen?: boolean
+  }
+  let {
+    structure = $bindable(),
+    bz_order = $bindable(1),
+    bz_data = $bindable(),
+    controls_open = $bindable(false),
+    info_pane_open = $bindable(false),
+    surface_color = $bindable(`#4488ff`),
+    surface_opacity = $bindable(0.3),
+    edge_color = $bindable(`#000000`),
+    edge_width = $bindable(0.05),
+    show_vectors = $bindable(true),
+    vector_scale = $bindable(1.0),
+    camera_projection = $bindable(`perspective`),
+    // Irreducible BZ options
+    show_ibz = $bindable(false),
+    ibz_color = $bindable(`#ff8844`),
+    ibz_opacity = $bindable(0.5),
+    ibz_data = $bindable<IrreducibleBZData | null>(null),
+    show_controls,
+    fullscreen = $bindable(false),
+    wrapper = $bindable(),
+    width = $bindable(0),
+    height = $bindable(0),
+    hovered = $bindable(false),
+    dragover = $bindable(false),
+    allow_file_drop = true,
+    png_dpi = $bindable(150),
+    fullscreen_toggle = DEFAULTS.structure.fullscreen_toggle,
+    data_url,
+    structure_string,
+    on_file_drop,
+    spinner_props = {},
+    loading = $bindable(false),
+    error_msg = $bindable(),
+    k_path_points = [],
+    k_path_labels = [],
+    hovered_k_point = null,
+    hovered_qpoint_index = null,
+    children,
+    tooltip_config,
+    on_file_load,
+    on_error,
+    on_fullscreen_change,
+    on_hover,
+    ...rest
+  }:
+    & {
+      structure?: Crystal
+      bz_order?: number
+      bz_data?: BrillouinZoneData
+      controls_open?: boolean
+      info_pane_open?: boolean
+      surface_color?: string
+      surface_opacity?: number
+      edge_color?: string
+      edge_width?: number
+      show_vectors?: boolean
+      vector_scale?: number
+      camera_projection?: CameraProjection
+      // Irreducible BZ options
+      show_ibz?: boolean
+      ibz_color?: string
+      ibz_opacity?: number
+      ibz_data?: IrreducibleBZData | null
+      /**
+       * 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', 'info-pane', 'export-pane', 'controls'
+       */
+      show_controls?: ShowControlsProp
+      fullscreen?: boolean
+      width?: number
+      height?: number
+      wrapper?: HTMLDivElement
+      png_dpi?: number
+      hovered?: boolean
+      dragover?: boolean
+      allow_file_drop?: boolean
+      fullscreen_toggle?: Snippet<[{ fullscreen: boolean }]> | boolean
+      data_url?: string
+      on_file_drop?: (content: string | ArrayBuffer, filename: string) => void
+      spinner_props?: ComponentProps<typeof Spinner>
+      loading?: boolean
+      error_msg?: string
+      structure_string?: string
+      // K-path points in Cartesian reciprocal space coordinates (not fractional coords)
+      // Should be computed using the reciprocal lattice matrix (includes 2π factor)
+      k_path_points?: Vec3[]
+      // K-path labels with positions in Cartesian reciprocal space coordinates
+      // Each position should match a corresponding point in k_path_points
+      k_path_labels?: { position: Vec3; label: string | null }[]
+      // Currently hovered k-point in Cartesian reciprocal space coordinates
+      hovered_k_point?: Vec3 | null
+      // Index of the currently hovered q-point in the band structure
+      hovered_qpoint_index?: number | null
+      children?: Snippet<
+        [{ structure?: Crystal; bz_data?: BrillouinZoneData }]
+      >
+      tooltip_config?: BZTooltipProp
+      on_file_load?: (data: BZHandlerData) => void
+      on_error?: (data: BZHandlerData) => void
+      on_fullscreen_change?: (data: BZHandlerData) => void
+      on_hover?: (data: BZHoverData | null) => void
+    }
+    & HTMLAttributes<HTMLDivElement> = $props()
+
+  let scene = $state(undefined)
+  let camera = $state(undefined)
+  let export_pane_open = $state(false)
+  let current_filename = $state<string | undefined>(undefined)
+  let hover_data = $state<BZHoverData | null>(null)
+
+  // Call on_hover callback when hover_data changes
+  $effect(() => {
+    on_hover?.(hover_data)
+  })
+
+  // Normalize show_controls prop into consistent config
+  let controls_config = $derived(normalize_show_controls(show_controls))
+
+  // Parse and load structure from content
+  function parse_structure(content: string | ArrayBuffer, filename: string) {
     const text = content instanceof ArrayBuffer
-        ? new TextDecoder().decode(content)
-        : content;
-    const parsed = parse_any_structure(text, filename);
-    if (!parsed)
-        throw new Error(`Failed to parse structure from ${filename}`);
-    structure = parsed;
-    current_filename = filename;
-    const file_size = new Blob([content]).size;
-    on_file_load?.({ structure, bz_data, bz_order, filename, file_size });
-}
-// Load with error handling
-function safe_parse(content, filename) {
+      ? new TextDecoder().decode(content)
+      : content
+    const parsed = parse_any_structure(text, filename)
+    if (!parsed) throw new Error(`Failed to parse structure from ${filename}`)
+
+    structure = parsed as Crystal
+    current_filename = filename
+    const file_size = new Blob([content]).size
+    on_file_load?.({ structure, bz_data, bz_order, filename, file_size })
+  }
+
+  // Load with error handling
+  function safe_parse(content: string | ArrayBuffer, filename: string) {
     try {
-        parse_structure(content, filename);
-    }
-    catch (err) {
-        error_msg = `Failed to parse ${filename}: ${err instanceof Error ? err.message : err}`;
-        on_error?.({ error_msg, filename });
+      parse_structure(content, filename)
+    } catch (err) {
+      error_msg = `Failed to parse ${filename}: ${
+        err instanceof Error ? err.message : err
+      }`
+      on_error?.({ error_msg, filename })
     }
-}
-// Compute BZ when structure/order changes
-$effect(() => {
+  }
+
+  // Compute BZ when structure/order changes
+  $effect(() => {
     // Skip if bz_data was already provided externally (has valid vertices)
-    if (bz_data?.vertices?.length)
-        return;
+    if (bz_data?.vertices?.length) return
+
     if (!structure || !(`lattice` in structure) || !structure.lattice) {
-        bz_data = undefined;
-        return;
+      bz_data = undefined
+      return
     }
+
     try {
-        const k_lattice = reciprocal_lattice(structure.lattice.matrix);
-        // Ensure bz_order is 1, 2, or 3
-        const valid_order = Math.min(Math.max(1, bz_order), 3);
-        bz_data = compute_brillouin_zone(k_lattice, valid_order);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        error_msg = `BZ computation failed: ${msg}`;
-        bz_data = undefined;
-        untrack(() => on_error?.({ error_msg, structure, bz_order }));
+      const k_lattice = reciprocal_lattice(structure.lattice.matrix)
+      // Ensure bz_order is 1, 2, or 3
+      const valid_order = Math.min(Math.max(1, bz_order), 3) as 1 | 2 | 3
+      bz_data = compute_brillouin_zone(k_lattice, valid_order)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      error_msg = `BZ computation failed: ${msg}`
+      bz_data = undefined
+      untrack(() => on_error?.({ error_msg, structure, bz_order }))
     }
-});
-// Compute IBZ when show_ibz is enabled and structure changes
-$effect(() => {
+  })
+
+  // Compute IBZ when show_ibz is enabled and structure changes
+  $effect(() => {
     if (!show_ibz || !bz_data || !structure?.lattice) {
-        ibz_data = null;
-        return;
+      ibz_data = null
+      return
     }
-    let stale = false;
-    const captured_bz = bz_data;
+
+    let stale = false
+    const captured_bz = bz_data
+
     analyze_structure_symmetry(structure, {})
-        .then((sym_data) => {
-        if (stale)
-            return;
-        const point_group_ops = extract_point_group_from_operations(sym_data.operations);
-        ibz_data = compute_irreducible_bz(captured_bz, point_group_ops);
-    })
-        .catch((err) => {
-        if (stale)
-            return;
-        console.warn(`IBZ computation failed:`, err);
-        ibz_data = null;
-    });
+      .then((sym_data) => {
+        if (stale) return
+        const point_group_ops = extract_point_group_from_operations(
+          sym_data.operations,
+        )
+        ibz_data = compute_irreducible_bz(captured_bz, point_group_ops)
+      })
+      .catch((err) => {
+        if (stale) return
+        console.warn(`IBZ computation failed:`, err)
+        ibz_data = null
+      })
+
     return () => {
-        stale = true;
-    };
-});
-// Load structure from URL or string
-$effect(() => {
-    const handle_error = (err, source) => {
-        error_msg = err instanceof Error ? err.message : String(err);
-        on_error?.({ error_msg, filename: source });
-    };
-    if (data_url && !structure) {
-        loading = true;
-        error_msg = undefined;
-        load_from_url(data_url, (content, filename) => on_file_drop
-            ? on_file_drop(content, filename)
-            : safe_parse(content, filename))
-            .catch((err) => handle_error(err, data_url))
-            .finally(() => (loading = false));
+      stale = true
     }
-    else if (structure_string && !data_url) {
-        loading = true;
-        error_msg = undefined;
-        try {
-            safe_parse(structure_string, `string`);
-        }
-        catch (err) {
-            handle_error(err, `string`);
-        }
-        finally {
-            loading = false;
-        }
-    }
-});
-async function handle_file_drop(event) {
-    event.preventDefault();
-    dragover = false;
-    if (!allow_file_drop)
-        return;
-    loading = true;
-    error_msg = undefined;
-    try {
-        const handler = on_file_drop || safe_parse;
-        const handled = await handle_url_drop(event, handler).catch(() => false);
-        if (handled)
-            return;
-        const file = event.dataTransfer?.files[0];
-        if (file) {
-            const { content, filename } = await decompress_file(file);
-            if (content)
-                handler(content, filename);
-        }
-    }
-    catch (err) {
-        error_msg = `File drop failed: ${err}`;
-        on_error?.({ error_msg });
+  })
+
+  // Load structure from URL or string
+  $effect(() => {
+    const handle_error = (err: unknown, source: string) => {
+      error_msg = err instanceof Error ? err.message : String(err)
+      on_error?.({ error_msg, filename: source })
     }
-    finally {
-        loading = false;
+
+    if (data_url && !structure) {
+      loading = true
+      error_msg = undefined
+      load_from_url(
+        data_url,
+        (content, filename) =>
+          on_file_drop
+            ? on_file_drop(content, filename)
+            : safe_parse(content, filename),
+      )
+        .catch((err) => handle_error(err, data_url))
+        .finally(() => (loading = false))
+    } else if (structure_string && !data_url) {
+      loading = true
+      error_msg = undefined
+      try {
+        safe_parse(structure_string, `string`)
+      } catch (err) {
+        handle_error(err, `string`)
+      } finally {
+        loading = false
+      }
     }
-}
-function onkeydown(event) {
-    const target = event.target;
-    if (target.tagName === `INPUT` || target.tagName === `TEXTAREA`)
-        return;
-    if (event.key === `f` && fullscreen_toggle)
-        toggle_fullscreen(wrapper);
-    else if (event.key === `i`)
-        info_pane_open = !info_pane_open;
+  })
+
+  const handle_file_drop = create_file_drop_handler({
+    allow: () => allow_file_drop,
+    on_drop: (content, filename) => (on_file_drop || safe_parse)(content, filename),
+    on_error: (msg) => {
+      error_msg = msg
+      on_error?.({ error_msg: msg })
+    },
+    set_loading: (val) => {
+      loading = val
+      if (val) [error_msg, dragover] = [undefined, false]
+    },
+  })
+
+  function onkeydown(event: KeyboardEvent) {
+    const target = event.target as HTMLElement
+    if (target.tagName === `INPUT` || target.tagName === `TEXTAREA`) return
+
+    if (event.key === `f` && fullscreen_toggle) toggle_fullscreen(wrapper)
+    else if (event.key === `i`) info_pane_open = !info_pane_open
     else if (event.key === `Escape`) {
-        if (info_pane_open)
-            info_pane_open = false;
-        else
-            controls_open = false;
+      if (info_pane_open) info_pane_open = false
+      else controls_open = false
     }
-}
-$effect(() => {
-    if (typeof window === `undefined`)
-        return;
-    const fs_el = document.fullscreenElement;
+  }
+
+  $effect(() => { // fullscreen and background
+    if (typeof window === `undefined`) return
+    const fs_el = document.fullscreenElement
     if (fullscreen && fs_el !== wrapper && wrapper) {
-        wrapper.requestFullscreen().catch(console.error);
-    }
-    else if (!fullscreen && fs_el === wrapper)
-        document.exitFullscreen();
-    set_fullscreen_bg(wrapper, fullscreen, `--bz-bg-fullscreen`);
-});
+      wrapper.requestFullscreen().catch(console.error)
+    } else if (!fullscreen && fs_el === wrapper) document.exitFullscreen()
+    set_fullscreen_bg(wrapper, fullscreen, `--bz-bg-fullscreen`)
+  })
 </script>
 
 <svelte:document
@@ -221,10 +349,7 @@ $effect(() => {
   {#if loading}
     <Spinner text="Loading structure..." {...spinner_props} />
   {:else if error_msg}
-    <div class="error-state">
-      <p class="error">{error_msg}</p>
-      <button onclick={() => (error_msg = undefined)}>Dismiss</button>
-    </div>
+    <StatusMessage bind:message={error_msg} type="error" dismissible />
   {:else if structure && `lattice` in structure}
     <section
       class="control-buttons {controls_config.class}"
@@ -384,7 +509,8 @@ $effect(() => {
     pointer-events: auto;
   }
   /* Mode: hover - controls visible on component hover */
-  .brillouin-zone:hover section.control-buttons.hover-visible {
+  .brillouin-zone:hover section.control-buttons.hover-visible,
+  .brillouin-zone:focus-within section.control-buttons.hover-visible {
     opacity: 1;
     pointer-events: auto;
   }
@@ -414,29 +540,4 @@ $effect(() => {
     text-align: center;
     padding: 2rem;
   }
-  .error-state {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    justify-content: center;
-    height: 100%;
-    padding: 2rem;
-    text-align: center;
-    box-sizing: border-box;
-  }
-  .error-state p {
-    color: var(--error-color, #ff6b6b);
-    margin: 0 0 1rem;
-  }
-  .error-state button {
-    padding: 0.5rem 1rem;
-    background: var(--error-color, #ff6b6b);
-    color: white;
-    border: none;
-    border-radius: 4px;
-    cursor: pointer;
-  }
-  .error-state button:hover {
-    background: var(--error-color-hover, #ff5252);
-  }
 </style>

package/dist/brillouin/BrillouinZone.svelte.d.ts

@@ -78,6 +78,6 @@ type $$ComponentProps = {
     on_fullscreen_change?: (data: BZHandlerData) => void;
     on_hover?: (data: BZHoverData | null) => void;
 } & HTMLAttributes<HTMLDivElement>;
-declare const BrillouinZone: import("svelte").Component<$$ComponentProps, {}, "height" | "width" | "dragover" | "fullscreen" | "structure" | "hovered" | "controls_open" | "camera_projection" | "info_pane_open" | "loading" | "error_msg" | "wrapper" | "png_dpi" | "bz_order" | "surface_color" | "surface_opacity" | "edge_color" | "edge_width" | "show_vectors" | "show_ibz" | "ibz_color" | "ibz_opacity" | "bz_data" | "vector_scale" | "ibz_data">;
+declare const BrillouinZone: import("svelte").Component<$$ComponentProps, {}, "structure" | "height" | "width" | "dragover" | "fullscreen" | "hovered" | "controls_open" | "loading" | "camera_projection" | "vector_scale" | "info_pane_open" | "wrapper" | "png_dpi" | "error_msg" | "bz_order" | "surface_color" | "surface_opacity" | "edge_color" | "edge_width" | "show_vectors" | "show_ibz" | "ibz_color" | "ibz_opacity" | "bz_data" | "ibz_data">;
 type BrillouinZone = ReturnType<typeof BrillouinZone>;
 export default BrillouinZone;

package/dist/brillouin/BrillouinZoneControls.svelte

@@ -1,8 +1,35 @@
-<script lang="ts">import SettingsSection from '../layout/SettingsSection.svelte';
-import DraggablePane from '../overlays/DraggablePane.svelte';
-let { controls_open = $bindable(false), bz_order = $bindable(1), surface_color = $bindable(`#4488ff`), surface_opacity = $bindable(0.3), edge_color = $bindable(`#000000`), edge_width = $bindable(0.05), show_vectors = $bindable(true), camera_projection = $bindable(`perspective`), 
-// Irreducible BZ options
-show_ibz = $bindable(false), ibz_color = $bindable(`#ff8844`), ibz_opacity = $bindable(0.5), } = $props();
+<script lang="ts">
+  import SettingsSection from '../layout/SettingsSection.svelte'
+  import DraggablePane from '../overlays/DraggablePane.svelte'
+  import type { CameraProjection } from '../settings'
+
+  let {
+    controls_open = $bindable(false),
+    bz_order = $bindable(1),
+    surface_color = $bindable(`#4488ff`),
+    surface_opacity = $bindable(0.3),
+    edge_color = $bindable(`#000000`),
+    edge_width = $bindable(0.05),
+    show_vectors = $bindable(true),
+    camera_projection = $bindable(`perspective`),
+    // Irreducible BZ options
+    show_ibz = $bindable(false),
+    ibz_color = $bindable(`#ff8844`),
+    ibz_opacity = $bindable(0.5),
+  }: {
+    controls_open?: boolean
+    bz_order?: number
+    surface_color?: string
+    surface_opacity?: number
+    edge_color?: string
+    edge_width?: number
+    show_vectors?: boolean
+    camera_projection?: CameraProjection
+    // Irreducible BZ options
+    show_ibz?: boolean
+    ibz_color?: string
+    ibz_opacity?: number
+  } = $props()
 </script>
 
 <DraggablePane