matterviz 0.4.1 → 0.4.2

package/dist/periodic-table/PeriodicTable.svelte

@@ -9,9 +9,13 @@
   import type { ComponentProps, Snippet } from 'svelte'
   import type { HTMLAttributes } from 'svelte/elements'
   import type { D3InterpolateName } from '../colors'
+  import type { MissingCellStyle } from '../heatmap-matrix'
   import type { ScaleContext } from './index'
   import { TableInset } from './index'
 
+  // a tile's heat value: scalar or 1-4-segment array of numbers/colors
+  type HeatValue = number | number[] | string | string[]
+
   const default_f_block_inset_tiles = [
     { name: `Lanthanides`, symbol: `La-Lu`, number: `57-71`, category: `lanthanide` },
     { name: `Actinides`, symbol: `Ac-Lr`, number: `89-103`, category: `actinide` },
@@ -36,7 +40,7 @@
     color_scale_range = [null, null],
     color_overrides = {},
     labels = {},
-    missing_color = `element-category`,
+    missing = {},
     split_layout = undefined,
     show_color_bar = true,
     color_bar_props = {},
@@ -50,12 +54,10 @@
     tile_props?: Partial<ComponentProps<typeof ElementTile>>
     show_photo?: boolean
     disabled?: boolean // disable hover and click events from updating active_element
-    // either array of numbers/colors (can be partial, missing elements default to 0) or object with
-    // element symbol as key and heat value as value
-    // NEW: each value can now be a single number/color or array of 1-4 numbers/colors for multi-segment display
-    heatmap_values?:
-      | Partial<Record<ElementSymbol, number | number[] | string | string[]>>
-      | (number | number[] | string | string[])[]
+    // array (positional by atomic number, can be partial) or object keyed by element symbol.
+    // each value is a single number/color or an array of 1-4 numbers/colors for multi-segment
+    // tiles. null/omitted -> missing (uses the `missing` fallback); 0 is a real value
+    heatmap_values?: Partial<Record<ElementSymbol, HeatValue | null>> | (HeatValue | null)[]
     // links is either string with element property (name, symbol, number, ...) to use as link,
     // or object with mapping element symbols to link
     links?: keyof ChemicalElement | Record<ElementSymbol, string> | null
@@ -78,9 +80,7 @@
     color_scale_range?: [number | null, number | null]
     color_overrides?: Partial<Record<ElementSymbol, string>>
     labels?: Partial<Record<ElementSymbol, string>>
-    // background color for elements missing from heatmap_values
-    // "element-category" falls back to element category default color
-    missing_color?: string
+    missing?: MissingCellStyle // styling for tiles with no heatmap value
     // control the layout of multi-value splits for all tiles
     split_layout?: `diagonal` | `horizontal` | `vertical` | `triangular` | `quadrant`
     // automatically show a color bar when heatmap_values is provided (default: true)
@@ -91,16 +91,16 @@
     bottom_left_inset?: Snippet<[{ active_element: ChemicalElement | null }]>
     tooltip?:
       | Snippet<
-        [
-          {
-            element: ChemicalElement
-            value: number | number[] | string | string[]
-            active: boolean
-            bg_color: string | null
-            scale_context: ScaleContext
-          },
-        ]
-      >
+          [
+            {
+              element: ChemicalElement
+              value: HeatValue | null
+              active: boolean
+              bg_color: string | null
+              scale_context: ScaleContext
+            },
+          ]
+        >
       | boolean
     children?: Snippet
     onenter?: (element: ChemicalElement) => void
@@ -114,7 +114,8 @@
             `each element possibly omitting elements at the end, got ${heatmap_values.length}`,
         )
         return []
-      }return heatmap_values
+      }
+      return heatmap_values
     } else if (typeof heatmap_values === `object`) {
       const bad_keys = Object.keys(heatmap_values).filter(
         (key) => !ELEM_SYMBOLS.includes(key as ElementSymbol),
@@ -125,7 +126,9 @@
         )
         return []
       }
-      return ELEM_SYMBOLS.map((symbol) => heatmap_values[symbol] ?? 0)
+      // keep absent elements as null (distinct from a real 0 value) so they map to the
+      // missing fallback while explicit 0 maps through the color scale
+      return ELEM_SYMBOLS.map((symbol) => heatmap_values[symbol] ?? null)
     }
     return []
   })
@@ -158,14 +161,11 @@
       ArrowDown: row === 6 && in_f_block ? 9 : row === 7 && in_f_block ? 10 : row + 1,
     }
     const target_row = row_map[event.key] ?? row
