@wick-charts/vue 0.5.1 → 0.6.1

package/src/ChartContainer.vue

@@ -5,9 +5,15 @@ import {
   ChartInstance,
   type ChartOptions,
   type ChartTheme,
+  type CrosshairPosition,
   type EdgeReachedInfo,
+  type FadeConfig,
+  type PointClickInfo,
+  type SeriesHoverInfo,
+  type VisibleRange,
   type VisibleRangeSpec,
   catppuccin,
+  deepEqual,
 } from '@wick-charts/core';
 import { computed, nextTick, onMounted, onUnmounted, provide, ref, shallowRef, watch } from 'vue';
 
@@ -25,7 +31,9 @@ type PerfOption = NonNullable<ChartOptions['perf']>;
 
 const props = withDefaults(
   defineProps<{
+    /** Visual theme. Live — changing this at runtime updates all themed elements. */
     theme?: ChartTheme;
+    /** Grouped axis configuration (Y/X visibility, bounds, sizing). Live. */
     axis?: AxisConfig;
     /**
      * Viewport padding. `top`/`bottom` are in pixels. `left`/`right` accept either pixels (`50`)
@@ -61,14 +69,55 @@ const props = withDefaults(
        */
       initialRange?: VisibleRangeSpec;
     };
-    /** Show the chart background gradient. Defaults to true. */
+    /**
+     * Controlled visible range. Same shape as the imperative
+     * `chart.setVisibleRange` — a bar count, an explicit `{from, to}` window,
+     * or `{from, bars}`. Every reference/value change applies via
+     * `chart.setVisibleRange`, so pair it with `onVisibleRangeChange` for a
+     * two-way binding; a same-value literal (compared structurally) is a
+     * no-op, so an inline object doesn't re-apply on every render.
+     *
+     * For a one-shot initial window that isn't re-applied on every prop
+     * change, use `viewport.initialRange` instead.
+     */
+    visibleRange?: VisibleRangeSpec;
+    /** Show the chart background gradient. Live. Defaults to true. */
     gradient?: boolean;
-    /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
+    /**
+     * Enable zoom, pan, and crosshair interactions. Defaults to true.
+     *
+     * Mount-only — core has no `setInteractive`, so changing this prop after
+     * mount is ignored.
+     */
     interactive?: boolean;
-    /** Background grid configuration. Default: `{ visible: true }`. */
+    /** Background grid configuration. Live. Default: `{ visible: true }`. */
     grid?: { visible: boolean };
     /**
-     * How `<Title>` and `<InfoBar>` are positioned relative to the canvas.
+     * 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.
      * - `'inline'`: flex siblings above the canvas — the canvas (and grid) shift down.
      */
@@ -79,10 +128,10 @@ const props = withDefaults(
      * `<CandlestickSeries>` / `<BarSeries>` override these chart-level
      * defaults unless the category here is explicitly `false`.
      *
-     * **Init-only by reference identity.** A new `animations` reference
-     * recreates the underlying `ChartInstance`. Hoist the object outside
-     * the render scope — an inline literal tears the chart down on every
-     * re-render.
+     * **Init-only, but diffed by value, not reference.** A same-value
+     * inline object literal is a no-op — only a genuine change to the
+     * resolved config recreates the underlying `ChartInstance`, since the
+     * animation engine doesn't support live reconfiguration yet.
      */
     animations?: boolean | AnimationsConfig;
     /**
@@ -97,11 +146,58 @@ const props = withDefaults(
      * the prop identity later is ignored.
      */
     onEdgeReached?: (info: EdgeReachedInfo) => void;
+    /**
+     * Fired on a click (or tap) on the chart canvas that isn't the tail end
+     * of a pan drag. `info.spatialHit` resolves a pie/heatmap/custom-spatial
+     * series directly under the pointer; for a time-series series, resolve
+     * the point yourself from `info.time` (`chart.getDataAtTime` /
+     * `buildHoverSnapshots`). Live — the latest callback is always used.
+     */
+    onPointClick?: (info: PointClickInfo) => void;
+    /**
+     * Fired on a double-click on the chart canvas. The chart also responds
+     * by calling `fitContent()`. Live — the latest callback is always used.
+     */
+    onPointDoubleClick?: (info: PointClickInfo) => void;
+    /**
+     * Fired when the spatially-hovered series/index changes (pie, heatmap,
+     * or a custom spatial kind) — `null` when the pointer leaves every hit
+     * area. Live — the latest callback is always used.
+     */
+    onSeriesHover?: (hit: SeriesHoverInfo | null) => void;
+    /**
+     * Fired once the underlying `ChartInstance` is constructed — on mount,
+     * and again if the chart is ever rebuilt (a genuine `animations` value
+     * change). Live — the latest callback is always used for the next rebuild.
+     */
+    onReady?: (chart: ChartInstance) => void;
+    /**
+     * Fired whenever the committed visible range changes — pan, zoom,
+     * `fitContent()`, a data update that shifts the tail-scroll window, or a
+     * `visibleRange` prop change. Live — the latest callback is always used.
+     */
+    onVisibleRangeChange?: (range: VisibleRange) => void;
+    /**
+     * Fired on every crosshair move, with `null` when the pointer leaves the
+     * chart. Live — the latest callback is always used.
+     */
+    onCrosshairMove?: (position: CrosshairPosition | null) => void;
   }>(),
   {
     theme: () => catppuccin.theme,
     gradient: true,
+    // Vue's type-based `defineProps` casts an absent Boolean-typed prop to
+    // `false` (not `undefined`) — without this explicit default, every chart
+    // that didn't pass `:interactive="true"` silently got zero pan/zoom/
+    // crosshair/click interactivity. `gradient` dodges the same trap only
+    // 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,
   },
 );
 
