@wick-charts/vue 0.6.2 → 0.6.4

package/src/BandSeries.vue

@@ -0,0 +1,87 @@
+<script setup lang="ts">
+import type { BandData, BandSeriesOptions, SeriesSyncState } from '@wick-charts/core';
+import { BandSeriesDef, EMPTY_SYNC_STATE, syncLayers, toLayers } from '@wick-charts/core';
+import { onMounted, onUnmounted, ref, watch } from 'vue';
+
+import { useChartInstance } from './context';
+
+const props = withDefaults(
+  defineProps<{
+    /**
+     * Band data — one band per layer. A single band passes a flat
+     * `{ time, low, high }[]`; several bands pass `BandPoint[][]`. To name/color
+     * a band, pass `{ label, color?, data }` (or an array of them). Time accepts
+     * ms or `Date`.
+     */
+    data: BandData;
+    /** Visual options override — fill, edge stroke, curve, entrance / intro / smoothing. */
+    options?: Partial<BandSeriesOptions>;
+    /** 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);
+// Per-layer sync state — drives the shared append/keepLast/update/replace
+// reconciliation (plus per-layer labels/colors) so streaming eases instead of
+// snapping Y every tick.
+let prevSync: SeriesSyncState[] = [];
+
+function applyData(id: string, data: BandData): void {
+  prevSync = syncLayers({ chart, id, data, prev: prevSync });
+}
+
+onMounted(() => {
+  const layerCount = toLayers(props.data).length;
+  const id = chart.addSeries(BandSeriesDef, {
+    ...props.options,
+    layers: layerCount,
+    id: props.id,
+  });
+  seriesId.value = id;
+  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(() => {
+  if (seriesId.value) chart.removeSeries(seriesId.value);
+});
+
+watch(
+  () => props.data,
+  (data) => {
+    const id = seriesId.value;
+    if (!id) return;
+
+    applyData(id, 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/ChartContainer.vue

@@ -81,7 +81,7 @@ const props = withDefaults(
      * change, use `viewport.initialRange` instead.
      */
     visibleRange?: VisibleRangeSpec;
-    /** Show the chart background gradient. Live. Defaults to true. */
+    /** Show the chart background gradient. Live. Defaults to false. */
     gradient?: boolean;
     /**
      * Enable zoom, pan, and crosshair interactions. Defaults to true.
@@ -96,16 +96,20 @@ const props = withDefaults(
      * 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.
+     * stays correct over a 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).
+     * column, before the label glyphs — on whichever side
+     * `axis.y.position` puts it (a left-axis ramp ends at the pane edge
+     * instead). The axis side's key (`{ right }` by default, `{ left }` for
+     * a left axis) overrides the total ramp width in CSS px (`0` disables);
+     * the other key adds a plain zone at the opposite pane edge (default
+     * off). A chart with only pie / heatmap series has no axis column, so
+     * both keys add plain zones there.
      *
      * **Top (under the header)** — opt-in. `true` enables the auto zone
      * (measured header + 24px run-out, half the header fold-in released so
@@ -185,7 +189,7 @@ const props = withDefaults(
   }>(),
   {
     theme: () => catppuccin.theme,
-    gradient: true,
+    gradient: false,
     // 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/
@@ -229,6 +233,13 @@ provide(NavigatorAnchorKey, navigatorAnchor);
 let resizeObserver: ResizeObserver | null = null;
 const topOverlayHeight = ref(0);
 
+// Watching `chart` hands a rebuilt instance the current height too.
+watch(
+  () => [chart.value, props.headerLayout === 'overlay' ? topOverlayHeight.value : 0] as const,
+  ([instance, height]) => instance?.setHeaderHeight(height),
+  { immediate: true },
+);
+
 /** 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;
@@ -310,8 +321,9 @@ function applyFade() {
     return;
   }
 
-  // Omitting `right` keeps the core's under-the-axis default armed; only an
-  // explicit value (or the all-off branch above) overrides it.
+  // Omitting a side keeps the core's auto default (the under-the-axis ramp
+  // on the Y-axis side); 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;

package/src/composables.ts

@@ -1,4 +1,4 @@
-import type { ChartInstance, CrosshairPosition, VisibleRange, YRange } from '@wick-charts/core';
+import type { ChartInstance, CrosshairPosition, VisibleRange, YAxisPosition, YRange } from '@wick-charts/core';
 import { type Ref, onMounted, onUnmounted, ref } from 'vue';
 
 export function useVisibleRange(chart: ChartInstance): Ref<VisibleRange> {
@@ -21,6 +21,40 @@ export function useYRange(chart: ChartInstance): Ref<YRange> {
   return range;
 }
 
+export interface AxisLayout {
+  yAxisPosition: YAxisPosition;
+  yAxisWidth: number;
+  xAxisHeight: number;
+}
+
+function readAxisLayout(chart: ChartInstance): AxisLayout {
+  return { yAxisPosition: chart.yAxisPosition, yAxisWidth: chart.yAxisWidth, xAxisHeight: chart.xAxisHeight };
+}
+
+/** The axis gutters overlays anchor to — refreshed on a Y-axis side or gutter size change. */
+export function useAxisLayout(chart: ChartInstance): Ref<AxisLayout> {
+  const layout = ref<AxisLayout>(readAxisLayout(chart)) as Ref<AxisLayout>;
+  const handler = () => {
+    const next = readAxisLayout(chart);
+    const prev = layout.value;
+    const unchanged =
+      prev.yAxisPosition === next.yAxisPosition &&
+      prev.yAxisWidth === next.yAxisWidth &&
+      prev.xAxisHeight === next.xAxisHeight;
+    if (unchanged) return;
+
+    layout.value = next;
+  };
+  onMounted(() => {
+    // The axis watcher may have landed a new config between setup and mount.
+    handler();
+    chart.on('viewportChange', handler);
+  });
+  onUnmounted(() => chart.off('viewportChange', handler));
+
+  return layout;
+}
+
 export function useLastYValue(chart: ChartInstance, seriesId: string): Ref<{ value: number; isLive: boolean } | null> {
   let snapshot = chart.getLastValue(seriesId);
   // Track the pixel Y the snapshot maps to so a pan/zoom/resize that leaves the

package/src/index.ts

@@ -13,6 +13,11 @@ export type {
   AnimationsConfig,
   AxisBound,
   AxisConfig,
+  BandData,
+  BandEntryAnimation,
+  BandPoint,
+  BandPointInput,
+  BandSeriesOptions,
   BarElementTransform,
   BarEntryAnimation,
   BarIntroDirectives,
@@ -51,6 +56,7 @@ export type {
   HeatmapSeriesOptions,
   HeatmapSeriesRenderer,
   HoverInfo,
+  LayerSnapshot,
   LegendItem,
   LineIntroDirectives,
   LineIntroFn,
@@ -61,6 +67,7 @@ export type {
   LineSeriesOptions,
   LoadingIndicatorArgs,
   LoadingIndicatorFn,
+  LogScaleOptions,
   MarkerConfig,
   MarkerShape,
   MultiLayerData,
@@ -86,6 +93,7 @@ export type {
   ReferenceLineStyle,
   RenderPadding,
   RoundedRectArgs,
+  ScaleTickArgs,
   SeriesCreateEnv,
   SeriesDefinition,
   SeriesHoverInfo,
@@ -128,10 +136,13 @@ export type {
   WaveIntroTransform,
   XAxisConfig,
   YAxisConfig,
+  YAxisPosition,
   YRange,
+  YScaleTransform,
 } from '@wick-charts/core';
 // Painters — custom per-element drawing for bar / candle / line series.
 export {
+  BandSeriesDef,
   BarSeriesDef,
   CandlestickSeriesDef,
   ChartInstance,
@@ -172,6 +183,7 @@ export {
   isTimeSeriesRenderer,
   lavenderMist,
   lightPink,
+  logScale,
   materialPalenight,
   minimalLight,
   mintBreeze,
@@ -214,6 +226,7 @@ export {
   wipeIntro,
 } from '@wick-charts/core';
 
+export { default as BandSeries } from './BandSeries.vue';
 export { default as BarSeries } from './BarSeries.vue';
 export { default as CandlestickSeries } from './CandlestickSeries.vue';
 // Vue components

package/src/ui/Crosshair.vue

@@ -56,11 +56,11 @@ const labelStyle = computed(() => ({
 
 <template>
   <template v-if="position">
-    <!-- Y label on right axis -->
+    <!-- Y label on the value axis -->
     <div
       :style="{
         position: 'absolute',
-        right: '0',
+        [chart.yAxisPosition]: '0',
         top: position.mediaY + 'px',
         transform: 'translateY(-50%)',
         ...labelStyle,

package/src/ui/InfoBar.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import {
+  type BandPoint,
   type OHLCData,
   type SeriesSnapshot,
   type SnapshotSort,
@@ -98,9 +99,13 @@ const displayTime = computed(() => {
 const slots = useSlots();
 const hasCustomSlot = computed(() => typeof slots.default === 'function');
 
-function isOHLC(data: OHLCData | TimePoint): data is OHLCData {
+function isOHLC(data: SeriesSnapshot['data']): data is OHLCData {
   return 'open' in data;
 }
+
+function isBand(data: SeriesSnapshot['data']): data is BandPoint {
+  return 'high' in data && !isOHLC(data);
+}
 </script>
 
 <template>
@@ -174,6 +179,20 @@ function isOHLC(data: OHLCData | TimePoint): data is OHLCData {
               </span>
             </template>
           </span>
+          <span v-else-if="isBand(s.data)" :style="{ display: 'inline-flex', alignItems: 'center', gap: '3px' }">
+            <span
+              :style="{
+                width: '6px',
+                height: '6px',
+                borderRadius: '1px',
+                background: s.color,
+                flexShrink: 0,
+              }"
+            />
+            <span :style="{ color: s.color, fontWeight: 500 }">
+              {{ effectiveFormat((s.data as BandPoint).low, 'low') }} – {{ effectiveFormat((s.data as BandPoint).high, 'high') }}
+            </span>
+          </span>
           <span v-else :style="{ display: 'inline-flex', alignItems: 'center', gap: '3px' }">
             <span
               :style="{

package/src/ui/TimeAxis.vue

@@ -1,7 +1,8 @@
 <script setup lang="ts">
 import { mountAxisLabels } from '@wick-charts/core';
-import { onMounted, onUnmounted, ref, watch } from 'vue';
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue';
 
+import { useAxisLayout } from '../composables';
 import { useChartInstance } from '../context';
 
 const props = defineProps<{
@@ -12,6 +13,8 @@ const props = defineProps<{
 }>();
 
 const chart = useChartInstance();
+const layout = useAxisLayout(chart);
+const onLeft = computed(() => layout.value.yAxisPosition === 'left');
 const containerRef = ref<HTMLDivElement | null>(null);
 
 const applyDensity = () => {
@@ -42,10 +45,10 @@ onUnmounted(() => {
     ref="containerRef"
     :style="{
       position: 'absolute',
-      left: '0',
+      left: (onLeft ? layout.yAxisWidth : 0) + 'px',
       bottom: '0',
-      right: chart.yAxisWidth + 'px',
-      height: chart.xAxisHeight + 'px',
+      right: (onLeft ? 0 : layout.yAxisWidth) + 'px',
+      height: layout.xAxisHeight + 'px',
       pointerEvents: 'none',
       display: 'flex',
       alignItems: 'center',

package/src/ui/Tooltip.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import {
+  type BandPoint,
   type OHLCData,
   type SeriesSnapshot,
   type SnapshotSort,
@@ -104,16 +105,18 @@ watchEffect((onCleanup) => {
 const floatingPos = computed<{ left: number; top: number } | null>(() => {
   if (!crosshair.value || snapshots.value.length === 0) return null;
   const mediaSize = chart.getMediaSize();
+  const chartLeft = chart.plotLeft;
   const chartWidth = mediaSize.width - chart.yAxisWidth;
   const chartHeight = mediaSize.height - chart.xAxisHeight;
 
   if (hasCustomSlot.value) {
     const size = measuredSize.value;
-    if (!size) return { left: 0, top: 0 };
+    if (!size) return { left: chartLeft, top: 0 };
 
     return computeTooltipPosition({
       x: crosshair.value.mediaX,
       y: crosshair.value.mediaY,
+      chartLeft,
       chartWidth,
       chartHeight,
       tooltipWidth: size.width,
@@ -123,12 +126,15 @@ const floatingPos = computed<{ left: number; top: number } | null>(() => {
 
   const hasOHLC = snapshots.value.some((s) => 'open' in s.data);
   const lineCount = snapshots.value.filter((s) => !('open' in s.data)).length;
-  const tooltipWidth = 160;
+  // A band row carries two numbers, so it needs a wider box than a line row.
+  const hasBand = snapshots.value.some((s) => 'high' in s.data && !('open' in s.data));
+  const tooltipWidth = hasBand ? 220 : 160;
   const tooltipHeight = hasOHLC ? 140 : 40 + lineCount * 22;
 
   return computeTooltipPosition({
     x: crosshair.value.mediaX,
     y: crosshair.value.mediaY,
+    chartLeft,
     chartWidth,
     chartHeight,
     tooltipWidth,
@@ -138,9 +144,13 @@ const floatingPos = computed<{ left: number; top: number } | null>(() => {
 
 const measured = computed(() => !hasCustomSlot.value || measuredSize.value !== null);
 
-function isOHLC(data: OHLCData | TimePoint): data is OHLCData {
+function isOHLC(data: SeriesSnapshot['data']): data is OHLCData {
   return 'open' in data;
 }
+
+function isBand(data: SeriesSnapshot['data']): data is BandPoint {
+  return 'high' in data && !isOHLC(data);
+}
 </script>
 
 <template>
@@ -212,6 +222,33 @@ function isOHLC(data: OHLCData | TimePoint): data is OHLCData {
           </span>
         </template>
       </div>
+      <div
+        v-else-if="isBand(s.data)"
+        :style="{ display: 'flex', alignItems: 'center', gap: '8px', padding: '2px 0' }"
+      >
+        <span
+          :style="{
+            width: '8px',
+            height: '8px',
+            borderRadius: '2px',
+            background: s.color,
+            flexShrink: 0,
+          }"
+        />
+        <span
+          :style="{
+            opacity: 0.6,
+            flex: '1',
+            minWidth: 0,
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }"
+        >{{ s.label ?? 'Range' }}</span>
+        <span :style="{ fontWeight: 600, color: s.color, whiteSpace: 'nowrap' }">
+          {{ effectiveFormat((s.data as BandPoint).low, 'low') }} – {{ effectiveFormat((s.data as BandPoint).high, 'high') }}
+        </span>
+      </div>
       <div v-else :style="{ display: 'flex', alignItems: 'center', gap: '8px', padding: '2px 0' }">
         <span
           :style="{

package/src/ui/YAxis.vue

@@ -2,6 +2,7 @@
 import { type ValueFormatter, mountAxisLabels } from '@wick-charts/core';
 import { onMounted, onUnmounted, ref, watch } from 'vue';
 
+import { useAxisLayout } from '../composables';
 import { useChartInstance } from '../context';
 
 const props = defineProps<{
@@ -17,6 +18,7 @@ const props = defineProps<{
 }>();
 
 const chart = useChartInstance();
+const layout = useAxisLayout(chart);
 const containerRef = ref<HTMLDivElement | null>(null);
 
 // Route the formatter through yScale so Crosshair / YLabel fallback use
@@ -52,10 +54,10 @@ onUnmounted(() => {
     ref="containerRef"
     :style="{
       position: 'absolute',
-      right: '0',
+      [layout.yAxisPosition]: '0',
       top: '0',
-      bottom: chart.xAxisHeight + 'px',
-      width: chart.yAxisWidth + 'px',
+      bottom: layout.xAxisHeight + 'px',
+      width: layout.yAxisWidth + 'px',
       pointerEvents: 'none',
     }"
   />

package/src/ui/YLabel.vue

@@ -1,12 +1,12 @@
 <script setup lang="ts">
 import {
   BadgeAnimator,
-  type ChartInstance,
   type ValueFormatter,
   type YLabelAnimate,
   firstVisibleValue,
   prefersReducedMotion,
   resolveAnimate,
+  resolveYLabelSeriesId,
 } from '@wick-charts/core';
 import { computed, onMounted, onUnmounted, ref, useSlots } from 'vue';
 
@@ -145,21 +145,10 @@ onUnmounted(() => {
   rafId = null;
 });
 
-function resolveSeriesId(c: ChartInstance, explicit: string | undefined): string | null {
-  if (explicit !== undefined) return explicit;
-
-  const singleLayer = c.getSeriesIdsByType('time', { visibleOnly: true, singleLayerOnly: true });
-  if (singleLayer.length > 0) return singleLayer[0];
-
-  const anyTime = c.getSeriesIdsByType('time', { visibleOnly: true });
-
-  return anyTime.length > 0 ? anyTime[0] : null;
-}
-
 const resolvedId = computed<string | null>(() => {
   void bump.value;
 
-  return resolveSeriesId(chart, props.seriesId);
+  return resolveYLabelSeriesId(chart, props.seriesId);
 });
 
 const last = computed<{ value: number; isLive: boolean } | null>(() => {
@@ -273,8 +262,8 @@ const effectiveFormat = computed<ValueFormatter>(() => {
       <div
         :style="{
           position: 'absolute',
-          left: '0',
-          right: chart.yAxisWidth + 'px',
+          left: chart.plotLeft + 'px',
+          right: (chart.yAxisPosition === 'left' ? 0 : chart.yAxisWidth) + 'px',
           top: y + 'px',
           height: '0',
           borderTop: '1px dashed ' + bgColor,
@@ -286,7 +275,7 @@ const effectiveFormat = computed<ValueFormatter>(() => {
       <div
         :style="{
           position: 'absolute',
-          right: '4px',
+          [chart.yAxisPosition]: '4px',
           top: y + 'px',
           transform: 'translateY(-50%)',
           opacity: opacity,