@perspective-dev/viewer-charts 4.3.0

package/dist/esm/charts/chart.d.ts

@@ -0,0 +1,338 @@
+import type { View } from "@perspective-dev/client";
+import type { ColumnDataMap } from "../data/view-reader";
+import type { WebGLContextManager } from "../webgl/context-manager";
+import type { ZoomController } from "../interaction/zoom-controller";
+import type { HostSink } from "../interaction/tooltip-controller";
+export interface ChartImplementation {
+    uploadAndRender(glManager: WebGLContextManager, columns: ColumnDataMap, startRow: number, endRow: number): void;
+    /**
+     * The single render entrypoint. Every render-triggering caller —
+     * upload chunks, zoom / pan, resize, theme invalidation,
+     * host-driven redraws — calls this. Routes through the
+     * module-level scheduler ([render/scheduler.ts]) so concurrent
+     * calls collapse to one `_fullRender` per RAF and the host
+     * blitter receives one bitmap per frame per chart.
+     *
+     * The returned promise resolves after this entry's `_fullRender`
+     * + `awaitGpuFence` + `endFrame` chain completes — independent
+     * of other charts in the same RAF, which run their fence waits
+     * in parallel.
+     *
+     * The synchronous-render bypass for `snapshotPng` (calls
+     * `_fullRender` directly, skips `endFrame`) is the only
+     * sanctioned exception and lives inside the worker renderer.
+     */
+    requestRender(glManager: WebGLContextManager): Promise<void>;
+    /**
+     * The chart-specific frame builder. The scheduler wraps this with
+     * fence + `endFrame`; callers must not invoke it directly except
+     * for `snapshotPng`, which needs an intact GL backbuffer for
+     * `gl.readPixels` and so must skip the `endFrame` pair.
+     */
+    _fullRender(glManager: WebGLContextManager): void;
+    /**
+     * Hand the current View to the chart so it can make on-demand
+     * per-row queries (for lazy tooltip column lookups). Called on
+     * every `draw`; the chart disposes any prior fetcher and clears
+     * dependent UI (pinned tooltip) so stale rows never surface.
+     *
+     * TODO: pinned tooltips are dismissed on view update today. A
+     * future enhancement is to keep a pinned tooltip visible (with its
+     * captured data) until the user dismisses it, even after the
+     * underlying view no longer contains that row.
+     */
+    setView?(view: View): void;
+    /**
+     * Set the gridline canvas (behind WebGL, for gridlines).
+     */
+    setGridlineCanvas?(canvas: HTMLCanvasElement | OffscreenCanvas): void;
+    /**
+     * Set the chrome canvas (above WebGL, for axes/labels/legend/tooltip).
+     */
+    setChromeCanvas?(canvas: HTMLCanvasElement | OffscreenCanvas): void;
+    /**
+     * Hand the chart a pre-computed CSS-variable map produced on the
+     * main thread via `snapshotThemeVars(el)`, which it can decode into
+     * a full `Theme` without touching the DOM (charts always run inside
+     * the renderer scope, which has no `getComputedStyle`).
+     */
+    setTheme?(vars: Record<string, string>): void;
+    /**
+     * Set the zoom controller for interactive zoom/pan.
+     */
+    setZoomController?(zc: ZoomController): void;
+    /**
+     * Wire the chart's `TooltipController` for virtual-dispatch hover /
+     * click events forwarded from the host. The renderer drives
+     * `dispatchHover` / `dispatchLeave` / `dispatchClick` /
+     * `dispatchDblClick` from `InteractionEvent`s; the supplied
+     * `HostSink` posts pin / dismiss / setCursor intents back to the
+     * host so the resulting DOM mutations happen there (the renderer
+     * scope has no DOM in worker mode, and uses the same channel
+     * in-process for symmetry).
+     */
+    attachTooltip?(host: HostSink): void;
+    /**
+     * Set the column slot config (with nulls for empty slots).
+     */
+    setColumnSlots?(slots: (string | null)[]): void;
+    /**
+     * Set group_by and split_by config from the viewer.
+     */
+    setViewPivots?(groupBy: string[], splitBy: string[]): void;
+    /**
+     * Set column type schema from the view (e.g., { "col": "date" }).
+     */
+    setColumnTypes?(schema: Record<string, string>): void;
+    /**
+     * Set the source-column types used for `group_by` level lookups —
+     * sourced from `table.schema()` + `view.expression_schema()`. Used
+     * by categorical-axis charts to detect numeric / date / boolean
+     * group_by levels (which are not keyed in `view.schema()` because
+     * they surface as `__ROW_PATH_N__` columns).
+     */
+    setGroupByTypes?(schema: Record<string, string>): void;
+    /**
+     * Set per-column render config (the second argument to `plugin.restore`).
+     * Key is the aggregate base name; value is an open object whose
+     * `chart_type` / `stack` fields are consumed by the Y-bar glyph router.
+     */
+    setColumnsConfig?(cfg: Record<string, any>): void;
+    /**
+     * Set the plugin's default glyph type. Used by the Y-series chart
+     * family (Y Bar / Y Line / Y Scatter / Y Area): each tag is the same
+     * `BarChart` impl with a different starting `chart_type` applied to
+     * columns that lack an explicit entry in `columns_config`.
+     */
+    setDefaultChartType?(chartType: string): void;
+    /**
+     * Set the faceting config: one small-multiple sub-plot per
+     * `split_by` group, optional shared axes, coordinated tooltip, and
+     * zoom routing mode. Seeded from `DEFAULT_FACET_CONFIG` at init;
+     * `plugin_config.facet_mode` / `facet_zoom_mode` override the
+     * matching fields via `AbstractChart.setPluginConfig`.
+     */
+    setFacetConfig?(cfg: FacetConfig): void;
+    /**
+     * Set the plugin-scoped global configuration — the values backing
+     * `plugin_config_schema` / `plugin_config` in `restore`. Replaces
+     * the previous module-level constants (`LINE_WIDTH_PX`,
+     * `POINT_SIZE_PX`, `BAND_INNER_FRAC`, `BAR_INNER_PAD`,
+     * `WICK_WIDTH_PX`, `OHLC_LINE_WIDTH_PX`, `AUTO_ALT_Y_AXIS`) plus
+     * the faceted/series zoom-mode semantics described in
+     * {@link PluginConfig}.
+     */
+    setPluginConfig?(cfg: PluginConfig): void;
+    /**
+     * Drop any cached theme values so the next render re-reads CSS
+     * variables. Driven from `plugin.restyle()`.
+     */
+    invalidateTheme?(): void;
+    /**
+     * Clear the `domain_mode: "expand"` accumulator state so the next
+     * data load starts from the current data extent. Driven from
+     * `resetAllZooms` (the user clicked "Reset Zoom"). View-config
+     * mutations route through `AbstractChart`'s `setColumnSlots` /
+     * `setViewPivots` / `setColumnTypes` setters, which call the same
+     * hook internally.
+     */
+    resetExpandedDomain?(): void;
+    destroy(): void;
+}
+export interface FacetConfig {
+    /**
+     * "grid" = small multiples (default); "overlay" = legacy single-plot.
+     */
+    facet_mode: "grid" | "overlay";
+    /**
+     * Share one bottom X axis across all columns of facets.
+     */
+    shared_x_axis: boolean;
+    /**
+     * Share one left Y axis across all rows of facets.
+     */
+    shared_y_axis: boolean;
+    /**
+     * Paint a tooltip in every facet (otherwise only the source facet).
+     */
+    coordinated_tooltip: boolean;
+    /**
+     * "shared" = one viewport for all facets; "independent" = per-facet.
+     */
+    zoom_mode: "shared" | "independent";
+    /**
+     * Pixel gap between adjacent facet cells in grid mode.
+     */
+    facet_padding: number;
+}
+export declare const DEFAULT_FACET_CONFIG: FacetConfig;
+/**
+ * Plugin-scoped global configuration — the user-facing settings backing
+ * `plugin_config_schema()` / the `plugin_config` slot in `restore`.
+ *
+ * Each chart type's `plugin_config_schema` returns only the fields that
+ * are applicable for that chart (see `applicable_plugin_fields` on
+ * `ChartTypeConfig`); inapplicable fields are hidden in the UI. The
+ * chart impl receives the full struct on `setPluginConfig` and reads
+ * only the fields its render / build pipeline cares about.
+ *
+ * Some fields overlap with {@link FacetConfig} (`facet_mode`,
+ * `facet_zoom_mode`); the base `AbstractChart.setPluginConfig` syncs
+ * those onto `_facetConfig` so deep render code keeps reading the
+ * single facet struct it already does. `series_zoom_mode` toggles the
+ * categorical-Y chart base's `_autoFitValue` flag.
+ */
+export interface PluginConfig {
+    /**
+     * Auto-detect Y dual-axis splits when aggregate magnitudes differ
+     * by more than `DUAL_Y_RATIO_THRESHOLD`×. Series charts only.
+     * Replaces the `AUTO_ALT_Y_AXIS` compile-time toggle.
+     */
+    auto_alt_y_axis: boolean;
+    /**
+     * Faceting strategy when `split_by` is non-empty.
+     *
+     * - `"grid"` — one small-multiple sub-plot per split group.
+     * - `"overlay"` — single plot with split groups differentiated by
+     *   color. Synced into `_facetConfig.facet_mode`.
+     */
+    facet_mode: "grid" | "overlay";
+    /**
+     * Faceted-cartesian zoom routing. `"shared"` — one viewport across
+     * all facets; `"independent"` — wheel/pan routes to the facet under
+     * the cursor with its own viewport. Synced into
+     * `_facetConfig.zoom_mode`.
+     */
+    facet_zoom_mode: "shared" | "independent";
+    /**
+     * Series-chart value-axis behavior on zoom.
+     *
+     * - `"dynamic"` — value axis refits to the visible categorical
+     *   slice (current default; `CategoricalYChart._autoFitValue` =
+     *   true).
+     * - `"fixed"` — value axis stays pinned to the full-data extent.
+     */
+    series_zoom_mode: "fixed" | "dynamic";
+    /**
+     * Anchor the value axis to zero — when true, `0` is forced into
+     * the rendered domain even if all data sits well above or below
+     * it. Natural for bar / area glyphs (which grow from the zero
+     * baseline) and surprising for line / scatter (where the
+     * interesting variation often lives far from zero). Per-chart-type
+     * defaults route through `ChartTypeConfig.plugin_field_defaults`:
+     * `true` for Y Bar / Y Area / X Bar, `false` elsewhere.
+     */
+    include_zero: boolean;
+    /**
+     * Domain accumulation policy across successive `View` updates.
+     *
+     * - `"fit"` — every update recomputes the rendered domain (and on
+     *   cartesian charts, the X/Y range and color/size scales) from
+     *   the current data extent. Can grow or shrink frame-to-frame.
+     * - `"expand"` — the rendered domain monotonically *grows*: each
+     *   update unions the new data extent with the previously rendered
+     *   extent, so once a value is in scope it stays in scope. Reset
+     *   by the "Reset Zoom" button, view-config changes (group_by /
+     *   split_by / column-slot / column-type), or toggling back to
+     *   `"fit"`.
+     */
+    domain_mode: "fit" | "expand";
+    /**
+     * Width of polyline glyphs in CSS pixels (multiplied by DPR at GL
+     * upload). Replaces the duplicated `LINE_WIDTH_PX` constants in
+     * the cartesian + series line glyphs.
+     */
+    line_width_px: number;
+    /**
+     * Diameter of scatter point glyphs in CSS pixels. Replaces
+     * `POINT_SIZE_PX`.
+     */
+    point_size_px: number;
+    /**
+     * Fraction of each category band occupied by its slot(s). Replaces
+     * `BAND_INNER_FRAC`. Affects buffer contents — takes effect on
+     * next data load.
+     */
+    band_inner_frac: number;
+    /**
+     * Relative inner padding between adjacent slots within a band.
+     * Replaces `BAR_INNER_PAD`. Affects buffer contents — takes effect
+     * on next data load.
+     */
+    bar_inner_pad: number;
+    /**
+     * Candlestick wick stroke width in CSS pixels. Replaces
+     * `WICK_WIDTH_PX`.
+     */
+    wick_width_px: number;
+    /**
+     * OHLC bar stroke width in CSS pixels. Replaces
+     * `OHLC_LINE_WIDTH_PX`.
+     */
+    ohlc_line_width_px: number;
+    /**
+     * density splat radius in CSS pixels. Each data point is
+     * rasterized as a soft disk of this radius into the accumulation
+     * FBO before the gradient LUT pass resolves to a heat color.
+     */
+    gradient_radius_px: number;
+    /**
+     * density per-splat intensity multiplier. Controls how
+     * fast the density grows when points overlap (low values produce
+     * a smoother, more diffuse field; high values produce sharper
+     * peaks).
+     */
+    gradient_intensity: number;
+    /**
+     * density clamp on the maximum accumulated heat used for
+     * the gradient-LUT lookup. Lower values saturate sooner (more of
+     * the LUT's hot stops show up); higher values stay cooler. In
+     * every mode this controls the alpha (intensity) ramp; in
+     * `density` mode it also drives the hue, and in `signed` mode it
+     * scales the signed-sum-to-hue mapping.
+     */
+    gradient_heat_max: number;
+    /**
+     * density color-reduction mode. Controls how each pixel's
+     * stack of overlapping splats is reduced to a single LUT-t / alpha
+     * pair in the resolve pass.
+     *
+     * - `mean` (default) — hue is the density-weighted average of
+     *   per-point color-t. Reads as "the typical color-column value
+     *   in this region." Uses robust (5th/95th-percentile) bounds so
+     *   one outlier can't compress the rest of the data toward the
+     *   gradient midpoint.
+     * - `density` — ignore the color column even when wired; hue and
+     *   alpha both follow density. Reads as "where do points cluster."
+     *   Useful when the color column is attached for tooltip lookup
+     *   only.
+     * - `extreme` — keep the per-pixel maximum signed deviation of
+     *   `t - 0.5` (split into positive and negative channels, MAX-
+     *   blended). Reads as "where are the outliers." Density still
+     *   drives alpha so a single-point extreme fades naturally.
+     *   Requires a second framebuffer; uses MRT on WebGL2 hardware
+     *   with `OES_draw_buffers_indexed`, two passes otherwise.
+     * - `signed` — accumulate signed `t - 0.5` and let positive vs
+     *   negative cancel out. Reads as "net positive vs net negative
+     *   in each region." Requires a float-capable framebuffer; on
+     *   `UNSIGNED_BYTE` fallback hardware degrades silently to
+     *   `mean` with a one-line console warning.
+     */
+    gradient_color_mode: "mean" | "density" | "extreme" | "signed";
+    /**
+     * Map basemap tile provider. Applies only to map plugin tags
+     * (`map-scatter`, `map-line`, `map-density`). Cartesian charts
+     * ignore the field. Surfaced as an enum on the settings panel so
+     * users can switch light/dark/voyager without writing custom
+     * tile-source code.
+     */
+    map_tile_provider: "carto-positron" | "carto-dark-matter" | "carto-voyager";
+    /**
+     * Map basemap alpha (0..1). Pre-multiplied into the tile fragment
+     * shader's output so the chart's glyph layer composites over a
+     * dimmer or brighter version of the basemap. `1.0` (default)
+     * shows the tiles at full opacity.
+     */
+    map_tile_alpha: number;
+}
+export declare const DEFAULT_PLUGIN_CONFIG: PluginConfig;

