@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/hierarchy/frame.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The steps every zoomable hierarchy chart (`treemap`, `icicle`, `sunburst`,
+ * `circlePack`, `tree`) takes on an update before drawing: lay out (both
+ * ends of a keyed transition, joined at `blend`), key, colour, resolve the
+ * drill-down and the zoom window, close a tooltip the view moved away from.
+ * Each step is cached on its inputs (see `shared.ts`), so a `progress` frame
+ * re-lays out nothing and a zoom scrub only moves the window.
+ *
+ * Internal to the family.
+ */
+import type { CompositeContext, SceneNode } from "@sophistry/core";
+import type { Point } from "@sophistry/core/geometry";
+import type { Theme } from "@sophistry/core/themes";
+import type { HierarchyNodeInfo } from "../math/hierarchy.js";
+import type { TooltipState } from "../tooltip.js";
+import type { ChartBreadcrumbsFrame } from "./breadcrumbs.js";
+import type { HierarchyDrill, HierarchyDrillProps, NodeInteractionProps } from "./drill.js";
+import type { HierarchyChartBaseProps, HierarchyEnds, HierarchyFocusSpec, HierarchyTransitionProps, HierarchyView, HierarchyZoom, Joined } from "./shared.js";
+/** The props the shared steps read. */
+export type ZoomableChartProps<T> = HierarchyChartBaseProps<T> & HierarchyTransitionProps<T> & HierarchyDrillProps<T> & {
+    focus?: HierarchyFocusSpec<T>;
+};
+/** One update's shared state of a hierarchy chart. @internal */
+export interface HierarchyChartFrame<T, N extends HierarchyNodeInfo<T>> {
+    ends: HierarchyEnds<N>;
+    /** The layout drawn: `data`'s, or both ends joined at `blend`. */
+    layout: readonly Joined<N>[];
+    /** Each node's identity (its path of names): the instance key of its mark. */
+    keys: readonly string[];
+    /** Each node's fill. */
+    fills: readonly string[];
+    drill: HierarchyDrill<T>;
+    zoom: HierarchyZoom;
+    /** The chart's tooltip: the enclosing chart's, else its own. */
+    tooltip: TooltipState;
+    /** Whether nodes take part in interaction (taps, tooltips, the item list). */
+    interactive: boolean;
+}
+/** How a chart turns its layout into the windows its zoom moves between. */
+export interface HierarchyViewOptions<N> {
+    /** The window showing the subtree of the node at `position`. */
+    viewOf: (layout: readonly Joined<N>[], position: number) => HierarchyView;
+    /** How two windows blend. @default linear */
+    blend?: (a: HierarchyView, b: HierarchyView, t: number) => HierarchyView;
+}
+/** A hierarchy chart's shared machinery. See {@link createHierarchyChart}. @internal */
+export interface HierarchyChart<T, N extends HierarchyNodeInfo<T>> {
+    /** Runs the shared steps for this update. */
+    frame(props: ZoomableChartProps<T>, theme: Theme, layoutOf: (data: T, end: "from" | "to") => N[], deps: readonly unknown[], view: HierarchyViewOptions<N>): HierarchyChartFrame<T, N>;
+    /**
+     * The batched node's interaction props for this update, named `name`;
+     * `positionOf` and `atOf` map a batched item to its node and tooltip anchor.
+     */
+    interaction(name: string, positionOf: (item: number) => number | undefined, atOf: (item: number) => Point | undefined): NodeInteractionProps;
+    /** Taps the node at layout `position`, as a tap on its item does (for a node's name). */
+    tapNode(position: number, at: Point): void;
+    /** The chart's own trail, or null for none. */
+    breadcrumbs(frame: Omit<ChartBreadcrumbsFrame<T>, "nodes" | "resolved" | "drill">): SceneNode | null;
+}
+/**
+ * A hierarchy chart's shared machinery: its layout cache, keys, fills,
+ * drill-down, zoom, tooltip and trail. Call once, in `setup`.
+ *
+ * @param fields - The numeric fields that place a node (for the keyed join).
+ * @internal
+ */
+export declare function createHierarchyChart<T, N extends HierarchyNodeInfo<T>, P extends ZoomableChartProps<T>>(ctx: CompositeContext<P>, fields: readonly (keyof N & string)[]): HierarchyChart<T, N>;

