@cfasim-ui/docs 0.4.4 → 0.4.6

package/charts/_shared/ChartAnnotations.vue

@@ -0,0 +1,346 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import type { ChartAnnotation } from "./annotations.js";
+import type { ChartBounds } from "./useChartPadding.js";
+
+const props = withDefaults(
+  defineProps<{
+    annotations?: readonly ChartAnnotation[];
+    /**
+     * Project an annotation's `(x, y)` (data coordinates) to pixel
+     * coordinates on the chart canvas. Return `null` to drop the
+     * annotation (e.g. an off-projection point on a map).
+     */
+    project: (x: number, y: number) => { x: number; y: number } | null;
+    /**
+     * Pixel-space bounds of the plot area. Required for rule annotations
+     * so the line can span the full plot. When omitted, rule annotations
+     * are skipped.
+     */
+    bounds?: ChartBounds;
+  }>(),
+  {
+    annotations: () => [],
+    bounds: undefined,
+  },
+);
+
+// Match the x/y axis label styling so annotations blend in by default.
+const DEFAULT_FONT_SIZE = 13;
+const DEFAULT_FONT_WEIGHT = "normal";
+const BOLD_FONT_WEIGHT = 700;
+const DEFAULT_HALO_COLOR = "var(--color-bg-0, #fff)";
+const DEFAULT_HALO_WIDTH = 3;
+const DEFAULT_LINE_WIDTH = 1;
+const ANCHOR_GAP_PX = 4;
+const LABEL_GAP_PX = 6;
+const LINE_HEIGHT_RATIO = 1.2;
+// Ratio of font-size that puts the pointer endpoint at the visual center
+// of the first text line (between baseline and cap-height). Lands on the
+// x-height middle for most fonts.
+const FIRST_LINE_CENTER_RATIO = 0.35;
+// Nudge the start of the curve a few pixels in the offset direction so
+// it doesn't sit directly on top of axis lines or gridlines at the
+// anchor.
+const START_NUDGE_PX = 3;
+
+interface TextRun {
+  text: string;
+  bold: boolean;
+  italic: boolean;
+}
+
+interface RenderedAnnotation {
+  lines: TextRun[][];
+  textX: number;
+  textY: number;
+  textAnchor: "start" | "middle" | "end";
+  dy: number;
+  fontSize: number;
+  fontWeight: string | number;
+  color: string;
+  haloColor: string;
+  haloWidth: number;
+  pointerPath: string;
+  lineColor: string;
+  lineWidth: number;
+  lineDash?: string;
+  arrow: boolean;
+  rule?: { x1: number; y1: number; x2: number; y2: number };
+}
+
+function resolveDash(
+  dash: string | number | readonly number[] | undefined,
+): string | undefined {
+  if (dash === undefined) return undefined;
+  if (typeof dash === "number") return `${dash} ${dash}`;
+  if (typeof dash === "string") return dash;
+  return dash.join(" ");
+}
+
+/**
+ * Parse a single line for `**bold**` and `_italic_` runs. Markers
+ * compose (`**_both_**`) and are forgiving — an unclosed marker carries
+ * its state through the rest of the line.
+ */
+function parseInline(line: string): TextRun[] {
+  const out: TextRun[] = [];
+  let bold = false;
+  let italic = false;
+  let buf = "";
+  const flush = () => {
+    if (buf) out.push({ text: buf, bold, italic });
+    buf = "";
+  };
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "*" && line[i + 1] === "*") {
+      flush();
+      bold = !bold;
+      i++;
+    } else if (ch === "_") {
+      flush();
+      italic = !italic;
+    } else {
+      buf += ch;
+    }
+  }
+  flush();
+  return out.length === 0 ? [{ text: "", bold: false, italic: false }] : out;
+}
+
+const items = computed<RenderedAnnotation[]>(() => {
+  const out: RenderedAnnotation[] = [];
+  for (const a of props.annotations) {
+    const projected = props.project(a.x, a.y);
+    if (!projected) continue;
+    if (!isFinite(projected.x) || !isFinite(projected.y)) continue;
+
+    const pointer = a.pointer ?? "curved";
+    const isRule = pointer.startsWith("rule");
+
+    // Rule pointers require known plot bounds.
+    if (isRule && !props.bounds) continue;
+
+    const { x: offsetX, y: offsetY } = a.offset;
+    const labelX = projected.x + offsetX;
+    const labelY = projected.y + offsetY;
+    const color = a.color ?? "currentColor";
+    const fontSize = a.fontSize ?? DEFAULT_FONT_SIZE;
+    const fontWeight = a.fontWeight ?? DEFAULT_FONT_WEIGHT;
+    const haloColor = a.haloColor ?? DEFAULT_HALO_COLOR;
+    const haloWidth = a.haloWidth ?? DEFAULT_HALO_WIDTH;
+    const lineColor = a.lineColor ?? color;
+    const lineWidth = a.lineWidth ?? DEFAULT_LINE_WIDTH;
+    const lineDash = resolveDash(a.lineDash);
+    const textAnchor =
+      a.textAnchor ?? (offsetX > 0 ? "start" : offsetX < 0 ? "end" : "middle");
+
+    let rule: RenderedAnnotation["rule"];
+    let pointerPath = "";
+    if (isRule && props.bounds) {
+      rule = computeRule(pointer, projected.x, projected.y, props.bounds);
+    } else {
+      pointerPath = buildPointerPath(
+        projected.x,
+        projected.y,
+        labelX,
+        labelY,
+        fontSize,
+        pointer as "curved" | "straight" | "none",
+      );
+    }
+
+    out.push({
+      lines: a.text.split("\n").map(parseInline),
+      textX: labelX,
+      textY: labelY,
+      textAnchor,
+      dy: fontSize * LINE_HEIGHT_RATIO,
+      fontSize,
+      fontWeight,
+      color,
+      haloColor,
+      haloWidth,
+      pointerPath,
+      lineColor,
+      lineWidth,
+      lineDash,
+      arrow: !isRule && (a.arrow ?? true),
+      rule,
+    });
+  }
+  return out;
+});
+
+/**
+ * Endpoints for a rule line through the anchor.
+ * - `ruleX` / `ruleY`: full plot span on the named axis.
+ * - `ruleUp` / `ruleDown` / `ruleFromLeft` / `ruleFromRight`: partial
+ *   rule from one plot edge in to the anchor.
+ */
+function computeRule(
+  pointer: string,
+  ax: number,
+  ay: number,
+  b: ChartBounds,
+): { x1: number; y1: number; x2: number; y2: number } {
+  switch (pointer) {
+    case "ruleX":
+      return { x1: ax, y1: b.top, x2: ax, y2: b.bottom };
+    case "ruleY":
+      return { x1: b.left, y1: ay, x2: b.right, y2: ay };
+    case "ruleUp":
+      return { x1: ax, y1: b.bottom, x2: ax, y2: ay };
+    case "ruleDown":
+      return { x1: ax, y1: b.top, x2: ax, y2: ay };
+    case "ruleFromLeft":
+      return { x1: b.left, y1: ay, x2: ax, y2: ay };
+    case "ruleFromRight":
+      return { x1: b.right, y1: ay, x2: ax, y2: ay };
+    default:
+      return { x1: ax, y1: ay, x2: ax, y2: ay };
+  }
+}
+
+/**
+ * Build the pointer line from the anchor to the label.
+ *
+ * - When the label has offset in only one dimension, the line is
+ *   straight (vertical or horizontal) ending at the label's baseline.
+ * - When both dimensions have offset, the line is a quarter-arc:
+ *   a quadratic Bezier with the control point at `(anchorX, firstLineY)`
+ *   where `firstLineY` is the visual center of the first line of text
+ *   (slightly above the baseline). The curve emerges from the anchor
+ *   vertically toward the label's row, then bends horizontally into the
+ *   label so the endpoint reads as pointing at the first line — not at
+ *   the bottom of a multi-line block.
+ */
+function buildPointerPath(
+  ax: number,
+  ay: number,
+  lx: number,
+  ly: number,
+  fontSize: number,
+  pointer: "curved" | "straight" | "none",
+): string {
+  if (pointer === "none") return "";
+  const dx = lx - ax;
+  const dy = ly - ay;
+
+  // Target the visual center of the first line so multi-line text
+  // doesn't have the pointer dive below the whole block.
+  const targetY = ly - fontSize * FIRST_LINE_CENTER_RATIO;
+
+  // Pure horizontal or vertical → straight line at baseline, no curve.
+  // Force straight when explicitly requested.
+  if (dx === 0 || dy === 0 || pointer === "straight") {
+    // For straight pointers, aim at first-line-center (so multi-line text
+    // still points at the first line) — but only when the anchor isn't
+    // already at exactly the same Y (pure horizontal offset). The pure
+    // horizontal case stays on the baseline so it's a real horizontal line.
+    const ey = dy === 0 ? ly : targetY;
+    const segDx = lx - ax;
+    const segDy = ey - ay;
+    const len = Math.hypot(segDx, segDy);
+    if (len <= ANCHOR_GAP_PX + LABEL_GAP_PX) return "";
+    const ux = segDx / len;
+    const uy = segDy / len;
+    const sx = ax + ux * ANCHOR_GAP_PX;
+    const sy = ay + uy * ANCHOR_GAP_PX;
+    const ex = lx - ux * LABEL_GAP_PX;
+    const eyClamped = ey - uy * LABEL_GAP_PX;
+    return `M${sx},${sy} L${ex},${eyClamped}`;
+  }
+
+  const adjDy = targetY - ay;
+
+  // Skip the curve if one dimension is too small to clear its gap.
+  if (Math.abs(adjDy) <= ANCHOR_GAP_PX || Math.abs(dx) <= LABEL_GAP_PX) {
+    return "";
+  }
+
+  const xDir = Math.sign(dx);
+  const yDir = Math.sign(adjDy);
+  // Nudge the start horizontally toward the label so the line doesn't
+  // sit on top of axis/grid lines passing through the anchor.
+  const sx = ax + xDir * START_NUDGE_PX;
+  const sy = ay + yDir * ANCHOR_GAP_PX;
+  const ex = lx - xDir * LABEL_GAP_PX;
+  const ey = targetY;
+  // Control sits at (sx, targetY) so the curve emerges from the nudged
+  // start tangent vertically and lands on the label horizontally —
+  // a clean quarter-arc shape.
+  return `M${sx},${sy} Q${sx},${targetY} ${ex},${ey}`;
+}
+</script>
+
+<template>
+  <defs>
+    <marker
+      id="chart-annotation-arrow"
+      viewBox="0 0 8 8"
+      refX="7"
+      refY="4"
+      markerWidth="6"
+      markerHeight="6"
+      orient="auto-start-reverse"
+      markerUnits="userSpaceOnUse"
+    >
+      <path d="M0,0 L8,4 L0,8 Z" fill="context-stroke" />
+    </marker>
+  </defs>
+  <g class="chart-annotations" pointer-events="none">
+    <template v-for="(item, i) in items" :key="i">
+      <line
+        v-if="item.rule"
+        :x1="item.rule.x1"
+        :y1="item.rule.y1"
+        :x2="item.rule.x2"
+        :y2="item.rule.y2"
+        :stroke="item.lineColor"
+        :stroke-width="item.lineWidth"
+        :stroke-dasharray="item.lineDash"
+        stroke-linecap="round"
+      />
+      <path
+        v-if="item.pointerPath"
+        :d="item.pointerPath"
+        fill="none"
+        :stroke="item.lineColor"
+        :style="{ color: item.lineColor }"
+        :stroke-width="item.lineWidth"
+        :stroke-dasharray="item.lineDash"
+        stroke-linecap="round"
+        :marker-start="item.arrow ? 'url(#chart-annotation-arrow)' : undefined"
+      />
+      <text
+        :x="item.textX"
+        :y="item.textY"
+        :text-anchor="item.textAnchor"
+        :font-size="item.fontSize"
+        :font-weight="item.fontWeight"
+        :fill="item.color"
+        :stroke="item.haloColor"
+        :stroke-width="item.haloWidth"
+        stroke-linejoin="round"
+        paint-order="stroke fill"
+      >
+        <tspan
+          v-for="(line, li) in item.lines"
+          :key="li"
+          :x="item.textX"
+          :dy="li === 0 ? 0 : item.dy"
+        >
+          <tspan
+            v-for="(run, ri) in line"
+            :key="ri"
+            :font-weight="run.bold ? BOLD_FONT_WEIGHT : undefined"
+            :font-style="run.italic ? 'italic' : undefined"
+            >{{ run.text }}</tspan
+          >
+        </tspan>
+      </text>
+    </template>
+  </g>
+</template>

