@wick-charts/react 0.3.2 → 0.3.4

package/dist/index.d.ts

@@ -6,39 +6,67 @@ import { ReactNode } from 'react';
 export declare const andromeda: ThemePreset;
 
 /**
- * Chart-level animation configuration. Split into two independent domains so
- * per-series defaults can't bleed into viewport-interaction timings:
+ * Chart-level animation configuration. Two independent domains so per-series
+ * defaults can't bleed into viewport-interaction timings.
  *
- * - `points` — animations applied to data: per-series entrance tween, live-
- *   tracking smoothing of the last candle/bar/line value, pulse cadence.
- *   These values act as defaults for each series. Per-series options always
- *   win unless the chart-level category is explicitly `false`, in which case
- *   the whole category is forced off.
+ * **Two layers — chart-level vs per-series.** The same data-animation knobs
+ * live on both layers; remember which is which:
  *
- * - `viewport` — animations applied to viewport interactions: post-gesture
- *   rebound duration and Y-axis range smoothing.
+ * | Field | Chart-level (here) | Per-series option |
+ * | ----- | ------------------ | ----------------- |
+ * | Entry duration | {@link AnimationsConfig.points}`.enterMs` | `<XSeries options={{ entryMs }}>` (canonical name; `enterMs` is a `@deprecated` alias) |
+ * | Live smoothing | `points.smoothMs` | `options={{ smoothMs }}` |
+ * | Line pulse period | `points.pulseMs` | `<LineSeries options={{ pulseMs }}>` |
  *
- * User-initiated pan/zoom (wheel, drag, touch) always applies instantly. The
- * latency of an exponential chase reads as laggy in practice. API-driven
- * transitions (`fitToData`, `scrollToEnd`) and post-gesture rebound still
- * tween via their own fixed-duration ease-out.
+ * Resolution: per-series option **wins** (it's the override). The chart-
+ * level field acts as the default for every series that didn't set its own
+ * override — *except* when the chart-level category is explicitly `false`,
+ * which is a hard disable that overrides per-series too.
+ *
+ * - `points` — applied to data: entrance tween, live-tracking smoothing of
+ *   the last candle/bar/line value, line pulse cadence.
+ * - `viewport` — applied to viewport interactions: post-gesture rebound,
+ *   Y-axis range chase, optional per-event ease for pan/zoom. Has no
+ *   per-series equivalent — these are chart-level only.
+ *
+ * All settling animations share a 250 ms default so the X re-fit, Y range
+ * update, and last-bar live-track all settle on the same frame on a
+ * streaming tick. Pulse cycle period (600 ms) and `inputResponseMs` (0,
+ * opt-in) keep their own values.
  */
