stream-charts 1.2.1 → 2.0.0

package/dist/app/charts/axes/axes.d.ts

@@ -1,10 +1,11 @@
-import { Dimensions, Margin } from "../styling/margins";
+import type { Dimensions, Margin } from "../styling/margins";
 import { ContinuousAxisRange } from "./ContinuousAxisRange";
-import { Axis, ScaleBand, ScaleContinuousNumeric, ZoomTransform } from "d3";
-import { AxisElementSelection, SvgSelection } from "../d3types";
+import type { AutoScale } from "./autoScale";
+import { type ScaleBand, type ScaleContinuousNumeric } from "d3";
+import type { CanvasContext } from "../d3types";
 import { AxesState } from "./AxesState";
-import { AxesAssignment } from "../plots/plot";
-import { BaseSeries } from "../series/baseSeries";
+import type { AxesAssignment } from "../plots/plot";
+import type { BaseSeries } from "../series/baseSeries";
 import { OrdinalAxisRange } from "./OrdinalAxisRange";
 import { BaseAxisRange } from "./BaseAxisRange";
 import { AxisInterval } from "./AxisInterval";
@@ -18,7 +19,8 @@ export type AxisTickStyle = {
 };
 /**
  * Factory function to create a default AxisTickStyle with the default font,
- * no rotation, and no auto-rotation.
+ * no rotation, and no autorotation.
+ * @return The default axis tick style
  */
 export declare function defaultAxisTickStyle(): AxisTickStyle;
 /**
@@ -33,6 +35,7 @@ export interface AxesFont {
 /**
  * Factory function to create a default AxesFont with the default font size, color,
  * family, and weight.
+ * @return The default axes font
  */
 export declare function defaultAxesFont(): AxesFont;
 /**
@@ -53,19 +56,59 @@ export interface SeriesLineStyle extends SeriesStyle {
 /**
  * Factory function to create a default SeriesLineStyle with the default color, line width,
  * highlight color, and highlight width.
+ * @return The default series line style
  */
 export declare function defaultLineStyle(): SeriesLineStyle;
 /**
- * The base interface that all Axes must implement. Each axis must have a unique ID,
- * a location (top, bottom, left, right), and d3 SVG selection for the axis.
+ * The concrete kind of an axis, set by every axis-creator function to its own unique value.
+ * Lets code that only has a `BaseAxis` (e.g. a plot's `axesFor` validating an `axisAssignments`
+ * entry) discriminate the concrete axis shape at runtime -- `BaseAxis`/`ContinuousNumericAxis`/
+ * `OrdinalStringAxis` are plain structural interfaces, so a type-level cast (`as ContinuousNumericAxis`)
+ * cannot do that; this field is what actually can.
+ * Note: replaces enums to support `erasableSyntaxOnly`
+ *  TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
+ */
+export declare const AxisType: {
+    readonly ContinuousNumeric: "ContinuousNumeric";
+    readonly OrdinalString: "OrdinalString";
+};
+export type AxisType = (typeof AxisType)[keyof typeof AxisType];
+/**
+ * Checks that a plot's axis is of the type the plot needs (e.g. a bar plot needs an ordinal x-axis).
+ * A missing axis passes, since the plots already skip the series whose axes aren't found.
+ * @param plotName The name of the plot's component (e.g. "RasterPlot")
+ * @param dimension Whether the axis is the plot's x-axis or its y-axis
+ * @param axis The axis (`undefined` when it isn't found)
+ * @param expected The axis type the plot needs
+ * @throws Error when the axis isn't of the expected type, naming the axis component it needs to be
+ */
+export declare function checkAxisType(plotName: string, dimension: 'x' | 'y', axis: BaseAxis | undefined, expected: AxisType): void;
+/**
+ * The base interface that all Axes must implement. Each axis must have a unique ID and a location
+ * (top, bottom, left, right). Under the old SVG-backed implementation this also carried a
+ * `selection`; that's gone now that axes draw onto a shared canvas instead of owning their own DOM
+ * elements.
  */
 export interface BaseAxis {
     axisId: string;
     location: AxisLocation;
-    selection: AxisElementSelection;
+    /**
+     * The concrete kind of this axis (see {@link AxisType}). Every axis-creator function sets this
+     * to its own unique value.
+     */
+    axisType: AxisType;
+    /**
+     * True for a placeholder axis added via `addEmptyXAxis`/`addEmptyYAxis` (just a
+     * line, with no real data domain behind it). Consumers that report a value for the mouse
+     * position -- e.g., the tracker's axis labels -- should skip axes marked this way, since their
+     * scale doesn't reflect anything meaningful.
+     */
+    isEmpty?: boolean;
 }
 /**
- * Represents a continuous numeric axis.
+ * Represents a continuous numeric axis. Draws itself by registering a draw function with the
+ * chart's {@link CanvasContext} (see `addContinuousNumericXAxis` and
+ * `addContinuousNumericYAxis`, below) rather than owning an SVG element.
  */
 export interface ContinuousNumericAxis extends BaseAxis {
     /**
@@ -73,200 +116,270 @@ export interface ContinuousNumericAxis extends BaseAxis {
      */
     scale: ScaleContinuousNumeric<number, number>;
     /**
-     * A d3 axis generator for a continuous numeric axis.
+     * When set, the axis' domain grows to fit the data plotted against it, within the settings'
+     * limits (see `ContinuousAxis`'s `autoScale` prop). Set by the axis component, and applied by
+     * the plots that support it (for y-axes).
      */
-    generator: Axis<number | {
-        valueOf(): number;
-    }>;
+    autoScale?: AutoScale;
     /**
-     * Updates the axis based on the specified domain and plot dimensions.
+     * Updates the axis based on the specified domain and plot dimensions and requests the plot
+     * to be redrawn.
      * @param domain The interval representing the domain of the axis.
      * @param plotDimensions The dimensions of the plot (without the margins).
      * @param margin The margins for the plot
      */
     update: (domain: AxisInterval, plotDimensions: Dimensions, margin: Margin) => void;
+    /**
+     * Updates the font (color, size, family, weight) used for ticks and the axis label, without
+     * recreating the axis or touching its domain. Used to keep the label color in sync with the
+     * chart's `color` prop (e.g., on a theme change) between full axis updates.
+     */
+    updateFont: (font: AxesFont) => void;
+    /**
+     * Highlights (or un-highlights) this axis -- used, for example, to indicate which axis a
+     * currently-hovered series is plotted against. When `highlighted` is true, the axis' domain
+     * line, ticks, and labels are drawn in `color` at `lineWidth` instead of the normal font color
+     * and 1px line; `color`/`lineWidth` are remembered across calls, so a later `setHighlighted(true)`
+     * without them reuses whatever was last passed (or the built-in default on the first call).
+     * @param highlighted Whether the axis should be drawn highlighted
+     * @param color The highlight color
+     * @param lineWidth The highlight line width
+     */
+    setHighlighted: (highlighted: boolean, color?: string, lineWidth?: number) => void;
 }
 /**
- * Represents an ordinal string axis.
+ * Represents an ordinal string axis. Draws itself by registering a draw function with the chart's
+ * {@link CanvasContext} rather than owning an SVG element.
  */
 export interface OrdinalStringAxis extends BaseAxis {
     /**
      * A d3 scale for an ordinal string axis.
      */
     scale: ScaleBand<string>;
-    /**
-     * A d3 axis generator for an ordinal string axis.
-     */
-    generator: Axis<string>;
     /**
      * The size of each category on the axis.
      */
     categorySize: number;
     /**
-     * Updates the axis based on the specified domain and plot dimensions.
+     * Updates the axis based on the specified categories, range, and plot dimensions, and requests
+     * the plot to be redrawn.
+     * @param categories The category names for the axis, in order -- replaces the scale's domain,
+     * so passing a different set of categories (e.g. because the number of series changed) is how
+     * an axis reflects a new category count. Pass `axis.scale.domain()` to leave the categories
+     * unchanged (e.g. from a pan/zoom call site that isn't varying the category set).
      * @param range An interval representing the range of the axis.
      * @param originalRange An interval representing the original range of the axis (before zooming or panning).
      * @param plotDimensions The dimensions of the plot (without the margins).
      * @param margin The margins for the plot
      * @return The number of pixels for each category on the axis.
      */
-    update: (range: AxisInterval, originalRange: AxisInterval, plotDimensions: Dimensions, margin: Margin) => number;
-}
-/**
- * Enumerates the possible locations of an axis.
- */
-export declare enum AxisLocation {
-    Left = 0,
-    Right = 1,
-    Bottom = 2,
-    Top = 3
+    update: (categories: Array<string>, range: AxisInterval, originalRange: AxisInterval, plotDimensions: Dimensions, margin: Margin) => number;
+    /**
+     * Updates the font used for the axis label without recreating the axis. The font's color is
+     * also the color of the axis line, the ticks, and the tick labels; the tick labels' size,
+     * family, and weight, though, stay fixed at whatever the tick style's font was set to when
+     * the axis was created.
+     */
+    updateFont: (font: AxesFont) => void;
+    /**
+     * Highlights (or un-highlights) this axis -- see {@link ContinuousNumericAxis.setHighlighted}
+     * for the full explanation. `color`/`lineWidth` are remembered across calls, so a later
+     * `setHighlighted(true)` without them reuses whatever was last passed (or the built-in
+     * default on the first call).
+     * @param highlighted Whether the axis should be drawn highlighted
+     * @param color The highlight color
+     * @param lineWidth The highlight line width
+     */
+    setHighlighted: (highlighted: boolean, color?: string, lineWidth?: number) => void;
 }
 /**
- * Adds a clip area for the chart to the specified SVG element. The clip-area is given
- * an `id` of `clip-series-<chart_id>`, which because the chart ID should be unique, makes
- * this unique as well
- * @param chartId The ID of the chart to which the clip area is to be added
- * @param axisId The ID of the axis to which the clip area is to be added
- * @param svg The SVG element to which the clip area is to be added
- * @param location The location of the axis
- * @param plotDimensions The dimensions of the plot
- * @param margin The margins around the plot
- * @return The ID of the clip-path
+ * The possible locations of an axis.
+ * Note: replaces enums to support `erasableSyntaxOnly`
+ *  TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
  */