package/dist/esm/charts/common/band-layout.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared per-category band geometry used by categorical-X charts (bar,
+ * candlestick, ohlc). The category axis uses unit-wide bands centered
+ * on integer indices; within each band, `numSlots` rectangles (bars,
+ * candles, …) are laid out side by side with a small inner padding.
+ */
+export interface SlotGeometry {
+    /**
+     * Width (in data-space units) of a single slot.
+     */
+    slotWidth: number;
+    /**
+     * Half the drawable width of each slot after inner padding.
+     */
+    halfWidth: number;
+}
+/**
+ * Compute slot geometry for `numSlots` rectangles per category band.
+ *
+ * `bandInnerFrac` is the fraction of each category's band width
+ * actually covered by slots; `barInnerPad` is the relative padding
+ * between adjacent slots within a band. Both come from
+ * {@link PluginConfig.band_inner_frac} / `bar_inner_pad`. Defaults
+ * match the previous hard-coded constants (0.5 / 0.1).
+ */
+export declare function computeSlotGeometry(numSlots: number, bandInnerFrac?: number, barInnerPad?: number): SlotGeometry;
+/**
+ * X-center for slot `slotIdx` of `numSlots` in the band centered at
+ * `catIdx`. Matches bar's layout: slot 0 on the far left, numSlots-1 on
+ * the far right, symmetric about `catIdx`.
+ */
+export declare function slotCenter(catIdx: number, slotIdx: number, numSlots: number, slotWidth: number): number;

