matterviz 0.3.7 → 0.4.0

package/dist/plot/sankey/Sankey.svelte.d.ts

@@ -0,0 +1,74 @@
+import type { BasePlotProps, LegendConfig, SankeyData, SankeyHandlerProps, SankeyLinkColorMode, SankeyLinkHandlerProps, SankeyNodeAlign, SankeyNodeHandlerProps, SankeyOrientation } from '..';
+import type { Sides } from '../core/layout';
+import { type PositionedLink, type PositionedNode } from './sankey';
+import { type Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+declare function $$render<Metadata extends Record<string, unknown> = Record<string, unknown>>(): {
+    props: HTMLAttributes<HTMLDivElement> & Omit<BasePlotProps, "change"> & {
+        data?: SankeyData<Metadata>;
+        orientation?: SankeyOrientation;
+        node_width?: number;
+        node_padding?: number;
+        node_align?: SankeyNodeAlign;
+        iterations?: number;
+        link_opacity?: number;
+        link_color_mode?: SankeyLinkColorMode;
+        show_node_labels?: boolean;
+        node_label?: (node: PositionedNode) => string;
+        value_format?: string;
+        padding?: Sides;
+        legend?: LegendConfig | null;
+        show_legend?: boolean;
+        tooltip?: Snippet<[SankeyHandlerProps<Metadata>]>;
+        node_content?: Snippet<[{
+            node: PositionedNode;
+            color: string;
+        }]>;
+        link_content?: Snippet<[{
+            link: PositionedLink;
+            color: string;
+        }]>;
+        change?: (data: SankeyHandlerProps<Metadata> | null) => void;
+        on_node_click?: (data: SankeyNodeHandlerProps<Metadata> & {
+            event: MouseEvent | KeyboardEvent;
+        }) => void;
+        on_node_hover?: (data: (SankeyNodeHandlerProps<Metadata> & {
+            event: MouseEvent | FocusEvent;
+        }) | null) => void;
+        on_link_click?: (data: SankeyLinkHandlerProps<Metadata> & {
+            event: MouseEvent | KeyboardEvent;
+        }) => void;
+        on_link_hover?: (data: (SankeyLinkHandlerProps<Metadata> & {
+            event: MouseEvent | FocusEvent;
+        }) | null) => void;
+        header_controls?: Snippet<[{
+            height: number;
+            width: number;
+            fullscreen: boolean;
+        }]>;
+        controls_extra?: Snippet<[{
+            orientation: SankeyOrientation;
+        }]>;
+    };
+    exports: {};
+    bindings: "data" | "orientation" | "show_controls" | "fullscreen" | "hovered" | "controls_open" | "node_align" | "node_width" | "node_padding" | "link_opacity" | "show_node_labels";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Metadata extends Record<string, unknown> = Record<string, unknown>> {
+    props(): ReturnType<typeof $$render<Metadata>>['props'];
+    events(): ReturnType<typeof $$render<Metadata>>['events'];
+    slots(): ReturnType<typeof $$render<Metadata>>['slots'];
+    bindings(): "data" | "orientation" | "show_controls" | "fullscreen" | "hovered" | "controls_open" | "node_align" | "node_width" | "node_padding" | "link_opacity" | "show_node_labels";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Metadata extends Record<string, unknown> = Record<string, unknown>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Metadata>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Metadata>['props']>, ReturnType<__sveltets_Render<Metadata>['events']>, ReturnType<__sveltets_Render<Metadata>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Metadata>['bindings']>;
+    } & ReturnType<__sveltets_Render<Metadata>['exports']>;
+    <Metadata extends Record<string, unknown> = Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<Metadata>['props']> & {}): ReturnType<__sveltets_Render<Metadata>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Sankey: $$IsomorphicComponent;
+type Sankey<Metadata extends Record<string, unknown> = Record<string, unknown>> = InstanceType<typeof Sankey<Metadata>>;
+export default Sankey;

package/dist/plot/sankey/SankeyControls.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+  import { SettingsSection } from '../../layout'
+  import type { SankeyNodeAlign, SankeyOrientation } from '..'
+  import ControlPane from '../core/components/ControlPane.svelte'
+  import { DEFAULTS } from '../../settings'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+
+  let {
+    show_controls = $bindable(true),
+    controls_open = $bindable(false),
+    orientation = $bindable(DEFAULTS.sankey.orientation),
+    node_width = $bindable(DEFAULTS.sankey.node_width),
+    node_padding = $bindable(DEFAULTS.sankey.node_padding),
+    node_align = $bindable(DEFAULTS.sankey.node_align),
+    link_opacity = $bindable(DEFAULTS.sankey.link_opacity),
+    show_node_labels = $bindable(DEFAULTS.sankey.show_node_labels),
+    toggle_props = {},
+    pane_props = {},
+    children,
+  }: {
+    show_controls?: boolean
+    controls_open?: boolean
+    orientation?: SankeyOrientation
+    node_width?: number
+    node_padding?: number
+    node_align?: SankeyNodeAlign
+    link_opacity?: number
+    show_node_labels?: boolean
+    toggle_props?: HTMLAttributes<HTMLButtonElement>
+    pane_props?: HTMLAttributes<HTMLDivElement>
+    children?: Snippet
+  } = $props()
+</script>
+
+{#if show_controls}
+  <ControlPane bind:controls_open controls_class="sankey" {toggle_props} {pane_props}>
+    {@render children?.()}
+    <SettingsSection
+      title="Sankey"
+      current_values={{
+        orientation,
+        node_align,
+        node_width,
+        node_padding,
+        link_opacity,
+        show_node_labels,
+      }}
+      on_reset={() => {
+        ;({
+          orientation,
+          node_align,
+          node_width,
+          node_padding,
+          link_opacity,
+          show_node_labels,
+        } = DEFAULTS.sankey)
+      }}
+      style="display: flex; flex-wrap: wrap; gap: 2ex"
+    >
+      <label style="flex: 1">
+        Orientation:
+        <select bind:value={orientation}>
+          <option value="horizontal">Horizontal</option>
+          <option value="vertical">Vertical</option>
+        </select>
+      </label>
+      <label style="flex: 1">
+        Node align:
+        <select bind:value={node_align}>
+          <option value="justify">Justify</option>
+          <option value="left">Left</option>
+          <option value="right">Right</option>
+          <option value="center">Center</option>
+        </select>
+      </label>
+      <label style="flex: 1 1 100%">
+        Node width:
+        <input type="range" min="4" max="60" step="1" bind:value={node_width} />
+        <input type="number" min="4" max="60" step="1" bind:value={node_width} />
+      </label>
+      <label style="flex: 1 1 100%">
+        Node padding:
+        <input type="range" min="0" max="40" step="1" bind:value={node_padding} />
+        <input type="number" min="0" max="40" step="1" bind:value={node_padding} />
+      </label>
+      <label style="flex: 1 1 100%">
+        Link opacity:
+        <input type="range" min="0.05" max="1" step="0.05" bind:value={link_opacity} />
+        <input type="number" min="0.05" max="1" step="0.05" bind:value={link_opacity} />
+      </label>
+      <label style="flex: 1 1 100%">
+        <input type="checkbox" bind:checked={show_node_labels} />
+        Show node labels
+      </label>
+    </SettingsSection>
+  </ControlPane>
+{/if}

package/dist/plot/sankey/SankeyControls.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { SankeyNodeAlign, SankeyOrientation } from '..';
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type $$ComponentProps = {
+    show_controls?: boolean;
+    controls_open?: boolean;
+    orientation?: SankeyOrientation;
+    node_width?: number;
+    node_padding?: number;
+    node_align?: SankeyNodeAlign;
+    link_opacity?: number;
+    show_node_labels?: boolean;
+    toggle_props?: HTMLAttributes<HTMLButtonElement>;
+    pane_props?: HTMLAttributes<HTMLDivElement>;
+    children?: Snippet;
+};
+declare const SankeyControls: import("svelte").Component<$$ComponentProps, {}, "orientation" | "show_controls" | "controls_open" | "node_align" | "node_width" | "node_padding" | "link_opacity" | "show_node_labels">;
+type SankeyControls = ReturnType<typeof SankeyControls>;
+export default SankeyControls;

package/dist/plot/sankey/index.d.ts

@@ -0,0 +1,4 @@
+export * from './sankey';
+export type * from './sankey-types';
+export { default as Sankey } from './Sankey.svelte';
+export { default as SankeyControls } from './SankeyControls.svelte';

package/dist/plot/sankey/index.js

@@ -0,0 +1,3 @@
+export * from './sankey';
+export { default as Sankey } from './Sankey.svelte';
+export { default as SankeyControls } from './SankeyControls.svelte';

package/dist/plot/sankey/sankey-types.d.ts

@@ -0,0 +1,42 @@
+export type SankeyOrientation = `horizontal` | `vertical`;
+export type SankeyNodeAlign = `left` | `right` | `center` | `justify`;
+export type SankeyLinkColorMode = `source` | `target` | `gradient` | `static`;
+export interface SankeyNode<Metadata = Record<string, unknown>> {
+    id?: string | number;
+    label?: string;
+    color?: string;
+    metadata?: Metadata;
+}
+export interface SankeyLink<Metadata = Record<string, unknown>> {
+    source: number | string;
+    target: number | string;
+    value: number;
+    color?: string;
+    label?: string;
+    metadata?: Metadata;
+}
+export interface SankeyData<Metadata = Record<string, unknown>> {
+    nodes: SankeyNode<Metadata>[];
+    links: SankeyLink<Metadata>[];
+}
+export interface SankeyNodeHandlerProps<Metadata = Record<string, unknown>> {
+    type: `node`;
+    node_idx: number;
+    id: string | number;
+    label?: string;
+    value: number;
+    color: string;
+    metadata?: Metadata;
+}
+export interface SankeyLinkHandlerProps<Metadata = Record<string, unknown>> {
+    type: `link`;
+    link_idx: number;
+    source_idx: number;
+    target_idx: number;
+    source_label?: string;
+    target_label?: string;
+    value: number;
+    color: string;
+    metadata?: Metadata;
+}
+export type SankeyHandlerProps<Metadata = Record<string, unknown>> = SankeyNodeHandlerProps<Metadata> | SankeyLinkHandlerProps<Metadata>;

package/dist/plot/sankey/sankey-types.js

@@ -0,0 +1,4 @@
+// === Sankey diagram types ===
+// Public input/event types for the Sankey component; layout-result types
+// (PositionedNode/PositionedLink) live in sankey.ts next to the layout math.
+export {};

package/dist/plot/sankey/sankey.d.ts

@@ -0,0 +1,52 @@
+import { sankeyCenter, sankeyJustify, sankeyLeft, sankeyRight } from 'd3-sankey';
+import type { SankeyLink as D3Link, SankeyNode as D3Node } from 'd3-sankey';
+import type { SankeyData, SankeyNodeAlign, SankeyOrientation } from '../core/types';
+interface NodeExtra {
+    node_idx: number;
+    id: string | number;
+    label?: string;
+    color?: string;
+}
+interface LinkExtra {
+    link_idx: number;
+    color?: string;
+    label?: string;
+}
+export type PositionedNode = D3Node<NodeExtra, LinkExtra> & {
+    node_idx: number;
+    id: string | number;
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+    value: number;
+    depth: number;
+};
+export type PositionedLink = D3Link<NodeExtra, LinkExtra> & {
+    link_idx: number;
+    width: number;
+    source: PositionedNode;
+    target: PositionedNode;
+    path: string;
+    mid: {
+        x: number;
+        y: number;
+    };
+};
+export interface SankeyLayoutOptions {
+    width: number;
+    height: number;
+    node_width?: number;
+    node_padding?: number;
+    node_align?: SankeyNodeAlign;
+    orientation?: SankeyOrientation;
+    iterations?: number;
+}
+export interface SankeyLayoutResult {
+    nodes: PositionedNode[];
+    links: PositionedLink[];
+}
+export declare function sankey_from_links(source: readonly number[], target: readonly number[], value: readonly number[], labels?: readonly string[]): SankeyData;
+export declare function compute_sankey_layout<Metadata = Record<string, unknown>>(data: SankeyData<Metadata>, opts: SankeyLayoutOptions): SankeyLayoutResult;
+export declare const sankey_align_fn: (align: SankeyNodeAlign) => typeof sankeyLeft | typeof sankeyRight | typeof sankeyCenter | typeof sankeyJustify;
+export {};

package/dist/plot/sankey/sankey.js

@@ -0,0 +1,187 @@
+// Layout helpers for Sankey diagrams, wrapping d3-sankey.
+// Single source of truth for node/link positioning math so the component stays
+// declarative and the layout is independently unit-testable.
+import { sankey as d3_sankey, sankeyCenter, sankeyJustify, sankeyLeft, sankeyRight, } from 'd3-sankey';
+const ALIGN_FNS = {
+    left: sankeyLeft,
+    right: sankeyRight,
+    center: sankeyCenter,
+    justify: sankeyJustify,
+};
+// Resolve a link source/target reference (id or index) to a node array index.
+// Prefers id lookup (ids may be numeric), falls back to treating numbers as indices.
+function resolve_node_ref(ref, id_to_idx, n_nodes) {
+    const by_id = id_to_idx.get(ref);
+    if (by_id !== undefined)
+        return by_id;
+    if (typeof ref === `number` && Number.isInteger(ref) && ref >= 0 && ref < n_nodes) {
+        return ref;
+    }
+    throw new Error(`Sankey link references unknown node: ${JSON.stringify(ref)}`);
+}
+function resolve_numeric_node_ref(ref, n_nodes) {
+    if (Number.isInteger(ref) && ref >= 0 && ref < n_nodes)
+        return ref;
+    throw new Error(`Sankey link references unknown node: ${JSON.stringify(ref)}`);
+}
+// Build a SankeyData object from parallel flat arrays (e.g. the plotly/matbench
+// `link.source`/`link.target`/`link.value` + `node.label` format).
+export function sankey_from_links(source, target, value, labels) {
+    if (source.length !== target.length || source.length !== value.length) {
+        throw new Error(`sankey_from_links: source (${source.length}), target (${target.length}) and value (${value.length}) must have equal length`);
+    }
+    // Single pass instead of Math.max(...source, ...target): spreading large index arrays
+    // (e.g. spacegroup correspondence matrices) as call args can exceed the arg-count limit.
+    let max_idx = -1;
+    for (const idx of source)
+        if (idx > max_idx)
+            max_idx = idx;
+    for (const idx of target)
+        if (idx > max_idx)
+            max_idx = idx;
+    // Cover the highest indexed link even when labels is shorter (missing labels fall
+    // back to the index string below), so links never reference a non-existent node.
+    const n_nodes = Math.max(labels?.length ?? 0, max_idx + 1);
+    const nodes = Array.from({ length: n_nodes }, (_, idx) => ({
+        id: idx,
+        label: labels?.[idx] ?? `${idx}`,
+    }));
+    const links = source.map((src, idx) => ({
+        source: src,
+        target: target[idx],
+        value: value[idx],
+    }));
+    return { nodes, links };
+}
+// Vertical ribbon path: mirror of d3's sankeyLinkHorizontal but flowing top->bottom.
+// Reads the raw d3 layout fields (link.y0/y1 are stacking-axis centers, which in
+// vertical mode map to screen x; source.x1/target.x0 are depth positions = screen y).
+function vertical_link_path(link) {
+    const x0 = link.y0 ?? 0;
+    const x1 = link.y1 ?? 0;
+    const y0 = link.source.x1;
+    const y1 = link.target.x0;
+    const ym = (y0 + y1) / 2;
+    return `M${x0},${y0}C${x0},${ym} ${x1},${ym} ${x1},${y1}`;
+}
+function horizontal_link_path(link) {
+    const x0 = link.source.x1;
+    const x1 = link.target.x0;
+    const y0 = link.y0 ?? 0;
+    const y1 = link.y1 ?? 0;
+    const xm = (x0 + x1) / 2;
+    return `M${x0},${y0}C${xm},${y0} ${xm},${y1} ${x1},${y1}`;
+}
+// Compute node boxes and link ribbon paths in screen space.
+// Clones input so the (reactive) user data is never mutated by d3-sankey.
+export function compute_sankey_layout(data, opts) {
+    const { width, height, node_width = 24, node_padding = 12, node_align = `justify`, orientation = `horizontal`, iterations = 6, } = opts;
+    // All-zero link values would make d3-sankey divide by zero (NaN ribbon paths)
+    const has_flow = data.links.some((link) => link.value > 0);
+    if (!(width > 0) || !(height > 0) || data.nodes.length === 0 || !has_flow)
+        return { nodes: [], links: [] };
+    // Resolve ids -> indices and clone into fresh objects (d3 mutates these).
+    // Links may reference a node by explicit `id`, or by `label` when no id is set,
+    // or by zero-based index (handled as a fallback in resolve_node_ref).
+    const needs_ref_lookup = data.links.some((link) => typeof link.source !== `number` || typeof link.target !== `number`) || data.nodes.some((node, idx) => typeof node.id === `number` && node.id !== idx);
+    let id_to_idx;
+    if (needs_ref_lookup) {
+        id_to_idx = new Map();
+        data.nodes.forEach((node, idx) => {
+            const key = node.id ?? node.label;
+            if (key === undefined)
+                return; // index-only node, resolved via fallback
+            if (id_to_idx?.has(key)) {
+                console.warn(`Sankey: duplicate node ${node.id !== undefined ? `id` : `label`} "${key}" — links resolve to the last occurrence. Set unique \`id\`s.`);
+            }
+            id_to_idx?.set(key, idx);
+        });
+    }
+    const node_copies = data.nodes.map((node, idx) => ({
+        node_idx: idx,
+        id: node.id ?? idx,
+        label: node.label,
+        color: node.color,
+    }));
+    // Resolve a source/target ref to a node index: id/label lookup when any link uses
+    // non-numeric refs, otherwise a cheap numeric-range check (no map built).
+    const resolve_ref = (ref) => needs_ref_lookup
+        ? resolve_node_ref(ref, id_to_idx, data.nodes.length)
+        : resolve_numeric_node_ref(ref, data.nodes.length);
+    const link_copies = data.links.map((link, idx) => ({
+        link_idx: idx,
+        color: link.color,
+        label: link.label,
+        source: resolve_ref(link.source),
+        target: resolve_ref(link.target),
+        value: link.value,
+    }));
+    // Drop nodes with no incoming or outgoing links. d3-sankey gives such orphans
+    // value 0 (zero height) and still stacks them with node_padding each, so extra
+    // labels pile up and overflow past the plot edge. They are never referenced by a
+    // link, so removing them can't break link resolution (node_idx stays stable).
+    const linked_node_idxs = new Set();
+    for (const link of link_copies) {
+        linked_node_idxs.add(link.source);
+        linked_node_idxs.add(link.target);
+    }
+    const used_nodes = node_copies.filter((node) => linked_node_idxs.has(node.node_idx));
+    const is_vertical = orientation === `vertical`;
+    // d3 lays out left->right (depth on x). For vertical we run in a transposed
+    // extent (depth on what becomes screen y) then swap node boxes afterwards.
+    const extent = is_vertical
+        ? [
+            [0, 0],
+            [height, width],
+        ]
+        : [
+            [0, 0],
+            [width, height],
+        ];
+    const layout = d3_sankey()
+        .nodeId((node) => node.node_idx)
+        .nodeWidth(node_width)
+        .nodePadding(node_padding)
+        .nodeAlign(ALIGN_FNS[node_align])
+        .iterations(iterations)
+        .extent(extent);
+    let graph;
+    try {
+        graph = layout({ nodes: used_nodes, links: link_copies });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Sankey layout failed (graph must be a DAG without cycles): ${msg}`, {
+            cause: err,
+        });
+    }
+    // Build link ribbon paths from raw d3 fields BEFORE transposing node boxes.
+    for (const link of graph.links) {
+        if (is_vertical) {
+            link.path = vertical_link_path(link);
+            link.mid = {
+                x: ((link.y0 ?? 0) + (link.y1 ?? 0)) / 2,
+                y: (link.source.x1 + link.target.x0) / 2,
+            };
+        }
+        else {
+            link.path = horizontal_link_path(link);
+            const x = (link.source.x1 + link.target.x0) / 2;
+            const y = ((link.y0 ?? 0) + (link.y1 ?? 0)) / 2;
+            link.mid = { x, y };
+        }
+    }
+    // Transpose node boxes into screen space for vertical orientation
+    if (is_vertical) {
+        for (const node of graph.nodes) {
+            const { x0, x1, y0, y1 } = node;
+            node.x0 = y0;
+            node.x1 = y1;
+            node.y0 = x0;
+            node.y1 = x1;
+        }
+    }
+    return graph;
+}
+// Map a node alignment string to the d3-sankey alignment function (exposed for tests)
+export const sankey_align_fn = (align) => ALIGN_FNS[align];