-export declare function setClipPath(chartId: number, axisId: string, svg: SvgSelection, location: AxisLocation, plotDimensions: Dimensions, margin: Margin): string;
+export declare const AxisLocation: {
+    readonly Left: "Left";
+    readonly Right: "Right";
+    readonly Bottom: "Bottom";
+    readonly Top: "Top";
+};
+export type AxisLocation = (typeof AxisLocation)[keyof typeof AxisLocation];
 /**
- * Adds a category axis to the specified location. When the location is top or bottom,
- * the category axis represents the x-axis. When the location is left or right, then the
- * category axis represents the y-axis.
- * @param chartId The unique ID of the chart to which this axis belongs
+ * Adds a category axis to the specified location, registering its draw function with the canvas
+ * context. When the location is top or bottom, the category axis represents the x-axis; when the
+ * location is left or right, it represents the y-axis.
+ * @param cc The canvas context to register the axis' draw function with
  * @param axisId A unique ID for the axis
- * @param svg The SVG selection (d3)
  * @param location The location of the axis
- * @param categories An array holding the category names
+ * @param categories The category names (the axis' `update` function can replace them later)
  * @param axisLabel The axis label
  * @param axesLabelFont The font for the axis label
- * @param axisTickStyle Styling information for the ticks (e.g. font, rotation, etc)
+ * @param axisTickStyle Styling information for the ticks (font, rotation, etc.)
  * @param plotDimensions The dimensions of the plot
  * @param margin The plot margin
- * @param setAxisRangeFor Lambda that sets the axis range for the specified axis
- * @param setOriginalAxisRangeFor Lambda that sets the original axis range for the specified axis
- * @return A category axis
+ * @param setAxisRangeFor Callback that sets the axis range for the specified axis
+ * @param setOriginalAxisRangeFor Callback that sets the original axis range for the specified axis
+ * @return An {@link OrdinalStringAxis}
  */
