matterviz 0.3.4 → 0.3.6

package/dist/src/lib/table/ToggleMenu.svelte

@@ -0,0 +1,385 @@
+<script lang="ts">
+  import Icon from '$lib/Icon.svelte'
+  import { sanitize_html } from '$lib/sanitize'
+  import type { Label } from '$lib/table'
+  import { click_outside, tooltip } from 'svelte-multiselect/attachments'
+  import { slide } from 'svelte/transition'
+
+  let {
+    columns = $bindable([]),
+    column_panel_open = $bindable(false),
+    n_columns,
+    collapsed_sections = $bindable<string[]>([]),
+    on_reset,
+  }: {
+    columns: Label[]
+    column_panel_open?: boolean
+    // Number of grid columns for toggle layout
+    n_columns?: number
+    collapsed_sections?: string[]
+    // Called after reset with the section name (or undefined for global reset)
+    on_reset?: (section?: string) => void
+  } = $props()
+
+  const col_id = (col: Label) => col.key ?? col.label
+
+  // Snapshot default visibility when column set changes (new dataset).
+  // Compare by keys and visibility defaults. Internal updates opt out below.
+  // Signature state is non-reactive; default visibility is state so reset UI updates after snapshots.
+  let prev_default_signature = ``
+  let internal_default_signature: string | undefined
+  let default_visibility = $state<Record<string, boolean>>({})
+  const default_signature = () =>
+    columns.map((col) => `${col_id(col)}:${col.visible !== false}`).join(`\0`)
+
+  function snapshot_defaults() {
+    default_visibility = {}
+    for (const col of columns) {
+      default_visibility[col_id(col)] = col.visible !== false
+    }
+    prev_default_signature = default_signature()
+  }
+  snapshot_defaults()
+
+  $effect(() => {
+    const current_signature = default_signature()
+    if (current_signature === internal_default_signature) {
+      internal_default_signature = undefined
+      return
+    }
+    if (current_signature === prev_default_signature) return
+    snapshot_defaults()
+  })
+
+  // Check if a column's visibility differs from its default
+  const is_changed = (col: Label) =>
+    (col.visible !== false) !== (default_visibility[col_id(col)] ?? true)
+
+  let has_any_changes = $derived(columns.some(is_changed))
+
+  // Reset columns to default visibility
+  function reset_columns(items: Label[]): void {
+    for (const col of items) {
+      col.visible = default_visibility[col_id(col)] ?? true
+    }
+    internal_default_signature = default_signature()
+    columns = [...columns]
+  }
+
+  function reset_all(): void {
+    reset_columns(columns)
+    on_reset?.()
+  }
+
+  function reset_section(section_name: string): void {
+    const section = sections.find((sec) => sec.name === section_name)
+    if (!section) return
+    reset_columns(section.items)
+    on_reset?.(section_name)
+  }
+
+  // Group columns by their group property
+  let sections = $derived.by(() => {
+    const grouped: Record<string, Label[]> = {}
+    const ungrouped: Label[] = []
+
+    for (const col of columns) {
+      if (col.group) {
+        grouped[col.group] ??= []
+        grouped[col.group].push(col)
+      } else {
+        ungrouped.push(col)
+      }
+    }
+
+    const result = Object.entries(grouped).map(([name, items]) => ({ name, items }))
+    if (ungrouped.length > 0) result.push({ name: ``, items: ungrouped })
+    return result
+  })
+
+  // Check if any column defines a group (to decide whether to show sections)
+  let has_sections = $derived(columns.some((col) => col.group))
+
+  function toggle_section(name: string) {
+    collapsed_sections = collapsed_sections.includes(name)
+      ? collapsed_sections.filter((section) => section !== name)
+      : [...collapsed_sections, name]
+  }
+
+  function toggle_column_visibility(col: Label, event: Event) {
+    if (!(event.target instanceof HTMLInputElement)) return
+    col.visible = event.target.checked
+    internal_default_signature = default_signature()
+    columns = [...columns] // trigger reactivity on parent binding
+  }
+
+  // Grid template for section items
+  let grid_template = $derived(
+    n_columns
+      ? `repeat(${n_columns}, max-content)`
+      : `repeat(auto-fill, minmax(135px, 1fr))`,
+  )
+
+  // Reposition dropdown: left-aligned by default, switch to right if it overflows viewport
+  let details_el: HTMLElement | undefined = undefined
+  $effect(() => {
+    if (!column_panel_open || !details_el) return
+    // Re-run when section state changes while open
+    void n_columns
+    void collapsed_sections
+    void sections
+    const dropdown = details_el.querySelector<HTMLElement>(
+      `.column-menu, .sections-container`,
+    )
+    if (!dropdown) return
+    // Reset to left-aligned
+    dropdown.style.left = `0`
+    dropdown.style.right = `auto`
+    requestAnimationFrame(() => {
+      const rect = dropdown.getBoundingClientRect()
+      if (rect.right > window.innerWidth) {
+        dropdown.style.left = `auto`
+        dropdown.style.right = `0`
+      }
+    })
+  })
+</script>
+
+{#snippet toggle_item(col: Label)}
+  <label
+    class="toggle-label"
+    class:disabled={col.disabled}
+    {@attach tooltip({ allow_html: true, content: sanitize_html(col.description ?? ``) })}
+  >
+    <input
+      type="checkbox"
+      checked={col.visible !== false}
+      disabled={col.disabled}
+      onchange={(event) => toggle_column_visibility(col, event)}
+    />
+    {@html sanitize_html(col.label)}
+  </label>
+{/snippet}
+
+<svelte:window
+  onkeydown={(event) => {
+    if (event.key === `Escape` && column_panel_open) {
+      column_panel_open = false
+      event.preventDefault()
+    }
+  }}
+/>
+
+<details
+  class="column-toggles"
+  bind:this={details_el}
+  bind:open={column_panel_open}
+  {@attach click_outside({ callback: () => (column_panel_open = false) })}
+>
+  <summary aria-expanded={column_panel_open}>
+    Columns <Icon icon="Columns" />
+    {#if has_any_changes}
+      <button
+        class="reset-btn"
+        onclick={(event) => {
+          event.stopPropagation()
+          event.preventDefault()
+          reset_all()
+        }}
+        type="button"
+        aria-label="Reset all columns to defaults"
+        {@attach tooltip()}
+      >
+        <Icon icon="Reset" width="12px" />
+      </button>
+    {/if}
+  </summary>
+
+  {#if has_sections}
+    <div class="sections-container" role="group">
+      {#each sections as section (section.name)}
+        {@const is_collapsed = section.name !== `` &&
+        collapsed_sections.includes(section.name)}
+        <div class="section">
+          {#if section.name}
+            <div class="section-header-row">
+              <button
+                class="section-header"
+                aria-expanded={!is_collapsed}
+                onclick={() => toggle_section(section.name)}
+                type="button"
+              >
+                <span class="collapse-icon">{is_collapsed ? `▶` : `▼`}</span>
+                {section.name}
+              </button>
+              {#if section.items.some(is_changed)}
+                <button
+                  class="reset-btn"
+                  onclick={() => reset_section(section.name)}
+                  type="button"
+                  aria-label="Reset {section.name} to defaults"
+                  {@attach tooltip()}
+                >
+                  <Icon icon="Reset" width="12px" />
+                </button>
+              {/if}
+            </div>
+          {/if}
+          {#if !is_collapsed}
+            <div
+              class="section-items"
+              style:grid-template-columns={grid_template}
+              transition:slide={{ duration: 200 }}
+            >
+              {#each section.items as col, idx (col.key ?? col.label ?? idx)}
+                {@render toggle_item(col)}
+              {/each}
+            </div>
+          {/if}
+        </div>
+      {/each}
+    </div>
+  {:else}
+    <div class="column-menu" role="group" style:grid-template-columns={grid_template}>
+      {#each columns as col, idx (col.key ?? col.label ?? idx)}
+        {@render toggle_item(col)}
+      {/each}
+    </div>
+  {/if}
+</details>
+
+<style>
+  .column-toggles {
+    position: relative;
+    summary {
+      background: var(--tgl-btn-bg, var(--btn-bg));
+      padding: 0 6pt;
+      margin: 4pt 0;
+      border-radius: var(--tgl-border-radius, 4pt);
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      gap: 4px;
+      &:hover {
+        background: var(--tgl-hover-bg, var(--nav-bg));
+      }
+      &::-webkit-details-marker {
+        display: none;
+      }
+    }
+  }
+  /* Shared dropdown styling */
+  .column-menu,
+  .sections-container {
+    font-size: var(--tgl-font-size, 1.1em);
+    position: absolute;
+    left: 0;
+    top: calc(100% + 1pt);
+    background: var(--tgl-dropdown-bg, var(--page-bg));
+    border: 1px solid
+      var(--tgl-dropdown-border, color-mix(in srgb, currentColor 10%, transparent));
+    border-radius: var(--tgl-border-radius, 4pt);
+    box-shadow: var(
+      --tgl-dropdown-shadow,
+      0 4px 12px color-mix(in srgb, currentColor 8%, transparent)
+    );
+    min-width: 150px;
+    max-height: var(--tgl-dropdown-max-height, min(70vh, 600px));
+    overflow-y: auto;
+    z-index: 1;
+  }
+  .column-menu {
+    padding: 3pt 5pt;
+    display: grid;
+  }
+  .sections-container {
+    padding: 6pt 8pt;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  .reset-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 2pt;
+    border: none;
+    border-radius: var(--tgl-border-radius, 3pt);
+    background: transparent;
+    cursor: pointer;
+    color: inherit;
+    opacity: 0.5;
+    flex-shrink: 0;
+    &:hover {
+      background: color-mix(in srgb, currentColor 12%, transparent);
+      opacity: 1;
+    }
+  }
+  summary .reset-btn {
+    margin-left: auto;
+  }
+  .section-header-row {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    margin-bottom: 4pt;
+    padding: 2pt 4pt;
+    border-radius: var(--tgl-border-radius, 3pt);
+    background: var(
+      --tgl-section-header-bg,
+      color-mix(in srgb, currentColor 5%, transparent)
+    );
+    &:hover {
+      background: var(
+        --tgl-section-header-hover-bg,
+        color-mix(in srgb, currentColor 12%, transparent)
+      );
+    }
+  }
+  .section-header {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    font-weight: 600;
+    font-size: 0.9em;
+    padding: 0;
+    border: none;
+    background: transparent;
+    cursor: pointer;
+    flex: 1;
+    text-align: left;
+    color: inherit;
+  }
+  .collapse-icon {
+    font-size: 0.7em;
+    width: 1em;
+    flex-shrink: 0;
+  }
+  .section-items {
+    display: grid;
+  }
+  .toggle-label {
+    display: inline-block;
+    margin: 1px 2px;
+    border-radius: 3px;
+    line-height: 1.3em;
+    height: 1.3em;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    &:hover:not(.disabled) {
+      background: var(--tgl-hover-bg, var(--nav-bg));
+    }
+    &.disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+      input {
+        cursor: not-allowed;
+      }
+    }
+  }
+  details :global(:is(sub, sup)) {
+    transform: translate(-3pt, 6pt);
+    font-size: 0.7em;
+  }
+</style>

package/dist/src/lib/table/index.ts

@@ -0,0 +1,139 @@
+import { pick_contrast_color } from '$lib/colors'
+import { max, min } from 'd3-array'
+import { scaleLog, scaleSequential } from 'd3-scale'
+import * as d3sc from 'd3-scale-chromatic'
+import type { Snippet } from 'svelte'
+
+export { default as HeatmapTable } from './HeatmapTable.svelte'
+export { default as ToggleMenu } from './ToggleMenu.svelte'
+
+// Cell value types for table data
+export type CellVal =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | Record<string, unknown>
+  | { [key: string]: string | number | null | undefined | boolean }[]
+
+// Row data for table entries
+export type RowData = { style?: string; class?: string; [key: string]: CellVal }
+
+// Column configuration for HeatmapTable
+export type Label = {
+  // Display label for the column header. Supports HTML markup (e.g., "n<sub>val</sub>")
+  // for subscripts/superscripts. Note: HTML is rendered via {@html}, so ensure
+  // labels are developer-defined, not user input, to avoid XSS vulnerabilities.
+  label: string
+  key?: string
+  // Group name for ToggleMenu section grouping. Columns with the same group
+  // are displayed together under a collapsible section header.
+  group?: string
+  description?: string
+  format?: string
+  better?: `higher` | `lower`
+  color_scale?: keyof typeof d3sc | null
+  scale_type?: `linear` | `log`
+  sticky?: boolean
+  visible?: boolean
+  sortable?: boolean
+  // Show sort direction/better-hint arrow in header. Set false to keep sorting
+  // enabled but hide the visual arrow indicator.
+  show_sort_indicator?: boolean
+  // When true, the toggle checkbox in ToggleMenu is greyed out and non-interactive
+  disabled?: boolean
+  style?: string
+  cell_style?: string
+}
+
+// Arguments passed to cell snippet renderers
+export type CellSnippetArgs = { row: RowData; col: Label; val: CellVal }
+
+// Type alias for cell snippets - use this for cross-package compatibility
+// instead of directly using Snippet<[CellSnippetArgs]> which can cause
+// type mismatches between different svelte package instances
+export type CellSnippet = Snippet<[CellSnippetArgs]>
+
+// Type for special_cells prop - maps column labels to cell snippets
+export type SpecialCells = Record<string, CellSnippet>
+
+// Sort state for single-column sorting
+export type SortState = { column: string; ascending: boolean }
+
+// Multi-column sort state (for Shift+click sorting)
+export type MultiSortState = SortState[]
+
+// Sort hint configuration (string for simple text, object for full control)
+export type SortHint =
+  | string
+  | {
+      text: string
+      position?: `top` | `bottom`
+      permanent?: boolean
+      style?: string
+      class?: string
+    }
+
+// Initial sort configuration (string for column name, object for full control)
+export type InitialSort = string | { column: string; direction?: `asc` | `desc` }
+
+// Pagination configuration (boolean to enable, object for full control)
+export type Pagination = boolean | { page_size?: number; page_sizes?: number[] }
+
+// Search configuration (boolean to enable, object for full control)
+export type Search = boolean | { placeholder?: string; expanded?: boolean }
+
+// Export configuration (boolean to enable, object for full control)
+export type ExportData = boolean | { formats?: (`csv` | `json`)[]; filename?: string }
+
+// Callback type for async server-side sorting
+export type OnSortCallback = (column: string, dir: `asc` | `desc`) => Promise<RowData[]>
+
+// Strip HTML tags from a string (for search, export, etc.)
+export const strip_html = (str: string): string => str.replace(/<[^>]*>/g, ``)
+
+// Calculate table cell background color based on its value and column config
+export function calc_cell_color(
+  val: number | null | undefined, // cell value
+  all_values: CellVal[], // all values in the column
+  better: `higher` | `lower` | undefined, // sort direction
+  color_scale: keyof typeof d3sc | null = `interpolateViridis`, // color scale name
+  scale_type: `linear` | `log` = `linear`, // scale type
+): { bg: string | null; text: string | null } {
+  // Skip color calculation for null/undefined/NaN values or if color_scale is null
+  if (val == null || Number.isNaN(val) || color_scale === null) {
+    return { bg: null, text: null }
+  }
+
+  // Log scale cannot handle non-positive values, return null colors
+  if (scale_type === `log` && val <= 0) {
+    return { bg: null, text: null }
+  }
+
+  const numeric_vals = all_values.filter(
+    (v): v is number =>
+      typeof v === `number` && !Number.isNaN(v) && (scale_type === `log` ? v > 0 : true), // Only filter non-positives for log scale
+  )
+
+  if (numeric_vals.length === 0) return { bg: null, text: null }
+
+  const range = [min(numeric_vals) ?? 0, max(numeric_vals) ?? 1]
+
+  // Reverse the range if lower values are better
+  if (better === `lower`) range.reverse()
+
+  // Get interpolator function, fallback to viridis if not a valid function
+  const scale_fn = d3sc[color_scale]
+  const interpolator = (
+    typeof scale_fn === `function` ? scale_fn : d3sc.interpolateViridis
+  ) as (t: number) => string
+
+  // Use log scale for positive values, otherwise linear/sequential scale
+  const bg =
+    scale_type === `log` && range[0] > 0 && range[1] > 0
+      ? interpolator(scaleLog().domain(range).range([0, 1]).clamp(true)(val))
+      : scaleSequential().domain(range).interpolator(interpolator)(val)
+
+  return { bg, text: pick_contrast_color({ bg_color: bg }) }
+}

package/dist/src/lib/theme/ThemeControl.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+  import { theme_state } from '$lib/state.svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import type { ThemeMode } from './index'
+  import { apply_theme_to_dom, save_theme_preference, THEME_OPTIONS } from './index'
+
+  let { theme_mode = $bindable(theme_state.mode), onchange = () => {}, ...rest }:
+    & Omit<HTMLAttributes<HTMLSelectElement>, `onchange`>
+    & {
+      theme_mode?: ThemeMode // Current theme mode (now bindable to global state)
+      onchange?: (mode: ThemeMode) => void // Callback when theme changes
+    } = $props()
+
+  $effect(() => { // Sync and save to local storage when theme changes
+    const prev = theme_state.mode
+    if (prev === theme_mode) return
+    theme_state.mode = theme_mode
+    save_theme_preference(theme_mode)
+    apply_theme_to_dom(theme_mode)
+    onchange(theme_mode)
+  })
+</script>
+
+<select bind:value={theme_mode} {...rest} class="theme-control {rest.class ?? ``}">
+  {#each THEME_OPTIONS as { label, icon, value } (value)}
+    <option {value}>{icon}&ensp;{label}</option>
+  {/each}
+</select>
+
+<style>
+  .theme-control {
+    position: fixed;
+    bottom: 1em;
+    left: 1em;
+    z-index: var(--theme-control-z-index, 2);
+    background: var(--btn-bg);
+    border: var(--pane-border);
+    color: var(--text-color);
+    border-radius: var(--theme-control-border-radius, var(--border-radius, 3pt));
+    padding: var(--theme-control-padding, 1pt 2pt);
+    backdrop-filter: blur(10px);
+    transition: all 0.2s ease;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  }
+  .theme-control:hover {
+    background: var(--btn-bg-hover);
+    border: var(--pane-border);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+  }
+  .theme-control:focus {
+    outline: 0.5px solid var(--accent-color);
+  }
+</style>

package/dist/src/lib/theme/index.ts

@@ -0,0 +1,107 @@
+// Theme System for MatterViz
+
+const is_browser = typeof window !== `undefined`
+const storage_key = `matterviz-theme`
+
+// Core theme constants
+export const COLOR_THEMES = {
+  light: `light`,
+  dark: `dark`,
+  white: `white`,
+  black: `black`,
+} as const
+
+export const AUTO_THEME = `auto` as const
+
+export type ThemeType = `light` | `dark`
+export const THEME_TYPE: Record<ThemeName, ThemeType> = {
+  [COLOR_THEMES.light]: `light`,
+  [COLOR_THEMES.dark]: `dark`,
+  [COLOR_THEMES.white]: `light`,
+  [COLOR_THEMES.black]: `dark`,
+} as const
+
+export type ThemeName = keyof typeof COLOR_THEMES
+export type ThemeMode = ThemeName | typeof AUTO_THEME
+
+export interface ThemeOption {
+  value: ThemeMode
+  label: string
+  icon: string
+}
+
+// Theme options for UI components
+export const THEME_OPTIONS: ThemeOption[] = [
+  { value: COLOR_THEMES.light, label: `Light`, icon: `☀️` },
+  { value: COLOR_THEMES.dark, label: `Dark`, icon: `🌙` },
+  { value: COLOR_THEMES.white, label: `White`, icon: `⚪` },
+  { value: COLOR_THEMES.black, label: `Black`, icon: `⚫` },
+  { value: AUTO_THEME, label: `Auto`, icon: `🔄` },
+]
+
+// Type guards and utilities
+export const is_valid_theme_mode = (value: string): value is ThemeMode =>
+  Object.keys(COLOR_THEMES).includes(value) || value === AUTO_THEME
+
+export const is_valid_theme_name = (value: string): value is ThemeName =>
+  Object.keys(COLOR_THEMES).includes(value)
+
+export const resolve_theme_mode = (
+  mode: ThemeMode,
+  system_preference: ThemeType = COLOR_THEMES.light,
+): ThemeName => (mode === AUTO_THEME ? system_preference : mode)
+
+// Theme preference management
+export const get_theme_preference = (): ThemeMode => {
+  if (!is_browser) return AUTO_THEME
+  try {
+    const saved = localStorage[storage_key]
+    return is_valid_theme_mode(saved || ``) ? (saved as ThemeMode) : AUTO_THEME
+  } catch {
+    return AUTO_THEME
+  }
+}
+
+export const save_theme_preference = (mode: ThemeMode): void => {
+  try {
+    localStorage[storage_key] = mode
+  } catch {
+    // Silently fail if localStorage is unavailable
+  }
+}
+
+export const get_system_mode = (): ThemeType =>
+  is_browser && matchMedia(`(prefers-color-scheme: dark)`).matches
+    ? COLOR_THEMES.dark
+    : COLOR_THEMES.light
+
+export const apply_theme_to_dom = (mode: ThemeMode): void => {
+  if (!is_browser) return
+
+  const resolved = resolve_theme_mode(mode, get_system_mode())
+  if (!resolved || !(resolved in THEME_TYPE)) {
+    throw new Error(`Invalid theme mode: ${resolved}`)
+  }
+  const theme = globalThis.MATTERVIZ_THEMES?.[resolved] || {}
+  const css_vars = globalThis.MATTERVIZ_CSS_MAP || {}
+
+  const root = document.documentElement
+  Object.entries(theme).forEach(([key, value]) => {
+    const css_var = css_vars[key]
+    if (css_var && value && typeof value === `string`) {
+      root.style.setProperty(css_var, value)
+    }
+  })
+
+  root.setAttribute(`data-theme`, resolved)
+  // Set color-scheme to ensure form elements respect the theme
+  const color_scheme = THEME_TYPE[resolved]
+  root.style.setProperty(`color-scheme`, color_scheme)
+}
+
+// Theme getters
+export const light_theme = () => globalThis.MATTERVIZ_THEMES?.[COLOR_THEMES.light] || {}
+export const dark_theme = () => globalThis.MATTERVIZ_THEMES?.[COLOR_THEMES.dark] || {}
+export const white_theme = () => globalThis.MATTERVIZ_THEMES?.[COLOR_THEMES.white] || {}
+export const black_theme = () => globalThis.MATTERVIZ_THEMES?.[COLOR_THEMES.black] || {}
+export const get_theme_by_name = (name: ThemeName) => globalThis.MATTERVIZ_THEMES?.[name] || {}