-    const target_col = event.key === `ArrowLeft`
-      ? col - 1
-      : event.key === `ArrowRight`
-      ? col + 1
-      : col
+    const target_col =
+      event.key === `ArrowLeft` ? col - 1 : event.key === `ArrowRight` ? col + 1 : col
     active_element =
       element_data.find((el) => el.column === target_col && el.row === target_row) ??
-        active_element
+      active_element
   }
 
   function handle_tooltip_enter(element: ChemicalElement, event: MouseEvent) {
@@ -188,124 +188,92 @@
     typeof color_scale === `string` ? get_d3_interpolator(color_scale) : color_scale,
   )
 
+  // finite numeric heat value (numeric strings coerced; colors, null/false and non-finite
+  // excluded so they can't poison the color-scale domain). null => not a mappable number
+  const to_heat_num = (value: number | string | false | null | undefined): number | null => {
+    if (value == null || value === false || is_color(value)) return null
+    const num = Number(value)
+    return Number.isFinite(num) ? num : null
+  }
+
+  let heat_nums = $derived(
+    heat_values
+      .flat()
+      .map(to_heat_num)
+      .filter((num): num is number => num !== null),
+  )
+  // values usable by the active scale (log excludes non-positive)
+  let usable_heat_nums = $derived(log ? heat_nums.filter((num) => num > 0) : heat_nums)
+
   let cs_min = $derived(
-    color_scale_range[0] ??
-      (heat_values.length > 0
-        ? Math.min(
-          ...heat_values.flat().filter((val): val is number => typeof val === `number`),
-        )
-        : 0),
+    color_scale_range[0] ?? (heat_nums.length > 0 ? Math.min(...heat_nums) : 0),
   )
   let cs_max = $derived(
-    color_scale_range[1] ??
-      (heat_values.length > 0
-        ? Math.max(
-          ...heat_values.flat().filter((val): val is number => typeof val === `number`),
-        )
-        : 1),
+    color_scale_range[1] ?? (heat_nums.length > 0 ? Math.max(...heat_nums) : 1),
   )
 
   // smallest positive bound for log color mapping (matches the auto ColorBar's log scale)
   let cs_min_pos = $derived.by(() => {
     if (cs_min > 0) return cs_min
-    const pos = heat_values.flat().filter((val): val is number =>
-      typeof val === `number` && val > 0
-    )
+    const pos = heat_nums.filter((num) => num > 0)
     return pos.length > 0 ? Math.min(...pos) : cs_max
   })
 
-  let bg_color = $derived(
-    (
-      value: number | number[] | string | string[] | false,
-      element?: ChemicalElement,
-    ): string | null => {
-      if (Array.isArray(value)) {
-        // For arrays, return the color of the first value (used as fallback)
-        return bg_color(value[0], element)
-      }
-
-      // If it's already a color string, return it directly
-      if (is_color(value)) return value
-
-      // Return missing color for zero/invalid values or when no heatmap data
-      if (
-        !value ||
-        value === 0 ||
-        (log && value <= 0) ||
-        !heat_values?.length ||
-        !color_scale_fn
-      ) {
-        // Use missing color for zero/missing values or when no heatmap data
-        if (missing_color === `element-category` && element) {
-          return colors.category[element.category] || `#cccccc`
-        }
-        return missing_color
-      }
-
-      // map value to [0, 1] range
-      const span = cs_max - cs_min
-      if (span === 0) return color_scale_fn?.(0.5) // midpoint when all values equal
+  // whether a value maps to a heatmap color (false => use the missing fallback). 0 is a
+  // real value; only absent/null/non-finite (and <=0 in log mode) count as missing. a
+  // multi-value tile is missing only when every segment is missing
+  const value_is_missing = (value: HeatValue | false | null): boolean => {
+    if (Array.isArray(value)) return value.every(value_is_missing) // [] -> true (missing)
+    if (is_color(value)) return false // explicit colors are real values, not missing
+    const num = to_heat_num(value)
+    return num === null || (log && num <= 0)
+  }
 
-      if (log) {
-        // log mapping matching the log ColorBar (value <= 0 returned missing_color above)
-        const log_span = Math.log(cs_max) - Math.log(cs_min_pos)
-        if (log_span === 0) return color_scale_fn?.(0.5)
-        value = (Math.log(value as number) - Math.log(cs_min_pos)) / log_span
-      } else value = ((value as number) - cs_min) / span
-      return color_scale_fn?.(value as number)
-    },
-  )
+  const bg_color = (
+    value: HeatValue | false | null,
+    element?: ChemicalElement,
+  ): string | null => {
+    if (Array.isArray(value)) return bg_color(value[0], element) // arrays: use first value
+    if (is_color(value)) return value // already a color string
+
+    if (!heat_values.length || !color_scale_fn || value_is_missing(value)) {
+      const category_color = (element && colors.category[element.category]) || `#cccccc`
+      if (missing.color === `element-category`) return category_color
+      // default: category colors for a plain table, gray for missing heatmap data
+      return missing.color || (heat_values.length ? `#666` : category_color)
+    }
 
-  let bg_colors = $derived(
-    (
-      value: number | number[] | string | string[] | false,
-      element?: ChemicalElement,
-    ) => {
-      if (!Array.isArray(value)) return []
+    // map value to [0, 1] range
+    const num = Number(value)
+    const span = cs_max - cs_min
+    if (span === 0) return color_scale_fn(0.5) // midpoint when all values equal
+    if (log) {
+      const log_span = Math.log(cs_max) - Math.log(cs_min_pos)
+      if (log_span === 0) return color_scale_fn(0.5)
+      return color_scale_fn((Math.log(num) - Math.log(cs_min_pos)) / log_span)
+    }
+    return color_scale_fn((num - cs_min) / span)
+  }
 
-      return value.map((val) => {
-        // If it's already a color string, return it directly
-        if (is_color(val)) return val
-        // Otherwise, map it through the color scale
-        return bg_color(val as number, element)
-      })
-    },
-  )
+  // per-segment colors for multi-value tiles (bg_color already handles color strings)
+  const bg_colors = (value: HeatValue | false, element?: ChemicalElement) =>
+    Array.isArray(value) ? value.map((val) => bg_color(val, element)) : []
 
   // Determine whether to automatically show the color bar