-export declare function addOrdinalStringAxis(chartId: number, axisId: string, svg: SvgSelection, location: AxisLocation, categories: Array<string>, axisLabel: string, axesLabelFont: AxesFont, axisTickStyle: AxisTickStyle, plotDimensions: Dimensions, margin: Margin, setAxisRangeFor: (axisId: string, range: AxisInterval) => void, setOriginalAxisRangeFor: (axisId: string, range: AxisInterval) => void): OrdinalStringAxis;
+export declare function addOrdinalStringAxis(cc: CanvasContext, axisId: string, location: AxisLocation, categories: Array<string>, axisLabel: string, axesLabelFont: AxesFont, axisTickStyle: AxisTickStyle, plotDimensions: Dimensions, margin: Margin, setAxisRangeFor: (axisId: string, range: AxisInterval) => void, setOriginalAxisRangeFor: (axisId: string, range: AxisInterval) => void): OrdinalStringAxis;
 /**
- * Adds a new empty x-axis to the SVG element at the specified location. An empty axis
- * is just a line where the axis would be, without any ticks or labels.
+ * Removes a category x-axis' draw function from the canvas context (e.g. when the axis unmounts)
+ * @param cc The canvas context the axis' draw function is registered with
+ * @param axisId The ID of the axis
+ */
+export declare function removeOrdinalXAxis(cc: CanvasContext, axisId: string): void;
+/**
+ * Removes a category y-axis' draw function from the canvas context (e.g. when the axis unmounts)
+ * @param cc The canvas context the axis' draw function is registered with
  * @param axisId The ID of the axis
- * @param svg The SVG selection to which to add the axis
- * @param plotDimensions The dimensions of the plot
- * @param location The location of the axis
- * @param scaleGenerator The higher-order function that returns the axis d3 "scale" function
- * @param domain The axis range (start, end)
- * @param margin The plot margins for the border of main SVG group
- * @param setAxisRangeFor A callback used to set the axis range
- * @return A {@link ContinuousNumericAxis} based on the arguments to this function
  */
-export declare function addEmptyXAxis(axisId: string, svg: SvgSelection, plotDimensions: Dimensions, location: AxisLocation.Bottom | AxisLocation.Top, scaleGenerator: ScaleContinuousNumeric<number, number>, margin: Margin, setAxisRangeFor: (axisId: string, timeRange: AxisInterval) => void, domain?: [minValue: number, maxValue: number]): ContinuousNumericAxis;
+export declare function removeOrdinalYAxis(cc: CanvasContext, axisId: string): void;
 /**
- * Adds a new empty y-axis to the SVG element at the specified location. An empty axis
+ * Adds a new, empty x-axis (a line with no ticks or label) to the canvas context. An empty axis
  * is just a line where the axis would be, without any ticks or labels.
+ * @param canvasContext The canvas context to register the axis' draw function with
  * @param axisId The ID of the axis
- * @param svg The SVG selection to which to add the axis
  * @param plotDimensions The dimensions of the plot
  * @param location The location of the axis
- * @param scaleGenerator The higher-order function that returns the axis d3 "scale" function
- * @param domain The axis range (start, end)
- * @param margin The plot margins for the border of main SVG group
- * @param setAxisRangeFor A callback used to set the axis range
- * @return A {@link ContinuousNumericAxis} based on the arguments to this function
+ * @param scaleGenerator The d3 scale to use for the axis (its domain and range get overwritten)
+ * @param margin The plot margins
+ * @param setAxisRangeFor A callback used to report the axis' domain when it's updated
+ * @param color The color of the axis line (the axis' `updateFont` updates it with the font's color)
+ * @param [domain=[0, 1]] The axis' initial domain (min, max)
+ * @return A {@link ContinuousNumericAxis} (marked `isEmpty`) based on the arguments to this function
  */