-declare interface AnimationsConfig {
+export declare interface AnimationsConfig {
     /**
      * Data-series animations. `false` disables every point animation (entrance,
-     * live-smoothing, pulse) across every series. An object overrides individual
-     * categories; omitted fields fall back to the built-in defaults.
+     * live-smoothing, pulse) across every series — overrides any per-series
+     * option set on the same fields. An object overrides individual categories;
+     * omitted fields fall back to the built-in defaults.
+     *
+     * Per-series options (`<LineSeries options={{ entryMs, smoothMs, pulseMs }}>`)
+     * win over chart-level numeric values. The chart-level field becomes the
+     * default for series that don't set their own.
      */
     points?: false | {
-        /** Per-point entrance duration (ms). `false`/`0` disables. Default: 400. */
+        /**
+         * Per-point entrance duration (ms). Default: 250.
+         * Per-series equivalent: `<XSeries options={{ entryMs }}>` (note the
+         * `y` — chart-level uses `enterMs`, per-series uses `entryMs` for
+         * historical reasons; both refer to the same animation). `false` /
+         * `0` disables.
+         */
         enterMs?: AnimationTime;
         /**
-         * Exponential-smoothing time constant (ms) for live last-value chase.
-         * `false`/`0` disables smoothing — the last point snaps to the target.
-         * Default: 70 ms (equivalent to the legacy `liveSmoothRate = 14`).
+         * Live-value chase duration (ms) for the displayed last point on
+         * `updateData` ticks. Animator-driven cubic ease — after this many ms
+         * with no new updates, the displayed value reaches exactly the
+         * actual last value. Default: 250. Per-series equivalent:
+         * `options={{ smoothMs }}`. `false` / `0` snaps.
          */
         smoothMs?: AnimationTime;
-        /** Pulse cycle period (ms) for the line last-point halo. Default: 600. */
+        /**
+         * Pulse cycle period (ms) for the line last-point halo — periodic,
+         * not a one-shot transition. Default: 600. Per-series equivalent:
+         * `<LineSeries options={{ pulseMs }}>`. `false` / `0` disables.
+         */
         pulseMs?: AnimationTime;
     };
     /**
@@ -49,15 +77,33 @@ declare interface AnimationsConfig {
         /** Rebound (snap-back) duration after pan/zoom overshoot (ms). Default: 350. */
         reboundMs?: AnimationTime;
         /**
-         * Y-axis range transition scale. **Frame-count-based, calibrated at
-         * 60 Hz — not wall-clock ms.** Each render frame closes
-         * `min(1, 16 / yAxisMs)` of the remaining gap. Default 80 ≈ the
-         * legacy 0.2-per-frame closure. `false` / `0` snaps the Y range
-         * instantly. Unlike `smoothMs` / `entryMs` / `reboundMs`, the
-         * perceptual duration scales with frame time on refresh rates far
-         * from 60 Hz.
+         * Y-axis range transition duration in wall-clock milliseconds. The Y
+         * min and max each ride their own {@link Animator} that retargets on
+         * data updates and eases toward the new bound over this many ms.
+         * Default `250` (shares the lockstep-arrival budget with viewport and
+         * live-track). Inward contraction always eases. Outward expansion
+         * eases when the per-point entrance is enabled (the entering candle's
+         * fade masks the brief overshoot); when entrance is hard-disabled
+         * (`points.enterMs === 0`), Y bounds snap outward to keep new
+         * highs/lows from clipping at the canvas edge. `false` / `0` snaps
+         * the Y range instantly on every update.
          */
         yAxisMs?: AnimationTime;
+        /**
+         * Per-event ease applied to user pan/zoom commits. Logical state
+         * advances synchronously (gesture math, edge detection, autoscroll
+         * all read the committed target); the visual range eases over this
+         * duration so back-to-back wheel/trackpad events interpolate
+         * smoothly through the same animator.
+         *
+         * Default `0` (instant-apply, matches the long-standing pre-Phase-5
+         * behaviour). Opt in via `inputResponseMs: 60` for an eased pan/zoom
+         * feel — the default is conservative because the animated visual
+         * range diverges from the committed target until the ease completes,
+         * and existing consumers reading `chart.getVisibleRange()`
+         * synchronously after a wheel/pan expect the new value.
+         */
+        inputResponseMs?: AnimationTime;
     };
 }
 
