@wick-charts/vue 0.3.3 → 0.3.5

package/README.md

@@ -2,20 +2,23 @@
 
 <!-- Generated from README.tmpl.md — edit the template, not this file. -->
 
-High-performance timeseries charts for **React**, **Vue**, and **Svelte**. Canvas-rendered, tree-shakeable, ~36KB gzipped when tree-shaken.
+[![codecov](https://codecov.io/gh/mo4islona/wick-charts/branch/main/graph/badge.svg)](https://codecov.io/gh/mo4islona/wick-charts) [![license](https://img.shields.io/github/license/mo4islona/wick-charts.svg)](./LICENSE)
+[![npm @wick-charts/vue](https://img.shields.io/npm/v/@wick-charts/vue.svg?label=%40wick-charts%2Fvue)](https://www.npmjs.com/package/@wick-charts/vue)
 
-[Live Demo](https://mo4islona.github.io/wick-charts/)
+High-performance timeseries charts for **React**, **Vue**, and **Svelte**. Canvas-rendered, tree-shakeable, zero runtime dependencies.
+
+[Live Demo](https://mo4islona.github.io/wick-charts/) · [Docs](https://mo4islona.github.io/wick-charts/#/api/chart-container)
 
 ## Features
 
-- **Candlestick, Line, Bar, Pie** — all from one package
-- **Real-time streaming** — append/update data at 60fps
-- **22 built-in themes** — dark, light, and custom
+- **Candlestick, Line, Bar, Pie, Sparkline** — all from one package
+- **Real-time streaming** — append/update at 60fps with coordinated animations
+- **22 built-in themes** plus `createTheme()` for custom palettes
 - **Interactive** — zoom, pan, crosshair, tooltips
 - **Stacking** — normal and percent modes for line/bar
-- **Custom-render helpers** — `buildHoverSnapshots` / `buildLastSnapshots` / `computeTooltipPosition` for overlays that need to escape the built-in UI (structural-equality cache included)
+- **Custom-render slots** — keep the built-in positioning, replace the contents
 - **Tree-shakeable** — import only what you use
-- **Zero dependencies** — just your framework
+- **Zero runtime dependencies** — just your framework
 
 ## Install
 
@@ -46,150 +49,23 @@ const props = defineProps(['data']);
 </template>
 ```
 
-## Series Types
-
-| Component | Data Format | Description |
-|---|---|---|
-| `CandlestickSeries` | `{ time, open, high, low, close, volume? }[]` | OHLC candlesticks with volume bars |
-| `LineSeries` | `{ time, value }[][]` | Line/area charts, multi-layer, stacking |
-| `BarSeries` | `{ time, value }[][]` | Histogram/bar charts, stacking |
-| `PieSeries` | `{ label, value, color? }[]` | Pie and donut charts |
-
-## UI Overlays
-
-Every DOM overlay ships a default UI **and** a scoped slot / render-prop so you can replace the contents with your own layout. Positioning, crosshair wiring, and data computation stay in the library — the slot just hands you the already-computed data.
-
-| Component | Description | Slot ctx |
-|---|---|---|
-| `Tooltip` | Floating glass tooltip near cursor on hover | `{ snapshots, time }` |
-| `InfoBar` | Compact OHLC / values info bar hoisted above the canvas | `{ snapshots, time, isHover }` |
-| `Title` | Chart title / subtitle bar hoisted above the canvas | — |
-| `Crosshair` | Axis labels at cursor position | — |
-| `YAxis` | Vertical price/value axis with animated ticks | — |
-| `TimeAxis` | Horizontal time axis with animated ticks | — |
-| `YLabel` | Floating price badge with dashed line | `{ value, y, bgColor, isLive, direction, format }` |
-| `Legend` | Clickable legend with toggle/isolate modes | `{ items: LegendItem[] }` |
-| `PieTooltip` | Tooltip for pie/donut hover | `{ info, format }` |
-| `PieLegend` | Slice labels with values or percentages | `{ slices, mode, format }` |
-
-## Custom render (slots / render-props)
-
-```vue
-<!-- Vue — same context, different syntax -->
-<Tooltip v-slot="{ snapshots, time }">
-  <div
-    v-for="s in snapshots.filter((x) => x.seriesId === 'btc' || x.seriesId === 'eth')"
-    :key="s.id"
-    :style="{ color: s.color }"
-  >
-    {{ s.label }}: {{ s.data.close ?? s.data.value }}
-  </div>
-</Tooltip>
-```
-
-Each overlay has its own slot context (see the Slot ctx column above); the shape is consistent across frameworks for the same overlay.
-
-### Public helpers (re-exported from each framework package)
-
-- `buildHoverSnapshots(chart, { time, sort?, cacheKey })` / `buildLastSnapshots(chart, { sort?, cacheKey })` — structural-equality-cached snapshot arrays for building your own floating widgets. Calls with the same args return the **same reference** while the chart's overlay version is unchanged, so `React.memo` / Vue `computed` / Svelte `$:` skip renders on no-op mousemoves.
-- `computeTooltipPosition({ x, y, chartWidth, chartHeight, tooltipWidth, tooltipHeight, offsetX?, offsetY? })` — flip + clamp positioning for a tooltip container you own.
-- Types: `SeriesSnapshot`, `LegendItem`, `SliceInfo`, `HoverInfo`.
-
-## Custom number formatting
-
-Every numeric overlay accepts a `format` prop so you can override the default label rendering. Two shared helpers ship in each framework package (`@wick-charts/react`, `@wick-charts/vue`, `@wick-charts/svelte`):
-
-- `formatCompact(v)` — K/M/B/T suffixes with adaptive precision. Default for `YAxis` (at ranges ≥ 1e6), `PieLegend`, `PieTooltip`, `Sparkline`.
-- `formatPriceAdaptive(v)` — full-precision display that scales decimals to the value's magnitude. Default for `Tooltip` / `InfoBar` OHLC and line-value cells. Handles sub-cent prices (`0.00001234` → `"0.00001234"`, not `"0.00"`).
-
-```vue
-<script setup>
-import { Tooltip, YAxis, formatCompact } from '@wick-charts/vue';
-
-const yFormat = (v) => `$${formatCompact(v)}`;
-const tipFormat = (v, field) => (field === 'volume' ? formatCompact(v) : v.toFixed(4));
-</script>
-
-<template>
-  <YAxis :format="yFormat" />
-  <Tooltip :format="tipFormat" />
-</template>
-```
-
-Tooltip / InfoBar pass a `field` arg (`'open' | 'high' | 'low' | 'close' | 'volume' | 'value'`) so you can branch on which cell you're formatting. All other overlays receive a single `value: number`.
+## API
 
-## Themes
+Every component, prop, type, and slot context lives in the docs site:
 
-22 built-in themes. Import only the ones you need (tree-shakable) and pass them to `ChartContainer` or `ThemeProvider` for global theming.
+[mo4islona.github.io/wick-charts/#/api/chart-container](https://mo4islona.github.io/wick-charts/#/api/chart-container)
 
-```vue
-<script setup>
-import { catppuccin } from '@wick-charts/vue';
-// Dark: andromeda, ayuMirage, catppuccin, dracula, gruvbox, highContrast,
-//       materialPalenight, monokaiPro, nightOwl, oneDarkPro, panda
-// Light: githubLight, handwritten, lavenderMist, lightPink, minimalLight, mintBreeze,
-//        peachCream, quietLight, rosePineDawn, sandDune, solarizedLight
-</script>
-
-<template>
-  <ChartContainer :theme="catppuccin.theme" />
-</template>
-```
-
-Create custom themes with `createTheme()`:
-
-```ts
-import { createTheme } from '@wick-charts/vue';
-
-const myTheme = createTheme({
-  background: '#1a1b2e',
-  candlestick: {
-    up: { body: '#00d4aa' },
-    down: { body: '#ff5577' },
-  },
-  axis: { textColor: '#8888aa' },
-});
-```
-
-## Real-Time Data
-
-```vue
-<template>
-  <!-- Full replace (initial load) -->
-  <CandlestickSeries :data="allCandles" />
-</template>
-
-<!--
-  The component auto-detects changes:
-  - data.length grew by 1-5 → append
-  - data.length same → update last point
-  - data.length shrunk or grew by >5 → full replace
--->
-```
-
-## Configuration
-
-```vue
-<template>
-  <ChartContainer
-    :theme="theme"
-    :axis="{
-      y: { visible: true, width: 55, min: 0, max: 'auto' },
-      x: { visible: true, height: 30 },
-    }"
-  />
-</template>
-
-<!-- Vue ChartContainer currently accepts theme + axis; padding/gradient/grid/interactive are React-only. -->
-```
+Start there for [ChartContainer](https://mo4islona.github.io/wick-charts/#/api/chart-container), then drill into the series ([Candlestick](https://mo4islona.github.io/wick-charts/#/api/candlestick-series), [Line](https://mo4islona.github.io/wick-charts/#/api/line-series), [Bar](https://mo4islona.github.io/wick-charts/#/api/bar-series), [Pie](https://mo4islona.github.io/wick-charts/#/api/pie-series), [Sparkline](https://mo4islona.github.io/wick-charts/#/api/sparkline)) and overlays ([Tooltip](https://mo4islona.github.io/wick-charts/#/api/tooltip), [InfoBar](https://mo4islona.github.io/wick-charts/#/api/info-bar), [Crosshair](https://mo4islona.github.io/wick-charts/#/api/crosshair), [Legend](https://mo4islona.github.io/wick-charts/#/api/legend), [YAxis](https://mo4islona.github.io/wick-charts/#/api/y-axis), [XAxis](https://mo4islona.github.io/wick-charts/#/api/x-axis), [Navigator](https://mo4islona.github.io/wick-charts/#/api/navigator), …).
 
-## Bundle Size
+## Bundle size
 
-Full `dist/index.js` (minified + gzipped):
+Tree-shaken React scenarios via `pnpm size` (esbuild, minified, browser target, React/ReactDOM external):
 
-| Package | Raw | Gzip |
-|---|---|---|
-| `@wick-charts/vue`    | 219 KB | 57.3 KB |
+| Scenario | Raw | Gzip | Brotli |
+|---|---:|---:|---:|
+| Candlestick only | 147 KB | 44 KB | 38 KB |
+| Line only        | 147 KB | 44 KB | 38 KB |
+| Full React       | 164 KB | 49 KB | 41 KB |
 
 ## Migration
 

package/dist/index.d.ts

@@ -165,6 +165,19 @@ declare type __VLS_Props_3 = {
      * - `'inline'`: flex siblings above the canvas — the canvas (and grid) shift down.
      */
     headerLayout?: 'overlay' | 'inline';
+    /**
+     * Chart-level animation configuration. See `AnimationsConfig` for the full shape.
+     *
+     * Two layers — chart-level (this prop) sets defaults for every series; per-series
+     * options on `<LineSeries>`/`<CandlestickSeries>`/`<BarSeries>` override that
+     * default for that one series.
+     *
+     * Shorthands: `true` / omitted — built-in defaults; `false` — disables every
+     * animation category; `{ points: false }` / `{ viewport: false }` disables a
+     * category. Updating this prop calls `chart.setAnimations(...)` so the new
+     * durations take effect on the next animation / render.
+     */
+    animations?: boolean | AnimationsConfig;
     /**
      * Enable runtime performance instrumentation. Off by default. Read at mount only;
      * later changes are ignored.
@@ -445,39 +458,67 @@ declare type __VLS_WithTemplateSlots_8<T, S> = T & {
 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.
+ *
+ * **Two layers — chart-level vs per-series.** The same data-animation knobs
+ * live on both layers; remember which is which:
  *
- * - `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.
+ * | 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 }}>` |
  *
- * - `viewport` — animations applied to viewport interactions: post-gesture
- *   rebound duration and Y-axis range smoothing.
+ * 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.
  *
- * 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.
+ * - `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 {
     /**
      * 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;
     };
     /**
@@ -488,15 +529,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;
     };
 }
 
@@ -590,12 +649,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>
+     * ```
+     *
+     * 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 BarSeriesOptions.entryAnimation
      */
@@ -603,13 +674,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.
      *
-     * When `animations.points.smoothMs` is `false` at the chart level, smoothing
-     * is forced off regardless of this field.
+     * ```
+     * // Per-series override:
+     * <BarSeries options={{ smoothMs: 100 }} data={data} />
+     *
+     * // Chart-level default:
+     * <ChartContainer animations={{ points: { smoothMs: 100 } }}>
+     *   <BarSeries 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;
 }
@@ -707,12 +787,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
      */
@@ -720,13 +812,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;
 }
@@ -944,6 +1045,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: {
@@ -972,6 +1092,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;
@@ -1279,6 +1410,13 @@ export declare interface CrosshairPosition {
     y: number;
 }
 
+/**
+ * @deprecated Use a named preset instead — `catppuccin.theme` is the new
+ * default dark palette, and `dracula`, `nightOwl`, `oneDarkPro`, `gruvbox`,
+ * `monokaiPro`, `materialPalenight`, or `panda` cover the rest of the
+ * dark spectrum. `darkTheme` is kept as an alias for the previous default
+ * and will be removed in a future major release.
+ */
 export declare const darkTheme: ChartTheme;
 
 export declare function detectInterval(times: number[]): number;
@@ -1414,6 +1552,13 @@ declare type LegendMode = 'toggle' | 'isolate' | 'solo';
 
 export declare const lightPink: ThemePreset;
 
+/**
+ * @deprecated Use a named light preset instead — `quietLight`, `githubLight`,
+ * `solarizedLight`, `minimalLight`, `peachCream`, `sandDune`, `lightPink`,
+ * `lavenderMist`, `mintBreeze`, `rosePineDawn`, or `handwritten`. `lightTheme`
+ * is kept as an alias for the previous default and will be removed in a
+ * future major release.
+ */
 export declare const lightTheme: ChartTheme;
 
 /** @deprecated Use {@link TimePoint} instead. */
@@ -1447,11 +1592,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'. */
@@ -1467,12 +1624,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
      */
@@ -1480,13 +1649,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;
 }