package/dist/esm/charts/common/categorical-y-chart.d.ts

@@ -0,0 +1,53 @@
+import type { PlotLayout } from "../../layout/plot-layout";
+import type { AxisDomain } from "../../axis/numeric-axis";
+import type { CategoricalDomain, CategoricalLevel } from "../../axis/categorical-axis";
+import type { ZoomConfig } from "../../interaction/zoom-controller";
+import { AbstractChart } from "../chart-base";
+/**
+ * Common base for charts with a categorical X axis, a numeric Y (value)
+ * axis, and an optional zoom-on-categorical interaction. Today that's
+ * Bar (all four Y-family plugins + X Bar) and Candlestick/OHLC.
+ *
+ * The class is deliberately thin: it consolidates the bookkeeping that
+ * genuinely repeats across those chart families (categorical domain
+ * state, last-frame cache for overlay-only redraws, value-axis lock
+ * default, shared GL-program + corner-buffer fields) and nothing more.
+ * Glyph rendering, hit-testing, build pipelines, and horizontal / dual-
+ * axis variance live in the concrete subclasses because they diverge
+ * too much to usefully share.
+ */
+export declare abstract class CategoricalYChart extends AbstractChart {
+    /**
+     * Row-path levels (group_by hierarchy) for X-axis tick rendering.
+     */
+    _rowPaths: CategoricalLevel[];
+    /**
+     * Number of categories on the X axis.
+     */
+    _numCategories: number;
+    /**
+     * Offset into the aggregated-row stream (total-rows are skipped).
+     */
+    _rowOffset: number;
+    _program: WebGLProgram | null;
+    _cornerBuffer: WebGLBuffer | null;
+    _lastLayout: PlotLayout | null;
+    _lastXDomain: CategoricalDomain | null;
+    _lastYDomain: AxisDomain | null;
+    _lastYTicks: number[] | null;
+    /**
+     * When true, the value axis refits to the visible categorical
+     * window each frame — so zooming the categorical axis tightens the
+     * value axis to just the bars / candles in view. Subclasses own
+     * the per-frame cache object because the cache key shape varies
+     * (bar needs `hiddenSeries`, candlestick doesn't; bar may have
+     * dual-axis extents, candlestick is single-axis).
+     */
+    _autoFitValue: boolean;
+    /**
+     * Lock the value axis by default — user wheel/pan should only
+     * scroll the categorical axis. Subclasses override to flip
+     * orientation (e.g. X Bar where the value axis is on X).
+     */
+    protected getZoomConfig(): ZoomConfig;
+}

