@cfasim-ui/docs 0.4.4 → 0.4.6

package/charts/LineChart/LineChart.md

@@ -391,6 +391,199 @@ Highlight a range of a series line by filling the area between the line and the
   </template>
 </ComponentDemo>
 
+### Annotations
+
+Pin callouts to data points with `annotations`. Each annotation anchors at
+`(x, y)` in data coordinates (the same x-space as the chart axis, so it
+respects `xMin` and explicit `x` values), with a pixel
+`offset: { x, y }` for the label position. Text supports `\n` for line
+breaks. A curved
+pointer line connects the anchor to the label, and the label gets a halo
+stroke matching the background so it stays legible over series lines.
+
+<ComponentDemo>
+  <LineChart
+    :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+    :annotations="[
+      { x: 5, y: 30, offset: { x: 24, y: -28 }, text: 'Peak\nDay 5' },
+      { x: 0, y: 0, offset: { x: 28, y: -22 }, text: 'Onset' },
+    ]"
+    :chart-padding="{ top: 40, right: 24 }"
+    :height="240"
+    x-label="Days"
+    y-label="Cases"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+  :annotations="[
+    { x: 5, y: 30, offset: { x: 24, y: -28 }, text: 'Peak\nDay 5' },
+    { x: 0, y: 0, offset: { x: 28, y: -22 }, text: 'Onset' },
+  ]"
+  :chart-padding="{ top: 40, right: 24 }"
+  :height="240"
+  x-label="Days"
+  y-label="Cases"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Use `chart-padding` to reserve room outside the plot so annotations (or
+any other overlay) don't clip the data area. It accepts a number (same on
+all sides) or an object with `top`, `right`, `bottom`, `left`.
+
+Annotation text supports a small set of inline markers:
+
+- `**bold**` — bold
+- `_italic_` — italic
+- `\n` — line break
+
+Markers compose (`**_bold italic_**`).
+
+<ComponentDemo>
+  <LineChart
+    :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+    :annotations="[
+      { x: 5, y: 30, offset: { x: 24, y: -28 }, text: '**Peak**\n_Day 5_' },
+    ]"
+    :chart-padding="{ top: 40, right: 24 }"
+    :height="240"
+    x-label="Days"
+    y-label="Cases"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+  :annotations="[
+    { x: 5, y: 30, offset: { x: 24, y: -28 }, text: '**Peak**\n_Day 5_' },
+  ]"
+  :chart-padding="{ top: 40, right: 24 }"
+  :height="240"
+  x-label="Days"
+  y-label="Cases"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+```ts
+interface ChartAnnotation {
+  x: number; // anchor in data coords (x-axis)
+  y: number; // anchor in data coords (y-axis)
+  text: string; // label text; \n produces line breaks
+  offset: { x: number; y: number }; // pixel offset from anchor to label
+  color?: string; // text / pointer color (default: currentColor)
+  fontSize?: number; // default: 13 (matches axis labels)
+  fontWeight?: string | number; // default: "normal"
+  haloColor?: string; // background-matched halo (default: var(--color-bg-0, #fff))
+  haloWidth?: number; // default: 3
+  textAnchor?: "start" | "middle" | "end"; // default: derived from offset[0] sign
+  lineColor?: string; // connector-line color override (default: color)
+  lineWidth?: number; // default: 1
+  lineDash?: string | number | readonly number[]; // SVG stroke-dasharray
+  // default: "curved"
+  // "ruleX" / "ruleY" span the full plot on the named axis;
+  // "ruleUp" / "ruleDown" / "ruleFromLeft" / "ruleFromRight" run from an edge to the anchor.
+  pointer?:
+    | "curved"
+    | "straight"
+    | "none"
+    | "ruleX"
+    | "ruleY"
+    | "ruleUp"
+    | "ruleDown"
+    | "ruleFromLeft"
+    | "ruleFromRight";
+  arrow?: boolean; // triangle marker at the anchor end (default: true)
+}
+```
+
+### Rules
+
+Set `pointer` to one of the rule values to replace the curved /
+straight connector with a straight line through the anchor:
+
+- `"ruleX"` — vertical line spanning the plot height at the annotation's `x`.
+- `"ruleY"` — horizontal line spanning the plot width at the annotation's `y`.
+- `"ruleUp"` — vertical from the bottom edge up to the anchor.
+- `"ruleDown"` — vertical from the top edge down to the anchor.
+- `"ruleFromLeft"` — horizontal from the left edge in to the anchor.
+- `"ruleFromRight"` — horizontal from the right edge in to the anchor.
+
+`lineColor`, `lineWidth`, and `lineDash` style the line. The label is
+positioned from the anchor as usual via `offset`.
+
+<ComponentDemo>
+  <LineChart
+    :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+    :annotations="[
+      {
+        x: 5,
+        y: 30,
+        offset: { x: 8, y: 14 },
+        text: 'Peak',
+        pointer: 'ruleX',
+        lineDash: '4 3',
+      },
+      {
+        x: 5,
+        y: 30,
+        offset: { x: -8, y: -6 },
+        text: 'Max',
+        textAnchor: 'end',
+        pointer: 'ruleFromLeft',
+        lineDash: '4 3',
+      },
+    ]"
+    :chart-padding="{ top: 24, right: 24 }"
+    :height="240"
+    x-label="Days"
+    y-label="Cases"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+  :annotations="[
+    {
+      x: 5,
+      y: 30,
+      offset: { x: 8, y: 14 },
+      text: 'Peak',
+      pointer: 'ruleX',
+      lineDash: '4 3',
+    },
+    {
+      x: 5,
+      y: 30,
+      offset: { x: -8, y: -6 },
+      text: 'Max',
+      textAnchor: 'end',
+      pointer: 'ruleFromLeft',
+      lineDash: '4 3',
+    },
+  ]"
+  :chart-padding="{ top: 24, right: 24 }"
+  :height="240"
+  x-label="Days"
+  y-label="Cases"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Custom CSV download
 
 By default, the Download CSV menu item exports the chart series as CSV. Use
