matterviz 0.3.4 → 0.3.6

package/dist/src/lib/heatmap-matrix/HeatmapMatrixControls.svelte

@@ -0,0 +1,225 @@
+<script lang="ts">
+  import DraggablePane from '$lib/overlays/DraggablePane.svelte'
+  import type { ComponentProps, Snippet } from 'svelte'
+  import {
+    ELEMENT_ORDERINGS,
+    ORDERING_LABELS,
+  } from './index'
+  import type { ElementAxisOrderingKey, DomainMode, HeatmapExportFormat, LegendPosition, NormalizeMode, SymmetricMode } from './index'
+
+  let {
+    ordering = $bindable(`atomic_number`),
+    orderings = ELEMENT_ORDERINGS,
+    controls_open = $bindable(false),
+    toggle_visible = $bindable(false),
+    normalize = $bindable(`linear`),
+    domain_mode = $bindable(`auto`),
+    show_legend = $bindable(false),
+    legend_position = $bindable(`bottom`),
+    search_query = $bindable(``),
+    symmetric = $bindable<SymmetricMode>(false),
+    show_values = $bindable<boolean | string>(false),
+    show_row_summaries = $bindable(false),
+    show_col_summaries = $bindable(false),
+    theme = $bindable<`default` | `light` | `dark` | `publication`>(`default`),
+    export_formats = [`csv`, `json`],
+    onexport,
+    show_pane = true,
+    pane_props = {},
+    toggle_props = {},
+    children,
+  }: {
+    ordering?: ElementAxisOrderingKey
+    orderings?: ElementAxisOrderingKey[]
+    controls_open?: boolean
+    toggle_visible?: boolean
+    normalize?: NormalizeMode
+    domain_mode?: DomainMode
+    show_legend?: boolean
+    legend_position?: LegendPosition
+    search_query?: string
+    symmetric?: SymmetricMode
+    show_values?: boolean | string
+    show_row_summaries?: boolean
+    show_col_summaries?: boolean
+    theme?: `default` | `light` | `dark` | `publication`
+    export_formats?: HeatmapExportFormat[]
+    onexport?: (format: HeatmapExportFormat) => void
+    show_pane?: boolean
+    pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`]
+    toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`]
+    children?: Snippet<[{ controls_open: boolean }]>
+  } = $props()
+
+  function merge_styles(base_style: string, override_style: unknown): string {
+    const override_style_str = typeof override_style === `string`
+      ? override_style
+      : ``
+    return override_style_str ? `${base_style}; ${override_style_str}` : base_style
+  }
+
+  // Stash custom format string so toggling the checkbox preserves it
+  let stashed_format = $state<string | null>(null)
+
+  let show_toggle = $derived(controls_open || toggle_visible)
+  let default_toggle_style = $derived(
+    [
+      `position: absolute`,
+      `top: var(--heatmap-matrix-controls-toggle-top, 6px)`,
+      `right: var(--heatmap-matrix-controls-toggle-right, 6px)`,
+      `z-index: var(--heatmap-matrix-controls-toggle-z-index, 20)`,
+      `opacity: ${show_toggle ? `1` : `0`}`,
+      `pointer-events: ${show_toggle ? `auto` : `none`}`,
+      `transition: var(--heatmap-matrix-controls-toggle-transition, opacity 0.2s ease)`,
+    ].join(`; `),
+  )
+  const default_pane_style = [
+    `z-index: var(--heatmap-matrix-controls-pane-z-index, 25)`,
+    `min-width: var(--heatmap-matrix-controls-pane-min-width, 220px)`,
+  ].join(`; `)
+</script>
+
+<DraggablePane
+  bind:show={controls_open}
+  {show_pane}
+  pane_props={{
+    ...pane_props,
+    class: `heatmap-controls ${pane_props?.class ?? ``}`.trim(),
+    style: merge_styles(default_pane_style, pane_props?.style),
+  }}
+  toggle_props={{
+    ...toggle_props,
+    title: toggle_props.title ?? (controls_open ? `` : `Heatmap controls`),
+    class: `heatmap-matrix-controls-toggle ${toggle_props?.class ?? ``}`.trim(),
+    style: merge_styles(default_toggle_style, toggle_props?.style),
+  }}
+  closed_icon="Settings"
+  open_icon="Cross"
+>
+  <label>
+    Ordering
+    <select bind:value={ordering}>
+      {#each orderings as ord (ord)}
+        <option value={ord}>{ORDERING_LABELS[ord]}</option>
+      {/each}
+    </select>
+  </label>
+  <label>
+    Search
+    <input bind:value={search_query} placeholder="Filter labels/keys" />
+  </label>
+  <div class="pane-row">
+    <label>
+      Normalize
+      <select bind:value={normalize}>
+        <option value="linear">linear</option>
+        <option value="log">log</option>
+      </select>
+    </label>
+    <label>
+      Domain
+      <select bind:value={domain_mode}>
+        <option value="auto">auto</option>
+        <option value="robust">robust</option>
+        <option value="fixed">fixed</option>
+      </select>
+    </label>
+  </div>
+  <div class="pane-row">
+    <label>
+      <input type="checkbox" bind:checked={show_legend} />
+      Legend
+    </label>
+    {#if show_legend}
+      <label>
+        Position
+        <select bind:value={legend_position}>
+          <option value="right">right</option>
+          <option value="bottom">bottom</option>
+        </select>
+      </label>
+    {/if}
+  </div>
+  <div class="pane-row">
+    <label>
+      Symmetric
+      <select bind:value={symmetric}>
+        <option value={false}>off</option>
+        <option value="lower">lower</option>
+        <option value="upper">upper</option>
+      </select>
+    </label>
+    <label>
+      Theme
+      <select bind:value={theme}>
+        <option value="default">default</option>
+        <option value="light">light</option>
+        <option value="dark">dark</option>
+        <option value="publication">publication</option>
+      </select>
+    </label>
+  </div>
+  <div class="pane-row">
+    <label>
+      <input
+        type="checkbox"
+        checked={!!show_values}
+        onchange={(evt) => {
+          if (evt.currentTarget.checked) {
+            show_values = stashed_format || true
+          } else {
+            stashed_format = typeof show_values === `string` ? show_values : null
+            show_values = false
+          }
+        }}
+      />
+      Values
+    </label>
+    <label>
+      <input type="checkbox" bind:checked={show_row_summaries} />
+      Row sums
+    </label>
+    <label>
+      <input type="checkbox" bind:checked={show_col_summaries} />
+      Col sums
+    </label>
+  </div>
+  <div class="pane-row">
+    {#each export_formats as export_format (export_format)}
+      <button type="button" onclick={() => onexport?.(export_format)}>
+        Export {export_format.toUpperCase()}
+      </button>
+    {/each}
+  </div>
+  {@render children?.({ controls_open })}
+</DraggablePane>
+
+<style>
+  :global(.heatmap-controls) {
+    font-size: 0.85em;
+    max-width: 320px;
+  }
+  .pane-row {
+    display: flex;
+    gap: 10pt;
+    flex-wrap: wrap;
+  }
+  label {
+    display: flex;
+    align-items: center;
+    gap: 6pt;
+  }
+  select,
+  input:not([type]) {
+    height: 1.8em;
+    padding: 0 0.5em;
+    border-radius: var(--border-radius, 3pt);
+    border: 1px solid light-dark(#ccc, #555);
+    background: light-dark(white, #333);
+    color: inherit;
+    font: inherit;
+    box-sizing: border-box;
+    flex: 1;
+    min-width: 0;
+  }
+</style>

package/dist/src/lib/heatmap-matrix/index.ts

@@ -0,0 +1,167 @@
+import type { ChemicalElement, ElementSymbol } from '$lib/element'
+import { element_data } from '$lib/element'
+import type { Snippet } from 'svelte'
+export { COLOR_OVERRIDE_KEY_SEPARATOR, make_color_override_key } from './shared'
+
+// === Types ===
+
+// Generic axis item -- works for elements, compositions, structures, etc.
+// T defaults to Record<string, unknown> but can be narrowed (e.g. ChemicalElement)
+export type AxisItem<T = Record<string, unknown>> = {
+  label: string // display text (e.g. element symbol "Fe")
+  key?: string // unique identifier, defaults to label
+  sort_value?: number // numeric value used for sorting (set by ordering)
+  category?: string // optional grouping (for label coloring)
+  data?: T // arbitrary metadata
+}
+
+// Context passed to tooltip, cell, and event handler snippets
+export type CellContext = {
+  x_item: AxisItem
+  y_item: AxisItem
+  x_idx: number
+  y_idx: number
+  value: number | string | null
+  bg_color: string | null
+}
+
+// Human-readable labels for built-in orderings
+export const ORDERING_LABELS = {
+  atomic_number: `Atomic Number`,
+  mendeleev_number: `Pettifor Chemical Similarity`,
+  alphabetical: `Alphabetical`,
+  atomic_mass: `Atomic Mass`,
+  electronegativity: `Pauling Electronegativity`,
+  first_ionization: `Ionization Energy`,
+  melting_point: `Melting Point`,
+  atomic_radius: `Atomic Radius`,
+  density: `Density`,
+  n_valence: `Valence Electrons`,
+} as const
+
+// String-only ordering key, derived from ORDERING_LABELS to avoid duplication
+export type ElementAxisOrderingKey = keyof typeof ORDERING_LABELS
+
+// Full ordering type: built-in key or custom comparator function
+export type ElementAxisOrdering =
+  | ElementAxisOrderingKey
+  | ((a: ChemicalElement, b: ChemicalElement) => number)
+
+// Shared types used by both HeatmapMatrix and HeatmapMatrixControls
+export type NormalizeMode =
+  | `linear`
+  | `log`
+  | ((value: number, min: number, max: number) => number)
+export type DomainMode = `auto` | `robust` | `fixed`
+export type LegendPosition = `right` | `bottom`
+// true is accepted as backward-compat alias for 'lower'
+export type SymmetricMode = boolean | `lower` | `upper`
+
+// Tooltip snippet type for HeatmapMatrix
+export type HeatmapTooltipProp = Snippet<[CellContext]> | boolean
+export type HeatmapSelection = { x_idx: number; y_idx: number }
+export type HeatmapExportFormat = `csv` | `json`
+export type HeatmapBrushPayload = {
+  x_range: [number, number]
+  y_range: [number, number]
+  cells: CellContext[]
+}
+
+// All built-in string ordering keys
+export const ELEMENT_ORDERINGS = Object.keys(ORDERING_LABELS) as ElementAxisOrderingKey[]
+
+export function matrix_to_rows(
+  x_items: AxisItem[],
+  y_items: AxisItem[],
+  values:
+    | (number | string | null)[][]
+    | Record<string, Record<string, number | string | null>>,
+): Record<string, number | string | null>[] {
+  const get_value = Array.isArray(values)
+    ? (x_idx: number, y_idx: number) => values[y_idx]?.[x_idx] ?? null
+    : (x_idx: number, y_idx: number) => {
+        const y_key = y_items[y_idx].key ?? y_items[y_idx].label
+        const x_key = x_items[x_idx].key ?? x_items[x_idx].label
+        return values[y_key]?.[x_key] ?? null
+      }
+  return y_items.map((y_item, y_idx) => {
+    const row: Record<string, number | string | null> = {
+      y_key: y_item.key ?? y_item.label,
+    }
+    for (const [x_idx, x_item] of x_items.entries()) {
+      row[x_item.key ?? x_item.label] = get_value(x_idx, y_idx)
+    }
+    return row
+  })
+}
+
+function escape_csv_field(value: number | string | null | undefined): string {
+  const field = String(value ?? ``)
+  if (!/[",\n\r]/.test(field)) return field
+  return `"${field.replaceAll(`"`, `""`)}"`
+}
+
+export function rows_to_csv(rows: Record<string, number | string | null>[]): string {
+  if (!rows.length) return ``
+  const headers = Object.keys(rows[0])
+  const lines = [
+    headers.map((header) => escape_csv_field(header)).join(`,`),
+    ...rows.map((row) => headers.map((header) => escape_csv_field(row[header])).join(`,`)),
+  ]
+  return lines.join(`\n`)
+}
+
+// === Helpers ===
+
+// Map ordering keys to ChemicalElement property names where they differ
+const PROPERTY_MAP: Partial<Record<ElementAxisOrderingKey, keyof ChemicalElement>> = {
+  atomic_number: `number`,
+  electronegativity: `electronegativity_pauling`,
+}
+
+// Convert element data to axis items with a given ordering.
+// Optionally filter to a subset of element symbols.
+export function elements_to_axis(
+  symbols?: ElementSymbol[],
+  ordering: ElementAxisOrdering = `atomic_number`,
+): AxisItem<ChemicalElement>[] {
+  let elements = [...element_data]
+
+  // Filter to subset if specified
+  if (symbols) {
+    const symbol_set = new Set(symbols)
+    elements = elements.filter((el) => symbol_set.has(el.symbol))
+  }
+
+  // Sort elements
+  if (typeof ordering === `function`) {
+    elements.sort(ordering)
+  } else if (ordering === `alphabetical`) {
+    elements.sort((a, b) => a.symbol.localeCompare(b.symbol))
+  } else {
+    // Sort by the named property, nulls/undefined last
+    const key = PROPERTY_MAP[ordering] ?? ordering
+    elements.sort((a, b) => {
+      const val_a = (a[key as keyof ChemicalElement] ?? null) as number | null
+      const val_b = (b[key as keyof ChemicalElement] ?? null) as number | null
+      if (val_a === null && val_b === null) return 0
+      if (val_a === null) return 1
+      if (val_b === null) return -1
+      return val_a - val_b
+    })
+  }
+
+  // Convert to AxisItem[]
+  return elements.map((el, idx) => ({
+    label: el.symbol,
+    key: el.symbol,
+    sort_value: idx,
+    category: el.category,
+    data: el,
+  }))
+}
+
+// === Component Exports ===
+
+export { default as HeatmapMatrix } from './HeatmapMatrix.svelte'
+export { default as HeatmapMatrixControls } from './HeatmapMatrixControls.svelte'

package/dist/src/lib/heatmap-matrix/shared.ts

@@ -0,0 +1,7 @@
+// Shared helpers/constants used by HeatmapMatrix module pieces.
+
+// Key format for color_overrides lookups: `${x_key}\0${y_key}`.
+export const COLOR_OVERRIDE_KEY_SEPARATOR = `\0`
+
+export const make_color_override_key = (x_key: string, y_key: string): string =>
+  `${x_key}${COLOR_OVERRIDE_KEY_SEPARATOR}${y_key}`