@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/end-space.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Where a keyed mark draws each end of its transition when a fitted axis
+ * changes kind between them (band ↔ continuous). Internal.
+ */
+import type { CoordinateSystem } from "@sophistry/core";
+import type { BandScale, Point } from "@sophistry/core/geometry";
+import type { ChartEnds, ChartFrame } from "./frame/types.js";
+import type { JoinEnd, JoinFrame } from "./join.js";
+import type { AreaPoint } from "./math/morph.js";
+/**
+ * What a mark's geometry maps through: a plot's `coordsToPoint`, {@link SCENE_UNITS},
+ * or mid-swap one of {@link EndSpace.morph}'s mixed-unit mappings.
+ */
+export interface Mapper extends Pick<CoordinateSystem, "coordsToPoint"> {
+    /** Which coordinates `coordsToPoint` takes already in scene units (the swapping axes, mid-swap); the rest it maps from data units. */
+    scene?: {
+        x: boolean;
+        y: boolean;
+    };
+}
+/** A mapping for geometry already in scene units: `coordsToPoint` returns its point as given. */
+export declare const SCENE_UNITS: Mapper;
+/** Area runs through `coords`, for a mid-swap area morph; runs reversed by the mapping are turned around so the morph still blends per x. */
+export declare function sceneAreaRuns(runs: readonly (readonly AreaPoint[])[], coords: Mapper): AreaPoint[][];
+/** Where a mark draws each end of its keyed transition: see {@link endSpace}. */
+export interface EndSpace {
+    /** The plot at each end while a fitted axis changes kind (see {@link ChartEnds}); undefined otherwise. */
+    ends: ChartEnds | undefined;
+    /** The coordinates a datum of `end` maps through: that end's plot mid-swap, else the mark's own. */
+    coords(end: JoinEnd): CoordinateSystem;
+    /** A band axis's scale at `end`: that end's mid-swap, else the chart's now. */
+    band(end: JoinEnd, axis: "x" | "y"): BandScale | undefined;
+    /**
+     * A key in both ends, in scene units at update progress `u`, from `a` (its
+     * `data` datum) to `b` (its `to` datum). Mid-swap, the swapping axis blends
+     * in scene units between the two ends' plots. Exact at `u` 0 and 1.
+     */
+    point(a: Point, b: Point, u: number): Point;
+    /** Whether a kind swap runs; marks building their own geometry then build each end through its own `coords` and blend in scene units. */
+    swapping: boolean;
+    /**
+     * A per-datum mark's anchor on one key's frame, in scene units. `anchor`
+     * reads one end's state as a data-unit point. Mid-swap, a key in both ends
+     * blends between its two ends' anchors; any other maps through its own end.
+     */
+    place<S>(frame: JoinFrame<S>, anchor: (state: S, end: JoinEnd) => Point): Point;
+    /**
+     * A per-datum mark's own geometry on one key's frame: `build` maps one
+     * end's state through given coordinates. Mid-swap, a key in both ends
+     * builds each end through its own plot and `blend`s them in scene units.
+     */
+    shape<S, G>(frame: JoinFrame<S>, build: (state: S, end: JoinEnd, coords: CoordinateSystem) => G | null, blend: (a: G, b: G, u: number) => G): G | null;
+    /**
+     * A grouped mark's shape for a group in both ends at update progress `u`.
+     * Without a swap, `morph` blends in data units and `build` maps through the
+     * mark's coordinates. Mid-swap, only the swapping axis blends in scene
+     * units (via `scene`), so an axis that keeps its kind (log, sqrt) morphs
+     * exactly as without a swap. Exact at `u` 0 and 1.
+     */
+    morph<S, G>(a: S, b: S, u: number, spec: {
+        scene: (state: S, coords: Mapper, end: JoinEnd) => S;
+        morph: (a: S, b: S, u: number) => S;
+        build: (state: S, coords: Mapper, end: JoinEnd) => G;
+    }): G;
+    /** Where the axes are drawn at `end`, in data units: that end's own mid-swap, else the chart's; outside a chart, the crossing. */
+    axesAt(end: JoinEnd): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Plumbing for a keyed mark in a {@link Chart} whose fitted axis changes
+ * kind between the ends (a bar chart's categories becoming a number line).
+ * Keys in both ends move from where end A draws them to where end B does,
+ * leaving keys draw through end A, entering keys through end B, so nothing
+ * jumps when the plot switches axes. Without a swap every method is the
+ * plain path. Call in each `update` with the frame and coordinates it read.
+ *
+ * @param coords - The coordinates the mark otherwise draws through.
+ */
+export declare function endSpace(frame: ChartFrame | null, coords: CoordinateSystem): EndSpace;

package/dist/entries/definitions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@sophistry/charts/definitions`: every definition the package's main
+ * entry exports, keyed by export name. What `@sophistry/codegen` reads
+ * to generate the framework bindings' chart components (`export const
+ * Scatter = wrap(scatter);`).
+ *
+ * Collected from the main entry's exports, so a definition is picked up as
+ * soon as it is exported from `@sophistry/charts`. Kept off the main
+ * entry: reading the whole module namespace would defeat tree shaking.
+ *
+ * @module @sophistry/charts/definitions
+ */
+import * as entry from "../index.js";
+/**
+ * Every definition `@sophistry/charts` exports, by export name
+ * (`{ chart, scatter, ... }`).
+ *
+ * @category Charts
+ */
+export declare const definitions: import("@sophistry/core/definitions").DefinitionExports<typeof entry>;

package/dist/entries/definitions.js

@@ -0,0 +1,6 @@
+import { t as e } from "../src-CwGo1bes.js";
+import { collectDefinitions as t } from "@sophistry/core/definitions";
+//#region src/entries/definitions.ts
+var n = t(e);
+//#endregion
+export { n as definitions };

package/dist/frame/band-axis.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A chart's categorical axis: the line the bands stand on, and a name under
+ * (or beside) each band. Internal to the frame (and a group's guides); not
+ * exported from the package entry.
+ */
+import type { AxisOptions, CoordinateSystem } from "@sophistry/core";
+import type { BandKey, BandScale } from "@sophistry/core/geometry";
+import type { MergedAxisOptions } from "./fit.js";
+/**
+ * Props for {@link bandAxis}.
+ *
+ * @category Extending
+ */
+export interface BandAxisProps {
+    band: BandScale;
+    /** A category name's opacity, 0..1 (a keyed transition fading it in or out). @default 1 */
+    weight?: (key: BandKey) => number;
+    options: MergedAxisOptions;
+    /** An outline around each name; see `LabelProps.halo`. */
+    halo?: AxisOptions["numberHalo"];
+    coords: CoordinateSystem;
+    along: "x" | "y";
+    /** The other axis's value the line sits at, in data units. */
+    at: number;
+    /** Where the line sits across the plot in scene units, in place of `at` (mid-swap). */
+    across?: number;
+    /** On the top or right edge: names face outward (up, right). */
+    far?: boolean;
+    /** The whole axis's opacity, 0..1 (a kind swap's cross-fade). @default 1 */
+    opacity?: number;
+    progress: number;
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * A categorical axis: the line the bands stand on, and a name under (or
+ * beside) each band, faded by `weight` and by where the band sits in a
+ * zoomed window.
+ *
+ * @category Extending
+ */
+export declare const bandAxis: import("@sophistry/core").Definition<BandAxisProps, import("@sophistry/core/internal").CompositeNode<BandAxisProps>, keyof BandAxisProps>;

package/dist/frame/coords.d.ts

@@ -0,0 +1,111 @@
+/**
+ * A `chart`'s coordinate systems: the plot through its primary and
+ * secondary axes, the ghost and end mappings of an axis changing kind, and
+ * where the axes stand.
+ *
+ * {@link createChartCoords} is made once per chart; its function runs on
+ * every update and returns the same coordinate system objects while their
+ * mapping is unchanged (they are immutable, so a new one means the mapping
+ * moved).
+ */
+import type { CoordinateSystem, XAxisPosition, YAxisPosition } from "@sophistry/core";
+import type { Bounds, Point, Range } from "@sophistry/core/geometry";
+import type { JoinStages, StageWindow } from "../math/join.js";
+import type { AxisEnds, MergedAxisOptions, ResolvedAxis } from "./fit.js";
+import type { SecondaryFlags } from "./secondary.js";
+import type { ChartEnd, ChartEnds } from "./types.js";
+/** A kind's crossing on an axis: a band axis's first slot, a continuous one's zero (or nearest end). */
+export declare const crossingOf: (axis: ResolvedAxis) => number;
+/** What one update of the chart's coordinates reads. */
+export interface ChartCoordsInput {
+    xOptions: MergedAxisOptions;
+    yOptions: MergedAxisOptions;
+    x: {
+        axis: ResolvedAxis;
+        range: Range;
+    };
+    y: {
+        axis: ResolvedAxis;
+        range: Range;
+    };
+    x2: {
+        axis: ResolvedAxis;
+        range: Range;
+        options: MergedAxisOptions;
+    };
+    y2: {
+        axis: ResolvedAxis;
+        range: Range;
+        options: MergedAxisOptions;
+    };
+    /** The primary axes' fitted ends (steady while the blend moves). */
+    xEnds: AxisEnds | undefined;
+    yEnds: AxisEnds | undefined;
+    /** The other end of an axis changing kind mid-swap. */
+    xGhost: ResolvedAxis | undefined;
+    yGhost: ResolvedAxis | undefined;
+    axisBands: {
+        x: boolean;
+        y: boolean;
+    };
+    xPosition: XAxisPosition;
+    yPosition: YAxisPosition;
+    plotWidth: number;
+    plotHeight: number;
+    center: Point;
+    stage(pick: (stages: JoinStages) => StageWindow): number;
+}
+/** A chart's coordinate systems on one update. */
+export interface ChartCoords {
+    /** The plot through the primary axes. */
+    coords: CoordinateSystem;
+    /** y through `y2`. */
+    coords2: CoordinateSystem;
+    /** x through `x2`. */
+    coords3: CoordinateSystem;
+    /** Both secondary axes. */
+    coords4: CoordinateSystem;
+    /** The plot through a kind-swapping x axis's ghost. */
+    ghostX: CoordinateSystem;
+    /** The plot through a kind-swapping y axis's ghost. */
+    ghostY: CoordinateSystem;
+    /** Where a kind-swapping axis's ghost stands across the other axis, in data units. */
+    ghostAt(axis: "x" | "y", ghost: ResolvedAxis): number;
+    /** Which fitted axes change kind across the keyed transition, if any. */
+    kindSwap: {
+        x: boolean;
+        y: boolean;
+    } | undefined;
+    /** The ends a context's layers see (see {@link ChartEnds}). */
+    endsThrough(flags: SecondaryFlags): ChartEnds | undefined;
+    /** The primary context's ends, with their mappings even when no axis swaps. */
+    primaryEnds: {
+        ends: ChartEnds | undefined;
+        from: ChartEnd;
+        to: ChartEnd;
+    };
+    /** Mid-swap, where the axes stand at each end blended in scene units. */
+    swapOrigin: (Point & {
+        x2: boolean;
+        y2: boolean;
+    }) | undefined;
+    /** Where each axis is drawn, in data units. */
+    axesAt: {
+        x: number;
+        y: number;
+    };
+    /** The y value the x axis runs along. */
+    xAxisAt: number;
+    /** The x value the y axis stands at. */
+    yAxisAt: number;
+    /** Where the axes are drawn, in scene units. */
+    origin: Point;
+    /** Where the axes' titles hang from. */
+    titlesAt: Point;
+    area: Bounds;
+}
+/**
+ * The chart's coordinate systems and where its axes stand. Make one per
+ * chart in `setup`; call the result in every update.
+ */
+export declare function createChartCoords(): (input: ChartCoordsInput) => ChartCoords;

package/dist/frame/fit.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Fitting one axis of a `chart` to its layers' reports: resolving,
+ * comparing, and transitioning axes, and {@link createAxisFit}, made once
+ * per axis (`x`, `y`, `x2`, `y2`) in the chart's `setup`.
+ *
+ * Each step is a function of the chart's current inputs with a last-value
+ * cache, so a step whose inputs
+ * kept their identity returns its last result (and a result equal by value
+ * to the last keeps the last one's identity, so the coordinate systems and
+ * guides downstream see nothing new).
+ */
+import type { BandKey, BandScale, Range, RangeTransition, ScaleSpec, TimeZone } from "@sophistry/core/geometry";
+import type { JoinStages, StageWindow } from "../math/join.js";
+import type { AxisExtent, ChartLayerExtent, ChartXAxisOptions, ChartYAxisOptions, LayerTransition } from "./types.js";
+/** One axis's options once `axis` and `xAxis`/`yAxis` are merged. */
+export type MergedAxisOptions = ChartXAxisOptions | ChartYAxisOptions;
+/** A range as given: fixed, or a transition between two. */
+export type GivenRange = Range | RangeTransition | undefined;
+/** How far a stage of the frame's keyed transition has got (0 without one). */
+export type StageAt = (pick: (stages: JoinStages) => StageWindow) => number;
+/** An axis as the plot maps through it: a band scale, or a continuous scale's range. */
+export type ResolvedAxis = {
+    kind: "band";
+    band: BandScale;
+    range: Range;
+} | {
+    kind: "continuous";
+    scale: ScaleSpec;
+    range: Range;
+    base?: number;
+    timeZone?: TimeZone;
+};
+/** Whether an axis's scale is plain linear (the default). */
+export declare function linearScale(scale: ScaleSpec | "band" | undefined): boolean;
+export declare function resolveAxis(options: MergedAxisOptions, fixed: Range | undefined, reports: readonly AxisExtent[], vertical: boolean): ResolvedAxis;
+/** A secondary axis when no layer maps through it (and the stand-in for a band one). */
+export declare const NO_SECONDARY_AXIS: ResolvedAxis;
+/** Both ends of an axis fitted for a keyed transition. */
+export interface AxisEnds {
+    from: ResolvedAxis;
+    to: ResolvedAxis;
+}
+/** How an axis changes over a keyed transition (see `rescaleKind`). */
+export type RescaleChange = "none" | "expand" | "contract" | "shift";
+/** A fitted axis's own transition while a keyed one runs. */
+export type FittedTransition = {
+    kind: "continuous";
+    range: RangeTransition;
+} | {
+    kind: "band";
+    band: BandScale;
+    from: BandScale;
+    to: BandScale;
+} | AxisSwap;
+/**
+ * A fitted axis that changes kind over a keyed transition (band ↔
+ * continuous): the two axes cross-fade over the update stage, the plot
+ * mapping through the near end's axis until its midpoint.
+ */
+export interface AxisSwap {
+    kind: "swap";
+    from: ResolvedAxis;
+    to: ResolvedAxis;
+    u: number;
+}
+export declare function sameAxis(a: ResolvedAxis, b: ResolvedAxis): boolean;
+/**
+ * How long an axis's range is in its own units: bands on a band axis, the
+ * logarithm's span on a log axis, the plain difference otherwise.
+ */
+export declare function axisSpan(axis: ResolvedAxis): number;
+/** {@link sameAxis}, and for a band axis every category in the same place (a blended or slotted band moves them). */
+export declare function samePlacement(a: ResolvedAxis, b: ResolvedAxis): boolean;
+/** Two optional axes placing everything alike. */
+export declare function sameOptionalPlacement(a: ResolvedAxis | undefined, b: ResolvedAxis | undefined): boolean;
+export declare function sameRangeEnds(a: {
+    from: Range;
+    to: Range;
+} | undefined, b: {
+    from: Range;
+    to: Range;
+} | undefined): boolean;
+export declare function sameEnds(a: AxisEnds | undefined, b: AxisEnds | undefined): boolean;
+/** How an axis's fitted range (or category count) changes between the ends. */
+export declare function endsKind(ends: AxisEnds | undefined): RescaleChange;
+/** A fixed range as shown now: itself, or a transition's blend. */
+export declare function shownRange(range: GivenRange, options: MergedAxisOptions): Range | undefined;
+/** Both ends of an axis fitted during a keyed transition; undefined when nothing transitions or the range is given. */
+export declare function fittedEnds(transitioning: boolean, options: MergedAxisOptions, given: GivenRange, list: readonly ChartLayerExtent[], pick: (report: ChartLayerExtent) => AxisExtent | undefined, pickTo: (transition: LayerTransition) => AxisExtent | undefined, vertical: boolean): AxisEnds | undefined;
+/**
+ * The axis the plot maps through now: mid-swap the near end's, on a fitted
+ * transition its blend, else resolved from `extents`. A band axis's `slot`
+ * applies last.
+ */
+export declare function axisNow(options: MergedAxisOptions, given: GivenRange, fit: FittedTransition | undefined, extents: readonly AxisExtent[], vertical: boolean, resolve?: typeof resolveAxis): ResolvedAxis;
+/** A category's strength on a band axis mid-transition: leaving ones fade with the exits, new ones with the enters. */
+export declare function bandWeight(fit: FittedTransition | undefined, stage: StageAt): ((key: BandKey) => number) | undefined;
+/** An axis changing kind through a keyed transition, as its guides draw it. */
+export interface AxisSwapView {
+    /** The opacity of the axis mapped through now. */
+    fade: number;
+    /** The other end, drawn at the rest; undefined outside the update stage. */
+    ghost: ResolvedAxis | undefined;
+}
+/**
+ * An axis changing kind through a keyed transition: `fade` is the opacity of
+ * the axis mapped through now, `ghost` the other end drawn at the rest. Make
+ * one per axis; the ghost keeps its identity while it places alike.
+ */
+export declare function createAxisSwap(): (fit: FittedTransition | undefined) => AxisSwapView;
+/** A secondary axis's range aligned with its primary's ticks, or fitted on its own when no alignment fits. */
+export declare function alignedToPrimary(range: Range, list: readonly AxisExtent[], mine: MergedAxisOptions, primary: MergedAxisOptions): Range;
+/** What one update of an axis's fit reads. Every field keeps its identity while unchanged. */
+export interface AxisFitInput {
+    options: MergedAxisOptions;
+    /** The range given for the axis, if any. */
+    given: GivenRange;
+    /** The reports the axis is fitted to (blends held out). */
+    reports: readonly ChartLayerExtent[];
+    /** Whether a keyed transition runs (steady while its blend moves). */
+    transitioning: boolean;
+    /** A secondary axis's state (see `secondaryFit`). */
+    secondary?: {
+        has: boolean;
+        aligns: boolean;
+        alignedEnds: {
+            from: Range;
+            to: Range;
+        } | undefined;
+    };
+}
+/** One axis as drawn on one update. */
+export interface PlacedAxis {
+    /** The fitted axis's own transition while a keyed one runs. */
+    fitted: FittedTransition | undefined;
+    /** The range as given, or the fitted transition while one runs: what the number line is given. */
+    given: GivenRange;
+    /** The axis the plot maps through now (identity kept while it places alike). */
+    axis: ResolvedAxis;
+    /** Its range (identity kept while equal). */
+    range: Range;
+}
+/** What {@link createAxisFit} fits an axis from. */
+export interface AxisFitDeps {
+    /** A report's extent on this axis. */
+    pick(report: ChartLayerExtent): AxisExtent | undefined;
+    /** A transitioning report's far end's extent on this axis. */
+    pickTo(transition: LayerTransition): AxisExtent | undefined;
+    /** The extents the axis is fitted to at rest; every report's `pick` by default. */
+    extents?: (reports: readonly ChartLayerExtent[]) => AxisExtent[];
+    vertical: boolean;
+    /** A secondary axis: continuous only, ranged by `alignedEnds` with `alignTicks`. */
+    secondary?: boolean;
+}
+/** One axis's fit; see {@link createAxisFit}. */
+export interface AxisFit {
+    /** Both ends during a keyed transition (steady while the blend moves); identity kept while equal. */
+    ends(input: AxisFitInput): AxisEnds | undefined;
+    /** How the axis rescales between the ends. */
+    change(input: AxisFitInput): RescaleChange;
+    /** The axis as drawn now. `primaryGiven` is the primary's given range, for a secondary axis. */
+    place(input: AxisFitInput, stage: StageAt, primaryGiven?: GivenRange): PlacedAxis;
+}
+/**
+ * One axis's fit, in two steps around the frame's transition stages:
+ * `ends` and `change` read only steady inputs and feed the stages;
+ * `place(stage)` gives the axis as drawn each update, compared by placement
+ * so unchanged frames keep every identity. Make one per axis in `setup`.
+ */
+export declare function createAxisFit(deps: AxisFitDeps): AxisFit;

package/dist/frame/format.d.ts

@@ -0,0 +1,40 @@
+/** How a `chart` writes a channel's value in a tooltip (`frame.format`). */
+import type { BandKey, TimeZone } from "@sophistry/core/geometry";
+import type { OrdinalColorScale } from "../math/ordinal.js";
+import type { MergedAxisOptions, ResolvedAxis } from "./fit.js";
+import type { SecondaryFlags } from "./secondary.js";
+import type { ChartColorOptions, ChartFormatChannel, ChartSizeLegendOptions } from "./types.js";
+/** A formatter of one channel's values. */
+export type ValueFormat = (value: number | BandKey) => string;
+/**
+ * How an axis writes a value in a tooltip: a band axis a category's name, a
+ * continuous one through its `tickFormat` at its current range (a full date,
+ * by default, on a time axis).
+ */
+export declare function axisValueFormat(options: MergedAxisOptions, axis: ResolvedAxis): ValueFormat;
+/** A moment written in full on `timeZone`'s clock, to the precision it carries: the day, then the minute or the second. */
+export declare function dateText(value: number, timeZone: TimeZone): string;
+/** An axis whose values a chart formats. */
+export interface FormatAxis {
+    options: MergedAxisOptions;
+    axis: ResolvedAxis;
+}
+/** What a chart's formats read on one update. */
+export interface ChartFormatsInput {
+    x: FormatAxis;
+    y: FormatAxis;
+    x2: FormatAxis;
+    y2: FormatAxis;
+    color: ChartColorOptions | undefined;
+    colorScale: OrdinalColorScale;
+    sizeOptions: ChartSizeLegendOptions;
+}
+/**
+ * The formatters a chart's contexts write values with, by secondary flags.
+ * Make one per chart; each update passes its axes, and a formatter is built
+ * lazily (when a tooltip asks) and kept while its axis keeps its identity.
+ *
+ * @returns `(input) => (flags) => format`: `format(channel)` for the context
+ *   through `flags`.
+ */
+export declare function createChartFormats(): (input: ChartFormatsInput) => (flags: SecondaryFlags) => (channel: ChartFormatChannel) => ValueFormat;

package/dist/frame/guide-metrics.d.ts

@@ -0,0 +1,36 @@
+/** Sizes and gaps for a chart's guides, shared by `chart` and a group's guides so they match. */
+/** An axis title's font size when none is given. */
+export declare const AXIS_LABEL_FONT_SIZE = 0.34;
+/** The gap between an axis's numbers and its title. */
+export declare const AXIS_LABEL_GAP = 0.22;
+/** The title's font size when none is given. */
+export declare const TITLE_FONT_SIZE = 0.42;
+/** The gap under the title. */
+export declare const TITLE_GAP = 0.35;
+/** The gap between the plotting area and a legend beside or above it. */
+export declare const LEGEND_GAP = 0.35;
+/** The gap between the colour legend and the size key under (or beside) it. */
+export declare const KEYS_GAP = 0.25;
+/** The colour bar's thickness. */
+export declare const COLORBAR_THICKNESS = 0.22;
+/**
+ * Half a line of text at `fontSize` (a line is `1.2` of it): from a line's
+ * edge to its middle, as a rotated title stands off the edge it reads along.
+ */
+export declare function halfLine(fontSize: number): number;
+/** A key's laid-out size, and how present it is (0 at a transition end with no legend), scaling the gap before it. */
+export interface KeyExtent {
+    width: number;
+    height: number;
+    presence: number;
+}
+/** A key's size at each end of a keyed transition (`to` only when the ends differ). */
+export interface KeyEnds {
+    from: KeyExtent;
+    to: KeyExtent | undefined;
+}
+/** Two laid-out boxes of the same size (or both none). */
+export declare function sameKeyExtent(a: KeyExtent | undefined, b: KeyExtent | undefined): boolean;
+export declare function sameKeyEnds(a: KeyEnds | undefined, b: KeyEnds | undefined): boolean;
+/** A key's size now: its own end's, or blended between the ends by the update stage's progress `u`. */
+export declare function keyExtentNow(ends: KeyEnds | undefined, u: () => number): KeyExtent | undefined;

package/dist/frame/guides.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What a `chart` draws around its layers: the grid, zero lines, axes
+ * (number lines and band axes, with a kind swap's ghost), titles, the colour
+ * bar, the legend and the size keys.
+ *
+ * {@link createChartGuides} is made once per chart; its function runs in
+ * every chart update, keeps each guide's node by role (writing props into
+ * it rather than rebuilding it) and returns the nodes in paint order.
+ */
+import type { CompositeContext, SceneNode } from "@sophistry/core";
+import type { Range } from "@sophistry/core/geometry";
+import type { Theme } from "@sophistry/core/themes";
+import type { JoinStages, StageWindow } from "../math/join.js";
+import type { ChartCoords } from "./coords.js";
+import type { AxisEnds, AxisSwapView, FittedTransition, GivenRange, MergedAxisOptions, ResolvedAxis } from "./fit.js";
+import type { ChartKeys } from "./keys.js";
+import type { ChartLayout } from "./layout.js";
+import type { ChartLayerExtent, ChartProps } from "./types.js";
+/** One primary axis as the guides draw it. */
+export interface GuideAxis {
+    options: MergedAxisOptions;
+    axis: ResolvedAxis;
+    range: Range;
+    given: GivenRange;
+    fitted: FittedTransition | undefined;
+    ends: AxisEnds | undefined;
+    /** A kind swap's cross-fade (see `createAxisSwap`). */
+    swap: AxisSwapView;
+}
+/** One secondary axis as the guides draw it. */
+export interface GuideSecondaryAxis {
+    has: boolean;
+    options: MergedAxisOptions;
+    given: GivenRange;
+    range: Range;
+}
+/** The frame state the guides draw from on one update. */
+export interface GuideFrame {
+    props: Readonly<ChartProps>;
+    theme: Theme;
+    reports: readonly ChartLayerExtent[];
+    x: GuideAxis;
+    y: GuideAxis;
+    x2: GuideSecondaryAxis;
+    y2: GuideSecondaryAxis;
+    axisZeros: {
+        xSpans: boolean;
+        ySpans: boolean;
+        xFrom: boolean;
+        yFrom: boolean;
+    };
+    axisBands: {
+        x: boolean;
+        y: boolean;
+    };
+    stage(pick: (stages: JoinStages) => StageWindow): number;
+    layout: ChartLayout;
+    keys: ChartKeys;
+    coords: ChartCoords;
+    frameProgress: number;
+    legendProgress: number;
+}
+/**
+ * The frame's guides. Make one per chart in `setup`; call the result in
+ * every update with the chart's context and frame state.
+ */
+export declare function createChartGuides(): (ctx: CompositeContext<ChartProps>, frame: GuideFrame) => SceneNode[];