@@ -444,36 +637,38 @@ until the user clicks Download:
 
 | Prop | Type | Required | Default |
 |------|------|----------|---------|
+| `width` | `number` | No | — |
+| `height` | `number` | No | — |
+| `title` | `string` | No | — |
+| `xLabel` | `string` | No | — |
+| `yLabel` | `string` | No | — |
+| `debounce` | `number` | No | — |
+| `menu` | `boolean \| string` | No | `true` |
+| `tooltipData` | `ArrayLike&lt;unknown&gt;` | No | — |
+| `tooltipTrigger` | `"hover" \| "click"` | No | — |
+| `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
+| `tooltipValueFormat` | `(value: number) =&gt; string` | No | — |
+| `csv` | `string \| (() =&gt; string)` | No | — |
+| `filename` | `string` | No | — |
+| `downloadLink` | `boolean \| string` | No | — |
+| `annotations` | `readonly ChartAnnotation[]` | No | — |
+| `chartPadding` | `ChartPadding` | No | — |
 | `y` | `LineChartData` | No | — |
 | `data` | `LineChartData` | No | — |
 | `x` | `LineChartData` | No | — |
 | `series` | `Series[]` | No | — |
 | `areas` | `Area[]` | No | — |
 | `areaSections` | `AreaSection[]` | No | — |
-| `width` | `number` | No | — |
-| `height` | `number` | No | — |
 | `lineOpacity` | `number` | No | `1` |
-| `title` | `string` | No | — |
-| `xLabel` | `string` | No | — |
-| `yLabel` | `string` | No | — |
 | `yMin` | `number` | No | — |
 | `xMin` | `number` | No | — |
 | `xTicks` | `number \| number[]` | No | — |
 | `yTicks` | `number \| number[]` | No | — |
 | `xTickFormat` | `(value: number, index: number) =&gt; string` | No | — |
 | `yTickFormat` | `(value: number) =&gt; string` | No | — |
-| `tooltipValueFormat` | `(value: number) =&gt; string` | No | — |
 | `xLabels` | `string[]` | No | — |
-| `debounce` | `number` | No | — |
-| `menu` | `boolean \| string` | No | `true` |
 | `xGrid` | `boolean` | No | — |
 | `yGrid` | `boolean` | No | — |
-| `tooltipData` | `ArrayLike&lt;unknown&gt;` | No | — |
-| `tooltipTrigger` | `"hover" \| "click"` | No | — |
-| `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
-| `csv` | `string \| (() =&gt; string)` | No | — |
-| `filename` | `string` | No | — |
-| `downloadLink` | `boolean \| string` | No | — |
 
 
 ### Data