@@ -133,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;
@@ -147,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
@@ -174,6 +347,21 @@ function syncHeaderObserver() {
   resizeObserver.observe(headerEl);
 }
 
+// `props` is a reactive proxy — reading `props.onX` inside these listeners
+// always sees the caller's latest callback, no ref-latch needed the way
+// React does. Shared between the mount path and the animations-triggered
+// rebuild below so the two don't drift.
+function subscribeDeclarativeEvents(instance: ChartInstance): void {
+  instance.on('pointClick', (info) => props.onPointClick?.(info));
+  instance.on('pointDoubleClick', (info) => props.onPointDoubleClick?.(info));
+  instance.on('seriesHover', (hit) => props.onSeriesHover?.(hit));
+  instance.on('crosshairMove', (position) => props.onCrosshairMove?.(position));
+  const emitVisibleRangeChange = () => props.onVisibleRangeChange?.(instance.getVisibleRange());
+  instance.on('viewportChange', emitVisibleRangeChange);
+  instance.on('dataUpdate', emitVisibleRangeChange);
+  instance.on('seriesChange', emitVisibleRangeChange);
+}
+
 onMounted(async () => {
   if (!containerRef.value) return;
 
@@ -187,7 +375,10 @@ 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);
 
   await nextTick();
   syncHeaderObserver();
@@ -236,9 +427,11 @@ watch(
   },
 );
 
-// Init-only: post-mount `animations` reference change tears down the
-// instance and rebuilds with the new config. Reference equality matters
-// — passing an inline literal recreates on every render.
+// Init-only: a post-mount `animations` VALUE change tears down the instance
+// and rebuilds with the new config. `deepEqual` (not reference equality)
+// gates the rebuild — a caller's brand-new inline literal with the same
+// values is a no-op, since Vue's `watch` fires this callback on every
+// reference change regardless of content.
 //
 // Children get the chart via `useChartInstance()` which snapshots
 // `chartRef.value` once at setup time. To force them to re-setup against
@@ -247,9 +440,12 @@ watch(
 // Vue commits the unmount before the new ChartInstance is constructed.
 // When `chart.value` becomes the new instance, the slot re-mounts and
 // every child's `setup()` runs again against the fresh chart.
+let lastAnimations = props.animations;
 watch(
   () => props.animations,
   async (next) => {
+    if (deepEqual(next, lastAnimations)) return;
+    lastAnimations = next;
     if (!chart.value || !containerRef.value) return;
     chart.value.destroy();
     chart.value = null;
@@ -264,10 +460,45 @@ 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);
   },
 );
 