package/dist/hierarchy/icicle.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `icicle`: the partition layout as rectangles, one band per depth.
+ *
+ * Every band is one `rect` instance of one instances node, keyed by the
+ * node's path of names; per-node picking, tooltips and drilling go through
+ * `event.item`. The level-by-level reveal grows each rectangle from its
+ * parent side (geometry). Names are `label` nodes, one per
+ * rectangle whose name fits.
+ */
+import type { Point } from "@sophistry/core/geometry";
+import type { RequiredUnless } from "../data/channels.js";
+import type { HierarchyDrillProps } from "./drill.js";
+import type { HierarchyChartBaseProps, HierarchyFocusSpec, HierarchyTransitionProps } from "./shared.js";
+/** @category Charts */
+export interface IcicleBaseProps<T> extends HierarchyChartBaseProps<T>, HierarchyTransitionProps<T>, HierarchyDrillProps<T> {
+    /** Width of the whole chart. */
+    width: number;
+    /** Height of the whole chart. */
+    height: number;
+    /** Centre of the chart. Defaults to the origin. */
+    center?: Point;
+    /**
+     * `"horizontal"`: the root is a column at the left, depth increasing to the right.
+     * `"vertical"`: the root is a row at the top, depth increasing downward.
+     * @default "horizontal"
+     */
+    orientation?: "horizontal" | "vertical";
+    /**
+     * Draw the root's band; `false` gives its room to the other levels.
+     * @default true
+     */
+    root?: boolean;
+    /**
+     * Gap left around each rectangle.
+     * @default 0.01
+     */
+    inset?: number;
+    /**
+     * Zoom into a node: it spans the whole breadth, its descendants fill the depth after it, and
+     * the rest fades away. A path of names below the root (`["a"]`), a predicate, or `{ from, to, t
+     * }` for a scrubbable transition. Given, the chart is controlled: taps only call
+     * `onFocusChange`. Defaults to the root.
+     */
+    focus?: HierarchyFocusSpec<T>;
+}
+/**
+ * Props of {@link icicle}: `value` is required unless the tree's nodes are numbers.
+ *
+ * @category Charts
+ */
+export type IcicleProps<T> = IcicleBaseProps<T> & RequiredUnless<T, number, "value">;
+/**
+ * An icicle chart: the partition layout as rectangles, one band per depth, each node spanning
+ * exactly its children, sized by value. Lays itself out in a `width × height` box; reveals one
+ * depth at a time from the root. Supports drill-down `focus` and keyed transitions. The
+ * rectangles are one instances node (`event.item` picks a node). See {@link partitionLayout} for
+ * the layout alone.
+ *
+ * @example
+ * ```ts
+ * import { icicle } from "@sophistry/charts";
+ *
+ * const files = {
+ * 	name: "repo",
+ * 	children: [
+ * 		{ name: "src", children: [{ name: "index.ts", size: 12 }, { name: "chart.ts", size: 30 }] },
+ * 		{ name: "README.md", size: 4 },
+ * 	],
+ * };
+ * icicle.create({ data: files, value: "size", label: "name", width: 8, height: 4, orientation: "vertical" });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#hierarchies
+ * @category Charts
+ */
+export declare const icicle: import("@sophistry/core").Definition<IcicleBaseProps<any>, import("@sophistry/core/internal").CompositeNode<IcicleBaseProps<any>>, keyof IcicleBaseProps<any>>;

package/dist/hierarchy/index.d.ts

@@ -0,0 +1,20 @@
+/** Family barrel: hierarchy. Owned by its family; re-exported from the package entry. */
+export type { BreadcrumbsProps } from "./breadcrumbs.js";
+export { breadcrumbs } from "./breadcrumbs.js";
+export type { CirclePackBaseProps, CirclePackProps } from "./circle-pack.js";
+export { circlePack } from "./circle-pack.js";
+export type { DrillDown, DrillDownOptions, DrillOptions, HierarchyBreadcrumbOptions, HierarchyDrillProps, } from "./drill.js";
+export { createDrillDown } from "./drill.js";
+export type { IcicleBaseProps, IcicleProps } from "./icicle.js";
+export { icicle } from "./icicle.js";
+export type { MosaicProps } from "./mosaic.js";
+export { mosaic } from "./mosaic.js";
+export type { SankeyBaseProps, SankeyProps } from "./sankey.js";
+export { sankey } from "./sankey.js";
+export type { HierarchyChartBaseProps, HierarchyFocus, HierarchyFocusSpec, HierarchyTransitionProps, HierarchyView, } from "./shared.js";
+export type { SunburstBaseProps, SunburstProps } from "./sunburst.js";
+export { sunburst } from "./sunburst.js";
+export type { TreeProps } from "./tree.js";
+export { tree } from "./tree.js";
+export type { TreemapBaseProps, TreemapProps } from "./treemap.js";
+export { treemap } from "./treemap.js";