package/charts/_shared/annotations.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared annotation API for charts. Each chart projects an annotation's
+ * data-space `(x, y)` to pixels with its own scales and hands the resolved
+ * positions to `ChartAnnotations.vue` for rendering.
+ */
+
+export interface ChartAnnotation {
+  /**
+   * Anchor x position in data coordinates. For `LineChart` this is the
+   * same x-space as the series data; for `BarChart` it's the category
+   * index (fractional values land between categories).
+   */
+  x: number;
+  /** Anchor y position in data coordinates (value axis). */
+  y: number;
+  /**
+   * Label text.
+   * - `\n` produces a line break.
+   * - `**bold**` renders a run in bold.
+   * - `_italic_` renders a run in italic.
+   * - The two compose: `**_both_**`.
+   */
+  text: string;
+  /**
+   * Pixel offset from the anchor to the label's reference position.
+   * Positive `x` = right, positive `y` = down (screen-space).
+   */
+  offset: { x: number; y: number };
+  /** Text and pointer-line color. Defaults to `currentColor`. */
+  color?: string;
+  /** Font size in pixels. Default: 13 (matches axis labels). */
+  fontSize?: number;
+  /**
+   * Base font weight applied to all non-bold runs. Default: `"normal"`
+   * (matches axis labels). `**bold**` runs in `text` always render at
+   * weight 700.
+   */
+  fontWeight?: string | number;
+  /**
+   * Halo (stroke) color drawn behind the text so the label stays legible
+   * against busy chart elements. Defaults to `var(--color-bg-0, #fff)` so
+   * it matches the page background out of the box.
+   */
+  haloColor?: string;
+  /** Halo stroke width in pixels. Default: 3. */
+  haloWidth?: number;
+  /**
+   * SVG text-anchor for the label. When omitted, derived from the sign of
+   * `offset.x`: positive → `start`, negative → `end`, zero → `middle`.
+   */
+  textAnchor?: "start" | "middle" | "end";
+  /** Pointer- or rule-line color override. Defaults to `color`. */
+  lineColor?: string;
+  /** Pointer- or rule-line width in pixels. Default: 1. */
+  lineWidth?: number;
+  /**
+   * SVG `stroke-dasharray` for the pointer or rule line. Accepts the
+   * raw string form (`"4 4"`), a single number (uniform dash/gap), or
+   * an array of numbers. Default: solid line.
+   */
+  lineDash?: string | number | readonly number[];
+  /**
+   * Connector shape between anchor and label.
+   * - `"curved"` (default): quarter-arc emerging vertically from the
+   *   anchor, landing horizontally at the label.
+   * - `"straight"`: single straight line from anchor to label.
+   * - `"none"`: no connector — just the text label is rendered.
+   * - `"ruleX"`: vertical rule at the annotation's `x` value spanning
+   *   the full plot height. Label still positions via `offset`.
+   * - `"ruleY"`: horizontal rule at the annotation's `y` value spanning
+   *   the full plot width.
+   * - `"ruleUp"`: vertical rule from the plot's bottom edge up to the
+   *   anchor.
+   * - `"ruleDown"`: vertical rule from the plot's top edge down to the
+   *   anchor.
+   * - `"ruleFromLeft"`: horizontal rule from the plot's left edge in to
+   *   the anchor.
+   * - `"ruleFromRight"`: horizontal rule from the plot's right edge in
+   *   to the anchor.
+   *
+   * When the offset is purely horizontal or vertical (and `pointer`
+   * isn't `"none"` or a rule), the pointer is always straight regardless
+   * of this setting. Rule pointers ignore `arrow`.
+   */
+  pointer?:
+    | "curved"
+    | "straight"
+    | "none"
+    | "ruleX"
+    | "ruleY"
+    | "ruleUp"
+    | "ruleDown"
+    | "ruleFromLeft"
+    | "ruleFromRight";
+  /**
+   * Whether to draw a small filled triangle at the anchor end of the
+   * connector line. Defaults to `true`. Set to `false` for an
+   * uncapped line. Ignored for rule pointers.
+   */
+  arrow?: boolean;
+}