-export declare function addEmptyYAxis(axisId: string, svg: SvgSelection, plotDimensions: Dimensions, location: AxisLocation.Left | AxisLocation.Right, scaleGenerator: ScaleContinuousNumeric<number, number>, margin: Margin, setAxisRangeFor: (axisId: string, timeRange: AxisInterval) => void, domain?: [minValue: number, maxValue: number]): ContinuousNumericAxis;
+export declare function addEmptyXAxis(canvasContext: CanvasContext, axisId: string, plotDimensions: Dimensions, location: typeof AxisLocation.Bottom | typeof AxisLocation.Top, scaleGenerator: ScaleContinuousNumeric<number, number>, margin: Margin, setAxisRangeFor: (axisId: string, timeRange: AxisInterval) => void, color: string, domain?: [minValue: number, maxValue: number]): ContinuousNumericAxis;
 /**
- * Adds a new x-axis to the SVG element at the specified location
- * @param chartId The ID of the chart
+ * Adds a new, empty y-axis (a line with no ticks or label) to the canvas context.
+ * @param cc The canvas context to register the axis' draw function with
  * @param axisId The ID of the axis
- * @param svg The SVG selection to which to add the axis
  * @param plotDimensions The dimensions of the plot
  * @param location The location of the axis
- * @param scaleGenerator The higher-order function that returns the axis d3 "scale" function
- * @param domain The axis range (start, end)
- * @param axesLabelFont The font for the axis labels
- * @param margin The plot margins for the border of main SVG group
+ * @param scaleGenerator The d3 scale to use for the axis (its domain and range get overwritten)
+ * @param margin The plot margins
+ * @param setAxisRangeFor A callback used to report the axis' domain when it's updated
+ * @param color The color of the axis line (the axis' `updateFont` updates it with the font's color)
+ * @param [domain=[0, 1]] The axis' initial domain (min, max)
+ * @return A {@link ContinuousNumericAxis} (marked `isEmpty`) based on the arguments to this function
+ */
+export declare function addEmptyYAxis(cc: CanvasContext, axisId: string, plotDimensions: Dimensions, location: typeof AxisLocation.Left | typeof AxisLocation.Right, scaleGenerator: ScaleContinuousNumeric<number, number>, margin: Margin, setAxisRangeFor: (axisId: string, timeRange: AxisInterval) => void, color: string, domain?: [minValue: number, maxValue: number]): ContinuousNumericAxis;
+/**
+ * Adds a new x-axis, registering its draw function with the canvas context.
+ * @param cc The canvas context to register the axis' draw function with
+ * @param axisId A unique ID for the axis
+ * @param plotDimensions The dimensions of the plot
+ * @param location The location of the axis (top or bottom)
+ * @param scaleGenerator The d3 scale to use for the axis (its domain/range get overwritten)
+ * @param domain The axis' initial domain (min, max)
+ * @param axesLabelFont The font for the axis label and ticks
+ * @param margin The plot margins
  * @param axisLabel The label for the axis
- * @param setAxisRangeFor A callback used to set the axis range
- * @return A {@link ContinuousNumericAxis} based on the arguments to this function
+ * @param setAxisRangeFor Callback used to report the axis' domain when it's updated
+ * @return A {@link ContinuousNumericAxis}
  */
-export declare function addContinuousNumericXAxis(chartId: number, axisId: string, svg: SvgSelection, plotDimensions: Dimensions, location: AxisLocation.Bottom | AxisLocation.Top, scaleGenerator: ScaleContinuousNumeric<number, number>, domain: [minValue: number, maxValue: number], axesLabelFont: AxesFont, margin: Margin, axisLabel: string, setAxisRangeFor: (axisId: string, timeRange: AxisInterval) => void): ContinuousNumericAxis;
+export declare function addContinuousNumericXAxis(cc: CanvasContext, axisId: string, plotDimensions: Dimensions, location: typeof AxisLocation.Bottom | typeof AxisLocation.Top, scaleGenerator: ScaleContinuousNumeric<number, number>, domain: [minValue: number, maxValue: number], axesLabelFont: AxesFont, margin: Margin, axisLabel: string, setAxisRangeFor: (axisId: string, timeRange: AxisInterval) => void): ContinuousNumericAxis;
 /**
- * Adds a new y-axis to the SVG element at the specified location
- * @param chartId The ID of the chart
- * @param axisId The ID of the axis
- * @param svg The SVG selection to which to add the axis
+ * Adds a new y-axis, registering its draw function with the canvas context.
+ * @param cc The canvas context to register the axis' draw function with
+ * @param axisId A unique ID for the axis
  * @param plotDimensions The dimensions of the plot
- * @param location The location of the axis
- * @param scaleGenerator The higher-order function that returns the axis d3 "scale" function
- * @param domain The axis range (start, end)
- * @param axesLabelFont The font for the axis labels
- * @param margin The plot margins for the border of main SVG group
+ * @param location The location of the axis (left or right)
+ * @param scaleGenerator The d3 scale to use for the axis (its domain/range get overwritten)
+ * @param domain The axis' initial domain (min, max)
+ * @param axesLabelFont The font for the axis label and ticks
+ * @param margin The plot margins
  * @param axisLabel The label for the axis
- * @param setAxisRangeFor A callback used to set the axis range
- * @return A {@link ContinuousNumericAxis} based on the arguments to this function
+ * @param setAxisRangeFor Callback used to report the axis' domain when it's updated
+ * @return A {@link ContinuousNumericAxis}
  */