package/dist/hierarchy/labels.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Node names of the hierarchy, flow and mosaic charts: one `label` node per
+ * name drawn, keyed by its node (so a name moving through a transition
+ * keeps its node), and a text-width cache so fitting names on every frame
+ * of a reveal or zoom measures each string once. Internal to the family.
+ */
+import type { CompositeContext, LabelProps, SceneNode } from "@sophistry/core";
+import type { Theme } from "@sophistry/core/themes";
+/** One label of a keyed list: its key and the label's props. */
+export interface KeyedLabel {
+    key: unknown;
+    props: LabelProps;
+}
+/**
+ * Keyed `label` nodes for one list (`slot`): a node per key, created once
+ * and updated in place, disposed when its key leaves.
+ */
+export declare function labelList<P>(ctx: CompositeContext<P>, slot: string, labels: readonly KeyedLabel[]): SceneNode[];
+/**
+ * A text-width cache for one chart: `(text, fontSize, theme, weight?)` is
+ * `textWidth` at the theme's font, measured once per string and size.
+ * Call once, in `setup`.
+ */
+export declare function createLabelMeasure(): (text: string, fontSize: number, theme: Theme, fontWeight?: number) => number;

package/dist/hierarchy/mosaic.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `mosaic`: a Marimekko chart, columns as wide as their share of the whole,
+ * split into segments as tall as each row's share within the column.
+ *
+ * Every segment is one `rect` instance of one instances node, keyed by its
+ * (column, row) pair; per-segment picking and tooltips go through
+ * `event.item`. Columns grow from the bottom edge (geometry).
+ * Segment and column names are `label` nodes, one per name that fits.
+ */
+import type { ColorInput } from "@sophistry/core/color";
+import type { Point } from "@sophistry/core/geometry";
+import type { Channel, ColorChannel } from "../data/channels.js";
+import type { MosaicKey } from "../math/mosaic.js";
+import type { TooltipSpec } from "../tooltip.js";
+/**
+ * Props of {@link mosaic}.
+ *
+ * @category Charts
+ */
+export interface MosaicProps<T> {
+    /** Long-form table: one datum per (column, row, value); duplicate pairs sum. */
+    data: readonly T[];
+    /** The column category. Data with no category are skipped. */
+    x: Channel<T, MosaicKey>;
+    /** The segment (row) category. Data with no category are skipped. */
+    y: Channel<T, MosaicKey>;
+    /**
+     * The amount; negative and non-finite values count as 0. Omitted, every datum counts 1 (a
+     * contingency table of counts).
+     */
+    value?: Channel<T, number>;
+    /** Column order, left to right; unlisted categories follow. Defaults to first-seen order. */
+    columns?: readonly MosaicKey[];
+    /** Segment order, bottom to top; unlisted categories follow. Defaults to first-seen order. */
+    rows?: readonly MosaicKey[];
+    /** Width of the mosaic. */
+    width: number;
+    /** Height of the mosaic (column names hang below it). */
+    height: number;
+    /** Centre of the mosaic. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Gap between columns, and between segments in a column.
+     * @default 0.04
+     */
+    padding?: number;
+    /**
+     * One colour for every segment, or `(d, i) => colour` called with the segment's first datum
+     * (returning nothing falls back to `colors`). Wins over `colors`.
+     */
+    color?: ColorChannel<T>;
+    /**
+     * Colours cycled across the row categories, so a row has one colour in every column. Defaults
+     * to the theme's categorical colours.
+     */
+    colors?: readonly ColorInput[];
+    /**
+     * Fill opacity of the segments, 0..1.
+     * @default 1
+     */
+    fillOpacity?: number;
+    /**
+     * Write each row's name inside its segment where it fits.
+     * @default true
+     */
+    labels?: boolean;
+    /**
+     * Write each column's name under it where it fits.
+     * @default true
+     */
+    columnLabels?: boolean;
+    /**
+     * Write each column's share of the total under its name.
+     * @default false
+     */
+    shares?: boolean;
+    /**
+     * Label font size.
+     * @default 0.2
+     */
+    labelFontSize?: number;
+    /**
+     * Reveal, 0..1: column names fade in first, then the columns grow left to right from the
+     * bottom, segment names fading in as they go.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the columns' reveal spent staggering column after column, 0..0.95.
+     * @default 0.5
+     */
+    stagger?: number;
+    /**
+     * Hover tooltip on a segment: `true` for "column · row: value (pct% of column)", or `(d, i) =>
+     * string` called with its first datum.
+     */
+    tooltip?: TooltipSpec<T>;
+    /** Paint order; labels draw at `zIndex + 1`. */
+    zIndex?: number;
+    /**
+     * Set to `false` to hide the chart.
+     * @default true
+     */
+    visible?: boolean;
+}
+/**
+ * A mosaic (Marimekko) chart: columns whose widths are their share of the whole, split into
+ * segments whose heights are each row's share within the column, so every rectangle's area is
+ * its value. `data` is long-form, one datum per (column, row, value). Lays itself out in a
+ * `width × height` box; needs no `chart`. The segments are one instances node (`event.item`
+ * picks one). See {@link mosaicLayout} for the layout alone.
+ *
+ * @example
+ * ```ts
+ * import { mosaic } from "@sophistry/charts";
+ *
+ * const sales = [
+ * 	{ region: "north", product: "tea", units: 30 },
+ * 	{ region: "north", product: "coffee", units: 50 },
+ * 	{ region: "south", product: "tea", units: 45 },
+ * 	{ region: "south", product: "coffee", units: 15 },
+ * ];
+ * mosaic.create({ data: sales, x: "region", y: "product", value: "units", width: 8, height: 4, shares: true });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#gauges-bullets-waffles-mosaics-and-radial-bars
+ * @category Charts
+ */
+export declare const mosaic: import("@sophistry/core").Definition<MosaicProps<any>, import("@sophistry/core/internal").CompositeNode<MosaicProps<any>>, keyof MosaicProps<any>>;