package/charts/_shared/chartProps.ts

@@ -0,0 +1,75 @@
+/**
+ * Prop / slot / emit types shared by LineChart and BarChart. Component
+ * authors compose these with chart-specific props via TypeScript
+ * intersection (e.g. `defineProps<ChartCommonProps & MyExtraProps>()`).
+ */
+
+import type { ChartAnnotation } from "./annotations.js";
+import type { ChartPadding } from "./useChartPadding.js";
+
+/**
+ * Props common to every cartesian chart component. Anything specific to
+ * the chart type (series shape, layout, value-axis details) lives on the
+ * component itself.
+ */
+export interface ChartCommonProps {
+  width?: number;
+  height?: number;
+  title?: string;
+  xLabel?: string;
+  yLabel?: string;
+  debounce?: number;
+  menu?: boolean | string;
+  /**
+   * Custom per-index data forwarded to the `tooltip` slot. Accepts a
+   * plain array or any `ArrayLike` (e.g. a typed-array column).
+   */
+  tooltipData?: ArrayLike<unknown>;
+  /** Tooltip activation mode. */
+  tooltipTrigger?: "hover" | "click";
+  /** Boundary for tooltip flip/clamp. Default: `"chart"`. */
+  tooltipClamp?: "none" | "chart" | "window";
+  /**
+   * Formatter for numeric values shown in the default tooltip. Receives
+   * the raw value. When omitted, the chart falls back to its value-axis
+   * tick formatter, then `formatTick`.
+   */
+  tooltipValueFormat?: (value: number) => string;
+  /**
+   * Custom CSV content (string or function) for the Download CSV menu
+   * item. When omitted, CSV is generated from the chart's series.
+   */
+  csv?: string | (() => string);
+  /** Filename (without extension) for SVG, PNG, and CSV downloads. */
+  filename?: string;
+  /**
+   * Show a plain text link below the chart to download CSV. Pass `true`
+   * for the default label or a string to customize.
+   */
+  downloadLink?: boolean | string;
+  /** Annotations rendered as the top layer of the chart. */
+  annotations?: readonly ChartAnnotation[];
+  /**
+   * Extra padding (pixels) added around the plot. Number = same on all
+   * sides; object = per-side. Useful for giving annotations or other
+   * overlays room to extend past the data area without clipping.
+   */
+  chartPadding?: ChartPadding;
+}
+
+/** Payload emitted on `hover` from a cartesian chart. */
+export type ChartHoverPayload = { index: number } | null;
+
+/** One per-series value passed to the tooltip slot. */
+export interface ChartTooltipValue {
+  value: number;
+  color: string;
+  seriesIndex: number;
+}
+
+/** Properties common to every chart's tooltip slot. */
+export interface ChartTooltipBaseProps {
+  index: number;
+  values: ChartTooltipValue[];
+  data: unknown;
+}