package/charts/LineChart/LineChart.vue

@@ -1,17 +1,18 @@
 <script setup lang="ts">
-import { computed, ref } from "vue";
+import { computed } from "vue";
 import ChartMenu from "../ChartMenu/ChartMenu.vue";
 import {
   snap,
   formatTick,
   computeTickValues,
   seriesToCsv,
-  useChartSize,
-  useChartTooltip,
-  useChartMenu,
-  useChartPadding,
-  INLINE_LEGEND_HEIGHT,
+  useChartFoundation,
+  makeTooltipValueFormatter,
+  ChartAnnotations,
   type ChartData,
+  type ChartCommonProps,
+  type ChartHoverPayload,
+  type ChartTooltipBaseProps,
 } from "../_shared/index.js";
 
 /**
@@ -83,118 +84,69 @@ export interface AreaSection {
   legend?: "inline" | "below" | false;
 }
 
-const props = withDefaults(
-  defineProps<{
-    /** Y-values. Equivalent to `data`. If both are set, `y` wins. */
-    y?: LineChartData;
-    /** Y-values (alternative name for `y`). */
-    data?: LineChartData;
-    /**
-     * Optional x-values paired with `y`/`data`. When provided, points
-     * are plotted at the given x positions instead of at their indices.
-     * Ignored when `series` is used — set `x` on each `Series` instead.
-     */
-    x?: LineChartData;
-    series?: Series[];
-    areas?: Area[];
-    areaSections?: AreaSection[];
-    width?: number;
-    height?: number;
-    lineOpacity?: number;
-    title?: string;
-    xLabel?: string;
-    yLabel?: string;
-    yMin?: number;
-    /**
-     * Offset applied to index-based x values (e.g. `xMin: 10` starts the
-     * x axis at 10 instead of 0). Ignored when any series or area has
-     * explicit `x` values.
-     */
-    xMin?: number;
-    /**
-     * Tick placement on the x-axis. Number = interval in data units
-     * (respecting `xMin`, e.g. `7` ticks every 7 days). Array = explicit tick
-     * values in data space; values outside the data range are dropped.
-     * When omitted, ticks are chosen automatically.
-     */
-    xTicks?: number | number[];
-    /**
-     * Tick placement on the y-axis. Number = interval in data units. Array =
-     * explicit tick values; values outside the data range are dropped. When
-     * omitted, ticks are chosen automatically.
-     */
-    yTicks?: number | number[];
-    /** Formatter for x-axis tick labels. Receives the raw numeric value. */
-    xTickFormat?: (value: number, index: number) => string;
-    /** Formatter for y-axis tick labels. Receives the raw numeric value. */
-    yTickFormat?: (value: number) => string;
-    /**
-     * Formatter for numeric values shown in the default tooltip. Receives
-     * the raw value. Defaults to the same tick formatter used for axes.
-     */
-    tooltipValueFormat?: (value: number) => string;
-    /**
-     * @deprecated Use `xTickFormat` (e.g. `(_, i) => labels[i]`) together
-     * with `xTicks` for explicit control. Still honored for tooltip x-labels
-     * and as a default x-tick formatter when `xTickFormat` is not provided.
-     */
-    xLabels?: string[];
-    debounce?: number;
-    menu?: boolean | string;
-    xGrid?: boolean;
-    yGrid?: boolean;
-    /**
-     * Custom per-index data passed to the tooltip slot. Accepts a plain
-     * array or any `ArrayLike` (e.g. a typed array column from a
-     * `ModelOutput`).
-     */
-    tooltipData?: ArrayLike<unknown>;
-    /** Tooltip activation mode. Default: 'hover' */
-    tooltipTrigger?: "hover" | "click";
-    /**
-     * Boundary for tooltip flip/clamp. `"none"` always places to the right of
-     * the pointer with no clamping. `"chart"` (default) uses the chart
-     * container's bounding box. `"window"` uses the viewport.
-     */
-    tooltipClamp?: "none" | "chart" | "window";
-    /**
-     * Custom CSV content for the Download CSV menu item. Can be a raw CSV
-     * string or a function returning one. When omitted, CSV is generated
-     * from the chart series.
-     */
-    csv?: string | (() => string);
-    /** Filename (without extension) for downloaded SVG, PNG and CSV files. */
-    filename?: string;
-    /**
-     * Show a plain text link below the chart to download the CSV data.
-     * Pass `true` for the default label ("Download data (CSV)") or a string
-     * to customize the link text.
-     */
-    downloadLink?: boolean | string;
-  }>(),
-  { lineOpacity: 1, menu: true, tooltipClamp: "chart" },
-);
+interface LineChartProps extends ChartCommonProps {
+  /** Y-values. Equivalent to `data`. If both are set, `y` wins. */
+  y?: LineChartData;
+  /** Y-values (alternative name for `y`). */
+  data?: LineChartData;
+  /**
+   * Optional x-values paired with `y`/`data`. When provided, points
+   * are plotted at the given x positions instead of at their indices.
+   * Ignored when `series` is used — set `x` on each `Series` instead.
+   */
+  x?: LineChartData;
+  series?: Series[];
+  areas?: Area[];
+  areaSections?: AreaSection[];
+  lineOpacity?: number;
+  yMin?: number;
+  /**
+   * Offset applied to index-based x values (e.g. `xMin: 10` starts the
+   * x axis at 10 instead of 0). Ignored when any series or area has
+   * explicit `x` values.
+   */
+  xMin?: number;
+  /**
+   * Tick placement on the x-axis. Number = interval in data units
+   * (respecting `xMin`, e.g. `7` ticks every 7 days). Array = explicit tick
+   * values in data space; values outside the data range are dropped.
+   * When omitted, ticks are chosen automatically.
+   */
+  xTicks?: number | number[];
+  /**
+   * Tick placement on the y-axis. Number = interval in data units. Array =
+   * explicit tick values; values outside the data range are dropped. When
+   * omitted, ticks are chosen automatically.
+   */
+  yTicks?: number | number[];
+  /** Formatter for x-axis tick labels. Receives the raw numeric value. */
+  xTickFormat?: (value: number, index: number) => string;
+  /** Formatter for y-axis tick labels. Receives the raw numeric value. */
+  yTickFormat?: (value: number) => string;
+  /**
+   * @deprecated Use `xTickFormat` (e.g. `(_, i) => labels[i]`) together
+   * with `xTicks` for explicit control. Still honored for tooltip x-labels
+   * and as a default x-tick formatter when `xTickFormat` is not provided.
+   */
+  xLabels?: string[];
+  xGrid?: boolean;
+  yGrid?: boolean;
+}
+
+const props = withDefaults(defineProps<LineChartProps>(), {
+  lineOpacity: 1,
+  menu: true,
+  tooltipClamp: "chart",
+});
 
 const emit = defineEmits<{
-  (e: "hover", payload: { index: number } | null): void;
+  (e: "hover", payload: ChartHoverPayload): void;
 }>();
 
 defineSlots<{
-  tooltip?(props: {
-    index: number;
-    xLabel?: string;
-    values: { value: number; color: string; seriesIndex: number }[];
-    data: unknown;
-  }): unknown;
+  tooltip?(props: ChartTooltipBaseProps & { xLabel?: string }): unknown;
 }>();
 