+// Controlled visible range: only re-apply when the resolved value actually
+// differs from what we last applied ourselves, so feeding the range from
+// `onVisibleRangeChange` back into this prop (the standard two-way-binding
+// shape) doesn't re-trigger `setVisibleRange` with an unchanged spec on
+// every render. The latch remembers which instance it applied to — a chart
+// rebuild (an `animations` change) must receive the range again even though
+// the spec's value hasn't moved.
+let lastAppliedVisibleRange: { instance: ChartInstance; spec: VisibleRangeSpec } | undefined;
+watch(
+  () => [chart.value, props.visibleRange] as const,
+  async ([instance, next]) => {
+    if (!instance || next === undefined) return;
+    if (
+      lastAppliedVisibleRange !== undefined &&
+      lastAppliedVisibleRange.instance === instance &&
+      deepEqual(lastAppliedVisibleRange.spec, next)
+    ) {
+      return;
+    }
+
+    lastAppliedVisibleRange = { instance, spec: next };
+    // On the chart's first tick, a series child (e.g. `<CandlestickSeries>`)
+    // hasn't mounted and seeded its data yet, so the engine is still on the
+    // placeholder `dataInterval` (60s) — a `{from, to}` spec sized for the
+    // real interval would fail the 2-bar-minimum guard. Awaiting a tick lets
+    // the child's data-seed (and its `detectInterval` call) land first.
+    await nextTick();
+    instance.setVisibleRange(next);
+  },
+  { immediate: true },
+);
+
 // Re-apply padding on any input that affects it — including `headerExtra`,
 // so a runtime `headerLayout` toggle re-runs even when `padding` is undefined
 // (the default top=20 still needs the fold-in/out).
@@ -282,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'];
@@ -289,7 +526,7 @@ const rootStyle = computed(() => {
   const background = props.gradient ? `linear-gradient(to bottom, ${gtop} 0%, ${bg} 70%, ${gbot} 100%)` : bg;
 
   return (
-    'position: relative; display: flex; flex-direction: column; width: 100%; height: 100%; overflow: hidden; ' +
+    'position: relative; display: flex; flex-direction: column; width: 100%; height: 100%; min-height: 240px; overflow: hidden; ' +
     `background: ${background}`
   );
 });

package/src/HeatmapSeries.vue

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import type { HeatmapCellData, HeatmapSeriesOptions } from '@wick-charts/core';
+import { HeatmapSeriesDef } from '@wick-charts/core';
+import { onMounted, onUnmounted, ref, watch } from 'vue';
+
+import { useChartInstance } from './context';
+
+const props = withDefaults(
+  defineProps<{
+    data: HeatmapCellData[];
+    options?: Partial<HeatmapSeriesOptions>;
+    /** Stable series ID — same value across remounts. */
+    id?: string;
+    /** Show/hide the series without unmounting it — excludes it from the Y-range fit and tooltip/legend. Default `true`. Live. */
+    visible?: boolean;
+  }>(),
+  // Vue's type-based `defineProps` casts an absent Boolean-typed prop to
+  // `false` (not `undefined`) without an explicit default — see the
+  // `interactive` fix in ChartContainer.vue for the full explanation.
+  { visible: true },
+);
+
+const chart = useChartInstance();
+const seriesId = ref<string | null>(null);
+
+onMounted(() => {
+  const id = chart.addSeries(HeatmapSeriesDef, { ...props.options, id: props.id });
+  seriesId.value = id;
+  // Lazy watcher — apply initial data here so static-data mounts render without a no-op first frame.
+  if (props.data.length > 0) {
+    chart.setSeriesData(id, props.data);
+  }
+  chart.setSeriesVisible(id, props.visible);
+});
+
+onUnmounted(() => {
+  if (seriesId.value) chart.removeSeries(seriesId.value);
+});
+
+watch(
+  () => props.data,
+  (data) => {
+    // No length guard: an empty array is a legitimate update (filter yields
+    // no rows) and must clear the previous cells, matching the React wrapper.
+    if (seriesId.value) {
+      chart.setSeriesData(seriesId.value, data);
+    }
+  },
+);
+
+watch(
+  () => props.options,
+  (options) => {
+    if (seriesId.value && options) {
+      chart.updateSeriesOptions(seriesId.value, options);
+    }
+  },
+  { deep: true },
+);
+
+watch(
+  () => props.visible,
+  (visible) => {
+    if (seriesId.value) chart.setSeriesVisible(seriesId.value, visible);
+  },
+);
+</script>
+
+<template><span v-if="false" /></template>

