@wick-charts/vue 0.6.0 → 0.6.1

package/dist/core/dist/components/crosshair.js

@@ -1,9 +1,11 @@
-function d(r, s, l, x) {
-  const { context: t, bitmapSize: e, horizontalPixelRatio: o, verticalPixelRatio: c } = r, a = Math.max(1, Math.round(c)), i = Math.max(1, Math.round(o));
-  t.strokeStyle = x.crosshair.color, t.lineWidth = Math.max(a, i), t.setLineDash([4 * o, 4 * o]);
-  const h = Math.round(s) + (i % 2 === 1 ? 0.5 : 0), n = Math.round(l) + (a % 2 === 1 ? 0.5 : 0);
-  t.beginPath(), t.moveTo(h, 0), t.lineTo(h, e.height), t.moveTo(0, n), t.lineTo(e.width, n), t.stroke(), t.setLineDash([]);
+function u(m) {
+  const { scope: x, bitmapX: o, bitmapY: i, theme: M, pane: a } = m, { context: t, bitmapSize: h, horizontalPixelRatio: e, verticalPixelRatio: p } = x, n = o <= a.width, r = i <= a.height;
+  if (!n && !r) return;
+  const s = Math.max(1, Math.round(p)), c = Math.max(1, Math.round(e));
+  t.strokeStyle = M.crosshair.color, t.lineWidth = Math.max(s, c), t.setLineDash([4 * e, 4 * e]);
+  const l = Math.round(o) + (c % 2 === 1 ? 0.5 : 0), d = Math.round(i) + (s % 2 === 1 ? 0.5 : 0);
+  t.beginPath(), n && (t.moveTo(l, 0), t.lineTo(l, h.height)), r && (t.moveTo(0, d), t.lineTo(h.width, d)), t.stroke(), t.setLineDash([]);
 }
 export {
-  d as renderCrosshair
+  u as renderCrosshair
 };

package/dist/core/dist/interactions/handler.js

@@ -6,8 +6,8 @@ function i(o, e) {
   const t = o.clientX - e.clientX, s = o.clientY - e.clientY;
   return Math.hypot(t, s);
 }
-const d = 5, v = 500;
-class M extends a {
+const d = 5, m = 500;
+class T extends a {
   zoom;
   pan;
   canvas;
@@ -15,13 +15,27 @@ class M extends a {
   yScale;
   target;
   constructor(e, t, s, n) {
-    super(), this.canvas = e, this.target = t, this.timeScale = s, this.yScale = n, this.zoom = new r(t, s), this.pan = new u(t, s, e), e.style.cursor = "crosshair", e.style.touchAction = "none", e.addEventListener("wheel", this.onWheel, { passive: !1 }), e.addEventListener("mousedown", this.onMouseDown), e.addEventListener("mousemove", this.onMouseMove), e.addEventListener("mouseup", this.onMouseUp), e.addEventListener("mouseleave", this.onMouseLeave), e.addEventListener("click", this.onClick), e.addEventListener("dblclick", this.onDblClick), e.addEventListener("touchstart", this.onTouchStart, { passive: !1 }), e.addEventListener("touchmove", this.onTouchMove, { passive: !1 }), e.addEventListener("touchend", this.onTouchEnd), e.addEventListener("touchcancel", this.onTouchCancel);
+    super(), this.canvas = e, this.target = t, this.timeScale = s, this.yScale = n, this.zoom = new r(t, s), this.pan = new u(t, s, e), e.style.cursor = "crosshair", this.syncPanZoomMode(), e.addEventListener("wheel", this.onWheel, { passive: !1 }), e.addEventListener("mousedown", this.onMouseDown), e.addEventListener("mousemove", this.onMouseMove), e.addEventListener("mouseup", this.onMouseUp), e.addEventListener("mouseleave", this.onMouseLeave), e.addEventListener("click", this.onClick), e.addEventListener("dblclick", this.onDblClick), e.addEventListener("touchstart", this.onTouchStart, { passive: !1 }), e.addEventListener("touchmove", this.onTouchMove, { passive: !1 }), e.addEventListener("touchend", this.onTouchEnd), e.addEventListener("touchcancel", this.onTouchCancel);
+  }
+  /** Live read of the target's capability — series can be added or removed at any time. */
+  panZoomEnabled() {
+    return this.target.canPanZoom?.() ?? !0;
+  }
+  /**
+   * Reflect the target's pan/zoom capability into the canvas CSS. While
+   * pan/zoomable, `touch-action: none` hands every touch gesture to the
+   * chart; on a spatial-only target native scrolling stays enabled so the
+   * chart doesn't trap the page. The host re-invokes this whenever the
+   * series mix changes.
+   */
+  syncPanZoomMode() {
+    this.canvas.style.touchAction = this.panZoomEnabled() ? "none" : "auto";
   }
   onWheel = (e) => {
-    this.zoom.handleWheel(e);
+    this.panZoomEnabled() && this.zoom.handleWheel(e);
   };
   onMouseDown = (e) => {
-    this.zoom.cancelPendingRebound(), this.pan.handleMouseDown(e), this.downClient = { x: e.clientX, y: e.clientY };
+    this.zoom.cancelPendingRebound(), this.panZoomEnabled() && this.pan.handleMouseDown(e), this.downClient = { x: e.clientX, y: e.clientY };
   };
   onMouseMove = (e) => {
     this.pan.isDragging() && this.pan.handleMouseMove(e), this.emitCrosshair(e.offsetX, e.offsetY);
@@ -54,36 +68,38 @@ class M extends a {
   // synthesize a phantom 'click'.
   gestureHadTwoFingers = !1;
   onTouchStart = (e) => {
-    e.preventDefault(), this.zoom.cancelPendingRebound(), this.touchCount = e.touches.length, e.touches.length === 1 ? (this.pan.handleMouseDown({
+    this.panZoomEnabled() && (e.preventDefault(), this.zoom.cancelPendingRebound(), this.touchCount = e.touches.length, e.touches.length === 1 ? (this.pan.handleMouseDown({
       button: 0,
       clientX: e.touches[0].clientX
-    }), this.downClient = { x: e.touches[0].clientX, y: e.touches[0].clientY }, this.touchDownTime = Date.now(), this.gestureHadTwoFingers = !1) : e.touches.length === 2 && (this.lastTouchDist = i(e.touches[0], e.touches[1]), this.gestureHadTwoFingers = !0);
+    }), this.downClient = { x: e.touches[0].clientX, y: e.touches[0].clientY }, this.touchDownTime = Date.now(), this.gestureHadTwoFingers = !1) : e.touches.length === 2 && (this.lastTouchDist = i(e.touches[0], e.touches[1]), this.gestureHadTwoFingers = !0));
   };
   onTouchMove = (e) => {
-    if (e.preventDefault(), e.touches.length === 1 && this.touchCount === 1)
-      this.pan.handleMouseMove({
-        clientX: e.touches[0].clientX
-      });
-    else if (e.touches.length === 2) {
-      const t = i(e.touches[0], e.touches[1]), s = (e.touches[0].clientX + e.touches[1].clientX) / 2, n = this.canvas.getBoundingClientRect();
-      if (t > 0 && this.lastTouchDist > 0) {
-        const h = l(this.lastTouchDist / t, 0.1, 10), c = this.timeScale.xToTime(s - n.left);
-        this.target.zoomAt(c, h, this.timeScale.getMediaWidth());
+    if (this.panZoomEnabled()) {
+      if (e.preventDefault(), e.touches.length === 1 && this.touchCount === 1)
+        this.pan.handleMouseMove({
+          clientX: e.touches[0].clientX
+        });
+      else if (e.touches.length === 2) {
+        const t = i(e.touches[0], e.touches[1]), s = (e.touches[0].clientX + e.touches[1].clientX) / 2, n = this.canvas.getBoundingClientRect();
+        if (t > 0 && this.lastTouchDist > 0) {
+          const h = l(this.lastTouchDist / t, 0.1, 10), c = this.timeScale.xToTime(s - n.left);
+          this.target.zoomAt(c, h, this.timeScale.getMediaWidth());
+        }
+        this.lastTouchDist = t;
       }
-      this.lastTouchDist = t;
     }
   };
   onTouchEnd = (e) => {
     if (e.touches.length === 0) {
       const t = e.changedTouches[0];
-      if (this.touchCount === 1 && !this.gestureHadTwoFingers && t && !this.movedBeyondClickTolerance(t.clientX, t.clientY) && Date.now() - this.touchDownTime <= v) {
+      if (this.touchCount === 1 && !this.gestureHadTwoFingers && t && !this.movedBeyondClickTolerance(t.clientX, t.clientY) && Date.now() - this.touchDownTime <= m) {
         const s = this.canvas.getBoundingClientRect();
         this.emit("click", this.posFromOffset(t.clientX - s.left, t.clientY - s.top));
       }
       this.pan.handleMouseUp(), this.touchCount = 0, this.lastTouchDist = 0, this.downClient = null, this.gestureHadTwoFingers = !1, this.emit("crosshairMove", null);
       return;
     }
-    e.touches.length === 1 && (this.touchCount = 1, this.lastTouchDist = 0, this.pan.handleMouseDown({ button: 0, clientX: e.touches[0].clientX }), this.downClient = { x: e.touches[0].clientX, y: e.touches[0].clientY }, this.touchDownTime = Date.now());
+    e.touches.length === 1 && this.touchCount === 2 && (this.touchCount = 1, this.lastTouchDist = 0, this.pan.handleMouseDown({ button: 0, clientX: e.touches[0].clientX }), this.downClient = { x: e.touches[0].clientX, y: e.touches[0].clientY }, this.touchDownTime = Date.now());
   };
   onTouchCancel = () => {
     this.pan.handleMouseUp(), this.touchCount = 0, this.lastTouchDist = 0, this.downClient = null, this.gestureHadTwoFingers = !1, this.emit("crosshairMove", null);
@@ -104,5 +120,5 @@ class M extends a {
   }
 }
 export {
-  M as InteractionHandler
+  T as InteractionHandler
 };

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.
@@ -2117,6 +2152,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 +2276,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 +2424,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 +2803,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 +3763,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;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wick-charts/vue",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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.1"
   },
   "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'];