@wick-charts/vue 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wick-charts/vue",
-  "version": "0.3.1",
+  "version": "0.3.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.3.1"
+    "@wick-charts/core": "^0.3.2"
   },
   "scripts": {
     "build": "vite build"

package/src/ChartContainer.vue

@@ -1,18 +1,63 @@
 <script setup lang="ts">
-import { type AxisConfig, ChartInstance, type ChartTheme, darkTheme } from '@wick-charts/core';
+import {
+  type AxisConfig,
+  ChartInstance,
+  type ChartOptions,
+  type ChartTheme,
+  darkTheme,
+} from '@wick-charts/core';
 import { computed, nextTick, onMounted, onUnmounted, provide, ref, shallowRef, watch } from 'vue';
 
-import { ChartKey, InfoBarAnchorKey, LegendAnchorKey, LegendRightAnchorKey, ThemeKey, TitleAnchorKey } from './context';
+import {
+  ChartKey,
+  InfoBarAnchorKey,
+  LegendAnchorKey,
+  LegendRightAnchorKey,
+  NavigatorAnchorKey,
+  ThemeKey,
+  TitleAnchorKey,
+} from './context';
+
+type PerfOption = NonNullable<ChartOptions['perf']>;
 
 const props = withDefaults(
   defineProps<{
     theme?: ChartTheme;
     axis?: AxisConfig;
+    /**
+     * Viewport padding. `top`/`bottom` are in pixels. `left`/`right` accept either pixels (`50`)
+     * or data intervals (`{ intervals: 3 }`). Set to 0 for edge-to-edge sparklines. Updates are
+     * applied reactively when this prop or the measured header height changes.
+     * Defaults: `{ top: 20, bottom: 20, right: { intervals: 3 }, left: { intervals: 0 } }`.
+     */
+    padding?: {
+      top?: number;
+      bottom?: number;
+      right?: number | { intervals: number };
+      left?: number | { intervals: number };
+    };
+    /** Show the chart background gradient. Defaults to true. */
+    gradient?: boolean;
+    /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
+    interactive?: boolean;
     /** Background grid configuration. Default: `{ visible: true }`. */
     grid?: { visible: boolean };
+    /**
+     * How `<Title>` and `<InfoBar>` are positioned relative to the canvas.
+     * - `'overlay'` (default): absolute overlays on top of the canvas.
+     * - `'inline'`: flex siblings above the canvas — the canvas (and grid) shift down.
+     */
+    headerLayout?: 'overlay' | 'inline';
+    /**
+     * Enable runtime performance instrumentation. Off by default. Read at mount only;
+     * later changes are ignored.
+     */
+    perf?: PerfOption;
   }>(),
   {
     theme: () => darkTheme,
+    gradient: true,
+    headerLayout: 'overlay',
   },
 );
 
@@ -20,16 +65,16 @@ const containerRef = ref<HTMLDivElement>();
 const chart = shallowRef<ChartInstance | null>(null);
 const themeRef = shallowRef<ChartTheme>(props.theme);
 
-// Anchors for hoisted overlays. Title / InfoBar teleport into a top
-// overlay anchor that is positioned *absolute* at the top of the canvas
-// block, so the canvas (and its grid) spans the full container height. The
-// combined anchor height is measured and fed into `chart.setPadding({ top })`
-// so data stays below the header.
+// Capture perf at mount only — mirrors React's perfRef so a new object
+// identity later doesn't recreate the chart.
+const perfAtMount = props.perf;
+
 const topOverlayRef = ref<HTMLElement | null>(null);
 const titleAnchor = ref<HTMLElement | null>(null);
 const infoBarAnchor = ref<HTMLElement | null>(null);
 const legendAnchor = ref<HTMLElement | null>(null);
 const legendRightAnchor = ref<HTMLElement | null>(null);
+const navigatorAnchor = ref<HTMLElement | null>(null);
 
 provide(ChartKey, chart);
 provide(ThemeKey, themeRef);
@@ -37,32 +82,66 @@ provide(TitleAnchorKey, titleAnchor);
 provide(InfoBarAnchorKey, infoBarAnchor);
 provide(LegendAnchorKey, legendAnchor);
 provide(LegendRightAnchorKey, legendRightAnchor);
+provide(NavigatorAnchorKey, navigatorAnchor);
 
 let resizeObserver: ResizeObserver | null = null;
-let topOverlayHeight = 0;
+const topOverlayHeight = ref(0);
+
+// 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));
 
 function applyPadding() {
   if (!chart.value) return;
-  chart.value.setPadding({ top: 20 + topOverlayHeight });
+  const userTop = props.padding?.top ?? 20;
+  const merged: ChartOptions['padding'] = { top: userTop + headerExtra.value };
+  if (props.padding?.bottom !== undefined) merged.bottom = props.padding.bottom;
+  if (props.padding?.right !== undefined) merged.right = props.padding.right;
+  if (props.padding?.left !== undefined) merged.left = props.padding.left;
+  chart.value.setPadding(merged);
+}
+
+// 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
+// layout reserve the height directly.
+function syncHeaderObserver() {
+  resizeObserver?.disconnect();
+  resizeObserver = null;
+
+  const headerEl = props.headerLayout === 'overlay' ? topOverlayRef.value : null;
+  if (!headerEl) {
+    // Reset stale measurement so the next applyPadding call drops back to the
+    // user's configured `padding.top` instead of carrying inline-mode height.
+    topOverlayHeight.value = 0;
+    applyPadding();
+
+    return;
+  }
+
+  const measure = () => {
+    topOverlayHeight.value = headerEl.getBoundingClientRect().height;
+    applyPadding();
+  };
+  measure();
+  resizeObserver = new ResizeObserver(measure);
+  resizeObserver.observe(headerEl);
 }
 
 onMounted(async () => {
   if (!containerRef.value) return;
-  const options: any = {};
+
+  const options: ChartOptions = {};
   if (props.axis) options.axis = props.axis;
   if (props.theme) options.theme = props.theme;
+  if (props.padding) options.padding = props.padding;
+  if (props.interactive !== undefined) options.interactive = props.interactive;
   if (props.grid !== undefined) options.grid = props.grid;
+  if (perfAtMount !== undefined) options.perf = perfAtMount;
   chart.value = new ChartInstance(containerRef.value, options);
 
   await nextTick();
-  if (!topOverlayRef.value) return;
-  const measure = () => {
-    topOverlayHeight = topOverlayRef.value?.getBoundingClientRect().height ?? 0;
-    applyPadding();
-  };
-  measure();
-  resizeObserver = new ResizeObserver(measure);
-  resizeObserver.observe(topOverlayRef.value);
+  syncHeaderObserver();
 });
 
 onUnmounted(() => {
@@ -72,6 +151,17 @@ onUnmounted(() => {
   chart.value = null;
 });
 
+// Re-attach the observer when `headerLayout` toggles after mount, so an
+// overlay → inline → overlay round-trip keeps measuring the new header.
+watch(
+  () => props.headerLayout,
+  async () => {
+    if (!chart.value) return;
+    await nextTick();
+    syncHeaderObserver();
+  },
+);
+
 watch(
   () => props.theme,
   (newTheme) => {
@@ -97,13 +187,31 @@ watch(
   },
 );
 
+// 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).
+watch(
+  () => [
+    props.padding?.top,
+    props.padding?.bottom,
+    typeof props.padding?.right === 'object' ? props.padding.right.intervals : props.padding?.right,
+    typeof props.padding?.left === 'object' ? props.padding.left.intervals : props.padding?.left,
+    headerExtra.value,
+  ],
+  applyPadding,
+);
+
 const rootStyle = computed(() => {
   const t = themeRef.value;
   const [gtop, gbot] = t?.chartGradient ?? ['transparent', 'transparent'];
   const bg = t?.background ?? 'transparent';
+  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; ' +
-    `background: linear-gradient(to bottom, ${gtop} 0%, ${bg} 70%, ${gbot} 100%)`
+    `background: ${background}`
   );
 });
 </script>
@@ -111,31 +219,43 @@ const rootStyle = computed(() => {
 <template>
   <div :style="rootStyle">
     <div style="display: flex; flex-direction: row; flex: 1; min-height: 0">
-      <div
-        ref="containerRef"
-        style="position: relative; flex: 1; min-width: 0; min-height: 0; overflow: hidden"
-      >
-        <!-- Top overlay (Title + InfoBar) — stacked absolute inside the
-             canvas block so the grid extends full-height behind them. -->
+      <!-- Canvas-block column. In inline mode the header is a flex sibling
+           above the canvas inside this column; in overlay mode it's absolute
+           over the canvas (rendered inside `containerRef`). -->
+      <div style="display: flex; flex-direction: column; flex: 1; min-width: 0; min-height: 0">
         <div
-          ref="topOverlayRef"
-          data-chart-top-overlay=""
-          style="position: absolute; top: 0; left: 0; right: 0; z-index: 2; pointer-events: none; display: flex; flex-direction: column"
+          v-if="headerLayout === 'inline'"
+          data-chart-header=""
+          style="flex-shrink: 0; display: flex; flex-direction: column; pointer-events: none"
         >
           <div ref="titleAnchor" data-chart-title-anchor="" />
           <div ref="infoBarAnchor" data-tooltip-legend-anchor="" />
         </div>
         <div
-          v-if="chart"
-          data-chart-series-overlay=""
-          style="position: absolute; inset: 0; pointer-events: none; z-index: 3"
+          ref="containerRef"
+          style="position: relative; flex: 1; min-width: 0; min-height: 0; overflow: hidden"
         >
-          <slot />
+          <div
+            v-if="headerLayout === 'overlay'"
+            ref="topOverlayRef"
+            data-chart-top-overlay=""
+            style="position: absolute; top: 0; left: 0; right: 0; z-index: 2; pointer-events: none; display: flex; flex-direction: column"
+          >
+            <div ref="titleAnchor" data-chart-title-anchor="" />
+            <div ref="infoBarAnchor" data-tooltip-legend-anchor="" />
+          </div>
+          <div
+            v-if="chart"
+            data-chart-series-overlay=""
+            style="position: absolute; inset: 0; pointer-events: none; z-index: 3"
+          >
+            <slot />
+          </div>
         </div>
       </div>
       <div ref="legendRightAnchor" data-legend-right-anchor="" style="flex: 0 0 auto" />
     </div>
     <div ref="legendAnchor" data-legend-anchor="" style="flex: 0 0 auto" />
+    <div ref="navigatorAnchor" data-navigator-anchor="" style="flex: 0 0 auto" />
   </div>
 </template>
-

package/src/context.ts

@@ -13,6 +13,7 @@ export const TitleAnchorKey: InjectionKey<Ref<HTMLElement | null>> = Symbol('wic
 export const InfoBarAnchorKey: InjectionKey<Ref<HTMLElement | null>> = Symbol('wick-info-bar-anchor');
 export const LegendAnchorKey: InjectionKey<Ref<HTMLElement | null>> = Symbol('wick-legend-anchor');
 export const LegendRightAnchorKey: InjectionKey<Ref<HTMLElement | null>> = Symbol('wick-legend-right-anchor');
+export const NavigatorAnchorKey: InjectionKey<Ref<HTMLElement | null>> = Symbol('wick-navigator-anchor');
 
 export function useChartInstance(): ChartInstance {
   const chartRef = inject(ChartKey);

package/src/index.ts

@@ -26,6 +26,12 @@ export type {
   /** @deprecated Use {@link TimePoint} instead. */
   LineData,
   LineSeriesOptions,
+  NavigatorCandlePoint,
+  NavigatorControllerParams,
+  NavigatorData,
+  NavigatorLinePoint,
+  NavigatorOptions,
+  NavigatorSeriesType,
   OHLCData,
   OHLCInput,
   PieSeriesOptions,
@@ -53,6 +59,7 @@ export type {
 } from '@wick-charts/core';
 export {
   ChartInstance,
+  NavigatorController,
   andromeda,
   autoGradient,
   ayuMirage,
@@ -105,6 +112,7 @@ export { default as PieSeries } from './PieSeries.vue';
 export { default as Crosshair } from './ui/Crosshair.vue';
 export { default as InfoBar } from './ui/InfoBar.vue';
 export { default as Legend } from './ui/Legend.vue';
+export { default as Navigator } from './ui/Navigator.vue';
 export { default as NumberFlow } from './ui/NumberFlow.vue';
 export { default as PieLegend } from './ui/PieLegend.vue';
 export { default as PieTooltip } from './ui/PieTooltip.vue';

package/src/ui/Navigator.vue

@@ -0,0 +1,78 @@
+<script setup lang="ts">
+import { NavigatorController, type NavigatorData } from '@wick-charts/core';
+import { computed, inject, onBeforeUnmount, ref, shallowRef, watch } from 'vue';
+
+import { ChartKey, NavigatorAnchorKey, ThemeKey } from '../context';
+
+const props = withDefaults(
+  defineProps<{
+    data: NavigatorData;
+    /** Strip height in CSS pixels. Defaults to `theme.navigator.height` (60). */
+    height?: number;
+  }>(),
+  {},
+);
+
+const anchor = inject(NavigatorAnchorKey);
+const chartRef = inject(ChartKey);
+const themeRef = inject(ThemeKey);
+
+if (!anchor || !chartRef || !themeRef) {
+  throw new Error('<Navigator> must be used within <ChartContainer>.');
+}
+
+const stripRef = ref<HTMLDivElement | null>(null);
+const controller = shallowRef<NavigatorController | null>(null);
+
+const resolvedHeight = computed(() => props.height ?? themeRef.value.navigator.height);
+
+// Mount the controller once the strip div exists and the chart is available.
+// Watch both — either may arrive after the other across Teleport boundaries.
+watch(
+  [stripRef, () => chartRef.value],
+  ([strip, chart]) => {
+    if (!strip || !chart || controller.value) return;
+    controller.value = new NavigatorController({
+      container: strip,
+      chart,
+      data: props.data,
+      options: props.height !== undefined ? { height: props.height } : undefined,
+    });
+  },
+  { flush: 'post', immediate: true },
+);
+
+watch(
+  () => props.data,
+  (next) => {
+    controller.value?.setData(next);
+  },
+);
+
+watch(
+  () => props.height,
+  (next) => {
+    controller.value?.setOptions(next !== undefined ? { height: next } : {});
+  },
+);
+
+onBeforeUnmount(() => {
+  controller.value?.destroy();
+  controller.value = null;
+});
+</script>
+
+<template>
+  <Teleport v-if="anchor" :to="anchor">
+    <div
+      ref="stripRef"
+      data-chart-navigator=""
+      :style="{
+        position: 'relative',
+        width: '100%',
+        height: resolvedHeight + 'px',
+        flexShrink: 0,
+      }"
+    />
+  </Teleport>
+</template>

package/src/ui/NumberFlow.vue

@@ -4,8 +4,12 @@ import { computed, onMounted, ref } from 'vue';
 const props = withDefaults(
   defineProps<{
     value: number;
-    /** Value-to-string formatter. Defaults to the current locale's `Intl.NumberFormat`. */
-    format?: (value: number) => string;
+    /**
+     * Value-to-string formatter. Defaults to the current locale's
+     * `Intl.NumberFormat` when omitted. `Intl.NumberFormatOptions` is also
+     * accepted (legacy) — routed through the built-in `Intl.NumberFormat`.
+     */
+    format?: ((value: number) => string) | Intl.NumberFormatOptions;
     locale?: string;
     spinDuration?: number;
   }>(),
@@ -20,8 +24,11 @@ onMounted(() => {
   mounted.value = true;
 });
 
-const defaultFormat = computed(() => {
-  const nf = new Intl.NumberFormat(props.locale);
+const effectiveFormat = computed<(v: number) => string>(() => {
+  const f = props.format;
+  if (typeof f === 'function') return f;
+  const nf = new Intl.NumberFormat(props.locale, typeof f === 'object' ? f : undefined);
+
   return (v: number) => nf.format(v);
 });
 
@@ -31,8 +38,7 @@ interface CharPart {
 }
 
 const parts = computed<CharPart[]>(() => {
-  const fn = props.format ?? defaultFormat.value;
-  const formatted = fn(props.value);
+  const formatted = effectiveFormat.value(props.value);
   const result: CharPart[] = [];
   for (const char of formatted) {
     if (char >= '0' && char <= '9') {

package/src/ui/PieLegend.vue

@@ -1,10 +1,11 @@
 <script setup lang="ts">
 import { type ChartInstance, type SliceInfo, type ValueFormatter, formatCompact } from '@wick-charts/core';
-import { computed, onMounted, onUnmounted, ref, useSlots } from 'vue';
+import { computed, inject, onMounted, onUnmounted, ref, useSlots } from 'vue';
 
-import { useChartInstance, useTheme } from '../context';
+import { LegendAnchorKey, LegendRightAnchorKey, useChartInstance, useTheme } from '../context';
 
 type PieLegendMode = 'value' | 'percent' | 'both';
+type PieLegendPosition = 'bottom' | 'right' | 'overlay';
 
 const props = withDefaults(
   defineProps<{
@@ -17,13 +18,31 @@ const props = withDefaults(
     mode?: PieLegendMode;
     /** Custom formatter for the absolute slice value. */
     format?: ValueFormatter;
+    /** Layout placement. Default: `'bottom'`. */
+    position?: PieLegendPosition;
   }>(),
   {
     mode: undefined,
     format: undefined,
+    position: 'bottom',
   },
 );
 
+const bottomAnchor = inject(LegendAnchorKey);
+const rightAnchor = inject(LegendRightAnchorKey);
+if (!bottomAnchor || !rightAnchor) {
+  throw new Error('<PieLegend> must be used within <ChartContainer>: missing legend anchors.');
+}
+
+// Overlay mode renders inline (no teleport) — same behaviour as React, where
+// `position='overlay'` keeps PieLegend in the series-overlay layer.
+const teleportTarget = computed(() => {
+  if (props.position === 'right') return rightAnchor.value;
+  if (props.position === 'bottom') return bottomAnchor.value;
+
+  return null;
+});
+
 defineSlots<{
   default?(ctx: { slices: readonly SliceInfo[]; mode: PieLegendMode; format: ValueFormatter }): unknown;
 }>();
@@ -77,8 +96,62 @@ const slices = computed<readonly SliceInfo[]>(() => {
     :mode="resolvedMode"
     :format="resolvedFormat"
   />
+  <Teleport
+    v-else-if="slices.length > 0 && teleportTarget"
+    :to="teleportTarget"
+  >
+    <div
+      data-chart-pie-legend=""
+      :data-chart-pie-legend-position="position"
+      :style="{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '6px',
+        padding: '6px 10px',
+        fontFamily: theme.typography.fontFamily,
+        fontSize: theme.typography.fontSize + 'px',
+        color: theme.tooltip.textColor,
+        pointerEvents: 'auto',
+      }"
+    >
+      <div
+        v-for="(slice, i) in slices"
+        :key="i"
+        :style="{ display: 'flex', alignItems: 'center', gap: '10px' }"
+      >
+        <span :style="{ width: '10px', height: '10px', borderRadius: '50%', background: slice.color, flexShrink: 0 }" />
+        <span :style="{ flex: 1, opacity: 0.8 }">{{ slice.label }}</span>
+        <span
+          v-if="resolvedMode === 'value' || resolvedMode === 'both'"
+          :style="{
+            fontWeight: 600,
+            fontVariantNumeric: 'tabular-nums',
+            minWidth: resolvedMode === 'value' ? '40px' : undefined,
+            textAlign: 'right',
+          }"
+        >
+          {{ resolvedFormat(slice.value) }}
+        </span>
+        <span
+          v-if="resolvedMode === 'percent' || resolvedMode === 'both'"
+          :style="{
+            opacity: resolvedMode === 'percent' ? 1 : 0.5,
+            fontWeight: resolvedMode === 'percent' ? 600 : 400,
+            fontSize: (resolvedMode === 'percent' ? theme.typography.fontSize : theme.axis.fontSize) + 'px',
+            fontVariantNumeric: 'tabular-nums',
+            minWidth: '40px',
+            textAlign: 'right',
+          }"
+        >
+          {{ slice.percent.toFixed(1) }}%
+        </span>
+      </div>
+    </div>
+  </Teleport>
   <div
     v-else-if="slices.length > 0"
+    data-chart-pie-legend=""
+    data-chart-pie-legend-position="overlay"
     :style="{
       display: 'flex',
       flexDirection: 'column',

package/src/ui/TimeAxis.vue

@@ -1,25 +1,44 @@
 <script setup lang="ts">
 import { formatTime, resolveAxisFontSize, resolveAxisTextColor } from '@wick-charts/core';
-import { computed } from 'vue';
+import { computed, onUnmounted, watch } from 'vue';
 
 import { useVisibleRange } from '../composables';
 import { useChartInstance } from '../context';
 
+const props = defineProps<{
+  /** Desired number of labels (≥ 2). Overrides chart-level `axis.x.labelCount`. */
+  labelCount?: number;
+  /** Minimum pixel gap between adjacent labels (hard floor). Overrides chart-level. */
+  minLabelSpacing?: number;
+}>();
+
 interface TrackedTick {
   opacity: number;
   addedAt: number;
 }
 
 const chart = useChartInstance();
-const _visibleRange = useVisibleRange(chart);
+const visibleRange = useVisibleRange(chart);
+
+const applyDensity = () => {
+  chart.setTimeAxisLabelDensity({
+    labelCount: props.labelCount ?? null,
+    minLabelSpacing: props.minLabelSpacing ?? null,
+  });
+};
+applyDensity();
+watch(() => [props.labelCount, props.minLabelSpacing], applyDensity);
+onUnmounted(() => {
+  chart.setTimeAxisLabelDensity({ labelCount: null, minLabelSpacing: null });
+});
 
 const tickMap = new Map<number, TrackedTick>();
 
 const theme = computed(() => chart.getTheme());
 
 const tickData = computed(() => {
-  // Access _visibleRange.value to track dependency
-  void _visibleRange.value;
+  // Access visibleRange.value to track dependency
+  void visibleRange.value;
 
   const dataInterval = chart.getDataInterval();
   const { ticks: currentTicks, tickInterval } = chart.timeScale.niceTickValues(dataInterval);

package/src/ui/Title.vue

@@ -1,17 +1,44 @@
 <script setup lang="ts">
-import { inject } from 'vue';
+import { computed, inject, useSlots } from 'vue';
 
 import { ThemeKey, TitleAnchorKey } from '../context';
 
 withDefaults(
   defineProps<{
+    /**
+     * @deprecated Use the named `sub` slot instead — it accepts arbitrary
+     * inline markup (icons, badges, formatted text) to mirror React's
+     * `sub: ReactNode`. The string-only prop is kept as a back-compat shim
+     * for callers upgrading from 0.3.1; the slot wins when both are provided.
+     *
+     * Note: the title strip is rendered with `pointer-events: none` so it
+     * doesn't intercept canvas hover events. Interactive children (`<a>`,
+     * `<button>`) need to opt back in with `pointer-events: auto`.
+     */
     sub?: string;
   }>(),
   {},
 );
 
+defineSlots<{
+  default?(): unknown;
+  /**
+   * Secondary label rendered in a muted colour next to the primary one. Use a
+   * named slot (instead of the legacy `sub` prop) so consumers can pass
+   * arbitrary inline markup — icons, badges, formatted text — to mirror
+   * React's `sub: ReactNode`. Interactive children (`<a>`, `<button>`) need
+   * `pointer-events: auto` to override the title strip's default
+   * `pointer-events: none`.
+   */
+  sub?(): unknown;
+}>();
+
 const anchor = inject(TitleAnchorKey);
 const theme = inject(ThemeKey);
+const slots = useSlots();
+// Slot wins when both are present — same precedence rule React uses for
+// children vs explicit props.
+const hasSubSlot = computed(() => typeof slots.sub === 'function');
 
 // Match the "loud failure" contract of other Vue overlays (`useChartInstance`,
 // `useTheme`) — misuse outside `<ChartContainer>` should throw, not render
@@ -43,14 +70,14 @@ if (!theme) {
     >
       <span><slot /></span>
       <span
-        v-if="sub"
+        v-if="hasSubSlot || sub"
         :style="{
           fontWeight: 400,
           color: theme.axis.textColor,
           fontSize: theme.axis.fontSize + 'px',
         }"
       >
-        {{ sub }}
+        <slot name="sub">{{ sub }}</slot>
       </span>
     </div>
   </Teleport>