package/dist/hierarchy/own-tooltip.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The tooltip a standalone hierarchy, flow or mosaic chart shows through:
+ * the enclosing chart's, else its own. Internal to the family.
+ *
+ * Outside a chart the state is kept (handlers, accessible names, the item
+ * walked by the keys) but no panel is drawn yet: the overlay is the chart
+ * frame's (`frame/tooltip-overlay.ts`).
+ */
+import type { CompositeContext } from "@sophistry/core";
+import type { TooltipState } from "../tooltip.js";
+/** Call once, in `setup`; read the result in each `update`. */
+export declare function createOwnTooltip(): <P>(ctx: CompositeContext<P>) => TooltipState;

package/dist/hierarchy/props.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The props descriptor the zoomable hierarchy charts share: every base,
+ * transition and drill prop reruns `update`, plus each chart's own. Internal
+ * to the family.
+ */
+import type { PropsDescriptor } from "@sophistry/core";
+/**
+ * A hierarchy chart's props descriptor: the shared keys and `own`, each
+ * rerunning `update` when written (`progress` defaults to 1).
+ *
+ * @internal
+ */
+export declare function hierarchyPropsDescriptor<P extends object>(own: readonly (keyof P & string)[]): PropsDescriptor<P>;

package/dist/hierarchy/sankey.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `sankey`: quantities flowing between stages.
+ *
+ * The flows are one path batch: each ribbon a closed ring with its own fill
+ * (its source's, target's or own colour), the fill opacity shared; per-flow
+ * picking and tooltips go through `event.item`. The node bars are `rect`
+ * instances of one instances node, keyed by node id. The left-to-right draw
+ * of a flow cuts its ring (`sankeyRibbon`'s `t`). Node names
+ * are `label` nodes placed beside their bars: outside the diagram for the first and last
+ * columns, right of the bar (with a halo over the flows) for the others.
+ */
+import type { ColorInput } from "@sophistry/core/color";
+import type { Point } from "@sophistry/core/geometry";
+import type { Channel, ColorChannel, RequiredUnless } from "../data/channels.js";
+import type { SankeyAlign, SankeyId } from "../math/sankey.js";
+import type { TooltipSpec } from "../tooltip.js";
+/** @category Charts */
+export interface SankeyBaseProps<L, N> {
+    /** The flows: one ribbon per datum. */
+    data: readonly L[];
+    /** The node a flow leaves. */
+    source: Channel<L, SankeyId>;
+    /** The node a flow enters. */
+    target: Channel<L, SankeyId>;
+    /** The flow's size; non-finite and negative values draw nothing. */
+    value: Channel<L, number>;
+    /**
+     * The nodes, in the order they are stacked and coloured. Every id a link names must be here
+     * (else throws). Defaults to the links' endpoints in first-seen order.
+     */
+    nodes?: readonly N[];
+    /**
+     * A node's id, matched against `source`/`target`. Defaults to the datum itself, when `nodes` is
+     * `(string | number)[]`.
+     */
+    nodeId?: Channel<N, SankeyId>;
+    /** The text beside a node. Defaults to its id. */
+    nodeLabel?: Channel<N, string>;
+    /** Width of the diagram, nodes included; labels may overhang it. */
+    width: number;
+    /** Height of the diagram. */
+    height: number;
+    /** Centre of the diagram. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Width of each node bar.
+     * @default 0.2
+     */
+    nodeWidth?: number;
+    /**
+     * Gap between nodes in a column.
+     * @default 0.2
+     */
+    nodePadding?: number;
+    /**
+     * How nodes are assigned to columns; see {@link SankeyAlign}.
+     * @default "justify"
+     */
+    align?: SankeyAlign;
+    /**
+     * Relaxation passes of the layout.
+     * @default 6
+     */
+    iterations?: number;
+    /** Node colours, cycled by node order. Defaults to the theme's categorical colours. */
+    colors?: readonly ColorInput[];
+    /**
+     * A flow's colour: its `"source"` node's, its `"target"` node's, or a colour channel of its
+     * own.
+     * @default "source"
+     */
+    linkColor?: "source" | "target" | ColorChannel<L>;
+    /**
+     * Fill opacity of the flows, 0..1.
+     * @default 0.35
+     */
+    linkOpacity?: number;
+    /**
+     * Draw node labels.
+     * @default true
+     */
+    labels?: boolean;
+    /**
+     * Font size of node labels.
+     * @default 0.24
+     */
+    labelFontSize?: number;
+    /**
+     * Reveal, 0..1: nodes appear column by column, then the flows draw left to right.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Hover tooltip: `true` shows "A → B: value" on a flow and "name: value" on a node; a function
+     * replaces the flow text.
+     */
+    tooltip?: TooltipSpec<L>;
+    /** Paint order of the flows; nodes paint above them. */
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * Props of {@link sankey}: `nodeId` is required when `nodes` holds records.
+ *
+ * @category Charts
+ */
+export type SankeyProps<L, N = SankeyId> = SankeyBaseProps<L, N> & RequiredUnless<N, SankeyId, "nodeId">;
+/**
+ * A Sankey diagram: quantities flowing between stages, each flow a ribbon as thick as its
+ * value, each node a bar as tall as what passes through it. Lays itself out in a
+ * `width × height` box; needs no `chart`. A cycle in the links throws. The flows are one path
+ * batch and the bars one instances node (`event.item` picks one). See {@link sankeyLayout} and
+ * {@link sankeyRibbon} for the geometry alone.
+ *
+ * @example
+ * ```ts
+ * import { sankey } from "@sophistry/charts";
+ *
+ * const flows = [
+ * 	{ from: "coal", to: "electricity", twh: 40 },
+ * 	{ from: "wind", to: "electricity", twh: 25 },
+ * 	{ from: "electricity", to: "homes", twh: 35 },
+ * 	{ from: "electricity", to: "industry", twh: 30 },
+ * ];
+ * sankey.create({ data: flows, source: "from", target: "to", value: "twh", width: 8, height: 4, tooltip: true });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#flows
+ * @category Charts
+ */
+export declare const sankey: import("@sophistry/core").Definition<SankeyBaseProps<any, any>, import("@sophistry/core/internal").CompositeNode<SankeyBaseProps<any, any>>, keyof SankeyBaseProps<any, any>>;