package/dist/esm/charts/common/category-axis-resolver.d.ts

@@ -0,0 +1,90 @@
+import type { ColumnDataMap, ColumnData } from "../../data/view-reader";
+import type { CategoricalLevel } from "../../axis/categorical-axis";
+export interface CategoryAxisResult {
+    /**
+     * Fully materialized hierarchical levels — labels and group runs are
+     * pre-resolved from the view's `__ROW_PATH_N__` dictionaries (or
+     * synthesized for non-string levels) so the chart can retain them
+     * past the `with_typed_arrays` callback scope. Empty when `groupBy`
+     * is empty.
+     */
+    rowPaths: CategoricalLevel[];
+    /**
+     * Rows that actually contribute a category (post-offset).
+     */
+    numCategories: number;
+    /**
+     * Leading rows skipped; callers use this to rebase per-row indices.
+     */
+    rowOffset: number;
+}
+export type AxisMode = {
+    mode: "category";
+} | {
+    mode: "numeric";
+    numericType: "date" | "datetime" | "integer" | "float";
+};
+/**
+ * Numeric category-axis state. Shared across bar / candlestick / heatmap
+ * pipelines: when an axis is driven by exactly one non-string group_by /
+ * split_by level, glyphs anchor at real data values via `categoryPositions`
+ * and the chrome renders a numeric (date-aware) tick row.
+ */
+export interface NumericCategoryDomain {
+    min: number;
+    max: number;
+    isDate: boolean;
+    label: string;
+    /**
+     * Data-unit width of one category band, from min adjacent delta.
+     */
+    bandWidth: number;
+}
+/**
+ * Compute `categoryPositions` (per-row real data values) plus a
+ * `NumericCategoryDomain` summarizing min/max/bandWidth for a numeric
+ * row-path column. `bandWidth` falls back to the full domain when there
+ * are <2 distinct positions. Pivot rows for a single group_by come ASC
+ * by default, so a forward sweep for `minDelta` is sufficient.
+ *
+ * Returns `null` when the row-path column is missing or carries no
+ * `values` array (e.g. dictionary-encoded string column).
+ */
+export declare function resolveNumericCategoryDomain(rpValues: ArrayLike<number> | null | undefined, numCategories: number, rowOffset: number, label: string, isDate: boolean): {
+    categoryPositions: Float64Array;
+    numericCategoryDomain: NumericCategoryDomain;
+} | null;
+/**
+ * Decide whether the categorical axis should render as a stringified
+ * category axis or a true numeric axis. Numeric mode is only used when
+ * there is exactly one `group_by` level AND that level is a non-string,
+ * non-boolean numeric type. Boolean and any multi-level case → category.
+ */
+export declare function resolveAxisMode(groupBy: string[], groupByTypes: Record<string, string>): AxisMode;
+/**
+ * Synthesize a `(indices, dictionary)` pair from a non-string row-path
+ * column so the rest of the categorical axis machinery (label
+ * pre-resolution, run-length encoding) can run unchanged. The dictionary
+ * uses `""` at index 0 as the rollup-row sentinel — this preserves the
+ * existing skip-rollup loop's `s !== ""` check.
+ */
+export declare function synthesizeStringLevel(rp: ColumnData, numRows: number, levelType: string): {
+    indices: Int32Array;
+    dictionary: string[];
+};
+/**
+ * Resolve the category axis for a categorical-X chart (bar, candlestick,
+ * ohlc, …). Walks the `__ROW_PATH_N__` hierarchy columns, skips the
+ * rollup rows at the top ("Total" parent aggregates), and returns fully
+ * JS-owned level structures (precomputed labels + runs) plus the
+ * trimmed category count.
+ *
+ * Non-string row-path columns (date / datetime / integer / float /
+ * boolean group_by levels) are stringified into a synthetic dictionary
+ * so the downstream label / run-length machinery is type-agnostic.
+ *
+ * When `groupByLen === 0`, there are no row-path columns and the
+ * category axis falls back to the raw row index — callers infer that
+ * from `rowPaths.length === 0`.
+ */
+export declare function resolveCategoryAxis(columns: ColumnDataMap, numRows: number, groupByLen: number, levelTypes?: string[]): CategoryAxisResult;