@@ -151,12 +197,24 @@ export declare interface BarSeriesOptions {
     /** @deprecated Use {@link entryAnimation} instead. */
     enterAnimation?: BarEntryAnimation;
     /**
-     * Entrance animation duration in milliseconds. `false` or `0` disables the
-     * per-bar entrance (equivalent to `entryAnimation: 'none'`). Omit to inherit
-     * from {@link AnimationsConfig.points}.`entryMs` (default 400).
+     * Per-bar entrance duration in milliseconds. Default: `250`.
+     *
+     * ```
+     * // Override for one series:
+     * <BarSeries options={{ entryMs: 600 }} data={data} />
+     *
+     * // Or set the default for every series at once:
+     * <ChartContainer animations={{ points: { enterMs: 600 } }}>
+     *   <BarSeries data={data} />
+     * </ChartContainer>
+     * ```
      *
-     * When `animations.points.entryMs` is `false` at the chart level, the
-     * entrance is forced off regardless of this field.
+     * Note: chart-level uses `enterMs`, per-series uses `entryMs` — same
+     * animation, two names for historical reasons.
+     *
+     * `false` or `0` disables the entrance (equivalent to
+     * `entryAnimation: 'none'`). A chart-level `animations.points: false` is a
+     * hard disable that wins over this field.
      *
      * @see BarSeriesOptions.entryAnimation
      */
@@ -164,13 +222,22 @@ export declare interface BarSeriesOptions {
     /** @deprecated Use {@link entryMs} instead. */
     enterMs?: number | false;
     /**
-     * Exponential-smoothing time constant (ms) for live-tracking the last
-     * bar's value under `updateLastPoint`. `0` or `false` snaps directly to the
-     * target (no smoothing). Omit to inherit from
-     * {@link AnimationsConfig.points}.`smoothMs` (default 70 ms).
+     * How long the displayed bar value takes to catch up to the actual one
+     * on every `updateLastPoint`. Default: `250` ms.
+     *
+     * ```
+     * // Per-series override:
+     * <BarSeries options={{ smoothMs: 100 }} data={data} />
+     *
+     * // Chart-level default:
+     * <ChartContainer animations={{ points: { smoothMs: 100 } }}>
+     *   <BarSeries data={data} />
+     * </ChartContainer>
+     * ```
      *
-     * When `animations.points.smoothMs` is `false` at the chart level, smoothing
-     * is forced off regardless of this field.
+     * `0` or `false` snaps the displayed value to the target on every tick
+     * (no smoothing). A chart-level `animations.points: false` is a hard
+     * disable that wins over this field.
      */
     smoothMs?: number | false;
 }
@@ -277,12 +344,24 @@ export declare interface CandlestickSeriesOptions {
     /** @deprecated Use {@link entryAnimation} instead. */
     enterAnimation?: CandlestickEntryAnimation;
     /**
-     * Entrance animation duration in milliseconds. `false` or `0` disables the
-     * per-candle entrance (equivalent to `entryAnimation: 'none'`). Omit to
-     * inherit from {@link AnimationsConfig.points}.`entryMs` (default 400).
+     * Per-candle entrance duration in milliseconds. Default: `250`.
+     *
+     * ```
+     * // Override for one series:
+     * <CandlestickSeries options={{ entryMs: 600 }} data={data} />
+     *
+     * // Or set the default for every series at once:
+     * <ChartContainer animations={{ points: { enterMs: 600 } }}>
+     *   <CandlestickSeries data={data} />
+     * </ChartContainer>
+     * ```
+     *
+     * Note: chart-level uses `enterMs`, per-series uses `entryMs` — same
+     * animation, two names for historical reasons.
      *
-     * When `animations.points.entryMs` is `false` at the chart level, the
-     * entrance is forced off regardless of this field.
+     * `false` or `0` disables the entrance (equivalent to
+     * `entryAnimation: 'none'`). A chart-level `animations.points: false` is a
+     * hard disable that wins over this field.
      *
      * @see CandlestickSeriesOptions.entryAnimation
      */
@@ -290,13 +369,22 @@ export declare interface CandlestickSeriesOptions {
     /** @deprecated Use {@link entryMs} instead. */
     enterMs?: number | false;
     /**
-     * Exponential-smoothing time constant (ms) for live-tracking the last
-     * candle's O/H/L/C under `updateLastPoint`. `0` or `false` snaps directly
-     * to the target (no smoothing). Omit to inherit from
-     * {@link AnimationsConfig.points}.`smoothMs` (default 70 ms).
+     * How long the displayed OHLC takes to catch up to the actual last value
+     * on every `updateLastPoint`. Default: `250` ms.
      *
-     * When `animations.points.smoothMs` is `false` at the chart level, smoothing
-     * is forced off regardless of this field.
+     * ```
+     * // Per-series override:
+     * <CandlestickSeries options={{ smoothMs: 100 }} data={data} />
+     *
+     * // Chart-level default:
+     * <ChartContainer animations={{ points: { smoothMs: 100 } }}>
+     *   <CandlestickSeries data={data} />
+     * </ChartContainer>
+     * ```
+     *
+     * `0` or `false` snaps the displayed value to the target on every tick
+     * (no smoothing). A chart-level `animations.points: false` is a hard
+     * disable that wins over this field.
      */
     smoothMs?: number | false;
 }
@@ -324,7 +412,7 @@ export declare const catppuccin: ThemePreset;
  *   - Legend — flex sibling at the bottom (or right, when `position="right"`), so its height is
  *     reserved by browser layout.
  */
-export declare function ChartContainer({ children, theme, axis, padding, gradient, interactive, grid, headerLayout, perf, style, className, }: ChartContainerProps): JSX_2.Element;
+export declare function ChartContainer({ children, theme, axis, padding, gradient, interactive, grid, headerLayout, perf, animations, style, className, }: ChartContainerProps): JSX_2.Element;
 
 /** Props for the {@link ChartContainer} component. */
 declare interface ChartContainerProps {
@@ -381,6 +469,36 @@ declare interface ChartContainerProps {
      *   the title. The chart background still spans the full container.
      */
     headerLayout?: 'overlay' | 'inline';
+    /**
+     * Chart-level animation configuration. See {@link AnimationsConfig} for the
+     * full shape.
+     *
+     * Two layers — remember which is which:
+     *
+     * - **Chart-level (this prop)** — `animations.points.{enterMs, smoothMs,
+     *   pulseMs}` and `animations.viewport.{reboundMs, yAxisMs,
+     *   inputResponseMs}`. Acts as the default for every series.
+     * - **Per-series** — `<LineSeries options={{ entryMs, smoothMs, pulseMs }}>`
+     *   (and the analogous CandlestickSeries / BarSeries options). Overrides
+     *   the chart-level default for that one series. Note the spelling:
+     *   `entryMs` per-series, `enterMs` chart-level — historical artefact,
+     *   both refer to the same animation.
+     *
+     * Resolution: per-series option wins over chart-level numeric value.
+     * Chart-level wins only when its category is explicitly `false` — that's
+     * a hard disable that overrides per-series too.
+     *
+     * Shorthands:
+     * - `true` / omitted — built-in defaults (every settling animation 250 ms,
+     *   pulse cycle 600 ms, input ease 0 / off).
+     * - `false` — disables every animation category.
+     * - `{ points: false }` / `{ viewport: false }` — disables a category.
+     *
+     * Runtime updates: changing this prop after mount calls
+     * `chart.setAnimations(...)` so the new durations take effect on the next
+     * animation / render.
+     */
+    animations?: boolean | AnimationsConfig;
     /**
      * Enable runtime performance instrumentation. Off by default.
      *
@@ -606,6 +724,25 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
      * a wrapper re-applies padding reactively (e.g. in response to a Title /
      * InfoBar ResizeObserver).
      */
+    /**
+     * Replace the chart-level animation configuration at runtime. Updates the
+     * resolved durations and propagates them to every dependent subsystem:
+     *
+     * - viewport: reboundMs (next rebound), inputResponseMs (next pan/zoom).
+     * - per-frame: yAxisMs (next render).
+     * - existing series: only the **hard-disable** signal (0 / false) is pushed
+     *   into renderers — that's the documented contract on
+     *   {@link AnimationsConfig.points}, "chart-level `false` wins over per-
+     *   series". Numeric chart-level changes update the default for *new*
+     *   series but leave existing per-series overrides intact, which avoids
+     *   silently clobbering custom values on every prop update from a React
+     *   wrapper.
+     *
+     * In-flight animations are NOT cancelled — the new durations apply to the
+     * next animation that fires. To force-snap the current animation, call
+     * the relevant API explicitly (e.g. `setRange`) afterwards.
+     */
+    setAnimations(animations: ChartOptions['animations']): void;
     setPadding(padding: ChartOptions['padding']): void;
     /** Show or hide the background grid. Takes effect on the next render frame. */
     setGrid(grid: {
@@ -634,6 +771,17 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
     private getDataBounds;
     private onDataChanged;
     private updateDataInterval;
+    /**
+     * Sample data inside `targetVisible` and return the unbounded [min, max] of
+     * the visible series, or `null` when nothing is in view. Bounds are NOT
+     * applied here — the caller composes them via {@link resolveBound}.
+     *
+     * `targetVisible` is the X *destination* (logicalRange), not the animating
+     * current. Sampling against a moving X would make Y chase a definition of
+     * "in view" that shifts every frame; passing the destination explicitly
+     * keeps Y on a stable target so X and Y converge together.
+     */
+    private computeTargetYRange;
     private updateYRange;
     /** Resolve an {@link AxisBound} to a concrete numeric value. */
     private resolveBound;
@@ -1175,11 +1323,23 @@ export declare interface LineSeriesOptions {
      */
     pulse: boolean;
     /**
-     * Pulse cycle period in milliseconds. `false`/`0` disables the halo (both
-     * the drawing and the associated animation loop). Omit to inherit from
-     * {@link AnimationsConfig.points}.`pulseMs` (default 600 ms). When
-     * `animations.points.pulseMs` is `false` at the chart level the pulse is
-     * forced off regardless of this field.
+     * Period of one halo pulse cycle in milliseconds. Continuous loop, not a
+     * one-shot — short values pulse fast, long values pulse slowly. Default:
+     * `600` (≈ 1.7 Hz, a calm "breathing" rhythm).
+     *
+     * ```
+     * // Per-series override:
+     * <LineSeries options={{ pulseMs: 1200 }} data={data} />
+     *
+     * // Chart-level default:
+     * <ChartContainer animations={{ points: { pulseMs: 1200 } }}>
+     *   <LineSeries data={data} />
+     * </ChartContainer>
+     * ```
+     *
+     * `false` or `0` turns the halo off entirely (drawing and animation loop).
+     * A chart-level `animations.points: false` is a hard disable that wins
+     * over this field.
      */
     pulseMs?: number | false;
     /** Stacking mode. Default: 'off'. */
@@ -1195,12 +1355,24 @@ export declare interface LineSeriesOptions {
     /** @deprecated Use {@link entryAnimation} instead. */
     enterAnimation?: LineEntryAnimation;
     /**
-     * Entrance animation duration in milliseconds. `false` or `0` disables the
-     * per-point entrance (equivalent to `entryAnimation: 'none'`). Omit to
-     * inherit from {@link AnimationsConfig.points}.`entryMs` (default 400).
+     * Per-point entrance duration in milliseconds. Default: `250`.
      *
-     * When `animations.points.entryMs` is `false` at the chart level, the
-     * entrance is forced off regardless of this field.
+     * ```
+     * // Override for one series:
+     * <LineSeries options={{ entryMs: 600 }} data={data} />
+     *
+     * // Or set the default for every series at once:
+     * <ChartContainer animations={{ points: { enterMs: 600 } }}>
+     *   <LineSeries data={data} />
+     * </ChartContainer>
+     * ```
+     *
+     * Note: chart-level uses `enterMs`, per-series uses `entryMs` — same
+     * animation, two names for historical reasons.
+     *
+     * `false` or `0` disables the entrance (equivalent to
+     * `entryAnimation: 'none'`). A chart-level `animations.points: false` is a
+     * hard disable that wins over this field.
      *
      * @see LineSeriesOptions.entryAnimation
      */
@@ -1208,13 +1380,22 @@ export declare interface LineSeriesOptions {
     /** @deprecated Use {@link entryMs} instead. */
     enterMs?: number | false;
     /**
-     * Exponential-smoothing time constant (ms) for live-tracking the last
-     * point's value under `updateLastPoint`. `0` or `false` snaps directly to
-     * the target (no smoothing). Omit to inherit from
-     * {@link AnimationsConfig.points}.`smoothMs` (default 70 ms).
+     * How long the displayed last value takes to catch up to the actual one
+     * on every `updateLastPoint`. Default: `250` ms.
+     *
+     * ```
+     * // Per-series override:
+     * <LineSeries options={{ smoothMs: 100 }} data={data} />
+     *
+     * // Chart-level default:
+     * <ChartContainer animations={{ points: { smoothMs: 100 } }}>
+     *   <LineSeries data={data} />
+     * </ChartContainer>
+     * ```
      *
-     * When `animations.points.smoothMs` is `false` at the chart level, smoothing
-     * is forced off regardless of this field.
+     * `0` or `false` snaps the displayed value to the target on every tick
+     * (no smoothing). A chart-level `animations.points: false` is a hard
+     * disable that wins over this field.
      */
     smoothMs?: number | false;
 }