-export declare function addContinuousNumericYAxis(chartId: number, axisId: string, svg: SvgSelection, plotDimensions: Dimensions, location: AxisLocation.Left | AxisLocation.Right, scaleGenerator: ScaleContinuousNumeric<number, number>, domain: [minValue: number, maxValue: number], axesLabelFont: AxesFont, margin: Margin, axisLabel: string, setAxisRangeFor: (axisId: string, range: AxisInterval) => void): ContinuousNumericAxis;
+export declare function addContinuousNumericYAxis(cc: CanvasContext, axisId: string, plotDimensions: Dimensions, location: typeof AxisLocation.Left | typeof AxisLocation.Right, scaleGenerator: ScaleContinuousNumeric<number, number>, domain: [minValue: number, maxValue: number], axesLabelFont: AxesFont, margin: Margin, axisLabel: string, setAxisRangeFor: (axisId: string, range: AxisInterval) => void): ContinuousNumericAxis;
 /**
- * Calculates a unique ID for the axis based on the location and chart ID
- * @param chartId The unique ID of the chart
- * @param location The axis location (i.e. top, bottom, left, right)
- * @return A unique ID for the axis
+ * Removes a continuous x-axis' draw function from the canvas context (called on "unmount" to avoid
+ * leaking a draw registration for an axis that's no longer part of the chart).
+ * @param cc The canvas context the axis' draw function is registered with
+ * @param axisId The ID of the axis
  */
-export declare function labelIdFor(chartId: number, location: AxisLocation): string;
+export declare function removeContinuousXAxis(cc: CanvasContext, axisId: string): void;
+/**
+ * Removes a continuous y-axis' draw function from the canvas context (called on "unmount" to avoid
+ * leaking a draw registration for an axis that's no longer part of the chart).
+ * @param cc The canvas context the axis' draw function is registered with
+ * @param axisId The ID of the axis
+ */
+export declare function removeContinuousYAxis(cc: CanvasContext, axisId: string): void;
 /**
  * The result of a zoom action
  */
 export interface ZoomResult<AR extends BaseAxisRange> {
     range: AR;
-    zoomFactor: number;
 }
 /**
  * Called when the user uses the scroll wheel (or scroll gesture) to zoom in or out. Zooms in/out
- * at the location of the mouse when the scroll wheel or gesture was applied, while ensure that
- * the range (start, end) is contained within the constraint (min, max).
- * @param transform The d3 zoom transformation information
- * @param x The x-position of the mouse when the scroll wheel or gesture is used
- * @param axis The axis being zoomed
+ * around the specified domain value (the pivot), while ensuring that the range (start, end) is
+ * contained within the constraint (min, max). The pivot is a domain value rather than a pixel
+ * position -- while streaming, callers pin it to the axis's current "now" rather than to wherever
+ * the mouse happens to be (see `calcZoomAndUpdate`'s `pivotDomainValueFor`), which is what keeps
+ * "now" fixed on screen as the zoom widens/narrows the window around it.
+ *
+ * `zoomFactor` is *incremental* (relative to the range's `.current`, not its `.original`) -- see
+ * {@link BaseAxisRange.scaledRange}. d3-zoom's own `transform.k` is cumulative from wherever
+ * `__zoom` was last reset to identity, so callers must convert it to an incremental factor (this
+ * event's `k` divided by the previously-applied `k`) before calling this -- see
+ * `useCanvasZoomPan`.
+ * @param zoomFactor The incremental zoom scale factor for this event
+ * @param domainValue The domain value to zoom around (the pivot)
  * @param range The current range for the axis being zoomed
  * @param constraint The minimum and maximum value the scaled range can have
- * @return The updated range and the new zoom factor
+ * @return The updated range
  */