package/dist/esm/charts/common/chrome-cache.d.ts

@@ -0,0 +1,18 @@
+import type { Canvas2D, Context2D } from "../canvas-types";
+export interface ChromeCacheChart {
+    _chromeCanvas: Canvas2D | null;
+    _chromeCache: ImageBitmap | null;
+    _chromeCacheDirty: boolean;
+    _chromeCacheGen: number;
+}
+/**
+ * Run the static-chrome cache pattern shared by sunburst + treemap.
+ * Resizes the canvas, paints the static layer (and snapshots it as an
+ * `ImageBitmap`) when dirty, otherwise blits the cache; then runs the
+ * caller-provided overlay layer for hover/highlight state.
+ *
+ * Returns the prepared `ctx` already in DPR-scaled space so the overlay
+ * callback can paint in CSS pixels — except `null` if either the canvas
+ * is missing a 2D context or the chart has nothing to paint.
+ */
+export declare function withChromeCache(chart: ChromeCacheChart, canvas: Canvas2D, dpr: number, cssWidth: number, cssHeight: number, drawStatic: (ctx: Context2D) => void, drawOverlay: ((ctx: Context2D) => void) | null): void;

package/dist/esm/charts/common/draw-tooltip-box.d.ts

@@ -0,0 +1,9 @@
+import type { Context2D } from "../canvas-types";
+import type { Theme } from "../../theme/theme";
+/**
+ * Draw a freestanding tooltip box anchored near (cx, cy), measuring
+ * lines, sizing/clamping the box, painting bg/border, and laying out
+ * text rows. Shared by sunburst + treemap which need a non-PlotLayout
+ * anchor.
+ */
+export declare function drawTooltipBox(ctx: Context2D, theme: Theme, lines: string[], cx: number, cy: number, cssWidth: number, cssHeight: number, fontFamily: string): void;

