@sophistry/charts 0.0.0-stage → 0.0.1

package/dist/mix.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Blends a keyed transition draws between its two ends — colours, paints,
+ * boxes, point lists — and the text colour that reads on a fill. Internal to
+ * the charts. Colour work is cached per colour (and per pair), since marks
+ * call these per datum per frame.
+ */
+import type { Bounds, Point } from "@sophistry/core/geometry";
+/** Two CSS colours blended at `t` in OKLCH, exact at 0 and 1, memoised per pair. */
+export declare function blendCss(a: string, b: string, t: number): string;
+/** Two boxes blended at `t`, edge by edge: `a` at 0, `b` at 1. */
+export declare function mixBounds(a: Bounds, b: Bounds, t: number): Bounds;
+/**
+ * Two point lists blended at `t`, point by point: `a` at 0, `b` at 1. Lists
+ * of different lengths can't blend point by point: the nearer one is
+ * returned whole.
+ */
+export declare function mixPoints<P extends readonly Point[]>(a: P, b: P, t: number): P;
+/**
+ * A paint blended at `t`: colours in OKLCH ({@link blendCss}); paints that
+ * are not colours (gradients) switch at the midpoint.
+ */
+export declare function mixPaint<P>(a: P, b: P, t: number): P;
+/** Whichever of `dark` and `light` reads better on `fill`, by OKLCH lightness, for numbers written on coloured cells. */
+export declare function readableOn(fill: string, dark: string, light: string): string;
+//# sourceMappingURL=mix.d.ts.map

package/dist/mix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mix.d.ts","sourceRoot":"","sources":["../src/mix.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAS9D,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAWhE;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CASjE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,KAAK,EAAE,EACnD,CAAC,EAAE,CAAC,EACJ,CAAC,EAAE,CAAC,EACJ,CAAC,EAAE,MAAM,GACP,CAAC,CAKH;AACD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAIpD;AAeD,yHAAyH;AACzH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM5E"}

