matterviz 0.4.0 → 0.4.2

package/dist/plot/core/utils/hierarchy-chart.js

@@ -0,0 +1,179 @@
+// State/interaction helpers shared by the hierarchical part-of-whole charts
+// (Sunburst, Treemap): metric coloring, hover/mute dimming, handler payloads,
+// breadcrumbs and keyboard plumbing. All pure functions over the flat pre-order
+// arc arrays that compute_sunburst_layout produces — each component keeps only
+// its geometry-specific logic (polar projection vs squarified tiling).
+import { get_relative_coords } from '../interactions';
+import { create_color_scale } from '../scales';
+import { node_display_name, node_label_variants } from './hierarchy-labels';
+import { compute_sunburst_layout } from '../../sunburst/sunburst';
+// Degrade to an empty layout (instead of crashing the host page) on invalid data
+export function safe_hierarchy_layout(data, opts) {
+    try {
+        return compute_sunburst_layout(data, opts);
+    }
+    catch (err) {
+        console.error(err);
+        return { arcs: [], root: null, max_depth: 0 };
+    }
+}
+// Continuous metric coloring: when color_values is given, nodes are colored by
+// their metric on a d3 colormap (nodes returning null keep their categorical
+// color). The user accessor runs exactly once per node.
+export function compute_metric_colors(arcs, color_values, color_scale, color_range) {
+    if (!color_values)
+        return null;
+    const vals = arcs.map((arc) => {
+        const val = arc.depth === 0 ? null : color_values(arc);
+        return val != null && Number.isFinite(val) ? val : null;
+    });
+    // iterative min/max: spreading into Math.min/max overflows the call stack
+    // for very large arc arrays
+    let min_val = Infinity;
+    let max_val = -Infinity;
+    for (const val of vals) {
+        if (val == null)
+            continue;
+        if (val < min_val)
+            min_val = val;
+        if (val > max_val)
+            max_val = val;
+    }
+    if (min_val > max_val)
+        return null; // no finite values
+    const range = color_range ?? [min_val, max_val];
+    const scale = create_color_scale({ scheme: color_scale, value_range: range }, range);
+    return {
+        range,
+        colors: vals.map((val, idx) => (val == null ? arcs[idx].color : scale(val))),
+    };
+}
+const MUTED_OPACITY = 0.12;
+// Legend muting + hover dimming per node, indexed by node_idx. The hovered node
+// + its ancestors/descendants stay fully opaque, other nodes dim to 0.3; muted
+// categories dim hardest. Pre-order indexing makes the ancestor/descendant
+// tests O(1): a subtree is the contiguous index range [node_idx, subtree_end].
+// Zoom-independent: recomputed only when hover/mute state changes, so during
+// zoom tweens (where geometry re-evaluates per frame) this is an array lookup.
+export function compute_node_dim(arcs, muted_ids, hovered_idx) {
+    const hov = hovered_idx != null ? arcs[hovered_idx] : null;
+    const active = (arc) => !hov ||
+        (arc.node_idx >= hov.node_idx && arc.node_idx <= hov.subtree_end) ||
+        (hov.node_idx >= arc.node_idx && hov.node_idx <= arc.subtree_end);
+    return arcs.map((arc) => {
+        const muted = arc.path.length > 0 && muted_ids.has(arc.path[0]);
+        return {
+            opacity: muted ? MUTED_OPACITY : active(arc) ? 1 : 0.3,
+            // labels dim only when muted, not when hover-inactive (undefined omits the attr)
+            label_opacity: muted ? MUTED_OPACITY : undefined,
+        };
+    });
+}
+// Drop muted ids that no longer exist in the current layout (e.g. after a data swap)
+export function prune_muted_ids(arcs, muted_ids) {
+    const valid = new Set(arcs.filter((arc) => arc.depth === 1).map((arc) => arc.id));
+    for (const id of muted_ids)
+        if (!valid.has(id))
+            muted_ids.delete(id);
+}
+// Toggle one depth-1 category's muted state (legend click)
+export function toggle_muted(muted_ids, id) {
+    if (id !== undefined && !muted_ids.delete(id))
+        muted_ids.add(id);
+}
+// Legend: one item per depth-1 category; toggling mutes (dims) rather than removes
+export function hierarchy_legend_items(depth1_arcs, muted_ids, color_for) {
+    return depth1_arcs.map((arc, idx) => ({
+        series_idx: idx,
+        label: node_display_name(arc),
+        visible: !muted_ids.has(arc.id),
+        display_style: { symbol_type: `Square`, symbol_color: color_for(arc) },
+    }));
+}
+// Handler props are the node minus its layout geometry (screen coords are an
+// implementation detail), plus the resolved parent id
+export function node_handler_props(arcs, arc, color) {
+    const { x0: _x0, x1: _x1, y0: _y0, y1: _y1, subtree_end: _end, parent_idx, ...node } = arc;
+    return {
+        ...node,
+        type: `node`,
+        color,
+        parent_id: parent_idx != null ? arcs[parent_idx].id : null,
+    };
+}
+// True while the user has an uncollapsed text selection inside the chart. Labels
+// are selectable text, and the mouseup that ends a selection drag also fires a
+// click — selecting a label must not zoom or fire on_node_click.
+export function selection_within(wrapper) {
+    const selection = globalThis.getSelection?.();
+    return Boolean(selection &&
+        !selection.isCollapsed &&
+        selection.anchorNode &&
+        wrapper?.contains(selection.anchorNode));
+}
+// Ancestor chain from the root to the current zoom root (clickable breadcrumb trail)
+export function ancestor_chain(arcs, zoom_root) {
+    if (!zoom_root || zoom_root.depth === 0)
+        return [];
+    const chain = [];
+    let cur = zoom_root;
+    while (cur) {
+        chain.unshift(cur);
+        cur = cur.parent_idx != null ? arcs[cur.parent_idx] : null;
+    }
+    return chain;
+}
+// Per-node label text, measured widths, fill/label colors, aria string (and
+// optional clickability) — all zoom-independent, so computed once per
+// layout/option change instead of per animation frame (format_value, canvas
+// measureText, contrast picking and color resolution would otherwise run per
+// visible node per frame during zoom tweens)
+export function compute_node_infos(arcs, opts) {
+    const { label_text, value_format, label_font } = opts;
+    return arcs.map((arc) => {
+        const { text, extended, short } = node_label_variants(arc, label_text, value_format);
+        const fill = opts.color_for(arc);
+        const variants = (text ? [extended, text, short] : []).flatMap((variant) => variant === undefined
+            ? []
+            : [{ text: variant, width: opts.text_width(variant, label_font) }]);
+        return {
+            variants,
+            aria: `${node_display_name(arc)}: ${arc.value}`,
+            fill,
+            label_fill: opts.contrast(fill),
+            ...(opts.clickable ? { clickable: opts.clickable(arc) } : {}),
+        };
+    });
+}
+// The font node labels actually render in (respects the chart's font-size CSS
+// var instead of assuming 11px), for canvas-measured label fitting
+export function svg_label_font(svg_element) {
+    if (!svg_element)
+        return `11px sans-serif`;
+    const { fontSize, fontFamily } = getComputedStyle(svg_element);
+    return `${fontSize} ${fontFamily}`;
+}
+// Anchor tooltips at the cursor (mouse hover) so they follow the pointer across
+// wide nodes; callers fall back to the node center on keyboard focus (no cursor).
+export const pointer_pos = (event, svg_element) => event instanceof MouseEvent ? get_relative_coords(event, svg_element) : null;
+export const is_activation_key = (evt) => [`Enter`, ` `].includes(evt.key);
+// Escape zooms out one level, then exits fullscreen once at the root — but only
+// when the user is interacting with this chart (pointer over it, focus inside
+// it, or fullscreen)
+export function handle_hierarchy_escape(evt, ctx) {
+    if (evt.key !== `Escape`)
+        return;
+    const within = ctx.fullscreen ||
+        (ctx.wrapper != null &&
+            (ctx.wrapper.matches(`:hover`) || ctx.wrapper.contains(document.activeElement)));
+    if (!within)
+        return;
+    if (ctx.zoomed) {
+        evt.preventDefault();
+        ctx.zoom_out();
+    }
+    else if (ctx.fullscreen) {
+        evt.preventDefault();
+        ctx.exit_fullscreen();
+    }
+}