-export declare function calculateConstrainedZoomFor(transform: ZoomTransform, x: number, axis: ContinuousNumericAxis, range: ContinuousAxisRange, constraint: [min: number, max: number]): ZoomResult<ContinuousAxisRange>;
+export declare function calculateConstrainedZoomFor(zoomFactor: number, domainValue: number, range: ContinuousAxisRange, constraint: [min: number, max: number]): ZoomResult<ContinuousAxisRange>;
 /**
- * Calculates the zoom for an ordinal axis.
- * @param transform The d3 zoom transformation information
+ * Calculates the zoom for an ordinal axis. Unlike {@link calculateConstrainedZoomFor}'s continuous
+ * axis, `zoomFactor` here is *cumulative* (d3-zoom's own `event.transform.k`, passed through
+ * unmodified) -- see {@link OrdinalAxisRange.scaledCumulative} for why: the range is scaled from
+ * `.current` by the incremental step the cumulative factor implies, except that a factor of
+ * exactly 1 snaps it back to `.original`, so that zooming all the way out always shows every
+ * category, whatever pivots were used along the way.
+ * @param zoomFactor The cumulative zoom scale factor for this event
  * @param x The x-position of the mouse when the scroll wheel or gesture is used
  * @param range The current range for the axis being zoomed
  * @param constraint The minimum and maximum value the scaled range can have
- * @return A ZoomResult holding the updated range and the new zoom factor
+ * @return A ZoomResult holding the updated range
  */
-export declare function calculateOrdinalConstrainedZoomFor(transform: ZoomTransform, x: number, range: OrdinalAxisRange, constraint: [min: number, max: number]): ZoomResult<OrdinalAxisRange>;
+export declare function calculateOrdinalConstrainedZoomFor(zoomFactor: number, x: number, range: OrdinalAxisRange, constraint: [min: number, max: number]): ZoomResult<OrdinalAxisRange>;
 /**
- * Adjusts the range and updates the plot when the plot is dragged to the left or right
- * @param delta The amount that the plot is dragged
- * @param axis The axis being zoomed
- * @param range The current range for the axis being zoomed
+ * Calculates the axis range after the plot is dragged to the left or right (x-axis) or up or down
+ * (y-axis).
+ * @param delta The amount (in pixels) that the plot is dragged
+ * @param axis The axis being panned
+ * @param range The current range for the axis being panned
  * @param [constrainToOriginalRange=false] When set to `true` then the pan requires that the axis
- * range remains a subset of the origin axis range; when `false` the pan allows and range
+ * range remains a subset of the original axis range (a pan that would leave it isn't made); when
+ * `false` the pan allows any range
  * @return The updated range
  */
 export declare function calculatePanFor(delta: number, axis: ContinuousNumericAxis, range: ContinuousAxisRange, constrainToOriginalRange?: boolean): ContinuousAxisRange;
-export declare function calculateOrdinalPanFor(delta: number, range: OrdinalAxisRange, plotDimensions: Dimensions, constrainToOriginalRange?: boolean): OrdinalAxisRange;
+/**
+ * Calculates the ordinal axis range after the plot is dragged to the left or right (x-axis) or up
+ * or down (y-axis). A pan that would leave part of the plot without categories (i.e. take the
+ * range's start past 0, or its end short of the plot's width or height) isn't made.
+ * @param delta The amount (in pixels) to pan the axis by.
+ * @param range The current axis range.
+ * @param plotDimensions The dimensions of the plot.
+ * @param location The location of the axis.
+ * @param constrainToOriginalRange Whether to constrain the pan to the original range.
+ * @returns The new axis range.
+ */
+export declare function calculateOrdinalPanFor(delta: number, range: OrdinalAxisRange, plotDimensions: Dimensions, location: AxisLocation, constrainToOriginalRange?: boolean): OrdinalAxisRange;
 /**
  * Accepts the series, the assignment of the series to axes, and the current x-axes state, and
- * returns an array of the distinct axis IDs that cover all the series in the plot.
+ * returns an array of the distinct x-axis IDs that cover all the series in the plot (a series
+ * without an x-axis assignment uses the default x-axis).
  *
  * @param series The array of series
  * @param axisAssignments A map association a series name with its axis assignments
- * @param axesState The current axis state
- * @return an array of the distinct axes that cover all the series in the plot
+ * @param axesState The current x-axes state
+ * @return an array of the distinct x-axis IDs that cover all the series in the plot
  */
 export declare function axesForSeriesGen<D, A extends BaseAxis>(series: Array<BaseSeries<D>>, axisAssignments: Map<string, AxesAssignment>, axesState: AxesState<A>): Array<string>;
 /**
@@ -276,7 +389,7 @@ export declare function axesForSeriesGen<D, A extends BaseAxis>(series: Array<Ba
  * to the left or right. After calling the handler function, the plot needs to be updated as well, and this is
  * left for the caller.
  *
- * Please note that the function generated by this function has side effects -- it updates the axes ranges.
+ * Please note that the function generated by this function has side effects -- it updates the axis ranges.
  *
  * @param axesForSeries The distinct axes that cover all the series
  * @param margin The plot margin
@@ -294,7 +407,7 @@ export declare function panHandler(axesForSeries: Array<string>, margin: Margin,
  * to the left or right. After calling the handler function, the plot needs to be updated as well, and this is
  * left for the caller.
  *
- * Please note that the function generated by this function has side effects -- it updates the axes ranges.
+ * Please note that the function generated by this function has side effects -- it updates the axes' ranges.
  *
  * @param axesForSeries The distinct axes that cover all the series
  * @param margin The plot margin
@@ -312,7 +425,7 @@ export declare function ordinalPanHandler(axesForSeries: Array<string>, margin:
  * to the left or right. After calling the handler function, the plot needs to be updated as well, and this is
  * left for the caller.
  *
- * Please note that the function generated by this function has side effects -- it updates the axes ranges.
+ * Please note that the function generated by this function has side effects -- it updates the axes' ranges.
  *
  * @param xAxesForSeries The distinct x-axes that cover all the series
  * @param yAxesForSeries The distinct y-axes that cover all the series
@@ -331,40 +444,40 @@ export declare function panHandler2D(xAxesForSeries: Array<string>, yAxesForSeri
  * function returns a handler function. And this handler function adjusts the range when the plot is zoomed.
  * After calling the handler function, the plot needs to be updated as well, and this is left for the caller.
  *
- * Please note that the function generated by this function has side effects -- it updates the axes ranges.
+ * Please note that the function generated by this function has side effects -- it updates the axes' ranges.
  *
  * @param axesForSeries The distinct axes that cover all the series
  * @param margin The plot margin
  * @param setRangeFor Function for setting the new time-range for a specific axis
  * @param axesState The current state of the x- or y-axes
- * @param scaleExtent The minimum and maximum allowed scale factors
- * @return A handler function for pan events
+ * @param [scaleExtent=[0, Infinity]] The minimum and maximum allowed scale factors
+ * @return A handler function for zoom events
  */