package/dist/esm/charts/common/leaf-color.d.ts

@@ -0,0 +1,33 @@
+import type { TreeChartBase } from "./tree-chart";
+import type { Vec3 } from "../../theme/palette";
+import { type GradientStop } from "../../theme/gradient";
+/**
+ * Perceptual luminance for a 0..1 RGB triple. Used by tree-chart label
+ * painters to pick a contrasting text color over each leaf's fill.
+ */
+export declare function luminance(r: number, g: number, b: number): number;
+/**
+ * Sample a gradient and drop the alpha channel. Treemap / sunburst
+ * fills carry alpha separately (see {@link leafRGBA}); this is the
+ * "just give me the RGB" entry point.
+ */
+export declare function sampleRGB(stops: GradientStop[], t: number): [number, number, number];
+/**
+ * Resolve a leaf's fill color according to the chart's color mode:
+ *   - `"numeric"` — sign-aware gradient sample via `colorValueToT`.
+ *   - `"series"` / `"empty"` — discrete palette lookup keyed by the
+ *     node's `colorLabel` (composite of group_by levels in series mode;
+ *     `""` in empty mode, which maps to `palette[0]`).
+ *
+ * Returns RGB only; the alpha channel is applied separately by
+ * {@link leafRGBA} using `negativeAlpha` for leaves whose raw size was
+ * negative.
+ */
+export declare function leafColor(chart: TreeChartBase, nodeId: number, stops: GradientStop[], palette: Vec3[]): [number, number, number];
+/**
+ * `leafColor` + an alpha channel. Negative-size leaves receive
+ * `negativeAlpha` (mirrors `theme.areaOpacity` for area charts) so
+ * they stay visually distinguishable from positive leaves without
+ * disappearing.
+ */
+export declare function leafRGBA(chart: TreeChartBase, nodeId: number, stops: GradientStop[], palette: Vec3[], negativeAlpha: number): [number, number, number, number];