package/dist/plot/core/utils/hierarchy-labels.d.ts

@@ -0,0 +1,20 @@
+import type { SunburstLabelText } from '../../sunburst/sunburst';
+interface LabeledNode {
+    id: string | number;
+    label?: string;
+    label_short?: string;
+    value: number;
+    fraction: number;
+    parent_fraction?: number;
+}
+export declare const node_display_name: (node: LabeledNode) => string;
+export declare function node_label_str(node: LabeledNode, label_text: SunburstLabelText, value_format: string): string;
+export declare function node_label_variants(node: LabeledNode, label_text: SunburstLabelText, value_format: string): {
+    text: string;
+    extended?: string;
+    short?: string;
+};
+export declare function make_cached_contrast(): (fill: string) => string;
+export declare function make_cached_text_width(): (text: string, font: string) => number;
+export declare function export_hierarchy_chart(svg_element: SVGSVGElement | null, base_filename: string, format: `svg` | `png`): void;
+export {};

package/dist/plot/core/utils/hierarchy-labels.js

@@ -0,0 +1,99 @@
+// Label/color helpers shared by the hierarchical part-of-whole charts
+// (Sunburst, Treemap): per-node label strings, memoized contrast picking and
+// text measurement, and SVG/PNG export. Pure + cache-factory functions so each
+// component instance owns its caches without sharing global state.
+import { pick_contrast_color } from '../../../colors';
+import { export_svg_as_png, export_svg_as_svg } from '../../../io/export';
+import { format_value } from '../../../labels';
+import { measure_text_width } from '../layout';
+export const node_display_name = (node) => node.label ?? `${node.id}`;
+// What a node's label displays, per the label_text mode (plotly textinfo
+// equivalent); percent is of the root total, parent-percent of the parent node
+export function node_label_str(node, label_text, value_format) {
+    const name = node_display_name(node);
+    if (label_text === `label`)
+        return name;
+    const val = format_value(node.value, value_format);
+    if (label_text === `value`)
+        return val;
+    if (label_text === `label+value`)
+        return `${name} ${val}`;
+    if (label_text === `label+parent-percent`) {
+        return `${name} (${format_value(node.parent_fraction ?? node.fraction, `.0%`)})`;
+    }
+    const pct = format_value(node.fraction, `.1%`);
+    if (label_text === `percent`)
+        return pct;
+    return `${name} ${pct}`; // label+percent
+}
+const COMPOUND_LABEL_MODES = new Set([
+    `label+value`,
+    `label+percent`,
+    `label+parent-percent`,
+]);
+// Base + optional richer/compact variants for fit-aware rendering: compound
+// modes degrade to the bare label when the full text doesn't fit its node,
+// and nodes with a `label_short` degrade once more to that compact form
+// before the label is hidden entirely.
+export function node_label_variants(node, label_text, value_format) {
+    const short = node.label_short;
+    const text = node_label_str(node, label_text, value_format);
+    if (!COMPOUND_LABEL_MODES.has(label_text))
+        return { text, short };
+    return { text: node_display_name(node), extended: text, short };
+}
+// Black/white label text, whichever contrasts with the given fill. Memoized per
+// color string - parsing/luminance is too slow per label per frame, and distinct
+// node colors are few.
+export function make_cached_contrast() {
+    const cache = new Map();
+    return (fill) => {
+        let contrast = cache.get(fill);
+        if (contrast === undefined) {
+            // growth guard (same as make_cached_text_width): continuous metric coloring
+            // can emit unbounded distinct fills
+            if (cache.size > 10_000)
+                cache.clear();
+            contrast = pick_contrast_color({ bg_color: fill });
+            cache.set(fill, contrast);
+        }
+        return contrast;
+    };
+}
+// Memoized canvas text measurement (far too slow per visible node per frame)
+export function make_cached_text_width() {
+    const cache = new Map();
+    return (text, font) => {
+        const key = `${font}|${text}`;
+        let text_width = cache.get(key);
+        if (text_width === undefined) {
+            if (cache.size > 10_000)
+                cache.clear(); // growth guard
+            text_width = measure_text_width(text, font);
+            cache.set(key, text_width);
+        }
+        return text_width;
+    };
+}
+// Styles these components apply via CSS that exported standalone SVGs must carry
+// as presentation attributes (inlined onto a clone by the io/export helpers)
+const EXPORT_INLINE_STYLES = [
+    `fill`,
+    `stroke`,
+    `stroke-width`,
+    `text-anchor`,
+    `dominant-baseline`,
+    `font-size`,
+    `font-family`,
+    `font-weight`,
+    `opacity`,
+];
+export function export_hierarchy_chart(svg_element, base_filename, format) {
+    if (!svg_element)
+        return;
+    const filename = `${base_filename}.${format}`;
+    if (format === `svg`)
+        export_svg_as_svg(svg_element, filename, EXPORT_INLINE_STYLES);
+    else
+        export_svg_as_png(svg_element, filename, 150, EXPORT_INLINE_STYLES);
+}

