matterviz 0.4.1 → 0.4.2

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

@@ -1,13 +1,14 @@
 import type { PaneProps, PaneToggleProps } from '../../overlays';
 import type { D3ColorSchemeName, D3InterpolateName } from '../../colors';
 import type { D3SymbolName } from '../../labels';
-import type { Point2D, Point3D, Vec2, Vec3 } from '../../math';
+import type { Point2D, Vec2 } from '../../math';
 import type { ComponentProps, Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import type { TweenOptions } from 'svelte/motion';
 import type { Sides } from './layout';
 import type PlotLegend from './components/PlotLegend.svelte';
 import type { TicksOption } from './scales';
+import type { FillGradient } from './types/fills';
 export type { TweenOptions } from 'svelte/motion';
 export type { BandwidthOption, BoxHandlerProps, BoxPlotSeries, ViolinKind, ViolinSide, WhiskerMode, } from '../box/box-plot';
 export type { CleaningConfig, CleaningQuality, CleaningResult, InstabilityResult, InvalidValueMode, LocalOutlierConfig, LocalOutlierResult, OscillationWeights, PhysicalBounds, SmoothingConfig, TruncationMode, } from './data-cleaning';
@@ -79,6 +80,7 @@ export interface BarStyle {
     ry?: number;
     [key: string]: unknown;
 }
+export type LineCurve = `linear` | `monotone` | `natural` | `step` | `basis` | `catmull-rom`;
 export interface LineStyle {
     color?: string;
     width?: number;
@@ -113,10 +115,12 @@ export interface DataSeries<Metadata = Record<string, unknown>> {
     label?: string;
     legend_group?: string;
     unit?: string;
+    axis_group?: string;
     line_style?: {
         stroke?: string;
         stroke_width?: number;
         line_dash?: string;
+        curve?: LineCurve;
     };
     filtered_data?: InternalPoint<Metadata>[];
     _id?: string | number;
@@ -200,6 +204,27 @@ export type SizeScaleConfig = {
     radius_range?: Vec2;
     value_range?: Vec2;
 };
+export declare const COLOR_BAR_DEFAULTS: {
+    readonly width: 220;
+    readonly horizontal_bar_height: 16;
+    readonly binned_bar_height: 10;
+    readonly horizontal_footprint: {
+        readonly width: 220;
+        readonly height: 56;
+    };
+    readonly vertical_footprint: {
+        readonly width: 56;
+        readonly height: 100;
+    };
+};
+export declare const SCALE_DEFAULTS: {
+    scheme: D3InterpolateName;
+    color: ColorScaleConfig;
+    radius: Vec2;
+    binned_radius: Vec2;
+    size: SizeScaleConfig;
+    size_3d: SizeScaleConfig;
+};
 export declare const is_scale_type_name: (val: string) => val is ScaleTypeName;
 export declare function get_scale_type_name(scale_type: ScaleType | undefined): ScaleTypeName;
 export declare function get_arcsinh_threshold(scale_type: ScaleType | undefined): number;
@@ -457,326 +482,6 @@ export declare const DEFAULT_GRID_STYLE: {
 export declare const DEFAULT_MARKERS: "line+points";
 export declare const DEFAULT_SERIES_COLORS: readonly ["#4e79a7", "#f28e2c", "#e15759", "#76b7b2", "#59a14f", "#edc949", "#af7aa1", "#ff9da7", "#9c755f", "#bab0ab"];
 export declare const DEFAULT_SERIES_SYMBOLS: readonly ["Circle", "Square", "Triangle", "Cross", "Diamond", "Star", "Wye"];
-export interface ScatterPoint3D<Metadata = Record<string, unknown>> extends Point<Metadata> {
-    z: number;
-}
-export interface DataSeries3D<Metadata = Record<string, unknown>> extends Omit<DataSeries<Metadata>, `y_axis` | `filtered_data`> {
-    z: readonly number[];
-    filtered_data?: InternalPoint3D<Metadata>[];
-}
-export interface InternalPoint3D<Metadata = Record<string, unknown>> extends ScatterPoint3D<Metadata> {
-    series_idx: number;
-    point_idx: number;
-    color_value?: number | null;
-    size_value?: number | null;
-    point_style?: PointStyle;
-}
-export type SurfaceType = `grid` | `parametric` | `triangulated`;
-export interface Surface3DConfig {
-    id?: string | number;
-    type: SurfaceType;
-    x_range?: Vec2;
-    y_range?: Vec2;
-    resolution?: number | Vec2;
-    z_fn?: (x: number, y: number) => number;
-    u_range?: Vec2;
-    v_range?: Vec2;
-    parametric_fn?: (u: number, v: number) => Point3D;
-    points?: Point3D[];
-    triangles?: Vec3[];
-    color?: string;
-    color_fn?: (x: number, y: number, z: number) => string;
-    opacity?: number;
-    wireframe?: boolean;
-    wireframe_color?: string;
-    wireframe_width?: number;
-    visible?: boolean;
-    double_sided?: boolean;
-}
-export interface AxisConfig3D extends AxisConfig {
-    show_plane?: boolean;
-    plane_opacity?: number;
-}
-export interface DisplayConfig3D extends DisplayConfig {
-    z_grid?: boolean;
-    z_zero_line?: boolean;
-    show_axes?: boolean;
-    show_axis_labels?: boolean;
-    show_bounding_box?: boolean;
-    show_grid?: boolean;
-    projections?: {
-        xy?: boolean;
-        xz?: boolean;
-        yz?: boolean;
-    };
-    projection_opacity?: number;
-    projection_scale?: number;
-}
-export interface Scatter3DHandlerProps<Metadata = Record<string, unknown>> extends Omit<HandlerProps<Metadata>, `x_axis` | `x2_axis` | `y_axis` | `y2_axis`> {
-    z: number;
-    x_axis: AxisConfig3D;
-    y_axis: AxisConfig3D;
-    z_axis: AxisConfig3D;
-    x_formatted: string;
-    y_formatted: string;
-    z_formatted: string;
-    color_value?: number | null;
-}
-export type Scatter3DHandlerEvent<Metadata = Record<string, unknown>> = Scatter3DHandlerProps<Metadata> & {
-    event?: MouseEvent;
-    point: InternalPoint3D<Metadata>;
-};
-export type CameraProjection3D = `perspective` | `orthographic`;
-export interface PlotConfig3D {
-    x_axis?: AxisConfig3D;
-    y_axis?: AxisConfig3D;
-    z_axis?: AxisConfig3D;
-    display?: DisplayConfig3D;
-}
-export interface StyleOverrides3D extends StyleOverrides {
-    point?: StyleOverrides[`point`] & {
-        sphere_segments?: number;
-    };
-}
-export interface ControlsConfig3D extends ControlsConfig {
-    show_camera_controls?: boolean;
-    show_surface_controls?: boolean;
-}
-export type FillBoundary = {
-    type: `series`;
-    series_idx: number;
-} | {
-    type: `series`;
-    series_id: string | number;
-} | {
-    type: `constant`;
-    value: number;
-} | {
-    type: `axis`;
-    axis: `x` | `x2` | `y` | `y2`;
-    value?: number;
-} | {
-    type: `function`;
-    fn: (coord: number) => number;
-} | {
-    type: `data`;
-    values: readonly number[];
-    x?: readonly number[];
-} | number;
-export interface FillGradient {
-    type: `linear` | `radial`;
-    angle?: number;
-    center?: {
-        x: number;
-        y: number;
-    };
-    stops: readonly [number, string][];
-}
-export interface FillEdgeStyle {
-    color?: string;
-    width?: number;
-    dash?: string;
-    opacity?: number;
-}
-export interface FillHoverStyle {
-    fill?: string;
-    fill_opacity?: number;
-    edge?: FillEdgeStyle;
-    cursor?: string;
-    scale?: number;
-    stroke?: string;
-    stroke_width?: number;
-}
-export interface FillHandlerEvent {
-    event: MouseEvent | KeyboardEvent;
-    region_idx: number;
-    region_id?: string | number;
-    x: number;
-    y: number;
-    px: number;
-    py: number;
-    label?: string;
-    metadata?: Record<string, unknown>;
-}
-export type LayerZIndex = `below-grid` | `below-lines` | `below-points` | `above-all`;
-export declare const FILL_CURVE_TYPES: readonly ["linear", "monotoneX", "monotoneY", "step", "stepBefore", "stepAfter", "basis", "cardinal", "catmullRom", "natural"];
-export type FillCurveType = (typeof FILL_CURVE_TYPES)[number];
-export interface FillRegion {
-    id?: string | number;
-    label?: string;
-    upper: FillBoundary;
-    lower: FillBoundary;
-    x_range?: [number | null, number | null];
-    y_range?: [number | null, number | null];
-    where?: (x: number, y_upper: number, y_lower: number) => boolean;
-    fill?: string | FillGradient;
-    fill_opacity?: number;
-    edge_upper?: FillEdgeStyle;
-    edge_lower?: FillEdgeStyle;
-    curve?: FillCurveType;
-    step_position?: number;
-    z_index?: LayerZIndex;
-    visible?: boolean;
-    hover_style?: FillHoverStyle;
-    on_click?: (event: FillHandlerEvent) => void;
-    on_hover?: (event: FillHandlerEvent | null) => void;
-    show_in_legend?: boolean;
-    legend_group?: string;
-    metadata?: Record<string, unknown>;
-}
-export interface ErrorBand {
-    series: {
-        type: `series`;
-        series_idx: number;
-    } | {
-        type: `series`;
-        series_id: string | number;
-    };
-    error: number | readonly number[] | {
-        upper: number | readonly number[];
-        lower: number | readonly number[];
-    };
-    fill?: string;
-    fill_opacity?: number;
-    edge_style?: FillEdgeStyle;
-    id?: string | number;
-    label?: string;
-    show_in_legend?: boolean;
-}
-export interface RefLineStyle {
-    color?: string;
-    width?: number;
-    dash?: string;
-    opacity?: number;
-}
-export interface RefLineAnnotation {
-    text: string;
-    position?: `start` | `center` | `end`;
-    side?: `above` | `below` | `left` | `right`;
-    offset?: {
-        x?: number;
-        y?: number;
-    };
-    gap?: number;
-    edge_padding?: number;
-    font_size?: string;
-    font_family?: string;
-    color?: string;
-    background?: string;
-    padding?: number;
-    rotate?: boolean;
-}
-export interface RefLineEvent {
-    event: MouseEvent | KeyboardEvent | FocusEvent;
-    line_idx: number;
-    line_id?: string | number;
-    type: RefLine[`type`];
-    label?: string;
-    metadata?: Record<string, unknown>;
-}
-export interface RefLineBase {
-    id?: string | number;
-    x_span?: [number | null, number | null];
-    y_span?: [number | null, number | null];
-    coord_mode?: `data` | `relative`;
-    x_axis?: `x1` | `x2`;
-    y_axis?: `y1` | `y2`;
-    style?: RefLineStyle;
-    annotation?: RefLineAnnotation;
-    z_index?: LayerZIndex;
-    visible?: boolean;
-    hover_style?: RefLineStyle;
-    on_click?: (event: RefLineEvent) => void;
-    on_hover?: (event: RefLineEvent | null) => void;
-    show_in_legend?: boolean;
-    label?: string;
-    legend_group?: string;
-    metadata?: Record<string, unknown>;
-}
-export type RefLineValue = number | Date | string;
-export type RefLine = RefLineBase & ({
-    type: `horizontal`;
-    y: RefLineValue;
-} | {
-    type: `vertical`;
-    x: RefLineValue;
-} | {
-    type: `diagonal`;
-    slope: number;
-    intercept: number;
-} | {
-    type: `segment`;
-    p1: [RefLineValue, RefLineValue];
-    p2: [RefLineValue, RefLineValue];
-} | {
-    type: `line`;
-    p1: [RefLineValue, RefLineValue];
-    p2: [RefLineValue, RefLineValue];
-});
-export declare const REF_LINE_STYLE_DEFAULTS: Required<RefLineStyle>;
-type Ref3DBase = Omit<RefLineBase, `coord_mode` | `x_axis` | `y_axis` | `style` | `hover_style` | `annotation` | `on_click` | `on_hover`> & {
-    z_span?: [number | null, number | null];
-};
-export interface RefLine3DBase extends Ref3DBase {
-    style?: RefLineStyle;
-    hover_style?: RefLineStyle;
-    annotation?: RefLineAnnotation;
-    on_click?: (event: {
-        line_idx: number;
-        line_id?: string | number;
-    }) => void;
-    on_hover?: (event: {
-        line_idx: number;
-        line_id?: string | number;
-    } | null) => void;
-}
-export type RefLine3D = RefLine3DBase & ({
-    type: `x-axis`;
-    y: number;
-    z: number;
-} | {
-    type: `y-axis`;
-    x: number;
-    z: number;
-} | {
-    type: `z-axis`;
-    x: number;
-    y: number;
-} | {
-    type: `segment`;
-    p1: Vec3;
-    p2: Vec3;
-} | {
-    type: `line`;
-    p1: Vec3;
-    p2: Vec3;
-});
-export interface RefPlaneStyle {
-    color?: string;
-    opacity?: number;
-    wireframe?: boolean;
-    wireframe_color?: string;
-    double_sided?: boolean;
-}
-export interface RefPlaneBase extends Ref3DBase {
-    style?: RefPlaneStyle;
-}
-export type RefPlane = RefPlaneBase & ({
-    type: `xy`;
-    z: number;
-} | {
-    type: `xz`;
-    y: number;
-} | {
-    type: `yz`;
-    x: number;
-} | {
-    type: `normal`;
-    normal: Vec3;
-    point: Vec3;
-} | {
-    type: `points`;
-    p1: Vec3;
-    p2: Vec3;
-    p3: Vec3;
-});
+export type * from './types/plot-3d';
+export * from './types/fills';
+export * from './types/reference-lines';

package/dist/plot/core/types.js

@@ -1,3 +1,24 @@
+// Shared defaults for color/size scales and colorbar layout (scatter, bar, binned-scatter, …)
+const COLOR_BAR_WIDTH = 220;
+export const COLOR_BAR_DEFAULTS = {
+    width: COLOR_BAR_WIDTH,
+    horizontal_bar_height: 16,
+    binned_bar_height: 10,
+    horizontal_footprint: { width: COLOR_BAR_WIDTH, height: 56 },
+    vertical_footprint: { width: 56, height: 100 },
+};
+// Shared color/size scale defaults for scatter, scatter-3d, binned-scatter, bar, …
+const VIRIDIS = `interpolateViridis`;
+const SCATTER_RADIUS = [2, 10];
+const BINNED_RADIUS = [4, 12];
+export const SCALE_DEFAULTS = {
+    scheme: VIRIDIS,
+    color: { type: `linear`, scheme: VIRIDIS, value_range: undefined },
+    radius: SCATTER_RADIUS,
+    binned_radius: BINNED_RADIUS,
+    size: { type: `linear`, radius_range: SCATTER_RADIUS, value_range: undefined },
+    size_3d: { type: `linear`, radius_range: [0.05, 0.2], value_range: undefined },
+};
 // Type guard for select value narrowing (avoids unsafe casts)
 const SCALE_TYPE_NAMES = new Set([`linear`, `log`, `arcsinh`, `time`]);
 export const is_scale_type_name = (val) => SCALE_TYPE_NAMES.has(val);
@@ -77,23 +98,5 @@ export const DEFAULT_SERIES_SYMBOLS = [
     `Star`,
     `Wye`,
 ];
-// Curve types supported for fill path generation (matching d3-shape curves)
-export const FILL_CURVE_TYPES = [
-    `linear`,
-    `monotoneX`,
-    `monotoneY`,
-    `step`,
-    `stepBefore`,
-    `stepAfter`,
-    `basis`,
-    `cardinal`,
-    `catmullRom`,
-    `natural`,
-];
-// Default style values for reference lines
-export const REF_LINE_STYLE_DEFAULTS = {
-    color: `currentColor`,
-    width: 1,
-    dash: ``,
-    opacity: 1,
-};
+export * from './types/fills';
+export * from './types/reference-lines';

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

@@ -0,0 +1,51 @@
+import type { D3InterpolateName } from '../../../colors';
+import type { Vec2 } from '../../../math';
+import type { LegendItem } from '../types';
+import type { PositionedArc, SunburstLabelText, SunburstLayoutOptions, SunburstLayoutResult, SunburstNode, SunburstNodeHandlerProps } from '../../sunburst/sunburst';
+export declare function safe_hierarchy_layout<Metadata>(data: SunburstNode<Metadata> | SunburstNode<Metadata>[], opts: SunburstLayoutOptions): SunburstLayoutResult<Metadata>;
+export declare function compute_metric_colors<Metadata>(arcs: readonly PositionedArc<Metadata>[], color_values: ((arc: PositionedArc<Metadata>) => number | null) | undefined, color_scale: D3InterpolateName, color_range?: Vec2): {
+    range: Vec2;
+    colors: string[];
+} | null;
+export declare function compute_node_dim<Metadata>(arcs: readonly PositionedArc<Metadata>[], muted_ids: ReadonlySet<string | number>, hovered_idx: number | null): {
+    opacity: number;
+    label_opacity: number | undefined;
+}[];
+export declare function prune_muted_ids<Metadata>(arcs: readonly PositionedArc<Metadata>[], muted_ids: Set<string | number>): void;
+export declare function toggle_muted(muted_ids: Set<string | number>, id: string | number | undefined): void;
+export declare function hierarchy_legend_items<Metadata>(depth1_arcs: readonly PositionedArc<Metadata>[], muted_ids: ReadonlySet<string | number>, color_for: (arc: PositionedArc<Metadata>) => string): LegendItem[];
+export declare function node_handler_props<Metadata>(arcs: readonly PositionedArc<Metadata>[], arc: PositionedArc<Metadata>, color: string): SunburstNodeHandlerProps<Metadata>;
+export declare function selection_within(wrapper: HTMLElement | undefined): boolean;
+export declare function ancestor_chain<Metadata>(arcs: readonly PositionedArc<Metadata>[], zoom_root: PositionedArc<Metadata> | null): PositionedArc<Metadata>[];
+export interface HierarchyNodeInfo {
+    variants: {
+        text: string;
+        width: number;
+    }[];
+    aria: string;
+    fill: string;
+    label_fill: string;
+    clickable?: boolean;
+}
+export declare function compute_node_infos<Metadata>(arcs: readonly PositionedArc<Metadata>[], opts: {
+    label_text: SunburstLabelText;
+    value_format: string;
+    label_font: string;
+    color_for: (arc: PositionedArc<Metadata>) => string;
+    text_width: (text: string, font: string) => number;
+    contrast: (fill: string) => string;
+    clickable?: (arc: PositionedArc<Metadata>) => boolean;
+}): HierarchyNodeInfo[];
+export declare function svg_label_font(svg_element: SVGSVGElement | null): string;
+export declare const pointer_pos: (event: MouseEvent | FocusEvent | undefined, svg_element: SVGSVGElement | null) => {
+    x: number;
+    y: number;
+} | null;
+export declare const is_activation_key: (evt: KeyboardEvent) => boolean;
+export declare function handle_hierarchy_escape(evt: KeyboardEvent, ctx: {
+    wrapper: HTMLElement | undefined;
+    fullscreen: boolean;
+    zoomed: boolean;
+    zoom_out: () => void;
+    exit_fullscreen: () => void;
+}): void;

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 {};