package/charts/_shared/index.ts

@@ -11,6 +11,8 @@ export {
   useChartPadding,
   INLINE_LEGEND_HEIGHT,
   type ChartPaddingOptions,
+  type ChartPadding,
+  type ChartBounds,
 } from "./useChartPadding.js";
 export {
   useChartTooltip,
@@ -18,3 +20,16 @@ export {
 } from "./useChartTooltip.js";
 export { useChartMenu, type ChartMenuOptions } from "./useChartMenu.js";
 export { seriesToCsv, categoricalToCsv, type CsvSeries } from "./seriesCsv.js";
+export { default as ChartAnnotations } from "./ChartAnnotations.vue";
+export type { ChartAnnotation } from "./annotations.js";
+export {
+  useChartFoundation,
+  makeTooltipValueFormatter,
+  type ChartFoundationOptions,
+} from "./useChartFoundation.js";
+export type {
+  ChartCommonProps,
+  ChartHoverPayload,
+  ChartTooltipValue,
+  ChartTooltipBaseProps,
+} from "./chartProps.js";

package/charts/_shared/useChartFoundation.ts

@@ -0,0 +1,124 @@
+import { computed } from "vue";
+import { formatTick } from "./axes.js";
+import { useChartSize } from "./useChartSize.js";
+import { useChartPadding, type ChartPadding } from "./useChartPadding.js";
+import { useChartTooltip } from "./useChartTooltip.js";
+import type { TooltipClamp } from "../tooltip-position.js";
+import { useChartMenu } from "./useChartMenu.js";
+
+const DEFAULT_WIDTH_FALLBACK = 400;
+const DEFAULT_HEIGHT = 200;
+
+export interface ChartFoundationOptions {
+  // Reactive getters for the shared chart props.
+  width: () => number | undefined;
+  height: () => number | undefined;
+  title: () => string | undefined;
+  xLabel: () => string | undefined;
+  yLabel: () => string | undefined;
+  debounce: () => number | undefined;
+  menu: () => boolean | string | undefined;
+  tooltipTrigger: () => "hover" | "click" | undefined;
+  tooltipClamp: () => TooltipClamp | undefined;
+  filename: () => string | undefined;
+  downloadLink: () => boolean | string | undefined;
+  chartPadding: () => ChartPadding | undefined;
+  // Chart-specific hooks that the composable can't infer.
+  hasInlineLegend: () => boolean;
+  hasTooltipSlot: () => boolean;
+  getCsv: () => string;
+  pointerToIndex: (clientX: number, clientY: number) => number | null;
+  onHover: (payload: { index: number } | null) => void;
+}
+
+/**
+ * Wires up the shared chart plumbing — size measurement, padding, tooltip
+ * interaction, and the menu/download wiring — that every cartesian chart
+ * needs. Returns the reactive values and refs each chart's template
+ * consumes.
+ */
+export function useChartFoundation(opts: ChartFoundationOptions) {
+  const { containerRef, measuredWidth } = useChartSize({
+    debounce: opts.debounce,
+  });
+
+  const width = computed(
+    () => opts.width() ?? (measuredWidth.value || DEFAULT_WIDTH_FALLBACK),
+  );
+  const height = computed(() => opts.height() ?? DEFAULT_HEIGHT);
+
+  const { padding, legendY, innerW, innerH, bounds } = useChartPadding({
+    title: opts.title,
+    xLabel: opts.xLabel,
+    yLabel: opts.yLabel,
+    hasInlineLegend: opts.hasInlineLegend,
+    width: () => width.value,
+    height: () => height.value,
+    extraPadding: opts.chartPadding,
+  });
+
+  const {
+    hoverIndex,
+    tooltipRef,
+    tooltipPos,
+    handlers: tooltipHandlers,
+  } = useChartTooltip({
+    enabled: opts.hasTooltipSlot,
+    trigger: opts.tooltipTrigger,
+    clamp: () => opts.tooltipClamp() ?? "chart",
+    pointerToIndex: opts.pointerToIndex,
+    containerRef,
+    onHover: opts.onHover,
+  });
+
+  const {
+    svgRef,
+    items: menuItems,
+    downloadLinkText,
+    csvHref,
+    resolvedFilename: menuFilename,
+  } = useChartMenu({
+    filename: opts.filename,
+    legacyMenuLabel: opts.menu,
+    getCsv: opts.getCsv,
+    downloadLink: opts.downloadLink,
+  });
+
+  return {
+    containerRef,
+    svgRef,
+    width,
+    height,
+    padding,
+    legendY,
+    innerW,
+    innerH,
+    bounds,
+    hoverIndex,
+    tooltipRef,
+    tooltipPos,
+    tooltipHandlers,
+    menuItems,
+    downloadLinkText,
+    csvHref,
+    menuFilename,
+  };
+}
+
+/**
+ * Build a tooltip value formatter that prefers `tooltipValueFormat`,
+ * falls back to the chart's axis tick formatter, and finally to
+ * `formatTick`. Both chart components use the same precedence order.
+ */
+export function makeTooltipValueFormatter(
+  tooltipFormat: () => ((v: number) => string) | undefined,
+  axisFormat: () => ((v: number) => string) | undefined,
+): (v: number) => string {
+  return (v: number) => {
+    const tf = tooltipFormat();
+    if (tf) return tf(v);
+    const af = axisFormat();
+    if (af) return af(v);
+    return formatTick(v);
+  };
+}