-export declare function continuousAxisZoomHandler(axesForSeries: Array<string>, margin: Margin, setRangeFor: (axisId: string, range: AxisInterval) => void, axesState: AxesState<ContinuousNumericAxis>, scaleExtent?: [min: number, max: number]): (transform: ZoomTransform, x: number, plotDimensions: Dimensions, ranges: Map<string, ContinuousAxisRange>) => void;
+export declare function continuousAxisZoomHandler(axesForSeries: Array<string>, margin: Margin, setRangeFor: (axisId: string, range: AxisInterval) => void, axesState: AxesState<ContinuousNumericAxis>, scaleExtent?: [min: number, max: number]): (zoomFactor: number, pivotDomainValueFor: (axisId: string, axis: ContinuousNumericAxis) => number, plotDimensions: Dimensions, ranges: Map<string, ContinuousAxisRange>) => void;
 /**
  * Higher-order function that generates a handler for zoom events, given the distinct series IDs that cover all
  * the axes in the chart, the margin, range update function, and the current state of the x- or y-axes. This
  * function returns a handler function. And this handler function adjusts the range when the plot is zoomed.
  * After calling the handler function, the plot needs to be updated as well, and this is left for the caller.
  *
- * Please note that the function generated by this function has side effects -- it updates the axes ranges.
+ * Please note that the function generated by this function has side effects -- it updates the axes' ranges.
  *
  * @param axesForSeries The distinct axes that cover all the series
  * @param margin The plot margin
  * @param setRangeFor Function for setting the new time-range for a specific axis
  * @param setOriginalRangeFor Function for setting the new original range for a specific axis
  * @param axesState The current state of the x- or y-axes
- * @param scaleExtent The minimum and maximum allowed scale factors
- * @return A handler function for pan events
+ * @param [scaleExtent=[0, Infinity]] The minimum and maximum allowed scale factors
+ * @return A handler function for zoom events
  */
-export declare function ordinalAxisZoomHandler(axesForSeries: Array<string>, margin: Margin, setRangeFor: (axisId: string, range: AxisInterval) => void, setOriginalRangeFor: (axisId: string, range: AxisInterval) => void, axesState: AxesState<OrdinalStringAxis>, scaleExtent?: [min: number, max: number]): (transform: ZoomTransform, x: number, plotDimensions: Dimensions, ranges: Map<string, OrdinalAxisRange>) => void;
+export declare function ordinalAxisZoomHandler(axesForSeries: Array<string>, margin: Margin, setRangeFor: (axisId: string, range: AxisInterval) => void, setOriginalRangeFor: (axisId: string, range: AxisInterval) => void, axesState: AxesState<OrdinalStringAxis>, scaleExtent?: [min: number, max: number]): (zoomFactor: number, x: number, plotDimensions: Dimensions, ranges: Map<string, OrdinalAxisRange>) => void;
 /**
  * Higher-order function that generates a handler for zoom events, given the distinct series IDs that cover all
  * the axes in the chart, the margin, range update function, and the current state of the x- or y-axes. This
  * function returns a handler function. And this handler function adjusts the time-range when the plot is zoomed.
  * After calling the handler function, the plot needs to be updated as well, and this is left for the caller.
  *
- * Please note that the function generated by this function has side effects -- it updates the axes ranges.
+ * Please note that the function generated by this function has side effects -- it updates the axes' ranges.
  *
  * @param xAxesForSeries The distinct x-axes that cover all the series
  * @param yAxesForSeries The distinct y-axes that cover all the series
@@ -373,47 +486,57 @@ export declare function ordinalAxisZoomHandler(axesForSeries: Array<string>, mar
  * @param xAxesState The current state of the x-axes
  * @param yAxesState The current state of the y-axes
  * @param scaleExtent The smallest and largest scale factors allowed
- * @return A handler function for pan events
+ * @return A handler function for zoom events
  */