-  let should_show_color_bar = $derived.by(() => {
-    if (!show_color_bar || inset || heat_values.length === 0) return false
-
-    const num_vals = heat_values
-      .flat()
-      .filter((val): val is number => typeof val === `number`)
-
-    const usable_values = log ? num_vals.filter((val) => val > 0) : num_vals
-
-    return usable_values.length > 0
-  })
+  let should_show_color_bar = $derived(show_color_bar && !inset && usable_heat_nums.length > 0)
 
   // Calculate heat range for color bar
   let heat_range = $derived.by((): Vec2 => {
     if (!should_show_color_bar) return [0, 1]
-
-    const numeric_values = heat_values
-      .flat()
-      .filter((val): val is number => typeof val === `number`)
-    const usable_values = log ? numeric_values.filter((val) => val > 0) : numeric_values
-
-    if (usable_values.length === 0) return [0, 1]
-
-    const min = color_scale_range[0] ?? Math.min(...usable_values)
-    const max = color_scale_range[1] ?? Math.max(...usable_values)
-
+    const min = color_scale_range[0] ?? Math.min(...usable_heat_nums)
+    const max = color_scale_range[1] ?? Math.max(...usable_heat_nums)
     return [min, max]
   })
 </script>
 
 <svelte:window bind:innerWidth={window_width} onkeydown={handle_key} />
 