package/dist/multiview/brush.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Gesture arithmetic behind `rangeBrush` and `chartZoom`: brush drags and
+ * wheel resizes, and zoom, pan and box zoom over a chart's coordinate
+ * system and range tracks. Components wire these to pointer, wheel and keys.
+ *
+ * The coordinate system is read through a getter on every gesture step: a
+ * chart publishes a new one whenever its ranges change, so a gesture never
+ * holds on to a stale one.
+ */
+import type { Animatable, CoordinateSystem, DragBehaviour, Readable, SceneNodeWheelEvent, ScenePointerEvent } from "@sophistry/core";
+import type { Point } from "@sophistry/core/geometry";
+/**
+ * A number a `rangeBrush` or `chartZoom` reads and writes: a `track(...)`, or
+ * any `Readable` with `set`.
+ *
+ * @category Charts
+ */
+export type BrushCell = Readable<number> & Animatable<number>;
+/**
+ * A drag-to-zoom rectangle, in the plot's local scene units: its two
+ * corners and which axes it zooms (a thin box zooms only along its length).
+ *
+ * @category Charts
+ */
+export interface ChartZoomBox {
+    a: Point;
+    b: Point;
+    x: boolean;
+    y: boolean;
+}
+/** Where the coordinate system comes from: read on every use. */
+type CoordsSource = () => CoordinateSystem;
+/** CSS pixels a wheel `deltaMode` of lines or pages is worth, as `panZoom` reads them. */
+export declare const WHEEL_LINE = 16;
+export declare const WHEEL_PAGE = 400;
+/** An axis of a chart, `"x"` or `"y"`. */
+type Axis = "x" | "y";
+/** One brushed axis: its two tracks and how they may move. */
+export interface BrushAxis {
+    axis: "x" | "y";
+    from: BrushCell;
+    to: BrushCell;
+    bounds: () => readonly [number, number] | undefined;
+    minSpan: () => number | undefined;
+    /** Keep the ends on whole slots (a band axis). */
+    snap: () => boolean;
+}
+/**
+ * The wheel on a `rangeBrush`: grows or shrinks its span about the
+ * cursor on every brushed axis (geometrically on a log axis), within the
+ * limits and `minSpan`; a snapped axis moves a whole slot once the resize
+ * accumulates. Returns whether the wheel was taken.
+ *
+ * @internal
+ */
+export declare function brushWheel(options: {
+    coords: CoordsSource;
+    axes: readonly BrushAxis[];
+    speed?: () => number;
+}): (event: SceneNodeWheelEvent) => boolean;
+/**
+ * The gestures of a one-axis `rangeBrush`: the body (keeping the span)
+ * and each edge, clamped to the bounds and snapped with `snap`.
+ *
+ * @internal
+ */
+export declare function brushDrags(options: {
+    coords: CoordsSource;
+    from: BrushCell;
+    to: BrushCell;
+    vertical: () => boolean;
+    bounds: () => readonly [number, number] | undefined;
+    minSpan: () => number | undefined;
+    snap?: () => boolean;
+    disabled: () => boolean;
+}): {
+    pointAt: (v: number) => Point;
+    drag: {
+        body: import("@sophistry/core").DraggableProps;
+        from: import("@sophistry/core").DraggableProps;
+        to: import("@sophistry/core").DraggableProps;
+    };
+};
+/**
+ * The gestures of a box `rangeBrush`: the body, the four edges and
+ * the four corners.
+ *
+ * @internal
+ */
+export declare function boxBrushDrags(options: {
+    coords: CoordsSource;
+    x: BrushAxis;
+    y: BrushAxis;
+    disabled: () => boolean;
+}): {
+    body: import("@sophistry/core").DraggableProps;
+    x: {
+        from: import("@sophistry/core").DraggableProps;
+        to: import("@sophistry/core").DraggableProps;
+    };
+    y: {
+        from: import("@sophistry/core").DraggableProps;
+        to: import("@sophistry/core").DraggableProps;
+    };
+    corners: {
+        x: "a" | "b";
+        y: "a" | "b";
+        drag: import("@sophistry/core").DraggableProps;
+    }[];
+};
+/**
+ * Zoom and pan over a chart's coordinate system and range tracks, as
+ * `chartZoom` wires them to pointer, wheel and keys. Positions are in
+ * the plot's local scene units.
+ *
+ * @internal
+ */
+export declare function chartZoomActions(options: {
+    coords: CoordsSource;
+    x?: readonly [BrushCell, BrushCell];
+    y?: readonly [BrushCell, BrushCell];
+    bounds: (axis: Axis) => readonly [number, number] | undefined;
+    minSpan: (axis: Axis) => number | undefined;
+    /** Whether an axis settles on whole slots (a band axis). Defaults to never. */
+    snap?: (axis: Axis) => boolean;
+}): {
+    /** Which axes zoom. */
+    has: (axis: Axis) => boolean;
+    transform: (at: Point, factor: number, by: Point) => void;
+    zoomAbout: (at: Point, factor: number) => void;
+    panBy: (by: Point) => void;
+    zoomTo: (box: ChartZoomBox) => boolean;
+    settle: (origin: readonly number[], how: "slide" | "ends", step?: boolean | "in" | "out") => void;
+    reset: () => boolean;
+    centre: () => Point;
+    pointOf: (value: {
+        x: number;
+        y: number;
+    }) => Point;
+    dataAt: (at: Point) => {
+        x: number;
+        y: number;
+    };
+    snapshot: () => number[];
+    restore: (values: readonly number[]) => void;
+};
+/**
+ * The pointer gestures of a `chartZoom`: one finger or the mouse
+ * pans, two fingers pinch-zoom; with `box`, the drag draws a rectangle and
+ * the release zooms into it. A still press stays a tap; a cancelled gesture
+ * puts the ranges back.
+ *
+ * @internal
+ */
+export declare function chartZoomDrag(actions: ReturnType<typeof chartZoomActions>, enabled: () => boolean, options?: {
+    /** Whether this press draws a zoom box rather than panning. */
+    box?: (event: ScenePointerEvent) => boolean;
+    /** The box as it is drawn, or null when it is gone. */
+    onBox?: (box: ChartZoomBox | null) => void;
+    /** A box zoom happened; `before` is the ranges it replaced (a {@link chartZoomActions} snapshot). */
+    onZoom?: (before: number[]) => void;
+    /** Whether one finger pans (a box can still be drawn without). Defaults to `enabled`. */
+    pan?: () => boolean;
+}): DragBehaviour;
+export {};
+//# sourceMappingURL=brush.d.ts.map