package/dist/plot/core/utils/label-placement.d.ts

@@ -42,7 +42,7 @@ export interface LeaderLineOptions {
 }
 export declare function parse_font_size(size_str?: string): number;
 export declare function estimate_label_size(text: string, font_size_str?: string): LabelSize;
-export declare function rect_overlap_area(a: Rect, b: Rect): number;
+export declare function rect_overlap_area(rect_a: Rect, rect_b: Rect): number;
 export declare function rect_circle_overlap(rect: Rect, cx: number, cy: number, radius: number): number;
 export declare function segments_intersect(ax1: number, ay1: number, ax2: number, ay2: number, bx1: number, by1: number, bx2: number, by2: number): boolean;
 export declare function segment_rect_intersects(sx1: number, sy1: number, sx2: number, sy2: number, rect: Rect): boolean;

package/dist/plot/core/utils/label-placement.js

@@ -18,10 +18,10 @@ const copy_state = (target, source) => {
 export function parse_font_size(size_str) {
     if (!size_str)
         return 12;
-    const match = /^(\d+(?:\.\d+)?)(px|em|rem)?$/.exec(size_str);
+    const match = /^(?<size>\d+(?:\.\d+)?)(?<unit>px|em|rem)?$/.exec(size_str);
     if (!match)
         return 12;
-    const value = parseFloat(match[1]);
+    const value = Number(match[1]);
     return match[2] === `em` || match[2] === `rem` ? value * 16 : value;
 }
 export function estimate_label_size(text, font_size_str) {
@@ -34,9 +34,9 @@ export function estimate_label_size(text, font_size_str) {
     };
 }
 // === Geometry helpers ===
-export function rect_overlap_area(a, b) {
-    const ox = Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x));
-    const oy = Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+export function rect_overlap_area(rect_a, rect_b) {
+    const ox = Math.max(0, Math.min(rect_a.x + rect_a.w, rect_b.x + rect_b.w) - Math.max(rect_a.x, rect_b.x));
+    const oy = Math.max(0, Math.min(rect_a.y + rect_a.h, rect_b.y + rect_b.h) - Math.max(rect_a.y, rect_b.y));
     return ox * oy;
 }
 export function rect_circle_overlap(rect, cx, cy, radius) {

package/dist/plot/core/utils.d.ts

@@ -1,3 +1,4 @@
+import type { Vec2 } from '../../math';
 import type { TweenOptions } from 'svelte/motion';
 export declare const unique_id: (prefix?: string) => string;
 export declare const LINE_TWEEN: {
@@ -8,4 +9,4 @@ export declare const resolve_line_tween: (line_tween: TweenOptions<string> | und
     series: number;
     points: number;
 }) => TweenOptions<string> | undefined;
-export declare function calc_auto_range(values: number[]): [number, number];
+export declare function calc_auto_range(values: number[]): Vec2;