package/src/LineSeries.vue

@@ -5,13 +5,21 @@ import { onMounted, onUnmounted, ref, watch } from 'vue';
 
 import { useChartInstance } from './context';
 
-const props = defineProps<{
-  /** Flat `TimePoint[]`, `TimePoint[][]`, or named `{ label, color?, data }` layers. Time accepts ms or `Date`. */
-  data: MultiLayerData;
-  options?: Partial<LineSeriesOptions>;
-  /** Stable series ID — same value across remounts. */
-  id?: string;
-}>();
+const props = withDefaults(
+  defineProps<{
+    /** Flat `TimePoint[]`, `TimePoint[][]`, or named `{ label, color?, data }` layers. Time accepts ms or `Date`. */
+    data: MultiLayerData;
+    options?: Partial<LineSeriesOptions>;
+    /** Stable series ID — same value across remounts. */
+    id?: string;
+    /** Show/hide the series without unmounting it — excludes it from the Y-range fit and tooltip/legend. Default `true`. Live. */
+    visible?: boolean;
+  }>(),
+  // Vue's type-based `defineProps` casts an absent Boolean-typed prop to
+  // `false` (not `undefined`) without an explicit default — see the
+  // `interactive` fix in ChartContainer.vue for the full explanation.
+  { visible: true },
+);
 
 const chart = useChartInstance();
 const seriesId = ref<string | null>(null);
@@ -35,6 +43,7 @@ onMounted(() => {
   prevSync = new Array(layerCount).fill(EMPTY_SYNC_STATE);
   // Lazy watcher — apply initial data here so static-data mounts render without a no-op first frame.
   applyData(id, props.data);
+  chart.setSeriesVisible(id, props.visible);
 });
 
 onUnmounted(() => {
@@ -60,6 +69,13 @@ watch(
   },
   { deep: true },
 );
+
+watch(
+  () => props.visible,
+  (visible) => {
+    if (seriesId.value) chart.setSeriesVisible(seriesId.value, visible);
+  },
+);
 </script>
 
 <template><span v-if="false" /></template>

package/src/PieSeries.vue

@@ -5,12 +5,20 @@ import { onMounted, onUnmounted, ref, watch } from 'vue';
 
 import { useChartInstance } from './context';
 
-const props = defineProps<{
-  data: PieSliceData[];
-  options?: Partial<PieSeriesOptions>;
-  /** Stable series ID — same value across remounts. */
-  id?: string;
-}>();
+const props = withDefaults(
+  defineProps<{
+    data: PieSliceData[];
+    options?: Partial<PieSeriesOptions>;
+    /** Stable series ID — same value across remounts. */
+    id?: string;
+    /** Show/hide the series without unmounting it — excludes it from the Y-range fit and tooltip/legend. Default `true`. Live. */
+    visible?: boolean;
+  }>(),
+  // Vue's type-based `defineProps` casts an absent Boolean-typed prop to
+  // `false` (not `undefined`) without an explicit default — see the
+  // `interactive` fix in ChartContainer.vue for the full explanation.
+  { visible: true },
+);
 
 const chart = useChartInstance();
 const seriesId = ref<string | null>(null);
@@ -22,6 +30,7 @@ onMounted(() => {
   if (props.data.length > 0) {
     chart.setSeriesData(id, props.data);
   }
+  chart.setSeriesVisible(id, props.visible);
 });
 
 onUnmounted(() => {
@@ -46,6 +55,13 @@ watch(
   },
   { deep: true },
 );
+
+watch(
+  () => props.visible,
+  (visible) => {
+    if (seriesId.value) chart.setSeriesVisible(seriesId.value, visible);
+  },
+);
 </script>
 
 <template><span v-if="false" /></template>