@wick-charts/vue 0.6.0 → 0.6.2

package/dist/core/dist/utils/pixel-grid.js

@@ -0,0 +1,10 @@
+function r(n) {
+  return Math.max(1, Math.round(n));
+}
+function t(n) {
+  return r(n) % 2 === 1 ? 0.5 : 0;
+}
+export {
+  t as crispCenterOffset,
+  r as crispLineWidth
+};

package/dist/index.d.ts

@@ -6,6 +6,12 @@ import { Ref } from 'vue';
 import { ShallowRef } from 'vue';
 
 declare const __VLS_component: DefineComponent<__VLS_Props_3, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_3> & Readonly<{}>, {
+fade: boolean | {
+top?: number;
+overlap?: number;
+right?: number;
+left?: number;
+};
 theme: ChartTheme;
 gradient: boolean;
 interactive: boolean;
@@ -275,6 +281,35 @@ declare type __VLS_Props_3 = {
     grid?: {
         visible: boolean;
     };
+    /**
+     * Soft fade-out at the top of the plot area, so series content dissolves
+     * under a floating `<Title>` / `<InfoBar>` instead of colliding with it.
+     * The mask erases canvas alpha rather than painting a cover color, so it
+     * stays correct over the default background gradient. Live.
+     *
+     * Two directions, independently controlled:
+     *
+     * **X (under the axis)** — panning content slides under the Y-axis
+     * column and dissolves instead of hard-clipping at the pane edge. **On
+     * by default** as a 60px ramp that finishes just inside the axis
+     * column, before the label glyphs; `{ right }` overrides the total
+     * ramp width in CSS px (`0` disables). `{ left }` adds the mirror zone
+     * at the left pane edge (default off).
+     *
+     * **Top (under the header)** — opt-in. `true` enables the auto zone
+     * (measured header + 24px run-out, half the header fold-in released so
+     * data rides up into the zone at rest), `{ top }` sets the zone height
+     * explicitly, and `{ overlap }` tunes how many px of the fold-in to
+     * release (0 keeps the strict fold-in). Off unless one of those is set.
+     *
+     * `false` — every mask off, strict edges everywhere.
+     */
+    fade?: boolean | {
+        top?: number;
+        overlap?: number;
+        right?: number;
+        left?: number;
+    };
     /**
      * How `<Title>` and `<InfoBar>` are positioned relative to the canvas. Live.
      * - `'overlay'` (default): absolute overlays on top of the canvas.
@@ -725,6 +760,15 @@ export declare interface AnimationsConfig {
          * @default {@link DEFAULT_TICKS_MS}
          */
         ticks?: AnimationTime;
+        /**
+         * Gridline layer opacity: the opening reveal on first paint and the
+         * fade out when `grid.visible` flips off. Independent of
+         * {@link ticks}, which owns the per-tick cross-fade on relabel.
+         * `false` makes the grid appear and disappear instantly.
+         *
+         * @default {@link DEFAULT_GRID_MS}
+         */
+        grid?: AnimationTime;
     };
     /**
      * Series-visibility toggle duration. Drives BOTH the renderer's alpha
@@ -2117,6 +2161,13 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
         color: string;
     }[] | null;
     getSeriesIds(): string[];
+    /**
+     * Whether pan/zoom gestures currently apply — true when any visible series
+     * has a time axis. Part of the {@link PanZoomTarget} surface: on a
+     * spatial-only chart (pie, heatmap) the interaction layer stops capturing
+     * wheel and touch events, so the page scrolls normally under the cursor.
+     */
+    canPanZoom(): boolean;
     /**
      * Filter `getSeriesIds()` by renderer type. A concrete kind (`'pie'`,
      * `'heatmap'`, a custom kind, …) returns series of that exact kind;
@@ -2234,6 +2285,14 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> implements
     setGrid(grid: {
         visible: boolean;
     }): void;
+    /**
+     * Set or clear the edge fade masks (see {@link ChartOptions.fade}).
+     * Content the main layer draws inside a zone dissolves toward that edge.
+     * `right` omitted re-arms its default (track the Y-axis width); pass
+     * `{ top: 0, right: 0, left: 0 }` to turn every mask off. Takes effect on
+     * the next render frame.
+     */
+    setFade(fade: ChartOptions['fade']): void;
     /**
      * Set the visual state for one side of the chart. Typically called in
      * response to the `onEdgeReached` callback:
@@ -2374,6 +2433,18 @@ export declare interface ChartOptions {
     grid?: {
         visible: boolean;
     };
+    /**
+     * Soft alpha fade applied at the edges of the plot area. Anything the main
+     * layer draws inside a zone (series, grid, time-region bands) dissolves to
+     * transparent as it approaches the edge: horizontally sliding under the
+     * Y-axis labels on the right (`right`, **on by default**), toward a
+     * floating Title / InfoBar at the top (`top`), or out the left edge
+     * (`left`). The mask *erases* pixels rather than painting a cover color,
+     * so it stays correct over any container background — including the
+     * default CSS gradient. Live — `chart.setFade()` updates it after
+     * construction.
+     */
+    fade?: FadeConfig;
     /**
      * Animation control. Grouped as `axis: { y, x, ticks }` (axis-side
      * behaviour), `toggle` (series visibility — alpha + Y refit), and
@@ -2741,6 +2812,27 @@ declare class EventEmitter<Events = Record<string, Listener>> {
     removeAllListeners(): void;
 }
 
+/** Shape of {@link ChartOptions.fade}. */
+declare interface FadeConfig {
+    /** Fade-zone height in CSS pixels, measured down from the top of the plot
+     *  area. `0` / omitted disables the mask. */
+    top?: number;
+    /**
+     * Total width in CSS pixels of the horizontal dissolve at the right edge.
+     * The ramp finishes just inside the Y-axis column — 12px past the pane
+     * edge, before the right-anchored label glyphs start — so content melts
+     * on approach (pan / tail-scroll exit) and is fully gone before it can
+     * cross any axis text; the rest of the width runs backward into the pane
+     * as a soft lead-in. **Defaults to a 60px ramp** — on out of the box;
+     * `0` disables. A no-op while the Y axis is hidden.
+     */
+    right?: number;
+    /** Fade-zone width in CSS pixels at the left pane edge — content panning
+     *  out to the left dissolves instead of hard-clipping at the canvas
+     *  boundary. `0` / omitted disables. */
+    left?: number;
+}
+
 /**
  * Plain staggered fade-in, no geometry motion. Works for both bar and
  * candlestick series.
@@ -3680,6 +3772,13 @@ declare interface PanZoomTarget {
      * `chartWidth` participates in soft-bound math the same way as in `pan`.
      */
     zoomAt(centerTime: number, factor: number, chartWidth?: number): void;
+    /**
+     * Whether pan/zoom gestures currently apply to this target. A spatial-only
+     * chart (pie, heatmap) has no time axis to gesture on, so the interaction
+     * layer leaves wheel and touch events to the page — scrolling past the
+     * chart keeps working. Targets that omit the hook are always pan/zoomable.
+     */
+    canPanZoom?(): boolean;
 }
 
 /**
@@ -5009,7 +5108,17 @@ export declare class XScale {
     formatX(timestamp: number, interval: number): string;
     private resetHysteresis;
     timeToX(time: number): number;
+    /** X in physical (bitmap) pixels, snapped to the pixel grid — for
+     *  axis-aligned edges that have to stay crisp. */
     timeToBitmapX(time: number): number;
