stream-charts 1.2.1 → 2.0.0

package/src/app/charts/hooks/useAxes.tsx

@@ -1,23 +1,16 @@
 import {AxesState} from "../axes/AxesState";
-import {BaseAxis} from "../axes/axes";
-import {AxesAssignment} from "../plots/plot";
-import {createContext, JSX, useContext, useRef} from "react";
-import {Dimensions} from "../styling/margins";
-import {usePlotDimensions} from "./usePlotDimensions";
+import type {BaseAxis} from "../axes/axes";
+import type {AxesAssignment} from "../plots/plot";
+import {createContext, useContext} from "react";
+import type {Dimensions} from "../styling/margins";
 import {BaseAxisRange} from "../axes/BaseAxisRange";
 import {AxisInterval} from "../axes/AxisInterval";
 import {Optional} from "result-fn";
 
-/**
- * No operation function for use when a default function is needed
- */
-const noop = () => {
-    /* empty on purpose */
-}
-
 /**
  * The values exposed by the hook
  * @template AR The type of the axis range (e.g. {@link ContinuousAxisRange} or {@link OrdinalAxisRange})
+ * @template A The axis type
  */
 export type UseAxesValues<AR extends BaseAxisRange, A extends BaseAxis> = {
     /**
@@ -32,7 +25,7 @@ export type UseAxesValues<AR extends BaseAxisRange, A extends BaseAxis> = {
      */
     addXAxis: (axis: A, id: string, range?: AR) => void
     /**
-     * The y-axes state holds the currently set x-axes, manipulation and accessor functions
+     * The y-axes state holds the currently set y-axes, manipulation and accessor functions
      */
     yAxesState: AxesState<A>
     /**
@@ -49,17 +42,20 @@ export type UseAxesValues<AR extends BaseAxisRange, A extends BaseAxis> = {
      */
     setAxisAssignments: (assignments: Map<string, AxesAssignment>) => void
     /**
-     * Retrieves the axis assigned to the specified series
+     * Retrieves the axes assigned to the specified series (the default x- and y-axes, when the
+     * series has no assignment)
+     * @param seriesName The name of the series
      * @return The axes assigned to the specified series
      */
     axisAssignmentsFor: (seriesName: string) => AxesAssignment
     /**
-     * Sets the axis ranges specified in the input map
+     * Sets the axis ranges specified in the input map (without dispatching them to the update
+     * handlers -- see {@link updateAxisRanges} for that)
      * @param ranges A map holding the axis ID to the axis range
      */
     setAxesRanges: (ranges: Map<string, AR>) => void
     /**
-     * Sets the axis range for the specified axis ID
+     * Sets the axis range for the specified axis ID (without dispatching it to the update handlers)
      * @param axisId The ID of the axis for which to set the range
      * @param range The new axis range
      */
@@ -68,42 +64,52 @@ export type UseAxesValues<AR extends BaseAxisRange, A extends BaseAxis> = {
      * Retrieves the current axis range for the specified axis ID
      * @param axisId The ID of the axis for which to retrieve the range
      * @return The current axis range for the specified axis ID wrapped
-     * in a n {@link Optional}, or an empty {@link Optional} if the axis
+     * in an {@link Optional}, or an empty {@link Optional} if the axis
      * ID is not found
      */
     axisRangeFor: (axisId: string) => Optional<AR>
     /**
-     * Sets the domain (interval) for the specified axis ID to the specified range
+     * Sets the domain (interval) of the specified axis' current range, leaving its original range
+     * as it is (does nothing when the axis has no range yet; doesn't dispatch the change to the
+     * update handlers)
      * @param axisId The ID of the axis for which to set the range
-     * @param domain The new domain as a `[start: number, end: number]` tuple
+     * @param domain The new domain
      */
     setAxisIntervalFor: (axisId: string, domain: AxisInterval) => void
     /**
-     * Sets the original axis bounds for the specified axis ID to the specified range
+     * Sets the original axis bounds for the specified axis ID to the specified range (does nothing
+     * when the axis has no range yet)
      * @param axisId The ID of the axis for which to set the range
-     * @param range The new range as a `[start, end]` tuple
+     * @param range The new original range
      */
     setOriginalAxisIntervalFor: (axisId: string, range: AxisInterval) => void
     /**
-     * Callback function that is called when the time ranges change. The time ranges could
-     * change because of a zoom action, a pan action, or as new data is streamed in.
+     * Updates the ranges of the specified axes, and dispatches the updates to every registered
+     * update handler (see {@link addAxesRangesUpdateHandler}) -- e.g. the axes, which redraw with
+     * their new domains. Called when the ranges change because of a zoom action, a pan action, or
+     * as new data is streamed in.
      * @param domains A `map(axis_id -> domain)` that associates the axis ID with the
      * current time range.
      */
     updateAxisRanges: (domains: Map<string, AR>) => void
     /**
-     * Retrieves the current axis bounds for the specified axis ID
-     * @return The current axis bounds as a map(axis_id, (start, end))
+     * Retrieves the current ranges of all the axes
+     * @return A copy of the current axis ranges, as a map(axis_id, range)
      */
     axesRanges: () => Map<string, AR>
     /**
-     * Resets the axis bounds to its original bounds
+     * Re-applies the specified axis' stored range: dispatches it, unchanged, to the update handlers
+     * (so that the axis redraws with it). Note that, despite its name, this does *not* restore the
+     * axis' original range, and the `<AxesProvider>`'s implementation ignores `axisBounds`.
      * @param axisId The ID of the axis
-     * @param [axisBounds] An optional bounds that resets the original bounds
+     * @param [axisBounds] Unused
      */
     resetAxisIntervalFor: (axisId: string, axisBounds?: AxisInterval) => void
     /**
-     * Resets all the axes bound to the original bounds
+     * Sets the ranges of the axes in the specified map, and dispatches them to the update handlers
+     * (the same as {@link updateAxisRanges}). Axes that aren't in the map are left as they are, so
+     * calling this without a map changes nothing -- despite its name, it doesn't restore the axes'
+     * original ranges.
      * @param [axesBounds] An optional map holds the new bounds for specified axes. The map
      * associates an axis ID with the new bounds.
      */
@@ -119,6 +125,15 @@ export type UseAxesValues<AR extends BaseAxisRange, A extends BaseAxis> = {
     /**
      * Adds a handler for when the axes are updated. An axis domain/range could change because of a zoom action,
      * a pan action, or as new data is streamed in.
+     *
+     * Throws if `handlerId` is already registered, rather than silently replacing or ignoring the
+     * new one -- a custom axis/plot component that could ever remount (not just re-render) with
+     * the same `handlerId` (e.g. one derived from a stable chart/axis ID) must call
+     * {@link removeAxesRangesUpdateHandler} in its own unmount cleanup before this would ever be
+     * called again for that ID, or the remount will throw here. See {@link ContinuousAxis}/
+     * {@link OrdinalAxis} for the reference pattern: a `useEffect` whose only job is calling
+     * `removeAxesRangesUpdateHandler` on unmount, kept separate from whatever other effect(s)
+     * register the handler.
      * @param handlerId The unique ID of the handler to register/add
      * @param handler The handler function that accepts a map of updates and a plot dimension
      */
@@ -130,211 +145,28 @@ export type UseAxesValues<AR extends BaseAxisRange, A extends BaseAxis> = {
     removeAxesRangesUpdateHandler: (handlerId: string) => void
 }
 
-export const defaultAxesValues = (): UseAxesValues<any, any> => ({
-    xAxesState: AxesState.empty(),
-    yAxesState: AxesState.empty(),
-    addXAxis: noop,
-    addYAxis: noop,
-    setAxisAssignments: noop,
-    axisAssignmentsFor: () => ({xAxis: "", yAxis: ""}),
-    updateAxisRanges: noop,
-    axesRanges: () => new Map<string, any>(),
-    axisRangeFor: () => Optional.empty(),
-    setAxesRanges: noop,
-    setAxisRangeFor: noop,
-    setAxisIntervalFor: noop,
-    setOriginalAxisIntervalFor: noop,
-    resetAxisIntervalFor: noop,
-    resetAxesRanges: noop,
-    addAxesRangesUpdateHandler: () => noop,
-    removeAxesRangesUpdateHandler: () => noop,
-})
-
-// the context for axes
-const AxesContext = createContext<UseAxesValues<any, any>>(defaultAxesValues())
-
-export type Props = {
-    /**y
-     * Callback when axes bounds change.
-     * @param ranges The ranges (start, end) for each axis in the plot
-     */
-    onUpdateAxesInterval?: (ranges: Map<string, AxisInterval>) => void
-
-    children: JSX.Element | Array<JSX.Element>
-}
-
-/**
- * The React context provider for the {@link UseAxesValues}
- * @param props The properties
- * @return The children wrapped in this provider
- */
-export default function AxesProvider<AR extends BaseAxisRange, A extends BaseAxis>(props: Props): JSX.Element {
-    const {onUpdateAxesInterval, children} = props
-
-    const plotDimensions = usePlotDimensions()
-
-    const xAxesStateRef = useRef<AxesState<A>>(AxesState.empty<A>())
-    const yAxesStateRef = useRef<AxesState<A>>(AxesState.empty<A>())
-    const axisAssignmentsRef = useRef<Map<string, AxesAssignment>>(new Map())
-    const axesBoundsUpdateHandlersRef = useRef<Map<string, (updates: Map<string, AR>, plotDim: Dimensions) => void>>(new Map())
-    const axesRangeRef = useRef<Map<string, AR>>(new Map())
-
-    /**
-     * Retrieves the x-axis and y-axis assignments for the specified series. If the axis does not have
-     * an assignment, then we assume it is using the default x- and y-axes.
-     * @param seriesName The name of the series for which to retrieve the axes assignments
-     * @return An {@link AxesAssignment} for the specified axes.
-     */
-    function axisAssignmentsFor(seriesName: string): AxesAssignment {
-        return axisAssignmentsRef.current.get(seriesName) || {
-            xAxis: xAxesStateRef.current.axisDefaultId().getOrElse(""),
-            yAxis: yAxesStateRef.current.axisDefaultId().getOrElse("")
-        }
-    }
-
-    /**
-     * Called when the domain/range is updated on one or more of the chart's axes (generally x-axes). In turn,
-     * dispatches the update to all the internal domain/range update handlers.
-     * @param updates A map holding the axis ID to the updated axis time-range (i.e., map(axis_id, axis_time_range))
-     */
-    function updateAxisRanges(updates: Map<string, AR>): void {
-        // update the current time-ranges reference
-        updates.forEach((range, id) => {
-            axesRangeRef.current.set(id, range)
-        })
-        // dispatch the updates to all the registered handlers
-        axesBoundsUpdateHandlersRef.current
-            .forEach((handler, ) => handler(updates, plotDimensions.plotDimensions))
-    }
-
-    /**
-     * Sets the axis ranges specified in the input map
-     * @param ranges The ranges to set
-     */
-    function setAxesRanges(ranges: Map<string, AR>): void {
-        ranges.forEach((range, id) => {
-            axesRangeRef.current.set(id, range)
-        })
-    }
-
-    /**
-     * Sets the axis range for the specified axis ID
-     * @param axisId The axis ID
-     * @param range The range to set
-     */
-    function setAxisRangeFor(axisId: string, range: AR): void {
-        axesRangeRef.current.set(axisId, range)
-    }
-
-    /**
-     * Sets the axis bounds for the specified axis ID. Note that this does not
-     * change the original axis interval
-     * @param axisId The axis ID
-     * @param interval The interval
-     */
-    function setAxisIntervalFor(axisId: string, interval: AxisInterval): void {
-        Optional.ofNullable(axesRangeRef.current.get(axisId))
-            .map(range => range.update(interval.start, interval.end) as AR)
-            .ifPresent(updatedRange => axesRangeRef.current.set(axisId, updatedRange))
-    }
-
-    /**
-     * Sets the original axis interval for the axis range
-     * @param axisId The axis ID
-     * @param interval The interval to which to set the origin interval
-     */
-    function setOriginalAxisIntervalFor(axisId: string, interval: AxisInterval): void {
-        Optional.ofNullable(axesRangeRef.current.get(axisId))
-            .map(range => range.updateOriginal(interval.start, interval.end) as AR)
-            .ifPresent(updatedRange => axesRangeRef.current.set(axisId, updatedRange))
-    }
-
-    /**
-     * Resets the bounds for the specified axis to the original range
-     * @param axisId The ID of the axis
-     */
-    function resetAxisIntervalFor(axisId: string): void {
-        Optional
-            .ofNullable(axesRangeRef.current.get(axisId))
-            .map(range => new Map<string, AR>([[axisId, range]]))
-            .ifPresent(updates => updateAxisRanges(updates))
-    }
-
-    /**
-     * Resets the bounds of all the axes to their original value or to the values specified
-     * in the optional bounds map.
-     * @param [axesRanges=new Map()] An optional map holds bounds for specified axes. The map
-     * associates an axis ID with the new bounds.
-     */
-    function resetAxesRanges(axesRanges: Map<string, AR> = new Map()): void {
-        updateAxisRanges(axesRanges)
-    }
-
-    /**
-     * Adds a handler to deal with updates to the bounds of the axes
-     * @param handlerId the unique ID of the handler
-     * @param handler The handler function that accepts a map of updates and a plot dimension
-     * @return A map with all the handlers
-     */
-    function addAxesRangesUpdateHandler(
-        handlerId: string,
-        handler: (updates: Map<string, AR>, plotDim: Dimensions) => void
-    ): Map<string, (updates: Map<string, AR>, plotDim: Dimensions) => void> {
-        if (axesBoundsUpdateHandlersRef.current.has(handlerId)) {
-            throw new Error(
-                `Handler with ID already exists, please remove it before adding it; ` +
-                `handler_id: ${handlerId}; ` +
-                `existing_handler_ids: [${Array.from(axesBoundsUpdateHandlersRef.current.keys()).join(", ")}]`
-            )
-        }
-      return axesBoundsUpdateHandlersRef.current.set(handlerId, handler)
-    }
-
-    return <AxesContext.Provider
-        value={{
-            xAxesState: xAxesStateRef.current,
-            yAxesState: yAxesStateRef.current,
-            addXAxis: (axis, id, range: AR) => {
-                xAxesStateRef.current = xAxesStateRef.current.addAxis(axis, id)
-                if (range !== undefined) {
-                    axesRangeRef.current.set(id, range)
-                }
-            },
-            addYAxis: (axis, id, range: AR) => {
-                yAxesStateRef.current = yAxesStateRef.current.addAxis(axis, id)
-                if (range !== undefined) {
-                    axesRangeRef.current.set(id, range)
-                }
-            },
-            setAxisAssignments: assignments => axisAssignmentsRef.current = assignments,
-            axisAssignmentsFor: seriesName => axisAssignmentsFor(seriesName),
-            updateAxisRanges,
-            axesRanges: () => new Map<string, AR>(axesRangeRef.current),
-            axisRangeFor: axisId => Optional.ofNullable(axesRangeRef.current.get(axisId)),
-            setAxesRanges,
-            setAxisRangeFor,
-            setAxisIntervalFor,
-            setOriginalAxisIntervalFor,
-            resetAxesRanges,
-            resetAxisIntervalFor,
-            onUpdateAxesInterval,
-            addAxesRangesUpdateHandler,
-            removeAxesRangesUpdateHandler: handlerId => axesBoundsUpdateHandlersRef.current.delete(handlerId),
-        }}
-    >
-        {children}
-    </AxesContext.Provider>
-}
+// the context is generic over the same type parameters as `UseAxesValues`, but a context
+// object can't itself carry unbound generics -- `useAxes` below casts it back to the caller's
+// concrete types, which is safe because `<AxesProvider/>` is what actually supplies the value
+//
+// IMPORTANT: as with `ChartContext` (see its identical note in useChart.tsx), this is NOT
+// statically enforced across the component tree -- each consumer casts to its own hardcoded
+// AR/A, independent of whatever `<AxesProvider<AR, A>>` ancestor actually supplied. A mismatched
+// axis-range/axis kind only fails at runtime, not at compile time.
+export const AxesContext = createContext<unknown>(undefined)
 
 /**
- * React hook that sets up the React context for the chart values.
+ * React hook for the chart's axes: their state, ranges, and the functions for updating them.
+ * Must be used within an {@link AxesProvider} (i.e. within a `<Chart>`).
  * @return The {@link UseAxesValues} held in the React context.
+ * @throws Error when used outside an `<AxesProvider>`
+ * @template AR The type of the axis range (e.g. {@link ContinuousAxisRange} or {@link OrdinalAxisRange})
+ * @template A The axis type
  */
 export function useAxes<AR extends BaseAxisRange, A extends BaseAxis>(): UseAxesValues<AR, A> {
-    const context = useContext<UseAxesValues<AR, A>>(AxesContext)
-    const {xAxesState} = context
-    if (xAxesState === undefined || xAxesState === null) {
+    const context = useContext(AxesContext)
+    if (context === undefined) {
         throw new Error("useAxes can only be used when the parent is a <AxesProvider/>")
     }
-    return context
+    return context as UseAxesValues<AR, A>
 }

package/src/app/charts/hooks/useCanvasSurface.tsx

@@ -0,0 +1,35 @@
+import {createContext, useContext} from "react";
+import type {CanvasContext} from "../d3types";
+
+/**
+ * The values exposed through the {@link useCanvasSurface} react hook.
+ */
+export type UseCanvasSurfaceValues = {
+    /**
+     * The `<canvas>` element backing the chart.
+     */
+    canvas: HTMLCanvasElement | null
+    /**
+     * The canvas drawing context and redraw-registration API for the chart.
+     */
+    canvasContext: CanvasContext | null
+}
+
+const defaultCanvasSurfaceValues: UseCanvasSurfaceValues = {
+    canvas: null,
+    canvasContext: null,
+}
+
+export const CanvasSurfaceContext = createContext<UseCanvasSurfaceValues>(defaultCanvasSurfaceValues)
+
+/**
+ * React hook that reads the canvas element and canvas drawing context from context. This is set
+ * up by {@link CanvasSurfaceProvider}, which sizes the canvas from {@link usePlotDimensions} (the
+ * single source of truth for the chart's dimensions) rather than from static width/height props,
+ * so that the canvas stays correctly sized even if dimensions change via
+ * `usePlotDimensions().updateDimensions(...)` independent of any prop.
+ * @return The {@link UseCanvasSurfaceValues} held in the React context.
+ */
+export function useCanvasSurface(): UseCanvasSurfaceValues {
+    return useContext(CanvasSurfaceContext)
+}

package/src/app/charts/hooks/useChart.tsx

@@ -1,22 +1,24 @@
-import {createContext, JSX, MutableRefObject, useContext} from "react";
-import {GSelection} from "../d3types";
-import {BaseAxis, SeriesLineStyle, SeriesStyle} from "../axes/axes";
-import {defaultAxesValues, useAxes, UseAxesValues} from "./useAxes";
-import {defaultMouseValues, useMouse, UseMouseValues} from "./useMouse";
-import {defaultTooltipValues, useTooltip, UseTooltipValues} from "./useTooltip";
-import {SvgStyle} from "../styling/svgStyle";
+import {createContext, useContext} from "react";
+import type {CanvasContext} from "../d3types";
+import type {BaseAxis, SeriesStyle} from "../axes/axes";
+import {type UseAxesValues} from "./useAxes";
+import {type UseMouseValues} from "./useMouse";
+import {type UseTooltipValues} from "./useTooltip";
 import {BaseAxisRange} from "../axes/BaseAxisRange";
+import {defaultUseChartValues} from "./defaultUseChartValues";
 
-export type NoTooltipMetadata = {}
+export type NoTooltipMetadata = object
 
 /**
  * The values exposed through the {@link useChart} react hook
  * @param chartId The unique ID for the chart
- * @param mainG The root <g> element for the chart
- * @param container The SVG element which is the container for this chart
+ * @param canvasContext The canvas drawing context and redraw-registration API for the chart
+ * @param canvas The `<canvas>` element which is the container for this chart
  * @template D The type of the series' datum
  * @template S The type of the series style
  * @template TM The type of the tooltip's metadata (data about the series data)
+ * @template AR The type of the axis range
+ * @template A The type of the axis
  */
 export interface UseChartValues<D, S extends SeriesStyle, TM, AR extends BaseAxisRange, A extends BaseAxis> {
     /**
@@ -24,25 +26,24 @@ export interface UseChartValues<D, S extends SeriesStyle, TM, AR extends BaseAxi
      */
     chartId: number
     /**
-     * The root <g> element for the chart
+     * The canvas drawing context and redraw-registration API for the chart. Axes, plots, and the
+     * tracker register a draw function here (via `canvasContext.register(id, drawFn, zIndex)`)
+     * instead of creating/updating SVG elements. Replaces the old `mainG`.
      */
-    mainG: GSelection | null
+    canvasContext: CanvasContext | null
     /**
-     * The SVG element which is the container for this chart
+     * The `<canvas>` element which is the container for this chart. Replaces the old `container`
+     * (root `<svg>` element).
      */
-    container: SVGSVGElement | null
+    canvas: HTMLCanvasElement | null
     /**
      * Base color
      */
     color: string
     /**
-     * The base/default background color. This can be overridden by the {@link Props.svgStyle} property.
+     * The base/default background color. This can be overridden by the {@link ChartProps.svgStyle} property.
      */
     backgroundColor: string
-    /**
-     * Overrides for the SVG style
-     */
-    svgStyle: Partial<SvgStyle>
     /**
      * A `map(series_name -> series_line_style)`
      */
@@ -57,7 +58,7 @@ export interface UseChartValues<D, S extends SeriesStyle, TM, AR extends BaseAxi
      | DATA PROCESSING
      */
     /**
-     * A regular expression uses against the series names to determine which series to show in the chart
+     * A regular expression used against the series names to determine which series to show in the chart
      */
     seriesFilter: RegExp
 
@@ -66,99 +67,39 @@ export interface UseChartValues<D, S extends SeriesStyle, TM, AR extends BaseAxi
      */
     mouse: UseMouseValues<D, TM>
     tooltip: UseTooltipValues<D, TM>
-    /**
-     * Ref tracking the currently-hovered series name (null when nothing is hovered).
-     * Updated by the Legend; read by plots so new path elements use the correct stroke.
-     */
-    hoveredSeriesRef: MutableRefObject<string | null>
 }
 
-const defaultUseChartValues: UseChartValues<any, any, any, any, any> = {
-    chartId: NaN,
-    container: null,
-    mainG: null,
-    color: '#d2933f',
-    backgroundColor: '#EEE',
-    svgStyle: new Map(),
-    seriesStyles: new Map(),
-
-    // axes
-    axes: defaultAxesValues(),
-
-    // data
-    seriesFilter: /./,
-
-    // internal chart-interaction event handlers
-    mouse: defaultMouseValues(),
-    tooltip: defaultTooltipValues(),
-    hoveredSeriesRef: { current: null },
-}
-
-const ChartContext = createContext<UseChartValues<any, any, any, any, any>>(defaultUseChartValues)
-
-export interface Props {
-    chartId: number
-    container: SVGSVGElement | null
-    mainG: GSelection | null
-    color: string
-    backgroundColor: string
-    svgStyle: Partial<SvgStyle>
-    seriesStyles?: Map<string, SeriesLineStyle>
-    seriesFilter?: RegExp
-    hoveredSeriesRef: MutableRefObject<string | null>
-
-    children: JSX.Element | Array<JSX.Element>
-}
-
-/**
- * The React context provider for the {@link UseChartValues}
- * @param props The properties
- * @return The children wrapped in this provider
- */
-export default function ChartProvider(props: Props): JSX.Element {
-    const {
-        chartId,
-        container,
-        mainG,
-        color,
-        backgroundColor,
-        seriesFilter = defaultUseChartValues.seriesFilter,
-        svgStyle,
-        seriesStyles = new Map<string, SeriesLineStyle>(),
-        hoveredSeriesRef,
-    } = props
-
-    const axes = useAxes()
-    const mouse = useMouse()
-    const tooltip = useTooltip()
-
-    return <ChartContext.Provider
-        value={{
-            chartId,
-            color,
-            backgroundColor,
-            svgStyle,
-            seriesStyles,
-            seriesFilter,
-            mainG,
-            container,
-
-            axes,
-            mouse,
-            tooltip,
-            hoveredSeriesRef,
-        }}
-    >
-        {props.children}
-    </ChartContext.Provider>
-}
+// the context is generic over the same type parameters as `UseChartValues`, but a context
+// object can't itself carry unbound generics -- `useChart` below casts it back to the caller's
+// concrete types, which is safe because `<ChartProvider/>` is what actually supplies the value
+//
+// IMPORTANT: this is NOT statically enforced across the component tree. `<Chart<CD, D, S, TM, AR,
+// A>>`'s AR/A are never referenced by its own Props type, so they can't even be inferred from
+// JSX; and every descendant (each axis component) calls `useChart<...>()` with its OWN hardcoded
+// generic arguments, entirely independent of whatever the ancestor `<Chart<...>>` was
+// instantiated with. Nothing at the type level stops e.g. a `<Chart<..., ContinuousAxisRange,
+// ContinuousNumericAxis>>` from having an `<OrdinalAxis>` child that casts this same context to
+// `UseChartValues<..., OrdinalAxisRange, OrdinalStringAxis>` internally -- a real mismatch here
+// only fails at runtime (a bad cast surfacing as a confusing error deeper in axis/plot code), not
+// at compile time. Making this a real compile-time guarantee would need a per-instantiation-typed
+// context (e.g. a context factory called once per concrete AR/A pairing) -- a broader refactor
+// than the type parameters alone might suggest, and not something to casually "fix" locally.
+export const ChartContext = createContext<unknown>(defaultUseChartValues())
 
 /**
- * React hook that sets up the React context for the chart values.
+ * React hook for the chart's values: its ID, canvas, colors, styles, axes, mouse and tooltip
+ * handlers, and highlighted series. Must be used within a `ChartProvider` (i.e. within a
+ * `<Chart>`).
  * @return The {@link UseChartValues} held in the React context.
+ * @throws Error when used outside a `<ChartProvider>`
+ * @template D The type of the series' datum
+ * @template S The type of the series style
+ * @template TM The type of the tooltip's metadata (data about the series data)
+ * @template AR The type of the axis range
+ * @template A The type of the axis
  */
 export function useChart<D, S extends SeriesStyle, TM, AR extends BaseAxisRange, A extends BaseAxis>(): UseChartValues<D, S, TM, AR, A> {
-    const context = useContext<UseChartValues<D, S, TM, AR, A>>(ChartContext)
+    const context = useContext(ChartContext) as UseChartValues<D, S, TM, AR, A>
     const {chartId} = context
     if (isNaN(chartId)) {
         throw new Error("useChart can only be used when the parent is a <ChartProvider/>")