@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/guides/size-legend.d.ts

@@ -0,0 +1,233 @@
+/**
+ * `sizeLegend`: a key to a size encoding, a hollow reference circle per
+ * value; `sizeKeyStack`: a frame's stack of them, one per size scale; and
+ * the measurements a frame lays them out with.
+ *
+ * A value's nodes are kept for as long as either end of a transition shows
+ * the value, and hidden with `visible: false` when they are not shown.
+ * Each end is measured once per change of its scale, values, title or font,
+ * not as `progress` or a transition's stages move.
+ */
+import type { Point } from "@sophistry/core/geometry";
+import type { SizeScale } from "../frame/types.js";
+/**
+ * A size key's keyed transition: the far end's scale and values, and how far each stage has
+ * got. `chart` passes one while a keyed transition runs.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+ * @category Charts
+ */
+export interface SizeLegendTransition {
+    /** The scale at the end. */
+    to: SizeScale;
+    /** The values the end shows. Defaults to `values`, else the end's own round values. */
+    values?: readonly number[];
+    /** Progress of the exit stage, 0..1. */
+    exit: number;
+    /** Progress of the update stage, 0..1. */
+    update: number;
+    /** Progress of the enter stage, 0..1. */
+    enter: number;
+}
+/**
+ * Props for {@link sizeLegend}.
+ *
+ * @category Charts
+ */
+export interface SizeLegendProps {
+    /** The size scale the key explains. */
+    scale: SizeScale;
+    /**
+     * The values to draw circles for, in order. Defaults to up to three round values of the scale.
+     */
+    values?: readonly number[];
+    /** How a value is written. Defaults to the axes' formatting. */
+    format?: (value: number) => string;
+    /** The key's top-left corner, in scene units. */
+    at: Point;
+    /**
+     * `"column"`: one circle per row. `"row"`: side by side, wrapping at `maxWidth`.
+     * @default "column"
+     */
+    direction?: "column" | "row";
+    /** With `direction: "row"`: wrap before an entry that would run past this width. */
+    maxWidth?: number;
+    /** A title line above the circles. */
+    title?: string;
+    /**
+     * Font size of the labels.
+     * @default 0.28
+     */
+    fontSize?: number;
+    /**
+     * Reveal, 0..1: the circles fade in one after another.
+     * @default 1
+     */
+    progress?: number;
+    /** A keyed data transition in progress; see {@link SizeLegendTransition}. */
+    transition?: SizeLegendTransition;
+    /** Paint order; higher draws later. */
+    zIndex?: number;
+    /** Set to `false` to hide the key. */
+    visible?: boolean;
+}
+/** Measurement options shared by {@link sizeLegend} and the frames that place one. */
+export interface SizeLegendMetrics {
+    direction?: "column" | "row";
+    maxWidth?: number;
+    title?: string;
+    fontSize?: number;
+    format?: (value: number) => string;
+    fontFamily: string;
+}
+/**
+ * A key to a size encoding: a hollow reference circle per value, with the value beside it,
+ * drawn through the same square-root scale as the marks. `chart` draws one automatically for
+ * layers sized by value (`scatter`'s `size`); use this directly for charts without a frame.
+ *
+ * @example
+ * ```ts
+ * import { sizeLegend } from "@sophistry/charts";
+ *
+ * sizeLegend.create({
+ * 	at: { x: 3, y: 2 },
+ * 	scale: { maxValue: 100, range: [0, 0.5] },
+ * 	values: [25, 100],
+ * 	title: "Population",
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/guides/charts/#series-and-legends
+ * @category Charts
+ */
+export declare const sizeLegend: import("@sophistry/core").Definition<SizeLegendProps, import("@sophistry/core/internal").CompositeNode<SizeLegendProps>, keyof SizeLegendProps>;
+/**
+ * One key of a frame's stack of size keys: the scale its sized layers draw on at each end of a
+ * keyed transition, and the first such layer's channel name.
+ *
+ * @internal
+ */
+export interface SizeKey {
+    maxValue: number;
+    to?: number;
+    range: readonly [number, number];
+    label?: string;
+}
+/**
+ * A key's laid-out size, and how far it is there at all (0 at an end without one).
+ *
+ * @internal
+ */
+export interface SizeKeyExtent {
+    width: number;
+    height: number;
+    presence: number;
+}
+/**
+ * A stack of size keys at each end of a keyed transition: the stack's size and each key's
+ * place in it.
+ *
+ * @internal
+ */
+export interface SizeKeysEnds {
+    from: SizeKeyExtent;
+    to: SizeKeyExtent | undefined;
+    /** Each key's top-left corner from the stack's: `x` to the right, `y` down. */
+    offsets: {
+        from: readonly Point[];
+        to: readonly Point[] | undefined;
+    };
+}
+/**
+ * Each key of a stack measured at each end, before the stack is flowed ({@link flowSizeKeys}).
+ *
+ * @internal
+ */
+export interface SizeKeyMeasures {
+    from: readonly SizeKeyExtent[];
+    to: readonly SizeKeyExtent[] | undefined;
+}
+/**
+ * How a stack of keys flows into columns: a key that would run past `maxHeight` starts a new
+ * column `gap` to the right.
+ *
+ * @internal
+ */
+interface SizeKeyColumns {
+    maxHeight: number;
+    gap: number;
+}
+/**
+ * Measures each key of a stack at each end (presence 0 where an end sizes nothing). Undefined
+ * without keys. Separate from {@link flowSizeKeys} so a re-flow doesn't re-measure text.
+ *
+ * @internal
+ */
+export declare function measureSizeKeyExtents(keys: readonly SizeKey[], options: Omit<SizeLegendMetrics, "title"> & {
+    title?: string;
+    values?: readonly number[];
+}): SizeKeyMeasures | undefined;
+/**
+ * Flows a stack's measured keys at each end: one under another `gap` apart, starting a new
+ * column when one would run past `columns.maxHeight`. A key absent at an end takes no room.
+ *
+ * @internal
+ */
+export declare function flowSizeKeys(measures: SizeKeyMeasures | undefined, gap: number, columns?: SizeKeyColumns): SizeKeysEnds | undefined;
+/**
+ * Measures a stack of size keys and flows it ({@link measureSizeKeyExtents},
+ * {@link flowSizeKeys}). Undefined without keys.
+ *
+ * @internal
+ */
+export declare function measureSizeKeys(keys: readonly SizeKey[], options: Omit<SizeLegendMetrics, "title"> & {
+    title?: string;
+    values?: readonly number[];
+}, gap: number, columns?: SizeKeyColumns): SizeKeysEnds | undefined;
+/** Two stacks' measured keys with the same sizes, end by end. */
+export declare function sameSizeKeyMeasures(a: SizeKeyMeasures | undefined, b: SizeKeyMeasures | undefined): boolean;
+/** Two measured stacks of size keys with the same sizes and places. */
+export declare function sameSizeKeysEnds(a: SizeKeysEnds | undefined, b: SizeKeysEnds | undefined): boolean;
+/**
+ * Each key's place in the stack now: its own end's, or while a key rescales, both ends'
+ * blended by the update progress `u`.
+ *
+ * @internal
+ */
+export declare function sizeKeyOffsets(ends: SizeKeysEnds | undefined, u: number): readonly Point[];
+/** Two lists of key places, compared by value. */
+export declare function sameOffsets(a: readonly Point[] | undefined, b: readonly Point[] | undefined): boolean;
+/** The stages a stack of keys transitions on: exit, update and enter progress, as `SizeLegendTransition` takes them. */
+export type SizeKeyStages = Pick<SizeLegendTransition, "exit" | "update" | "enter">;
+/**
+ * Props for {@link sizeKeyStack}.
+ *
+ * @internal
+ */
+export interface SizeKeyStackProps {
+    keys: readonly SizeKey[];
+    /** Each key's top-left corner from `at`: `x` to the right, `y` down. */
+    offsets: readonly Point[];
+    /** The stack's top-left corner. */
+    at: Point;
+    /** A title for the first key (see `sizeKeyTitle`). */
+    title?: string;
+    values?: readonly number[];
+    format?: (value: number) => string;
+    direction: "column" | "row";
+    maxWidth?: number;
+    fontSize?: number;
+    progress?: number;
+    /** The keyed transition's stages, while one runs. */
+    stages?: SizeKeyStages;
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * A frame's size keys, one {@link sizeLegend} per key at its place in the stack, each blending to
+ * its far end's scale while `stages` is given. Keys are kept by position in the stack.
+ *
+ * @internal
+ */
+export declare const sizeKeyStack: import("@sophistry/core").Definition<SizeKeyStackProps, import("@sophistry/core/internal").CompositeNode<SizeKeyStackProps>, keyof SizeKeyStackProps>;
+export {};

package/dist/hierarchy/breadcrumbs.d.ts

@@ -0,0 +1,133 @@
+/**
+ * `breadcrumbs`: a trail of names for a drill-down, and the trail a zoomable
+ * hierarchy chart draws for its own `breadcrumbs` prop.
+ *
+ * A trail is a handful of words, each its own tap target and tab stop, so
+ * every crumb, separator and the back control stay `label` nodes (keyed by
+ * the crumb's path, so a crumb cross-fading through a zoom keeps its node).
+ */
+import type { SceneNode } from "@sophistry/core";
+import type { Point } from "@sophistry/core/geometry";
+import type { HierarchyPathSpec } from "../math/breadcrumbs.js";
+import type { HierarchyNodeInfo } from "../math/hierarchy.js";
+import type { HierarchyBreadcrumbOptions, HierarchyDrill } from "./drill.js";
+import type { ResolvedFocus } from "./shared.js";
+/** @category Charts */
+export interface BreadcrumbsProps {
+    /**
+     * The trail: names below the root (`[]` is the root alone), or a `{ from, to, t }` transition
+     * such as {@link createDrillDown}'s `focus`, so the crumbs follow a zoom.
+     */
+    path: HierarchyPathSpec;
+    /**
+     * The root crumb's text.
+     * @default "All"
+     */
+    root?: string;
+    /**
+     * Anchor x.
+     * @default 0
+     */
+    x?: number;
+    /**
+     * Anchor y (the text's vertical middle).
+     * @default 0
+     */
+    y?: number;
+    /**
+     * Where the anchor is on the trail.
+     * @default "left"
+     */
+    align?: "left" | "center" | "right";
+    /**
+     * Font size.
+     * @default 0.24
+     */
+    fontSize?: number;
+    /**
+     * Drawn between crumbs.
+     * @default "›"
+     */
+    separator?: string;
+    /**
+     * The widest the trail may be: a deeper path collapses its middle into one `…` crumb (tap it to
+     * climb), keeping the root and as many last crumbs as fit. Omitted, the trail never collapses.
+     */
+    maxWidth?: number;
+    /**
+     * The collapsed crumbs' text.
+     * @default "…"
+     */
+    ellipsis?: string;
+    /**
+     * A back control before the root crumb: `true` for `"←"`, or its text. With `onSelect`, tapping
+     * it asks for the parent of the node in focus; it fades out at the root. Defaults to none.
+     */
+    back?: boolean | string;
+    /** The last crumb's colour (the node in focus). Defaults to the theme foreground. */
+    color?: string;
+    /** The other crumbs' colour, marking them as tappable. Defaults to the theme accent. */
+    linkColor?: string;
+    /**
+     * Called with a crumb's path when an earlier crumb is tapped (or Enter is pressed on it).
+     * Without it the crumbs are not interactive.
+     */
+    onSelect?: (path: string[]) => void;
+    /**
+     * Reveal, 0..1: the trail fades in.
+     * @default 1
+     */
+    progress?: number;
+    /** Paint order; higher draws later. */
+    zIndex?: number;
+    /**
+     * Set to `false` to hide the trail.
+     * @default true
+     */
+    visible?: boolean;
+}
+/**
+ * A breadcrumb trail for a drill-down: the root's name, then each name on the path to the node
+ * in focus. Tap (or Enter on) an earlier crumb to go back up; Escape asks for the parent. Give
+ * it the same `path` as a hierarchy chart's `focus` and it scrubs with the zoom. The hierarchy
+ * charts draw one themselves with their `breadcrumbs` prop.
+ *
+ * @example
+ * ```ts
+ * import { createScene } from "@sophistry/core";
+ * import { breadcrumbs, createDrillDown } from "@sophistry/charts";
+ *
+ * const scene = createScene({ host: document.querySelector("#figure")!, units: 10 });
+ * const zoom = createDrillDown({ clock: scene.clock });
+ * breadcrumbs.create({ path: zoom.focus, root: "repo", x: -4, y: 2.4, onSelect: (path) => void zoom.zoomTo(path) });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#hierarchies
+ * @category Charts
+ */
+export declare const breadcrumbs: import("@sophistry/core").Definition<BreadcrumbsProps, import("@sophistry/core/internal").CompositeNode<BreadcrumbsProps>, keyof BreadcrumbsProps>;
+/** Where a chart's trail goes and how wide it may grow. @internal */
+export interface ChartBreadcrumbsFrame<T> {
+    options: boolean | HierarchyBreadcrumbOptions | undefined;
+    nodes: readonly HierarchyNodeInfo<T>[];
+    resolved: ResolvedFocus;
+    drill: HierarchyDrill<T>;
+    /** The chart's top-left corner, in scene units. */
+    corner: Point;
+    /** The chart's width: how wide the trail may grow by default. */
+    width: number;
+    /** The chart's label font size. */
+    labelFontSize: number;
+    progress?: number;
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * The trail a zoomable hierarchy chart draws for its `breadcrumbs` prop: its
+ * focus as names, just above the chart's top-left unless placed, collapsing
+ * past the chart's width. Call once, in `setup`; the result hands back the
+ * trail's node (made the first time it is asked for), or null for none.
+ *
+ * @internal
+ */
+export declare function createChartBreadcrumbs<T>(): (frame: ChartBreadcrumbsFrame<T>) => SceneNode | null;

package/dist/hierarchy/circle-pack.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `circlePack`: every leaf a disc, packed inside its parent's circle.
+ *
+ * Every circle is one `circle` instance of one instances node, keyed by the
+ * node's path of names, with its own fill, fill opacity and stroke (groups
+ * are tinted and outlined, leaves filled); per-node picking, tooltips and
+ * drilling go through `event.item`. Circles grow from their centres
+ * (radius). While zoomed, the node and the leaf names sit in
+ * a `group` clipped to the root's disc. Names are `label` nodes, one per
+ * leaf 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 CirclePackBaseProps<T> extends HierarchyChartBaseProps<T>, HierarchyTransitionProps<T>, HierarchyDrillProps<T> {
+    /** Centre of the chart. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Radius of the root circle.
+     * @default 1
+     */
+    radius?: number;
+    /**
+     * Gap between sibling circles and their parent's rim.
+     * @default 0.03
+     */
+    padding?: number;
+    /**
+     * Draw the root's circle.
+     * @default true
+     */
+    root?: boolean;
+    /**
+     * Zoom into a node: its circle grows to fill the root's while the rest fades away along a
+     * smooth zoom path. 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 circlePack}: `value` is required unless the tree's nodes are numbers.
+ *
+ * @category Charts
+ */
+export type CirclePackProps<T> = CirclePackBaseProps<T> & RequiredUnless<T, number, "value">;
+/**
+ * Circle packing: every leaf a disc with area proportional to its value, packed inside its
+ * parent's circle. Draws in scene units; circles grow from their centres, parents first.
+ * Supports drill-down `focus` and keyed transitions. The circles are one instances node
+ * (`event.item` picks a circle). See {@link packLayout} for the layout alone.
+ *
+ * @example
+ * ```ts
+ * import { circlePack } 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 },
+ * 	],
+ * };
+ * circlePack.create({ data: files, value: "size", label: "name", radius: 2, drill: true });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#hierarchies
+ * @category Charts
+ */
+export declare const circlePack: import("@sophistry/core").Definition<CirclePackBaseProps<any>, import("@sophistry/core/internal").CompositeNode<CirclePackBaseProps<any>>, keyof CirclePackBaseProps<any>>;

package/dist/hierarchy/drill.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Tap-to-drill for the zoomable hierarchy charts (`treemap`, `icicle`,
+ * `sunburst`, `circlePack`, `tree`): {@link createDrillDown}, which turns
+ * "zoom to this node" into a tweened, scrubbable `{ from, to, t }` focus,
+ * plus the drill props the charts share and the interaction a chart's
+ * batched node carries.
+ *
+ * The drill-down is plain tracks (`focus` and `path` are `Readable`s a chart
+ * prop binds to) and its zoom runs on a clock it is given. A chart without
+ * a controlled `focus` keeps one of its own on its scene's clock.
+ *
+ * A chart's nodes are one batched node, so the chart is one tab stop whose
+ * nodes the arrow keys walk (the accessibility layer's item list): Enter or
+ * Space taps the current node (drilling as a tap does), Escape zooms out one
+ * level (`aria-keyshortcuts="Escape"`). The item list walks every drawn node.
+ */
+import type { Clock, CompositeContext, Easing, KeyboardBehaviour, PlayResult, Readable, ReducedMotion, ScenePointerEvent, Track } from "@sophistry/core";
+import type { Point } from "@sophistry/core/geometry";
+import type { HierarchyPathSpec } from "../math/breadcrumbs.js";
+import type { HierarchyNodeInfo } from "../math/hierarchy.js";
+import type { TooltipSpec, TooltipState } from "../tooltip.js";
+import type { HierarchyFocusSpec, ResolvedFocus } from "./shared.js";
+/**
+ * How a drill-down zoom animates.
+ *
+ * @category Charts
+ */
+export interface DrillOptions {
+    /** Length of the zoom, in seconds. @default 0.75 */
+    duration?: number;
+    /** Easing of the zoom. @default "smooth" */
+    easing?: Easing;
+}
+/**
+ * Options for {@link createDrillDown}.
+ *
+ * @category Charts
+ */
+export interface DrillDownOptions extends DrillOptions {
+    /** The path in focus at first. Defaults to the root. @default [] */
+    initial?: readonly string[];
+    /**
+     * The clock the zoom's tween runs on: pass the scene's (`scene.clock`) so
+     * it pauses and steps with it. @default defaultClock
+     */
+    clock?: Clock;
+    /**
+     * Whether the zoom reduces motion (jumps to its end): `"auto"` defers to
+     * the clock, a `Readable` answers live (a scene's own setting).
+     * @default "auto"
+     */
+    reducedMotion?: ReducedMotion | Readable<boolean>;
+    /** Called just before a reduced-motion zoom jumps to its end. */
+    onReducedJump?: () => void;
+}
+/**
+ * A drill-down's state: where it is going and the tween getting it there.
+ * Returned by {@link createDrillDown}.
+ *
+ * @category Charts
+ */
+export interface DrillDown {
+    /**
+     * The focus to hand to a chart (and to {@link breadcrumbs}): a transition
+     * from the view when the last zoom started to {@link DrillDown.path}. A
+     * `Readable`: pass it as the chart's `focus` prop and the chart follows.
+     */
+    readonly focus: Readable<HierarchyPathSpec>;
+    /** Where the drill-down is (or is going): names below the root. */
+    readonly path: Readable<readonly string[]>;
+    /** The last zoom's 0..1 track; set or scrub it to replay that zoom. */
+    readonly t: Track<number>;
+    /**
+     * Zooms to the node at `path` from the view on screen now, interrupting any
+     * running zoom. Resolves `"done"`, or `"aborted"` if replaced; a no-op when
+     * already there. Hand it straight to a chart's `onFocusChange` or a trail's
+     * `onSelect`.
+     */
+    zoomTo(path: readonly string[]): Promise<PlayResult>;
+    /** Zooms out one level, to the parent of {@link DrillDown.path}. */
+    zoomOut(): Promise<PlayResult>;
+}
+/**
+ * Animated, scrubbable drill-down for a zoomable hierarchy chart. Pass
+ * `focus` to the chart (and to {@link breadcrumbs}), and `zoomTo` to the
+ * chart's `onFocusChange`; every frame is a pure function of the track `t`.
+ * Give it the scene's clock so the zoom runs with the scene.
+ *
+ * @example
+ * ```ts
+ * import { createScene } from "@sophistry/core";
+ * import { createDrillDown, treemap } from "@sophistry/charts";
+ *
+ * const scene = createScene({ host: document.querySelector("#figure")!, units: 10 });
+ * const files = {
+ * 	name: "repo",
+ * 	children: [
+ * 		{ name: "src", children: [{ name: "index.ts", size: 12 }, { name: "chart.ts", size: 30 }] },
+ * 		{ name: "README.md", size: 4 },
+ * 	],
+ * };
+ * const zoom = createDrillDown({ clock: scene.clock });
+ * scene.add(
+ * 	treemap.create({
+ * 		data: files,
+ * 		value: "size",
+ * 		label: "name",
+ * 		width: 8,
+ * 		height: 4,
+ * 		focus: zoom.focus,
+ * 		onFocusChange: (path) => void zoom.zoomTo(path),
+ * 	}),
+ * );
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#hierarchies
+ * @category Charts
+ */
+export declare function createDrillDown(options?: DrillDownOptions): DrillDown;
+/**
+ * A breadcrumb trail drawn by a zoomable hierarchy chart itself (its
+ * `breadcrumbs` prop), by default just above the chart's top-left corner.
+ *
+ * @category Charts
+ */
+export interface HierarchyBreadcrumbOptions {
+    /** The root crumb's text. Defaults to the root's `label`, else `"All"`. */
+    root?: string;
+    /** Where the trail starts (its left end, vertically centred). */
+    at?: Point;
+    /** Font size. Defaults to the chart's label size + 0.04. */
+    fontSize?: number;
+    /**
+     * The widest the trail may be before its middle collapses into `…`;
+     * `false` never collapses. Defaults to the chart's width.
+     */
+    maxWidth?: number | false;
+    /**
+     * A back control before the trail (`true` for `"←"`, or its text) that zooms
+     * out one level.
+     * @default false
+     */
+    back?: boolean | string;
+}
+/**
+ * Tap-to-drill props shared by `treemap`, `icicle`, `sunburst`, `circlePack`
+ * and `tree`. Uncontrolled (`drill`, no `focus`), the chart keeps its own
+ * focus and tweens to tapped nodes; controlled (`focus` + `onFocusChange`),
+ * a tap only calls `onFocusChange`. A tap on the focused node zooms out,
+ * on a parent zooms in, on a leaf zooms to its parent; Enter and Space tap
+ * the node the arrow keys are on, Escape zooms out. Focus is by name path,
+ * so keep sibling labels unique.
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#hierarchies
+ * @category Charts
+ */
+export interface HierarchyDrillProps<T> {
+    /**
+     * Tap or Enter on a node to zoom to it: `true`, or the zoom's timing.
+     * Defaults to true when `onFocusChange` is given, else false.
+     */
+    drill?: boolean | DrillOptions;
+    /** Called when a tap or breadcrumb asks to zoom, with the path below the root and that node's datum. */
+    onFocusChange?: (path: string[], datum: NoInfer<T>) => void;
+    /** The uncontrolled focus at first: a path of names below the root. Defaults to the root. */
+    defaultFocus?: readonly string[];
+    /** Draw a breadcrumb trail of the focus path above the chart; tap a crumb to zoom out to it. */
+    breadcrumbs?: boolean | HierarchyBreadcrumbOptions;
+}
+/** The drill prop keys every zoomable hierarchy chart declares. */
+export declare const DRILL_PROP_KEYS: readonly ["drill", "onFocusChange", "defaultFocus", "breadcrumbs", "focus"];
+/** A chart's drill-down state on one update: the focus to draw and how to ask for a new one. @internal */
+export interface HierarchyDrill<T> {
+    /** The focus to draw. */
+    focus: HierarchyFocusSpec<T> | undefined;
+    /** Whether taps drill. */
+    enabled: boolean;
+    /** Whether asking to zoom does anything (uncontrolled, or someone listens). */
+    canSelect: boolean;
+    /** Asks to zoom to the node at `position` of the current layout. */
+    select(position: number): void;
+    /** Asks to zoom to a path. */
+    selectPath(path: readonly string[]): void;
+}
+/** The props {@link createHierarchyDrill} reads. */
+type DrillChartProps<T> = HierarchyDrillProps<T> & {
+    focus?: HierarchyFocusSpec<T>;
+};
+/**
+ * A chart's drill-down: its `focus`, `drill`, `onFocusChange` and
+ * `defaultFocus` props resolved, with the uncontrolled focus kept on the
+ * scene's clock. The chart reruns its `update` while its own zoom runs.
+ * Call once, in `setup`; call the result in every update.
+ *
+ * @internal
+ */
+export declare function createHierarchyDrill<T, P extends DrillChartProps<T>>(ctx: CompositeContext<P>): (props: DrillChartProps<T>, nodes: readonly HierarchyNodeInfo<T>[]) => HierarchyDrill<T>;
+/** What a chart's node interaction reads on each event: the latest update's state. @internal */
+export interface NodeInteractionState<T> {
+    /** The chart's tooltip. */
+    tooltip: TooltipState;
+    /** The chart's `tooltip` prop. */
+    spec: TooltipSpec<T> | undefined;
+    /** The whole layout. */
+    nodes: readonly HierarchyNodeInfo<T>[];
+    /** The node the zoom is heading for. */
+    target: number;
+    /** The resolved focus: no tooltip opens while it moves. */
+    resolved: ResolvedFocus;
+    drill: HierarchyDrill<T>;
+    /** A batched item's position in the whole layout, or undefined. */
+    positionOf(item: number): number | undefined;
+    /** Where a batched item's tooltip points, in scene units. */
+    atOf(item: number): Point | undefined;
+}
+/** The interaction props a hierarchy chart's batched node carries. @internal */
+export interface NodeInteractionProps {
+    label?: string;
+    itemLabel?: (item: number) => string | undefined;
+    onEnter?: (event: ScenePointerEvent) => void;
+    onLeave?: (event: ScenePointerEvent) => void;
+    onTap?: (event: ScenePointerEvent) => void;
+    keyboard?: KeyboardBehaviour;
+    cursor?: string;
+}
+/** A chart's node interaction: see {@link createNodeInteraction}. @internal */
+export interface NodeInteraction {
+    /**
+     * The props to spread into the batched node's shared props (empty when
+     * neither drilling nor tooltips are on), naming the node `name`.
+     */
+    props(name: string): NodeInteractionProps;
+    /** Taps the node at layout `position` (its tooltip pointing at `at`), as a tap on its item does. */
+    tapNode(position: number, at: Point): void;
+}
+/**
+ * The interaction of a hierarchy chart's batched node (tooltip, drilling
+ * tap, Escape, cursor, each node's accessible name), made once so the
+ * handlers' identities hold across updates. `stateOf` hands back the latest
+ * update's state. Call once, in `setup`.
+ *
+ * @internal
+ */
+export declare function createNodeInteraction<T>(stateOf: () => NodeInteractionState<T>): NodeInteraction;
+export {};