-export declare function axesZoomHandler(xAxesForSeries: Array<string>, yAxesForSeries: Array<string>, margin: Margin, setRangeFor: (axisId: string, range: AxisInterval) => void, xAxesState: AxesState<ContinuousNumericAxis>, yAxesState: AxesState<ContinuousNumericAxis>, scaleExtent: [min: number, max: number]): (transform: ZoomTransform, mousePosition: [x: number, y: number], plotDimensions: Dimensions, xRanges: Map<string, ContinuousAxisRange>, yRanges: Map<string, ContinuousAxisRange>) => void;
+export declare function axesZoomHandler(xAxesForSeries: Array<string>, yAxesForSeries: Array<string>, margin: Margin, setRangeFor: (axisId: string, range: AxisInterval) => void, xAxesState: AxesState<ContinuousNumericAxis>, yAxesState: AxesState<ContinuousNumericAxis>, scaleExtent: [min: number, max: number]): (zoomFactor: number, mousePosition: [x: number, y: number], plotDimensions: Dimensions, xRanges: Map<string, ContinuousAxisRange>, yRanges: Map<string, ContinuousAxisRange>) => void;
 /**
- * Calculates the axis-ranges for each of the continuous numeric axes in the map
+ * Calculates the axis-ranges for each of the continuous numeric axes in the map, from each axis'
+ * current domain (see {@link continuousRange})
  * @param axes The map containing the axes and their associated IDs
- * @return a map associating the axis IDs to their continuous axis-range
+ * @return a map associating the axis IDs with their continuous axis-range
  */
 export declare function continuousAxisRanges(axes: Map<string, ContinuousNumericAxis>): Map<string, ContinuousAxisRange>;
 /**
- * Calculates the axis-ranges for each of the ordinal axes in the map
+ * Calculates the axis-ranges for each of the ordinal axes in the map, read from each axis's own
+ * scale range.
  * @param axes The map containing the axes and their associated IDs
- * @param originalRange The original range of the axis
- * @return a map associating the axis IDs to their ordinal axis-range
+ * @return a map associating the axis IDs with their ordinal axis-range
  */
-export declare function ordinalAxisRanges(axes: Map<string, OrdinalStringAxis>, originalRange: AxisInterval): Map<string, OrdinalAxisRange>;
+export declare function ordinalAxisRanges(axes: Map<string, OrdinalStringAxis>): Map<string, OrdinalAxisRange>;
 /**
- * Calculates the axis interval (start, end) for each of the axis
- * @param axes The axes representing the time
- * @return A map associating each axis with a (start, end) interval
+ * Calculates the axis interval (start, end) of each axis' current domain
+ * @param axes The axes, by their IDs
+ * @return A map associating each axis ID with its domain's (start, end) interval
  */
 export declare function continuousAxisIntervals(axes: Map<string, ContinuousNumericAxis>): Map<string, AxisInterval>;
 /**
- * Calculates the axis interval (start, end) for each of the axis
- * @param axes The axes representing the time
- * @return A map associating each axis with a (start, end) interval
+ * Calculates the pixel interval (start, end) of each ordinal axis' current range, along with its
+ * categories
+ * @param axes The axes, by their IDs
+ * @return A map associating each axis ID with its range's (start, end) interval and its categories
  */
 export declare function ordinalAxisIntervals(axes: Map<string, OrdinalStringAxis>): Map<string, {
     interval: AxisInterval;
     categories: Array<string>;
 }>;
 /**
- * Returns the bounds on the specified continuous numeric axes
+ * Returns the bounds on the specified continuous numeric axes: a new axis range (with its original
+ * range the same as its current range) from each axis' current domain
  * @param axes A map associating an axis ID with a {@link ContinuousNumericAxis}
  * @return A map associating each specified axis ID with the interval covered (bounds) by the axis
  */
 export declare function continuousRange(axes: Map<string, ContinuousNumericAxis>): Map<string, ContinuousAxisRange>;
 /**
- * Returns the bounds on the specified continuous numeric axes
+ * Returns the bounds on the specified ordinal axes, read from each axis's own scale range.
+ *
+ * Previously mapped every axis ID to one shared, caller-supplied `originalRange`, discarding the
+ * axis object entirely (`[id, ]`) -- harmless today only because there's no per-axis margin/offset
+ * mechanism anywhere in this codebase, so every ordinal axis in a chart is architecturally
+ * guaranteed to span the same pixel range already. Reading each axis's own `.scale.range()`
+ * instead (mirroring {@link ordinalAxisIntervals}, which already does this correctly) removes that
+ * latent footgun for a chart with multiple category axes whose ranges genuinely differ.
  * @param axes A map associating an axis ID with a {@link OrdinalStringAxis}
- * @param originalRange The original range of the axis
  * @return A map associating each specified axis ID with the interval covered (bounds) by the axis
  */
-export declare function ordinalRange(axes: Map<string, OrdinalStringAxis>, originalRange: AxisInterval): Map<string, OrdinalAxisRange>;
+export declare function ordinalRange(axes: Map<string, OrdinalStringAxis>): Map<string, OrdinalAxisRange>;
+//# sourceMappingURL=axes.d.ts.map