package/dist/multiview/brush.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brush.d.ts","sourceRoot":"","sources":["../../src/multiview/brush.ts"],"names":[],"mappings":"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"}

package/dist/multiview/chart-group.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Frames that share scales: the store behind `chartLink`, `facet`,
+ * `pairPlot` and `jointPlot`. Each `chart` inside registers as a panel;
+ * panels with the same share key on an axis fit it to the union of their
+ * reports, all colour through one scale, and with `shareSize` all sized
+ * layers share one maximum. Nothing here draws. Internal.
+ *
+ * How it runs (one commit, as a chart and its layers do): a preset (or
+ * `chartLink`) makes the store in `setup` and provides a
+ * {@link ChartGroupScope} through {@link chartGroupContext}. A chart that
+ * finds one joins as a panel ({@link chartPanel}): at the start of each of
+ * its updates it publishes its layers' reports, then fits its shared axes to
+ * the group's. A report that changed by value marks every other panel
+ * (`ctx.invalidate`), which refit in the same commit; the panel's guide
+ * room, axis spans and transition stages, published at the end of its
+ * update, mark only the group's watchers (the preset laying the panels
+ * out). Values equal to the last ones change nothing, so the loop settles.
+ */
+import type { CompositeContext, ContextKey } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey, Range, RangeTransition } from "@sophistry/core/geometry";
+import type { ChartLayerExtent, LegendMark, RampExtent, SharedSizeDomain, SizeExtent } from "../frame/types";
+import type { JoinStages } from "../math/join";
+import type { OrdinalColorScale } from "../math/ordinal";
+/** Room a panel's guides take on each side of its plotting area, in scene units. */
+export interface PanelRoom {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+/** Which scales a panel shares: panels with the same key on an axis fit it together. */
+export interface PanelKeys {
+    x?: string;
+    y?: string;
+    /** Axes where the panel takes the shared fit without adding its data (a joint plot's marginals). */
+    follows?: {
+        x?: boolean;
+        y?: boolean;
+    };
+}
+/** Where a panel sits in its preset's grid, when it has one. */
+export interface PanelPlace {
+    /** Grid row, from the top. */
+    readonly row: number;
+    /** Grid column, from the left. */
+    readonly column: number;
+}
+/** A panel's own state, as it last published it. */
+export interface PanelState {
+    /** The panel's own layers' reports, a keyed transition's blend held out (its `t` reads 0). */
+    reports: readonly ChartLayerExtent[];
+    /** The blend of the panel's first transitioning layer, if any. */
+    blend: number | undefined;
+    /** The panel could draw on its own (its layers have reported). */
+    ready: boolean;
+    /** The room its guides take around the plot. */
+    room: PanelRoom;
+    /** The stages of the keyed transition its frame runs, if any (the group's guides follow them). */
+    stages: JoinStages | undefined;
+    /**
+     * Each axis's range length in its own units (band count, data span,
+     * decades on a log axis), independent of panel size, for `facet`'s `space="free"`.
+     */
+    span: {
+        x: number;
+        y: number;
+    } | undefined;
+}
+/** A panel as the group sees it: its keys, place and last published state. */
+export interface GroupPanel {
+    readonly keys: PanelKeys;
+    readonly place: PanelPlace | undefined;
+    readonly state: Readonly<PanelState>;
+}
+/** A panel's link to its group: what it publishes, and leaving. */
+export interface GroupMember {
+    /**
+     * Publishes what the other panels read: the panel's reports and its
+     * transition's blend. Marks the other panels and the watchers when it
+     * changed. Call at the start of the panel's update, before reading the
+     * group's shared fits.
+     */
+    publishReports(reports: readonly ChartLayerExtent[], blend?: number): void;
+    /**
+     * Publishes what only the preset reads (room, spans, stages, readiness).
+     * Marks the watchers when it changed by value.
+     */
+    publishLayout(layout: Partial<Pick<PanelState, "room" | "span" | "stages" | "ready">>): void;
+    /** Leaves the group; the others refit. */
+    dispose(): void;
+}
+/** The colour scale options a group takes (`ChartColorOptions`). */
+export interface GroupColorOptions {
+    domain?: readonly BandKey[];
+    range?: readonly ColorInput[];
+    label?: (key: BandKey, index: number) => string;
+}
+/** Options for {@link createChartGroup}, set again on every update of the owner. */
+export interface ChartGroupOptions {
+    color?: GroupColorOptions;
+    /** A range every panel sharing x (under any key) takes, unless it gives its own. */
+    xRange?: Range | RangeTransition;
+    /** A range every panel sharing y takes, unless it gives its own. */
+    yRange?: Range | RangeTransition;
+    /**
+     * Give every panel's sized layers one size scale: the greatest maximum any
+     * reports. A layer pinning `sizeMaxValue` keeps its own.
+     * @default false
+     */
+    shareSize?: boolean;
+    /** The colours a scale without `color.range` cycles: the theme's series colours. */
+    palette?: readonly string[];
+}
+/** One legend entry of a group's shared legend. */
+export interface GroupLegendEntry {
+    key: BandKey;
+    label: string;
+    color: string;
+    mark: LegendMark;
+}
+/** A group of panels sharing scales. */
+export interface ChartGroup {
+    /**
+     * Adds a panel. `onChange` is told (mark only) whenever something the
+     * panel reads from the group changed: another panel's reports, the
+     * options. Returns the panel's link.
+     */
+    join(entry: {
+        keys: PanelKeys;
+        place?: PanelPlace;
+    }, onChange: () => void): GroupMember;
+    /**
+     * Watches every change (the preset laying the panels out): `onChange` is
+     * told whenever any panel published something new. Returns unsubscribe.
+     */
+    watch(onChange: () => void): () => void;
+    /** Sets the options; a change marks every panel. */
+    setOptions(options: ChartGroupOptions): void;
+    /** The panels, in joining order. */
+    panels(): readonly GroupPanel[];
+    /** Every panel's reports (blends held out, as in {@link PanelState.reports}). */
+    all(): readonly ChartLayerExtent[];
+    /** The blend of the first panel in a keyed transition: the one the group stages on. */
+    blend(): number | undefined;
+    /** The reports of every panel sharing `key` on `axis`. */
+    shared(axis: "x" | "y", key: string): readonly ChartLayerExtent[];
+    /** The range given for an axis, for panels sharing it. */
+    range(axis: "x" | "y"): Range | RangeTransition | undefined;
+    /** The one colour scale; the same object while its domain and colours hold. */
+    colorScale(): OrdinalColorScale;
+    /** One entry per category of the colour scale, swatches merged over every panel's layers. */
+    legendEntries(): readonly GroupLegendEntry[];
+    /** The first value-coloured layer's ramp, for one colour bar. */
+    ramp(): RampExtent | undefined;
+    /** The size maximum every panel's sized layers share at each end; undefined unless sharing and some layer sizes by value. */
+    sizeDomain(): SharedSizeDomain | undefined;
+    /** A layer's size scale as it is drawn in this group: the shared maximum, unless it pins its own. */
+    sizeOf(size: SizeExtent): SizeExtent;
+    /** The stages of the panels' keyed transition (the first that has one), for the group's own guides. */
+    stages(): JoinStages | undefined;
+    /** Every panel is ready, so shared fits are complete. */
+    ready(): boolean;
+    /** The largest room any panel's guides take on each side. */
+    room(): PanelRoom;
+}
+/**
+ * What a panel finds in context: its group and its share keys.
+ *
+ * @category Extending
+ */
+export interface ChartGroupScope {
+    group: ChartGroup;
+    keys: PanelKeys;
+    /** The panel's place in the grid, so the preset can tell its panels' rooms apart. */
+    place?: PanelPlace;
+}
+/**
+ * The group a `chart` is a panel of, or null. Presets provide it on a
+ * container around each panel; `chartLink` provides it to its whole subtree.
+ *
+ * @category Extending
+ */
+export declare const chartGroupContext: ContextKey<ChartGroupScope | null>;
+/** Column widths (x) or row heights (y) for `space="free"`: each as long as the longest range among its panels. */
+export declare function spanRatios(panels: readonly GroupPanel[], axis: "x" | "y", count: number): number[];
+/** Two optional ratio lists with the same entries. */
+export declare function sameRatios(a: readonly number[] | undefined, b: readonly number[] | undefined): boolean;
+/** The legend swatch over every reporting layer: what `chart` merges too. */
+export declare function mergedLegendMark(reports: readonly ChartLayerExtent[]): LegendMark;
+/**
+ * One size scale over sized layers' reports: the greatest maximum at each
+ * end (a pinned `sizeMaxValue` counts at both). Undefined when no layer
+ * sizes by value.
+ */
+export declare function sharedSizeDomain(reports: readonly ChartLayerExtent[]): SharedSizeDomain | undefined;
+/** Two shared size domains with the same ends. */
+export declare function sameSizeDomain(a: SharedSizeDomain | undefined, b: SharedSizeDomain | undefined): boolean;
+/** A layer's size scale on a shared one: the shared maximum at each end, unless the layer pins its own or nothing is shared. */
+export declare function onSharedSize(size: SizeExtent, shared: SharedSizeDomain | undefined): SizeExtent;
+/**
+ * A frame's size keys over its sized layers, in layer order: one per
+ * distinct drawn scale, titled by its first layer's channel. With
+ * `byRange` (a group's keys), one per distinct `sizeRange`, left out
+ * unless its layers agree on the maximum.
+ */
+export declare function sizeKeysOf(sizes: readonly (SizeExtent | undefined)[], drawn: (size: SizeExtent) => SizeExtent, byRange?: boolean): SizeExtent[];
+/**
+ * A group store. Make one in a composite's `setup`, give it its options in
+ * every update ({@link ChartGroup.setOptions}), and provide a
+ * {@link ChartGroupScope} through {@link chartGroupContext}; panels find it
+ * there. Everything it computes is cached until a panel publishes or the
+ * options change.
+ */
+export declare function createChartGroup(options?: ChartGroupOptions): ChartGroup;
+/**
+ * A chart's side of a group: the hook `chart` calls so it works as a panel.
+ * Outside a group every method falls back to the chart's own state.
+ *
+ * In the chart's update, in this order:
+ *
+ * ```ts
+ * const panel = state.panel.begin(reports, blend); // publishes; null outside a group
+ * const xReports = state.panel.fitReports("x", reports);
+ * const xGiven = numericRange(props.xRange) ?? state.panel.range("x");
+ * const colorScale = state.panel.colorScale() ?? colorScaleOf(...);
+ * const sizeDomain = state.panel.sizeDomain() ?? ownSizeDomain;
+ * // ... fit, lay out, draw ...
+ * state.panel.end({ room, span, stages, ready });
+ * ```
+ *
+ * @category Extending
+ */
+export interface ChartPanel {
+    /**
+     * Reads the group scope (joining or leaving as it changes) and publishes
+     * the chart's layers' reports. Returns the scope, or null outside a group.
+     */
+    begin(reports: readonly ChartLayerExtent[], blend?: number): ChartGroupScope | null;
+    /** The reports an axis is fitted to: its share key's across the group, or the chart's own. */
+    fitReports(axis: "x" | "y", own: readonly ChartLayerExtent[]): readonly ChartLayerExtent[];
+    /** Every report a keyed transition stages on: the whole group's, or the chart's own. */
+    allReports(own: readonly ChartLayerExtent[]): readonly ChartLayerExtent[];
+    /** The group's range for an axis the chart shares, or undefined. */
+    range(axis: "x" | "y"): Range | RangeTransition | undefined;
+    /** The group's colour scale, or undefined outside a group. */
+    colorScale(): OrdinalColorScale | undefined;
+    /** The group's shared size domain, or undefined (outside, or not sharing). */
+    sizeDomain(): SharedSizeDomain | undefined;
+    /** The group's blend (the first transitioning panel's), or undefined. */
+    blend(): number | undefined;
+    /** Whether the chart is a panel (its legend is the group's, its room the group's to lay out). */
+    readonly grouped: boolean;
+    /** Publishes what the preset lays the panels out by. */
+    end(layout: Partial<Pick<PanelState, "room" | "span" | "stages" | "ready">>): void;
+}
+/** Why a chart's update reruns for its group: another panel or the options changed. */
+export declare const GROUP_CHANGED: ContextKey<unknown>;
+/**
+ * Makes a chart's {@link ChartPanel}. Call once, in the chart's `setup`.
+ * Leaves the group when the chart is disposed.
+ *
+ * @category Extending
+ */
+export declare function chartPanel<P>(ctx: CompositeContext<P>): ChartPanel;
+//# sourceMappingURL=chart-group.d.ts.map

package/dist/multiview/chart-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-group.d.ts","sourceRoot":"","sources":["../../src/multiview/chart-group.ts"],"names":[],"mappings":"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"}

package/dist/multiview/chart-link.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Linked frames: `chartLink` shares scales between `chart`s, and
+ * `rangeBrush` is the interaction that drives a linked range. Both are
+ * driven by tracks, so they scrub and seek.
+ */
+import type { SceneNode } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey, BandScale, Range, RangeTransition } from "@sophistry/core/geometry";
+import type { ChartColorOptions, ChartFrame } from "../frame/types";
+import type { BrushCell } from "./brush";
+/**
+ * Props for {@link chartLink}.
+ *
+ * @category Charts
+ */
+export interface ChartLinkProps {
+    /**
+     * Share the x axis: every member fits x to the union of all members' layers.
+     * @default true
+     */
+    x?: boolean;
+    /**
+     * Share the y axis the same way.
+     * @default false
+     */
+    y?: boolean;
+    /**
+     * A range every member sharing x takes (unless it gives its own `xRange`): one value to zoom
+     * them all. Omitted, the shared fit.
+     */
+    xRange?: Range | RangeTransition;
+    /** A range every member sharing y takes; see `xRange`. */
+    yRange?: Range | RangeTransition;
+    /** The members' one colour scale: order, colours and legend names. */
+    color?: ChartColorOptions;
+    /** The `chart`s to link, anywhere inside. */
+    children?: readonly SceneNode[];
+}
+/**
+ * Links the `chart`s inside it: one shared colour scale, and the axes chosen by `x`/`y`
+ * fitted to the union of every member's data (or all set to `xRange`/`yRange`). A member with
+ * its own `xRange` keeps it, so an overview with a {@link rangeBrush} can drive linked detail
+ * views. Each member draws its own legend; set `legend: false` on all but one. Which axes are
+ * shared (`x`, `y`) is read once, at creation.
+ *
+ * @example
+ * ```ts
+ * import { derive, track } from "@sophistry/core";
+ * import { chart, chartLink, linePlot } from "@sophistry/charts";
+ *
+ * const data = [3, 1, 4, 1, 5, 9, 2, 6];
+ * const from = track(2);
+ * const to = track(5);
+ * chartLink.create({
+ * 	xRange: derive([from, to], (a, b) => [a, b]),
+ * 	children: [chart.create({ width: 8, height: 3, children: [linePlot.create({ data })] })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/guides/charts/#multiple-views
+ * @category Charts
+ */
+export declare const chartLink: import("@sophistry/core").Definition<ChartLinkProps, import("@sophistry/core/internal").CompositeNode<ChartLinkProps>, keyof ChartLinkProps>;
+/**
+ * A per-axis option of {@link rangeBrush}: one value for every brushed axis, or one per axis.
+ *
+ * @category Charts
+ */
+export type BrushAxisOption<V> = V | {
+    x?: V;
+    y?: V;
+};
+/**
+ * Props for {@link rangeBrush}.
+ *
+ * @category Charts
+ */
+export interface RangeBrushProps {
+    /** The selection's low end, in data units, read and written while dragging. Use with `axis`. */
+    from?: BrushCell;
+    /** The selection's high end, in data units. */
+    to?: BrushCell;
+    /**
+     * The axis `from`/`to` run along.
+     * @default "x"
+     */
+    axis?: "x" | "y";
+    /** The x selection's two ends, `[from, to]`; with `y` too, a box brush. */
+    x?: readonly [BrushCell, BrushCell];
+    /** The y selection's two ends; with `x`, a box brush. */
+    y?: readonly [BrushCell, BrushCell];
+    /**
+     * Where the ends may go, in data units: `[min, max]`, or per axis. Defaults to the frame's
+     * range on each axis.
+     */
+    bounds?: BrushAxisOption<readonly [number, number]>;
+    /**
+     * The narrowest selection an edge drag can make, in data units (or per axis). Defaults to 0
+     * (one category on a band axis).
+     */
+    minSpan?: BrushAxisOption<number>;
+    /**
+     * On a band axis, keep the ends on whole categories (the tracks hold slot edges, `0`..`n`).
+     * Read the selection with {@link brushedCategories}. Defaults to true on a band axis.
+     */
+    snap?: boolean;
+    /** Fill and edge colour. Defaults to the theme's first series colour. */
+    color?: ColorInput;
+    /**
+     * Opacity of the selection's fill.
+     * @default 0.18
+     */
+    fillOpacity?: number;
+    /**
+     * Draw a draggable edge at each end (and corners on a box brush).
+     * @default true
+     */
+    handles?: boolean;
+    /** Read-only: draw the selection but take no input. */
+    disabled?: boolean;
+    /**
+     * Let the wheel over the brush grow or shrink it about the cursor, within `bounds` and
+     * `minSpan`.
+     * @default false
+     */
+    wheel?: boolean;
+    /**
+     * Multiplies the wheel's resize.
+     * @default 1
+     */
+    wheelSpeed?: number;
+    /**
+     * Accessible name of the selection; its edges add `"start"`/`"end"`.
+     * @default "selected range"
+     */
+    label?: string;
+    /**
+     * Reveal, 0..1: fades in with the frame's data.
+     * @default 1
+     */
+    progress?: number;
+    zIndex?: number;
+    visible?: boolean;
+}
+/** A per-axis option's value for one axis. Internal. */
+export declare function brushAxisOption<V>(option: BrushAxisOption<V> | undefined, axis: "x" | "y", isValue: (option: BrushAxisOption<V>) => option is V): V | undefined;
+export declare const isPair: (option: BrushAxisOption<readonly [number, number]>) => option is readonly [number, number];
+export declare const isNumber: (option: BrushAxisOption<number>) => option is number;
+/**
+ * The categories a band brush's selection covers: those whose slot's middle lies between
+ * `from` and `to`. Pass the axis's {@link BandScale} (`chartHandle(node).xBand`) or the
+ * categories in axis order.
+ *
+ * @category Charts
+ */
+export declare function brushedCategories<K extends BandKey>(categories: readonly K[] | BandScale<K>, from: number, to: number): K[];
+/**
+ * Throws unless the node is inside a chart, and returns its frame.
+ * @internal
+ */
+export declare function requireFrame(frame: ChartFrame | null, name: string): ChartFrame;
+/**
+ * A draggable selection on a `chart`: a band between `from` and `to` on one axis, or a
+ * box with `x` and `y`. It holds no state of its own: the tracks are the state, so any chart
+ * reading them (`xRange: derive([from, to], (a, b) => [a, b])`) is linked. Drag the body to
+ * move, an edge or corner to resize; the body and edges are also keyboard-focusable (arrows,
+ * Shift for fine steps, Escape cancels a drag). Which tracks it brushes is read once, at
+ * creation.
+ *
+ * @example
+ * ```ts
+ * import { track } from "@sophistry/core";
+ * import { chart, linePlot, rangeBrush } from "@sophistry/charts";
+ *
+ * const data = [3, 1, 4, 1, 5, 9, 2, 6];
+ * const from = track(2);
+ * const to = track(4);
+ * chart.create({
+ * 	width: 8,
+ * 	height: 2,
+ * 	children: [linePlot.create({ data }), rangeBrush.create({ from, to })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/guides/charts/#multiple-views
+ * @category Charts
+ */
+export declare const rangeBrush: import("@sophistry/core").Definition<RangeBrushProps, import("@sophistry/core/internal").CompositeNode<RangeBrushProps>, keyof RangeBrushProps>;
+//# sourceMappingURL=chart-link.d.ts.map