-const { containerRef, measuredWidth } = useChartSize({
-  debounce: () => props.debounce,
-});
-
-const width = computed(() => props.width ?? (measuredWidth.value || 400));
-const height = computed(() => props.height ?? 200);
-
 const hasInlineLegend = computed(
   () =>
     allSeries.value.some((s) => s.legend) ||
@@ -204,15 +156,6 @@ const hasInlineLegend = computed(
     false,
 );
 
-const { padding, innerW, innerH } = useChartPadding({
-  title: () => props.title,
-  xLabel: () => props.xLabel,
-  yLabel: () => props.yLabel,
-  hasInlineLegend: () => hasInlineLegend.value,
-  width: () => width.value,
-  height: () => height.value,
-});
-
 /**
  * Internal series shape where `data` (y-values) is always resolved.
  * `Series.y` takes precedence over `Series.data` when both are set.
@@ -225,11 +168,10 @@ function resolveSeries(s: Series): ResolvedSeries {
   return { ...s, data: s.y ?? s.data ?? EMPTY_DATA };
 }
 
-function formatTooltipValue(v: number): string {
-  if (props.tooltipValueFormat) return props.tooltipValueFormat(v);
-  if (props.yTickFormat) return props.yTickFormat(v);
-  return formatTick(v);
-}
+const formatTooltipValue = makeTooltipValueFormatter(
+  () => props.tooltipValueFormat,
+  () => props.yTickFormat,
+);
 
 const allSeries = computed<ResolvedSeries[]>(() => {
   if (props.series && props.series.length > 0)
@@ -758,6 +700,18 @@ const hoverSlotProps = computed(() => {
   };
 });
 
+function projectAnnotation(
+  x: number,
+  y: number,
+): { x: number; y: number } | null {
+  if (!isFinite(x) || !isFinite(y)) return null;
+  const internalX = x - xDisplayOffset.value;
+  const { min, range } = extent.value;
+  const py =
+    padding.value.top + innerH.value - (y - min) * (innerH.value / range);
+  return { x: xPixel(internalX), y: py };
+}
+
 function indexFromPointer(clientX: number): number | null {
   const rect = containerRef.value?.getBoundingClientRect();
   if (!rect) return null;
@@ -771,30 +725,41 @@ function indexFromPointer(clientX: number): number | null {
 }
 
 const {
+  containerRef,
+  svgRef,
+  width,
+  height,
+  padding,
+  legendY,
+  innerW,
+  innerH,
+  bounds,
   hoverIndex,
   tooltipRef,
   tooltipPos,
-  handlers: tooltipHandlers,
-} = useChartTooltip({
-  enabled: () => hasTooltipSlot.value,
-  trigger: () => props.tooltipTrigger,
-  clamp: () => props.tooltipClamp,
-  pointerToIndex: indexFromPointer,
-  containerRef,
-  onHover: (payload) => emit("hover", payload),
-});
-
-const {
-  svgRef,
-  items: menuItems,
+  tooltipHandlers,
+  menuItems,
   downloadLinkText,
   csvHref,
-  resolvedFilename: menuFilename,
-} = useChartMenu({
+  menuFilename,
+} = useChartFoundation({
+  width: () => props.width,
+  height: () => props.height,
+  title: () => props.title,
+  xLabel: () => props.xLabel,
+  yLabel: () => props.yLabel,
+  debounce: () => props.debounce,
+  menu: () => props.menu,
+  tooltipTrigger: () => props.tooltipTrigger,
+  tooltipClamp: () => props.tooltipClamp,
   filename: () => props.filename,
-  legacyMenuLabel: () => props.menu,
-  getCsv: toCsv,
   downloadLink: () => props.downloadLink,
+  chartPadding: () => props.chartPadding,
+  hasInlineLegend: () => hasInlineLegend.value,
+  hasTooltipSlot: () => hasTooltipSlot.value,
+  getCsv: toCsv,
+  pointerToIndex: indexFromPointer,
+  onHover: (payload) => emit("hover", payload),
 });
 </script>
 
@@ -821,9 +786,9 @@ const {
           <line
             v-if="item.type === 'series'"
             :x1="padding.left + i * 120"
-            :y1="padding.top - INLINE_LEGEND_HEIGHT / 2"
+            :y1="legendY"
             :x2="padding.left + i * 120 + 12"
-            :y2="padding.top - INLINE_LEGEND_HEIGHT / 2"
+            :y2="legendY"
             :stroke="item.color"
             stroke-width="2"
             :stroke-dasharray="item.dashed ? '4 2' : undefined"
@@ -832,7 +797,7 @@ const {
           <circle
             v-else
             :cx="padding.left + i * 120 + 4"
-            :cy="padding.top - INLINE_LEGEND_HEIGHT / 2"
+            :cy="legendY"
             r="4"
             :fill="item.color"
             :fill-opacity="item.fillOpacity"
@@ -841,7 +806,7 @@ const {
           />
           <text
             :x="padding.left + i * 120 + 18"
-            :y="padding.top - INLINE_LEGEND_HEIGHT / 2 + 4"
+            :y="legendY + 4"
             font-size="11"
             fill="currentColor"
           >
@@ -1074,6 +1039,13 @@ const {
         style="cursor: crosshair; touch-action: none"
         v-on="tooltipHandlers"
       />
+      <!-- annotations (top layer) -->
+      <ChartAnnotations
+        v-if="annotations && annotations.length > 0"
+        :annotations="annotations"
+        :project="projectAnnotation"
+        :bounds="bounds"
+      />
       <!-- area section labels -->
       <g v-for="(item, i) in sectionLabels.labels" :key="'seclab' + i">
         <circle