@wick-charts/vue 0.4.1 → 0.4.2

package/README.md

@@ -63,9 +63,9 @@ Tree-shaken React scenarios via `pnpm size` (esbuild, minified, browser target,
 
 | Scenario | Raw | Gzip | Brotli |
 |---|---:|---:|---:|
-| Candlestick only | 165.2 kB | 49.5 kB | 42.3 kB |
-| Line only        | 165.3 kB | 49.5 kB | 42.4 kB |
-| Full React       | 183.3 kB | 54.6 kB | 46.5 kB |
+| Candlestick only | 174.1 kB | 52.4 kB | 44.8 kB |
+| Line only        | 174.1 kB | 52.5 kB | 44.8 kB |
+| Full React       | 191.2 kB | 57.4 kB | 49.0 kB |
 
 ## Migration
 

package/dist/index.d.ts

@@ -815,6 +815,41 @@ export declare const ayuMirage: ThemePreset;
  */
 declare type BarEntryAnimation = 'none' | 'fade' | 'grow' | 'slide' | 'fade-grow';
 
+/** Post-transform bitmap rectangle a bar painter fills. */
+declare interface BarGeometry {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** The edge the bar grows from — the zero line, or the segment's own base. */
+    baselineY: number;
+}
+
+/** Arguments handed to a {@link BarPainter} once per bar / stacked segment. */
+export declare interface BarPaintArgs {
+    geom: BarGeometry;
+    /** Semantic fill color — the legend / tooltip source of truth. */
+    color: string;
+    /**
+     * Free-end-aware corner mask. The renderer computed this from the draw mode
+     * (single / overlap / stacked-positive / stacked-negative / percent). A square
+     * bar arrives as all-false.
+     */
+    corners: CornerMask;
+    /** Resolved, pre-clamped bitmap radius. `0` means square. */
+    radius: number;
+    /**
+     * Entrance progress 0→1; advisory only — `geom` is already transformed by it.
+     * Forced to `1` when `isProjected` (a forecast bar doesn't "arrive").
+     */
+    progress: number;
+    /** Ghost / forecast flag derived from the series' `projectedFrom`. */
+    isProjected: boolean;
+}
+
+/** Paints one bar / stacked segment. Owns its fill — it calls `ctx.fill()`. */
+export declare type BarPainter = (env: PaintEnv, args: BarPaintArgs) => void;
+
 export declare const BarSeries: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** Visual options for a bar series. */
@@ -874,6 +909,33 @@ export declare interface BarSeriesOptions {
      * disable that wins over this field.
      */
     smoothMs?: number | false;
+    /**
+     * Free-end corner radius in CSS pixels. Default: `4`. `0` is byte-identical to
+     * the pre-rounding square output. The radius is clamped to half the smaller
+     * bar dimension, so thin bars / sub-radius segments degrade to flat.
+     *
+     * The renderer decides which edge is "free" per draw mode — a positive bar
+     * rounds its top, a negative bar its bottom, and in a stack only the topmost
+     * (or bottommost) segment per column rounds, interior segments stay square.
+     * `anchor` is orthogonal: rounding operates on the already-offset rect.
+     */
+    cornerRadius?: number;
+    /**
+     * Custom bar painter — a raw `BarPainter` function that owns the bar fill.
+     * Leave unset for the built-in rounded fill (driven by `cornerRadius`). Read
+     * fresh each frame; a new function reference is honored on the next render
+     * regardless of wrapper change-detection. Keep it a stable reference (module
+     * scope or `useCallback`) so the wrapper diffs it cleanly. A throw falls back
+     * to the default fill.
+     */
+    barPainter?: BarPainter;
+    /**
+     * Time (epoch ms) at/after which bars are flagged as projected / forecast
+     * "ghost" bars. The default painter fills those with a translucent derivative
+     * of their color; projected bars also skip the entrance transform so the ghost
+     * never double-fades. Omitted: no projected bars.
+     */
+    projectedFrom?: number;
 }
 
 /**
@@ -920,6 +982,40 @@ export declare interface BuildLastSnapshotsArgs {
     cacheKey: string;
 }
 
+/** Post-transform bitmap rectangle a candle-body painter fills. */
+declare interface CandleGeometry {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+/** Arguments handed to a {@link CandlePainter} once per candle body. */
+export declare interface CandlePaintArgs {
+    geom: CandleGeometry;
+    /**
+     * Engine-resolved fillStyle — the 2-stop gradient when the body color is a
+     * `[top, bottom]` tuple AND the body is tall enough, else the flat color. It
+     * is ALSO pre-set on `ctx.fillStyle`, so a painter that ignores this field
+     * still fills correctly. The painter MUST NOT call `createLinearGradient` —
+     * the ≤2px collapse and gradient build already happened upstream.
+     */
+    fillStyle: string | CanvasGradient;
+    /** Representative flat color (the gradient's top stop). For derived shades. */
+    color: string;
+    /** All-true for candles (no baseline); the radius is clamped per element. */
+    corners: CornerMask;
+    /** Resolved, pre-clamped bitmap radius. `0` means square. */
+    radius: number;
+    /** Entrance progress 0→1; advisory only — `geom` is already transformed. */
+    progress: number;
+    /** `close >= open`. */
+    isBullish: boolean;
+}
+
+/** Paints one candle body. Owns its fill. Never re-creates the gradient. */
+export declare type CandlePainter = (env: PaintEnv, args: CandlePaintArgs) => void;
+
 /**
  * `body` shape encodes the fill mode: a single color renders flat; a
  * `[top, bottom]` tuple renders a 2-stop vertical gradient. Use
@@ -1003,6 +1099,24 @@ export declare interface CandlestickSeriesOptions {
      * a hard disable that wins over this field.
      */
     smoothMs?: number | false;
+    /**
+     * Body corner radius in CSS pixels, applied to all four corners (a candle
+     * body has no baseline). Default: `3`. `0` is byte-identical to the prior
+     * square output. Clamped to half the smaller body dimension, so dojis and
+     * ≤2px bodies degrade to flat. The `[top, bottom]` gradient is preserved —
+     * the painter fills with the engine-resolved gradient and never rebuilds it.
+     */
+    cornerRadius?: number;
+    /**
+     * Custom candle-body painter — a raw `CandlePainter` function that owns the
+     * body fill. Leave unset for the built-in rounded fill (driven by
+     * `cornerRadius`). Read fresh each frame; a new reference is honored on the
+     * next render regardless of wrapper change-detection. Keep it a stable
+     * reference (module scope or `useCallback`) so the wrapper diffs it cleanly.
+     * A throw falls back to the default fill. The wick and volume histogram are
+     * unaffected.
+     */
+    candlePainter?: CandlePainter;
 }
 
 export declare const catppuccin: ThemePreset;
@@ -1664,6 +1778,18 @@ export declare interface ChartTheme {
 
 export declare function computeTooltipPosition(args: TooltipPositionArgs): TooltipPosition;
 
+/**
+ * Which corners a rounded-rect path rounds. A `false` corner is drawn square.
+ * The RENDERER owns this decision (it knows the stack / overlap / percent mode);
+ * a painter consumes the mask verbatim and never infers which edge is free.
+ */
+export declare interface CornerMask {
+    tl: boolean;
+    tr: boolean;
+    br: boolean;
+    bl: boolean;
+}
+
 /**
  * Build a complete {@link ThemePreset} from a partial config.
  * Only `background` is required — everything else is derived from it.
@@ -1684,6 +1810,9 @@ export declare interface CrosshairPosition {
     y: number;
 }
 
+/** Path-shape selector for {@link tracePath}. */
+export declare type CurveKind = 'straight' | 'smooth' | 'stepped';
+
 export declare function detectInterval(times: number[]): number;
 
 export declare const dracula: ThemePreset;
@@ -1717,6 +1846,19 @@ declare class EventEmitter<Events = Record<string, Listener>> {
     removeAllListeners(): void;
 }
 
+/**
+ * Fill a rounded rectangle with per-corner masking, using manual `arcTo` so the
+ * output is deterministic and independent of `CanvasRenderingContext2D.roundRect`
+ * availability. Self-contained: it opens its own path and fills with the current
+ * `ctx.fillStyle`.
+ *
+ * Degenerate inputs — a sub-1px clamped radius, or a non-positive dimension —
+ * fall back to a plain `fillRect`. That guarantees a tiny / 1px bar or a doji can
+ * never emit a zero-radius or `NaN` `arcTo`, byte-matching the pre-rounding
+ * output for those cases.
+ */
+export declare function fillRoundedRect(ctx: CanvasRenderingContext2D, args: RoundedRectArgs): void;
+
 /**
  * Compact notation for large magnitudes (K / M / B / T) with adaptive
  * precision for values below 1. Default decimal count for the compact
@@ -1830,6 +1972,45 @@ export declare const lightPink: ThemePreset;
  */
 declare type LineEntryAnimation = 'none' | 'grow' | 'fade';
 
+/** Arguments handed to a {@link LinePainter} once per finite run. */
+export declare interface LinePaintArgs {
+    /**
+     * One finite run of points — gaps already split runs, and the trailing-grow
+     * endpoint is already appended. Read-only.
+     */
+    points: readonly LinePoint[];
+    color: string;
+    lineWidth: number;
+    /**
+     * `false` while building the stroke path; `true` while building the area-fill
+     * top edge, before the engine appends the baseline `lineTo`×2 + `closePath` +
+     * `fill`.
+     */
+    closing: boolean;
+    /**
+     * `true` while the trailing endpoint is an eased, frame-moving point (the
+     * 'grow' entrance). A smooth builder MUST degrade the in-flight last segment to
+     * a straight `lineTo` (only the settled run is curve-fit) so the head can't
+     * wobble or overshoot while it glides.
+     */
+    grew: boolean;
+}
+
+/**
+ * Builds the path for one finite run. MUST issue only
+ * `moveTo` / `lineTo` / `bezierCurveTo` / `quadraticCurveTo` onto `env.ctx`, and
+ * MUST NOT call `beginPath` / `stroke` / `fill` / `closePath` — the engine wraps
+ * the builder so the SAME path drives both the stroke and the baseline-closed
+ * area polygon.
+ */
+export declare type LinePainter = (env: PaintEnv, args: LinePaintArgs) => void;
+
+/** A single bitmap-space point on a line run. */
+declare interface LinePoint {
+    x: number;
+    y: number;
+}
+
 export declare const LineSeries: DefineComponent<__VLS_Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_4> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /** Visual options for a line series. */
@@ -1918,6 +2099,26 @@ export declare interface LineSeriesOptions {
      * disable that wins over this field.
      */
     smoothMs?: number | false;
+    /**
+     * Declarative line smoothing. Default: `'straight'` (zero visual change —
+     * the prior polyline). Resolves to a shipped built-in path builder inside the
+     * renderer and drives the stroke, the area fill, and stacked slices from one
+     * path:
+     * - `'straight'` — plain polyline.
+     * - `'smooth'` — Fritsch–Carlson monotone cubic (non-overshooting, so it stays
+     *   inside an area fill that closes to a baseline).
+     * - `'stepped'` — horizontal-then-vertical step at each sample.
+     */
+    curve?: 'straight' | 'smooth' | 'stepped';
+    /**
+     * Custom line path builder — a raw `LinePainter` function. Overrides `curve`,
+     * applied per finite run to both the stroke and the area-fill top edge. Read
+     * fresh each frame; keep it a stable reference so the wrapper diffs it cleanly.
+     * A throw falls back to the straight builder. Stacked mode uses the `curve`
+     * kind for gap-free interior tiling, so a custom `linePainter` there falls back
+     * to `'straight'`.
+     */
+    linePainter?: LinePainter;
 }
 
 declare type Listener = (...args: any[]) => void;
@@ -2048,6 +2249,21 @@ export declare type OHLCInput = Omit<OHLCData, 'time'> & {
 
 export declare const oneDarkPro: ThemePreset;
 
+/**
+ * Engine context shared by every painter. `ctx.globalAlpha` is ALREADY composed
+ * (layer × series × entrance fade) by the renderer, and every geometry handed to
+ * a painter is already post-transform. Painters MUST NOT mutate `globalAlpha`
+ * and MUST NOT re-run an entrance transform.
+ */
+export declare interface PaintEnv {
+    ctx: CanvasRenderingContext2D;
+    theme: ChartTheme;
+    /** Horizontal device-pixel ratio — scale your own CSS-px radii / insets by this. */
+    horizontalPixelRatio: number;
+    /** Vertical device-pixel ratio. */
+    verticalPixelRatio: number;
+}
+
 export declare const panda: ThemePreset;
 
 /**
@@ -2355,6 +2571,27 @@ declare interface RetargetOptions {
 
 export declare const rosePineDawn: ThemePreset;
 
+/** DEFAULT bar painter (registered as `'rounded'`). Trusts the engine-supplied
+ *  `corners` / `radius` / `isProjected`; a projected bar fills with a translucent
+ *  derivative of its color instead of mutating `globalAlpha`. */
+export declare const roundedBarFill: BarPainter;
+
+/** DEFAULT candle-body painter (registered as `'rounded'`). Fills with the
+ *  engine-resolved `fillStyle` (gradient or flat) and never rebuilds a gradient. */
+export declare const roundedCandleFill: CandlePainter;
+
+/** Arguments for {@link fillRoundedRect}. */
+export declare interface RoundedRectArgs {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Pre-resolved bitmap radius applied to masked corners. */
+    radius: number;
+    /** Which corners to round; unmasked corners are square. */
+    corners: CornerMask;
+}
+
 export declare const sandDune: ThemePreset;
 
 /**
@@ -2394,6 +2631,10 @@ declare interface Size {
 
 export declare type SliceInfo = HoverInfo;
 
+/** `curve: 'smooth'` — monotone cubic. The in-flight last segment stays straight
+ *  while the trailing endpoint is growing so the head can't wobble / overshoot. */
+export declare const smoothCurve: LinePainter;
+
 /** Sort order applied to a snapshot list by the helper. */
 export declare type SnapshotSort = 'none' | 'asc' | 'desc';
 
@@ -2402,6 +2643,13 @@ export declare const solarizedLight: ThemePreset;
 /** Stacking mode for bar/line series: off (overlap), normal (stacked), percent (100% stacked). */
 export declare type StackingMode = 'off' | 'normal' | 'percent';
 
+/** `curve: 'stepped'` — horizontal-then-vertical step at each sample. */
+export declare const steppedCurve: LinePainter;
+
+/** DEFAULT line builder (`curve: 'straight'`). A plain polyline — identical to
+ *  the pre-feature stroke path. */
+export declare const straightCurve: LinePainter;
+
 /**
  * Input config for {@link createTheme}. Mirrors the structure of {@link ChartTheme}
  * but everything is optional except `background`. Missing values are derived automatically.
@@ -2547,6 +2795,27 @@ export declare interface TooltipPositionArgs {
     offsetY?: number;
 }
 
+/**
+ * Emit path commands for one run of points onto `env.ctx`. Issues only
+ * `moveTo` / `lineTo` / `bezierCurveTo`; it never opens or closes a path, so the
+ * engine can wrap the same trace into both a stroke and a baseline-closed area
+ * polygon. Takes the full {@link PaintEnv} (not the raw context) so a custom
+ * painter can compose on it directly with the `(env, args)` it receives.
+ */
+export declare function tracePath(env: PaintEnv, args: TracePathArgs): void;
+
+/** Arguments for {@link tracePath}. */
+export declare interface TracePathArgs {
+    points: readonly LinePoint[];
+    kind: CurveKind;
+    /**
+     * When `true`, the final segment is drawn as a straight `lineTo` even for the
+     * smooth kind — used while the trailing endpoint is mid-grow so the moving head
+     * can't wobble or overshoot.
+     */
+    settledOnly: boolean;
+}
+
 /**
  * Smoothing-curve contract. Implementations (`YRangeHermite`, `YRangeSpring`,
  * `RangeSnap` for Y; `VisibleRangeSpring`, `RangeSnap` for X) drive a value