-<div {...rest} class="periodic-table {rest.class ?? ``}">
+<div {...rest} class={[`periodic-table`, rest.class]}>
   <div class="ptable-grid" style:gap>
     {#if should_show_color_bar}
       <TableInset class="auto-colorbar-inset">
@@ -326,28 +294,32 @@
     {#each element_data as element (element.number)}
       {@const { column, row, category, name, symbol } = element}
       {@const value = heat_values[element.number - 1]}
+      {@const override = color_overrides[symbol]}
+      {@const tile_missing = heat_values.length > 0 && !override && value_is_missing(value)}
       {@const is_active_elem = active_elements?.some((active_elem) =>
         typeof active_elem === `string`
           ? active_elem === symbol
-          : active_elem?.symbol === symbol
+          : active_elem?.symbol === symbol,
       )}
-      {@const active = active_category === category ||
-        active_element?.name === name || is_active_elem}
-      {@const style = `grid-column: ${column}; grid-row: ${row};`}
+      {@const active =
+        active_category === category || active_element?.name === name || is_active_elem}
+      {@const style = `grid-column: ${column}; grid-row: ${row};${
+        tile_props?.style ? ` ${tile_props.style}` : ``
+      }${tile_missing && missing.style ? ` ${missing.style}` : ``}`}
       <ElementTile
         {element}
         href={links
-        ? typeof links == `string`
-          ? `/${element[links]}`.toLowerCase()
-          : links[symbol]
-        : undefined}
-        {style}
-        {value}
-        bg_color={color_overrides[symbol] ?? bg_color(value, element) ?? undefined}
-        bg_colors={Array.isArray(value) ? bg_colors(value, element) : []}
+          ? typeof links == `string`
+            ? `/${element[links]}`.toLowerCase()
+            : links[symbol]
+          : undefined}
+        value={tile_missing ? undefined : (value ?? undefined)}
+        bg_color={override ?? bg_color(value, element) ?? undefined}
+        bg_colors={!override && Array.isArray(value) ? bg_colors(value, element) : []}
         {active}
-        label={labels[symbol]}
+        label={labels[symbol] ?? (tile_missing ? missing.label : undefined)}
         {...tile_props}
+        {style}
         onmouseenter={(event: MouseEvent) => {
           set_active_element(element)()
           handle_tooltip_enter(element, event)
@@ -390,17 +362,16 @@
     {#if tooltip_visible && tooltip_element}
       {@const el = tooltip_element as ChemicalElement}
       {@const style = `left: ${tooltip_pos.x}px; top: ${tooltip_pos.y}px;`}
-      {@const tooltip_value = heat_values[el.number - 1] ?? 0}
+      {@const tooltip_value = heat_values[el.number - 1]}
       {#if typeof tooltip == `function`}
         <div class="tooltip" {style}>
           {@render tooltip({
-          element: el,
-          value: tooltip_value,
-          active: active_category === el.category ||
-            active_element?.name === el.name,
-          bg_color: color_overrides[el.symbol] ?? bg_color(tooltip_value, el),
-          scale_context: { min: cs_min, max: cs_max, color_scale },
-        })}
+            element: el,
+            value: tooltip_value ?? null,
+            active: active_category === el.category || active_element?.name === el.name,
+            bg_color: color_overrides[el.symbol] ?? bg_color(tooltip_value, el),
+            scale_context: { min: log ? cs_min_pos : cs_min, max: cs_max, color_scale },
+          })}
         </div>
       {:else if tooltip !== false}
         <div class="tooltip" {style}>
@@ -448,10 +419,7 @@
   .tooltip {
     position: absolute;
     transform: translate(-50%, -10%);
-    background: var(
-      --tooltip-bg,
-      light-dark(rgba(255, 255, 255, 0.95), rgba(0, 0, 0, 0.85))
-    );
+    background: var(--tooltip-bg, light-dark(rgba(255, 255, 255, 0.95), rgba(0, 0, 0, 0.85)));
     color: var(--tooltip-color, light-dark(#222, #eee));
     padding: var(--tooltip-padding, 4px 6px);
     border-radius: var(--tooltip-border-radius, var(--border-radius, 3pt));

package/dist/periodic-table/PeriodicTable.svelte.d.ts

@@ -4,12 +4,14 @@ import { ColorBar } from '../plot';
 import type { ComponentProps, Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import type { D3InterpolateName } from '../colors';
+import type { MissingCellStyle } from '../heatmap-matrix';
 import type { ScaleContext } from './index';
+type HeatValue = number | number[] | string | string[];
 type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
     tile_props?: Partial<ComponentProps<typeof ElementTile>>;
     show_photo?: boolean;
     disabled?: boolean;
-    heatmap_values?: Partial<Record<ElementSymbol, number | number[] | string | string[]>> | (number | number[] | string | string[])[];
+    heatmap_values?: Partial<Record<ElementSymbol, HeatValue | null>> | (HeatValue | null)[];
     links?: keyof ChemicalElement | Record<ElementSymbol, string> | null;
     log?: boolean;
     color_scale?: D3InterpolateName | ((num: number) => string);
@@ -28,7 +30,7 @@ type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
     color_scale_range?: [number | null, number | null];
     color_overrides?: Partial<Record<ElementSymbol, string>>;
     labels?: Partial<Record<ElementSymbol, string>>;
-    missing_color?: string;
+    missing?: MissingCellStyle;
     split_layout?: `diagonal` | `horizontal` | `vertical` | `triangular` | `quadrant`;
     show_color_bar?: boolean;
     color_bar_props?: Partial<ComponentProps<typeof ColorBar>>;
@@ -41,7 +43,7 @@ type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
     tooltip?: Snippet<[
         {
             element: ChemicalElement;
-            value: number | number[] | string | string[];
+            value: HeatValue | null;
             active: boolean;
             bg_color: string | null;
             scale_context: ScaleContext;

package/dist/periodic-table/PeriodicTableControls.svelte

@@ -205,7 +205,7 @@
   }
 </script>
 
-<div {...rest} class="controls-grid {rest.class ?? ``}">
+<div {...rest} class={[`controls-grid`, rest.class]}>
   <section class="category-colors">
     <h3 id="element-category-colors-reset" style="grid-column: span 2">
       Element Category Colors
@@ -220,10 +220,7 @@
         onmouseleave={() => (selected.category = null)}
         onblur={() => (selected.category = null)}
       >
-        <input
-          type="color"
-          bind:value={colors.category[category]}
-        />
+        <input type="color" bind:value={colors.category[category]} />
         <span>{category}</span>
         {#if colors.category[category] !== DEFAULT_CATEGORY_COLORS[category]}
           <button
@@ -262,32 +259,14 @@
 
     <label>
       <span>Inner transition offset</span>
-      <input
-        type="range"
-        min="0.1"
-        max="2"
-        step="0.1"
-        bind:value={inner_transition_offset}
-      />
-      <input
-        type="number"
-        min="0.1"
-        max="2"
-        step="0.1"
-        bind:value={inner_transition_offset}
-      />
+      <input type="range" min="0.1" max="2" step="0.1" bind:value={inner_transition_offset} />
+      <input type="number" min="0.1" max="2" step="0.1" bind:value={inner_transition_offset} />
       <button onclick={() => reset_property(`inner_transition_offset`)}>reset</button>
     </label>
 
     <label>
       <span>Transition duration (s)</span>
-      <input
-        type="range"
-        min="0.1"
-        max="2"
-        step="0.1"
-        bind:value={tile_transition_duration}
-      />
+      <input type="range" min="0.1" max="2" step="0.1" bind:value={tile_transition_duration} />
       <input
         type="number"
         min="0.1"
@@ -350,39 +329,15 @@
 
     <label>
       <span>Symbol weight</span>
-      <input
-        type="range"
-        min="100"
-        max="900"
-        step="100"
-        bind:value={symbol_font_weight}
-      />
-      <input
-        type="number"
-        min="100"
-        max="900"
-        step="100"
-        bind:value={symbol_font_weight}
-      />
+      <input type="range" min="100" max="900" step="100" bind:value={symbol_font_weight} />
+      <input type="number" min="100" max="900" step="100" bind:value={symbol_font_weight} />
       <button onclick={() => reset_property(`symbol_font_weight`)}>reset</button>
     </label>
 
     <label>
       <span>Number weight</span>
-      <input
-        type="range"
-        min="100"
-        max="900"
-        step="100"
-        bind:value={number_font_weight}
-      />
-      <input
-        type="number"
-        min="100"
-        max="900"
-        step="100"
-        bind:value={number_font_weight}
-      />
+      <input type="range" min="100" max="900" step="100" bind:value={number_font_weight} />
+      <input type="number" min="100" max="900" step="100" bind:value={number_font_weight} />
       <button onclick={() => reset_property(`number_font_weight`)}>reset</button>
     </label>
   </section>
@@ -424,13 +379,7 @@
     <label>
       <span>Line height</span>
       <input type="range" min="0.8" max="2" step="0.1" bind:value={tooltip_line_height} />
-      <input
-        type="number"
-        min="0.8"
-        max="2"
-        step="0.1"
-        bind:value={tooltip_line_height}
-      />
+      <input type="number" min="0.8" max="2" step="0.1" bind:value={tooltip_line_height} />
       <button onclick={() => reset_property(`tooltip_line_height`)}>reset</button>
     </label>
 
@@ -449,8 +398,7 @@
 <style>
   .controls-grid {
     display: grid;
-    grid-template-columns:
-      var(--ptable-ctrl-columns, repeat(auto-fit, minmax(320px, 1fr)));
+    grid-template-columns: var(--ptable-ctrl-columns, repeat(auto-fit, minmax(320px, 1fr)));
     gap: var(--ptable-ctrl-gap, 1.5em);
     margin: var(--ptable-ctrl-margin, 2em auto);
     padding: 0 1em;

package/dist/periodic-table/TableInset.svelte

@@ -2,12 +2,17 @@
   import type { Snippet } from 'svelte'
   import type { HTMLAttributes } from 'svelte/elements'
 
-  let { as = `aside`, children, ...rest }:
-    & HTMLAttributes<HTMLElementTagNameMap[`aside`]>
-    & { as?: keyof HTMLElementTagNameMap; children?: Snippet } = $props()
+  let {
+    as = `aside`,
+    children,
+    ...rest
+  }: HTMLAttributes<HTMLElementTagNameMap[`aside`]> & {
+    as?: keyof HTMLElementTagNameMap
+    children?: Snippet
+  } = $props()
 </script>
 
-<svelte:element this={as} {...rest} class="table-inset {rest.class ?? ``}">
+<svelte:element this={as} {...rest} class={[`table-inset`, rest.class]}>
   {@render children?.()}
 </svelte:element>