package/dist/esm/charts/common/node-store.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Struct-of-arrays storage for a hierarchical tree (treemap + sunburst).
+ * A node is a numeric `id` into parallel typed arrays; hot numeric
+ * fields live in `Float32Array` / `Int32Array` so iteration is
+ * cache-linear and heap pressure stays flat.
+ *
+ * Children are a singly-linked list per parent (`firstChild` /
+ * `nextSibling`, with `lastChild` for O(1) append). The `NULL_NODE = -1`
+ * sentinel marks "no node" for `parent`, end-of-list for `nextSibling`,
+ * and "leaf" for `firstChild`.
+ *
+ * Layout fields come in two flavors:
+ *   - `x0 / y0 / x1 / y1`  — rectangular coords (treemap, future bar
+ *     hierarchies)
+ *   - `a0 / a1 / r0 / r1`  — polar coords (sunburst)
+ * Each chart populates only its own flavor; the other set wastes ~16 B
+ * per node (32 MB at 2M nodes) — a small price for keeping a single
+ * unified store across hierarchical chart types.
+ *
+ * At typical tree shapes the SOA + linked-list representation is ~10×
+ * cheaper on heap and ~4× faster to build than per-node `Object` +
+ * `Array<Child>` (which allocates ~300 B / node and is O(N²) for naive
+ * child-name lookup). At 2M nodes the former OOMs the tab; the latter
+ * stays under 100 MB.
+ */
+export declare const NULL_NODE = -1;
+export declare class NodeStore {
+    size: Float32Array;
+    value: Float32Array;
+    colorValue: Float32Array;
+    /**
+     * Sign of the leaf's raw size column value: `-1` when the source row
+     * was negative, `1` otherwise. `size` itself always stores the
+     * magnitude so layout code continues to treat negatives as positive
+     * area; render code uses `sizeSign` to apply a lower alpha on
+     * negative leaves. Always `1` for branches.
+     */
+    sizeSign: Int8Array;
+    x0: Float32Array;
+    y0: Float32Array;
+    x1: Float32Array;
+    y1: Float32Array;
+    a0: Float32Array;
+    a1: Float32Array;
+    r0: Float32Array;
+    r1: Float32Array;
+    depth: Int32Array;
+    parent: Int32Array;
+    firstChild: Int32Array;
+    nextSibling: Int32Array;
+    lastChild: Int32Array;
+    childCount: Int32Array;
+    leafRowIdx: Int32Array;
+    name: string[];
+    colorLabel: string[];
+    count: number;
+    capacity: number;
+    constructor(initialCapacity?: number);
+    reset(): void;
+    /**
+     * Reserve a new node id. Caller must immediately initialize the
+     * hot numeric fields and set `parent` / `depth`; topology fields
+     * default to `NULL_NODE`.
+     */
+    allocate(): number;
+    /**
+     * O(1) append `childId` as the last child of `parentId`.
+     */
+    appendChild(parentId: number, childId: number): void;
+    /**
+     * `true` if the node has no children (branches set firstChild when they acquire one).
+     */
+    isLeaf(id: number): boolean;
+    private _allocate;
+}
+/**
+ * Walk the ancestor chain back to (but not including) the synthetic
+ * root, topmost first. Allocates a fresh string array — callers that
+ * care about allocations should inline the walk.
+ */
+export declare function ancestorNames(store: NodeStore, id: number): string[];