+    /** Same in physical pixels, off the grid — see {@link YScale.valueToBitmapYExact}. */
+    timeToBitmapXExact(time: number): number;
+    /**
+     * X position in CSS pixels of the *stroke center* the canvas grid draws for
+     * `time`. DOM axis labels position off this instead of raw {@link timeToX}
+     * so text and gridline share one pixel grid.
+     */
+    timeToSnappedX(time: number): number;
     xToTime(x: number): number;
     pixelDeltaToTimeDelta(pixelDelta: number): number;
     barWidthMedia(dataInterval: number): number;
@@ -5131,8 +5240,21 @@ export declare class YScale {
     setTickGenerator(fn: ValueTickGenerator | null): void;
     /** Convert a value to a Y position in CSS (media) pixels. */
     valueToY(value: number): number;
-    /** Convert a value to a Y position in physical (bitmap) pixels. */
+    /** Convert a value to a Y position in physical (bitmap) pixels, snapped to
+     *  the pixel grid — for axis-aligned edges that have to stay crisp. */
     valueToBitmapY(value: number): number;
+    /**
+     * Same in physical pixels, off the grid. Anti-aliased geometry reads this
+     * one: snapping buys a diagonal stroke no sharpness, and during a slow
+     * animation it quantises the motion into whole-pixel jumps.
+     */
+    valueToBitmapYExact(value: number): number;
+    /**
+     * Y position in CSS pixels of the *stroke center* the canvas grid draws for
+     * `value`. DOM axis labels position off this instead of raw {@link valueToY}
+     * so text and gridline share one pixel grid.
+     */
+    valueToSnappedY(value: number): number;
     /** Convert a Y position in CSS pixels back to a value. */
     yToValue(y: number): number;
     /**

package/dist/ui/YLabel.vue.js

@@ -1,8 +1,9 @@
 import { defineComponent as q, useSlots as j, computed as n, ref as I, onMounted as G, onUnmounted as P, openBlock as w, createElementBlock as B, Fragment as A, renderSlot as W, createElementVNode as _, normalizeStyle as T, unref as H, createVNode as J, createCommentVNode as K } from "vue";
-import { resolveAnimate as Q, prefersReducedMotion as X, firstVisibleValue as Z, BadgeAnimator as ee } from "../core/dist/chart/badge-animator.js";
+import { prefersReducedMotion as Q } from "../core/dist/animation/reduced-motion.js";
+import { resolveAnimate as X, firstVisibleValue as Z, BadgeAnimator as ee } from "../core/dist/chart/badge-animator.js";
 import { useChartInstance as te } from "../context.js";
 import ne from "./NumberFlow.vue.js";
-const re = /* @__PURE__ */ q({
+const ie = /* @__PURE__ */ q({
   __name: "YLabel",
   props: {
     seriesId: {},
@@ -12,18 +13,18 @@ const re = /* @__PURE__ */ q({
   },
   setup(z) {
     const f = z, e = te(), Y = j(), E = n(() => typeof Y.default == "function"), i = I(0), u = I(null);
-    let m = null, g = null, o = null;
-    const M = n(() => Q(f.animate));
-    function S() {
+    let p = null, g = null, o = null;
+    const M = n(() => X(f.animate));
+    function L() {
       o = null;
       const t = s.value, l = t !== null ? e.getStackedLastValue(t) : null;
       if (t === null || !l) {
-        m = null, g = null;
+        p = null, g = null;
         return;
       }
       const v = l.value;
-      (m === null || g !== t) && (m = new ee(v), g = t);
-      const { glide: d, countUp: U, settleMs: $ } = M.value, F = e.getIntroFront(t), c = m.frame({
+      (p === null || g !== t) && (p = new ee(v), g = t);
+      const { glide: d, countUp: U, settleMs: $ } = M.value, F = e.getIntroFront(t), c = p.frame({
         target: v,
         // Only needed for the intro count-up; skip the visible-range binary search
         // entirely once the reveal has settled (the hot streaming path).
@@ -33,20 +34,20 @@ const re = /* @__PURE__ */ q({
         glide: d,
         countUp: U,
         settleMs: $,
-        reducedMotion: X()
+        reducedMotion: Q()
       }), y = u.value;
-      (y === null || y.positionValue !== c.positionValue || y.textValue !== c.textValue || y.opacity !== c.opacity) && (u.value = { positionValue: c.positionValue, textValue: c.textValue, opacity: c.opacity }), c.animating && o === null && (o = requestAnimationFrame(S));
+      (y === null || y.positionValue !== c.positionValue || y.textValue !== c.textValue || y.opacity !== c.opacity) && (u.value = { positionValue: c.positionValue, textValue: c.textValue, opacity: c.opacity }), c.animating && o === null && (o = requestAnimationFrame(L));
     }
     function N() {
-      o === null && (o = requestAnimationFrame(S));
+      o === null && (o = requestAnimationFrame(L));
     }
-    const p = () => {
+    const m = () => {
       i.value++, N();
     };
     G(() => {
-      e.setYLabel(!0), e.on("overlayChange", p), e.on("viewportChange", p), e.getSeriesIds().length > 0 && p();
+      e.setYLabel(!0), e.on("overlayChange", m), e.on("viewportChange", m), e.getSeriesIds().length > 0 && m();
     }), P(() => {
-      e.setYLabel(!1), e.off("overlayChange", p), e.off("viewportChange", p), o !== null && cancelAnimationFrame(o), o = null;
+      e.setYLabel(!1), e.off("overlayChange", m), e.off("viewportChange", m), o !== null && cancelAnimationFrame(o), o = null;
     });
     function O(t, l) {
       if (l !== void 0) return l;
@@ -55,11 +56,11 @@ const re = /* @__PURE__ */ q({
       const d = t.getSeriesIdsByType("time", { visibleOnly: !0 });
       return d.length > 0 ? d[0] : null;
     }
-    const s = n(() => (i.value, O(e, f.seriesId))), a = n(() => (i.value, s.value !== null ? e.getStackedLastValue(s.value) : null)), b = n(() => (i.value, s.value !== null ? e.getPreviousClose(s.value) : null)), r = n(() => (i.value, e.getTheme())), R = n(() => u.value !== null ? u.value.positionValue : a.value?.value ?? 0), D = n(() => u.value !== null ? u.value.textValue : a.value?.value ?? 0), h = n(() => u.value !== null ? u.value.opacity : s.value === null ? 1 : e.getIntroFront(s.value) < 1 ? 0 : 1), x = n(() => (i.value, a.value === null ? 0 : e.yScale.valueToY(R.value))), L = n(() => a.value === null || b.value === null ? "neutral" : a.value.value > b.value ? "up" : a.value.value < b.value ? "down" : "neutral"), V = n(() => {
+    const s = n(() => (i.value, O(e, f.seriesId))), a = n(() => (i.value, s.value !== null ? e.getStackedLastValue(s.value) : null)), b = n(() => (i.value, s.value !== null ? e.getPreviousClose(s.value) : null)), r = n(() => (i.value, e.getTheme())), R = n(() => u.value !== null ? u.value.positionValue : a.value?.value ?? 0), D = n(() => u.value !== null ? u.value.textValue : a.value?.value ?? 0), h = n(() => u.value !== null ? u.value.opacity : s.value === null ? 1 : e.getIntroFront(s.value) < 1 ? 0 : 1), x = n(() => (i.value, a.value === null ? 0 : e.yScale.valueToY(R.value))), S = n(() => a.value === null || b.value === null ? "neutral" : a.value.value > b.value ? "up" : a.value.value < b.value ? "down" : "neutral"), V = n(() => {
       if (a.value === null) return r.value.yLabel.neutralBackground;
       if (!a.value.isLive) return r.value.axis.textColor;
       if (f.color) return f.color;
-      switch (L.value) {
+      switch (S.value) {
         case "up":
           return r.value.yLabel.upBackground;
         case "down":
@@ -87,7 +88,7 @@ const re = /* @__PURE__ */ q({
         y: x.value,
         bgColor: V.value,
         isLive: a.value.isLive,
-        direction: L.value,
+        direction: S.value,
         format: C.value,
         opacity: h.value
       }) : (w(), B(A, { key: 1 }, [
@@ -134,5 +135,5 @@ const re = /* @__PURE__ */ q({
   }
 });
 export {
-  re as default
+  ie as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wick-charts/vue",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "High-performance canvas timeseries charts for Vue — candlestick, line, bar, pie. Tree-shakeable, zero runtime deps.",
   "license": "MIT",
   "repository": {
@@ -45,7 +45,7 @@
     "vue": ">=3.3.0"
   },
   "devDependencies": {
-    "@wick-charts/core": "^0.6.0"
+    "@wick-charts/core": "^0.6.2"
   },
   "scripts": {
     "build": "vite build"

package/src/ChartContainer.vue

@@ -7,6 +7,7 @@ import {
   type ChartTheme,
   type CrosshairPosition,
   type EdgeReachedInfo,
+  type FadeConfig,
   type PointClickInfo,
   type SeriesHoverInfo,
   type VisibleRange,
@@ -91,6 +92,30 @@ const props = withDefaults(
     interactive?: boolean;
     /** Background grid configuration. Live. Default: `{ visible: true }`. */
     grid?: { visible: boolean };
+    /**
+     * Soft fade-out at the top of the plot area, so series content dissolves
+     * under a floating `<Title>` / `<InfoBar>` instead of colliding with it.
+     * The mask erases canvas alpha rather than painting a cover color, so it
+     * stays correct over the default background gradient. Live.
+     *
+     * Two directions, independently controlled:
+     *
+     * **X (under the axis)** — panning content slides under the Y-axis
+     * column and dissolves instead of hard-clipping at the pane edge. **On
+     * by default** as a 60px ramp that finishes just inside the axis
+     * column, before the label glyphs; `{ right }` overrides the total
+     * ramp width in CSS px (`0` disables). `{ left }` adds the mirror zone
+     * at the left pane edge (default off).
+     *
+     * **Top (under the header)** — opt-in. `true` enables the auto zone
+     * (measured header + 24px run-out, half the header fold-in released so
+     * data rides up into the zone at rest), `{ top }` sets the zone height
+     * explicitly, and `{ overlap }` tunes how many px of the fold-in to
+     * release (0 keeps the strict fold-in). Off unless one of those is set.
+     *
+     * `false` — every mask off, strict edges everywhere.
+     */
+    fade?: boolean | { top?: number; overlap?: number; right?: number; left?: number };
     /**
      * How `<Title>` and `<InfoBar>` are positioned relative to the canvas. Live.
      * - `'overlay'` (default): absolute overlays on top of the canvas.
@@ -168,6 +193,11 @@ const props = withDefaults(
     // because it already had a default.
     interactive: true,
     headerLayout: 'overlay',
+    // Same Boolean-cast trap, opposite goal: an absent `fade` must stay
+    // `undefined` (keep the core's default X mask armed) and remain
+    // distinguishable from an explicit `:fade="false"` all-off opt-out.
+    // Declaring a default (even `undefined`) suppresses the cast.
+    fade: undefined,
   },
 );
 
@@ -199,9 +229,49 @@ provide(NavigatorAnchorKey, navigatorAnchor);
 let resizeObserver: ResizeObserver | null = null;
 const topOverlayHeight = ref(0);
 
+/** Run-out below the measured header (CSS px) for the auto `fade` zone —
+ *  content starts dissolving this far before it slides under the header. */
+const FADE_AUTO_BAND = 24;
+
+// Fade resolution — shared by the header fold-in below and `applyFade`.
+// Vue casts an absent Boolean-typed prop to `false`, which conveniently is
+// also the "off" value here. `overlap` deliberately applies only while the
+// fade is on: without the mask, letting data ride under the header would
+// just recreate the collision the strict fold-in exists to prevent.
+// The top mask is opt-in: `true`, `{ top }`, or `{ overlap }` arms it (a
+// pure X config like `{ right: 0 }` does not).
+const fadeEnabled = computed(() => {
+  if (props.fade === false) return false;
+
+  return typeof props.fade === 'object'
+    ? props.fade.top !== undefined || props.fade.overlap !== undefined
+    : props.fade === true;
+});
+// Auto overlap: half the measured header — with the full fold-in intact the
+// zone would cover only padding and enabling the fade would change nothing
+// visible at rest. Explicit `overlap` (including 0) wins.
+const fadeOverlap = computed(() => {
+  if (!fadeEnabled.value) return 0;
+
+  const explicit = typeof props.fade === 'object' ? props.fade.overlap : undefined;
+  if (explicit !== undefined) return Math.max(0, explicit);
+
+  return topOverlayHeight.value / 2;
+});
+const resolvedFadeTop = computed(() => {
+  if (!fadeEnabled.value) return 0;
+  if (typeof props.fade === 'object' && props.fade.top !== undefined) return props.fade.top;
+
+  const measured = props.headerLayout === 'overlay' ? topOverlayHeight.value : 0;
+
+  return measured > 0 ? measured + FADE_AUTO_BAND : FADE_AUTO_BAND;
+});
+
 // Inline mode: browser flex already reserves header height, so folding it
 // into padding.top would double-shift the data. Only overlay needs the fold.
-const headerExtra = computed(() => (props.headerLayout === 'overlay' ? topOverlayHeight.value : 0));
+const headerExtra = computed(() =>
+  props.headerLayout === 'overlay' ? Math.max(0, topOverlayHeight.value - fadeOverlap.value) : 0,
+);
 
 function applyPadding() {
   if (!chart.value) return;
@@ -213,6 +283,43 @@ function applyPadding() {
   chart.value.setPadding(merged);
 }
 
+/** Seed the constructor's fade config so the very first frame is already
+ *  correct — `applyFade` lands the header-measured top zone right after, but
+ *  an opted-out chart must not flash the default X mask for one paint. */
+function seedFadeOption(options: ChartOptions): void {
+  if (props.fade === false) {
+    options.fade = { top: 0, right: 0, left: 0 };
+
+    return;
+  }
+  if (typeof props.fade !== 'object') return;
+
+  const seed: FadeConfig = {};
+  if (props.fade.top !== undefined) seed.top = props.fade.top;
+  if (props.fade.right !== undefined) seed.right = props.fade.right;
+  if (props.fade.left !== undefined) seed.left = props.fade.left;
+  options.fade = seed;
+}
+
+function applyFade() {
+  if (!chart.value) return;
+
+  if (props.fade === false) {
+    chart.value.setFade({ top: 0, right: 0, left: 0 });
+
+    return;
+  }
+
+  // Omitting `right` keeps the core's under-the-axis default armed; only an
+  // explicit value (or the all-off branch above) overrides it.
+  const next: FadeConfig = { top: resolvedFadeTop.value };
+  if (typeof props.fade === 'object') {
+    if (props.fade.right !== undefined) next.right = props.fade.right;
+    if (props.fade.left !== undefined) next.left = props.fade.left;
+  }
+  chart.value.setFade(next);
+}
+
 // Wires up (or tears down) the header-height observer for the current
 // `headerLayout`. Called on mount AND whenever `headerLayout` flips at
 // runtime — overlay needs a live measurement, inline lets browser flex
@@ -268,6 +375,7 @@ onMounted(async () => {
   if (perfAtMount !== undefined) options.perf = perfAtMount;
   if (onEdgeReachedAtMount) options.onEdgeReached = onEdgeReachedAtMount;
   if (props.animations !== undefined) options.animations = props.animations;
+  seedFadeOption(options);
   chart.value = new ChartInstance(containerRef.value, options);
   subscribeDeclarativeEvents(chart.value);
   props.onReady?.(chart.value);
@@ -352,6 +460,7 @@ watch(
     if (perfAtMount !== undefined) opts.perf = perfAtMount;
     if (onEdgeReachedAtMount) opts.onEdgeReached = onEdgeReachedAtMount;
     if (next !== undefined) opts.animations = next;
+    seedFadeOption(opts);
     chart.value = new ChartInstance(containerRef.value, opts);
     subscribeDeclarativeEvents(chart.value);
     props.onReady?.(chart.value);
@@ -404,6 +513,12 @@ watch(
   applyPadding,
 );
 
+// Fade rides the chart identity too, so a rebuilt instance (an `animations`
+// change) receives the current zones again; `setFade` no-ops on unchanged
+// values, so the extra fires are free. `immediate` covers the mount path —
+// the first run lands right after `chart.value` is set.
+watch(() => [chart.value, resolvedFadeTop.value, props.fade] as const, applyFade, { immediate: true });
+
 const rootStyle = computed(() => {
   const t = themeRef.value;
   const [gtop, gbot] = t?.chartGradient ?? ['transparent', 'transparent'];