@cfasim-ui/charts 0.7.7 → 0.8.0

package/src/_shared/ChartAnnotations.vue

@@ -0,0 +1,420 @@
+<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_OUTLINE_COLOR = "var(--color-bg-0, #fff)";
+const DEFAULT_OUTLINE_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 a text line (between baseline and cap-height). Lands on the x-height
+// middle for most fonts.
+const LINE_CENTER_RATIO = 0.35;
+
+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;
+  outlineColor: string;
+  outlineWidth: number;
+  pointerPath: string;
+  lineColor: string;
+  lineWidth: number;
+  lineDash?: string;
+  arrow: boolean;
+  // Inline arrow geometry. Rendered as a triangle with explicit fill so it
+  // renders correctly in Safari (which doesn't support `context-stroke` on
+  // SVG markers). Present only when an arrow should be drawn.
+  arrowTip?: { x: number; y: number; angle: number };
+  arrowTransform: string;
+  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 outlineColor = a.outlineColor ?? DEFAULT_OUTLINE_COLOR;
+    const outlineWidth = a.outlineWidth ?? DEFAULT_OUTLINE_WIDTH;
+    const lineColor = a.lineColor ?? color;
+    const lineWidth = a.lineWidth ?? DEFAULT_LINE_WIDTH;
+    const lineDash = resolveDash(a.lineDash);
+    const alignMap = { left: "start", center: "middle", right: "end" } as const;
+    const align =
+      a.align ?? (offsetX > 0 ? "left" : offsetX < 0 ? "right" : "center");
+    const textAnchor = alignMap[align];
+
+    const lines = a.text.split("\n").map(parseInline);
+
+    let rule: RenderedAnnotation["rule"];
+    let pointerPath = "";
+    let arrowTip: RenderedAnnotation["arrowTip"];
+    const wantArrow = !isRule && (a.arrow ?? true);
+    if (isRule && props.bounds) {
+      rule = computeRule(pointer, projected.x, projected.y, props.bounds);
+    } else {
+      const built = buildPointerPath(
+        projected.x,
+        projected.y,
+        labelX,
+        labelY,
+        fontSize,
+        lines.length,
+        pointer as "curved" | "straight" | "none",
+      );
+      pointerPath = built.path;
+      if (wantArrow && built.arrow) arrowTip = built.arrow;
+    }
+
+    out.push({
+      lines,
+      textX: labelX,
+      textY: labelY,
+      textAnchor,
+      dy: fontSize * LINE_HEIGHT_RATIO,
+      fontSize,
+      fontWeight,
+      color,
+      outlineColor,
+      outlineWidth,
+      pointerPath,
+      lineColor,
+      lineWidth,
+      lineDash,
+      arrow: wantArrow,
+      arrowTip,
+      arrowTransform: arrowTip
+        ? `translate(${arrowTip.x} ${arrowTip.y}) rotate(${arrowTip.angle})`
+        : "",
+      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, targetY)`
+ *   where `targetY` is the visual center of the text line nearest the
+ *   anchor (slightly above its baseline). The curve emerges from the
+ *   anchor vertically toward the label's row, then bends horizontally
+ *   into the label.
+ *
+ * `targetY` tracks the *near* edge of the text block: the first line
+ * when the label sits below the anchor (connector points up at the top
+ * line), the last line when the label sits above the anchor (connector
+ * points up at the bottom line) — so multi-line text above the point
+ * connects to its bottom edge instead of having the line cut through it.
+ */
+interface PointerGeom {
+  path: string;
+  // Tip position and rotation (degrees) for the inline arrow head. The
+  // arrow points opposite the path's start tangent — matching the look of
+  // `marker-start` with `orient="auto-start-reverse"`, but rendered as a
+  // plain triangle so the color works in Safari.
+  arrow?: { x: number; y: number; angle: number };
+}
+
+function buildPointerPath(
+  ax: number,
+  ay: number,
+  lx: number,
+  ly: number,
+  fontSize: number,
+  lineCount: number,
+  pointer: "curved" | "straight" | "none",
+): PointerGeom {
+  if (pointer === "none") return { path: "" };
+  const dx = lx - ax;
+  const dy = ly - ay;
+
+  // Aim at the visual center of the text line nearest the anchor: the
+  // first (top) line when the label is below the anchor, the last
+  // (bottom) line when the label is above it. That keeps the connector
+  // attached to the block's near edge instead of cutting through the
+  // lower lines of text that sits above the point.
+  const lineHeight = fontSize * LINE_HEIGHT_RATIO;
+  const nearestBaseline = dy < 0 ? ly + (lineCount - 1) * lineHeight : ly;
+  const targetY = nearestBaseline - fontSize * 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 the near-line center (so multi-line
+    // text above the point connects to its bottom edge) — 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 { path: "" };
+    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;
+    // Arrow points back toward the anchor (opposite of (ux, uy)).
+    const angle = (Math.atan2(-uy, -ux) * 180) / Math.PI;
+    return {
+      path: `M${sx},${sy} L${ex},${eyClamped}`,
+      arrow: { x: sx, y: sy, angle },
+    };
+  }
+
+  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 { path: "" };
+  }
+
+  const xDir = Math.sign(dx);
+  const yDir = Math.sign(adjDy);
+  // Start the curve directly above/below the anchor so the arrow head
+  // lines up with the data point rather than sitting off to one side.
+  const sx = ax;
+  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 start
+  // tangent vertically and lands on the label horizontally —
+  // a clean quarter-arc shape. The start tangent is (0, yDir), so the
+  // arrow points (0, -yDir) — straight up when yDir=1, down when yDir=-1.
+  const angle = yDir > 0 ? -90 : 90;
+  return {
+    path: `M${sx},${sy} Q${sx},${targetY} ${ex},${ey}`,
+    arrow: { x: sx, y: sy, angle },
+  };
+}
+</script>
+
+<template>
+  <g class="chart-annotations" pointer-events="none">
+    <template v-for="(item, i) in items" :key="i">
+      <!--
+        Outline pass. Each shape is rendered first in `outlineColor` at a
+        wider stroke so the rule line, pointer, and arrow tip stay legible
+        over busy series. Outline elements carry `class="annotation-outline"`
+        so consumers (and tests) can target the "real" shape directly.
+        Outlines deliberately drop `stroke-dasharray` — a dashed outline
+        would expose gaps where legibility matters most.
+      -->
+      <line
+        v-if="item.rule && item.outlineWidth > 0"
+        v-bind="item.rule"
+        class="annotation-outline"
+        :stroke="item.outlineColor"
+        :stroke-width="item.lineWidth + item.outlineWidth"
+        stroke-linecap="round"
+      />
+      <path
+        v-if="item.pointerPath && item.outlineWidth > 0"
+        :d="item.pointerPath"
+        class="annotation-outline"
+        fill="none"
+        :stroke="item.outlineColor"
+        :stroke-width="item.lineWidth + item.outlineWidth"
+        stroke-linecap="round"
+      />
+      <polygon
+        v-if="item.arrowTip && item.outlineWidth > 0"
+        points="0,0 -6,-3 -6,3"
+        class="annotation-outline"
+        :fill="item.outlineColor"
+        :stroke="item.outlineColor"
+        :stroke-width="item.outlineWidth"
+        stroke-linejoin="round"
+        :transform="item.arrowTransform"
+      />
+      <!-- Actual shapes. -->
+      <line
+        v-if="item.rule"
+        v-bind="item.rule"
+        :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"
+        :stroke-width="item.lineWidth"
+        :stroke-dasharray="item.lineDash"
+        stroke-linecap="round"
+      />
+      <!--
+        Inline arrow head. Drawn as an explicit triangle (not via
+        `<marker>`) because Safari does not implement `context-stroke` on
+        marker fills, so a shared marker rendered as black instead of the
+        line color.
+      -->
+      <polygon
+        v-if="item.arrowTip"
+        points="0,0 -6,-3 -6,3"
+        :fill="item.lineColor"
+        :transform="item.arrowTransform"
+      />
+      <text
+        :x="item.textX"
+        :y="item.textY"
+        :text-anchor="item.textAnchor"
+        :font-size="item.fontSize"
+        :font-weight="item.fontWeight"
+        :fill="item.color"
+        :stroke="item.outlineColor"
+        :stroke-width="item.outlineWidth"
+        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/src/_shared/ChartZoomControls.vue

@@ -0,0 +1,138 @@
+<script setup lang="ts">
+withDefaults(
+  defineProps<{
+    canZoomIn?: boolean;
+    canZoomOut?: boolean;
+    /** Reset is a no-op at the identity transform — disable it there. */
+    canReset?: boolean;
+    /** Insets the stack further from the corner while the chart fills the
+     * window, matching the ChartMenu trigger area. */
+    isFullscreen?: boolean;
+  }>(),
+  { canZoomIn: true, canZoomOut: true, canReset: true, isFullscreen: false },
+);
+
+const emit = defineEmits<{
+  (e: "zoomIn"): void;
+  (e: "zoomOut"): void;
+  (e: "reset"): void;
+}>();
+</script>
+
+<template>
+  <div
+    class="chart-zoom-controls"
+    :class="{ 'chart-zoom-controls--expanded': isFullscreen }"
+  >
+    <button
+      type="button"
+      class="chart-zoom-button"
+      aria-label="Zoom in"
+      :disabled="!canZoomIn"
+      @click="emit('zoomIn')"
+    >
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 14 14"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.5"
+        stroke-linecap="round"
+        aria-hidden="true"
+      >
+        <path d="M7 2v10M2 7h10" />
+      </svg>
+    </button>
+    <button
+      type="button"
+      class="chart-zoom-button"
+      aria-label="Zoom out"
+      :disabled="!canZoomOut"
+      @click="emit('zoomOut')"
+    >
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 14 14"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.5"
+        stroke-linecap="round"
+        aria-hidden="true"
+      >
+        <path d="M2 7h10" />
+      </svg>
+    </button>
+    <button
+      type="button"
+      class="chart-zoom-button"
+      aria-label="Reset view"
+      :disabled="!canReset"
+      @click="emit('reset')"
+    >
+      <!-- Counterclockwise "reset" arrow (rotate-ccw). -->
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 14 14"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.5"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        aria-hidden="true"
+      >
+        <path
+          d="M1.75 7a5.25 5.25 0 1 0 5.25-5.25c-1.48 0-2.9.6-3.94 1.6L1.75 4.7"
+        />
+        <path d="M1.75 1.75v2.95h2.95" />
+      </svg>
+    </button>
+  </div>
+</template>
+
+<style scoped>
+.chart-zoom-controls {
+  position: absolute;
+  top: 0.5em;
+  left: 0.5em;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+/* Mirror .chart-menu-trigger-area--expanded: while the chart fills the
+   window the wrapper's padding doesn't move absolute children, so inset
+   further for modal-style breathing room. */
+.chart-zoom-controls--expanded {
+  top: 1.25em;
+  left: 1.25em;
+}
+
+/* Same look as .chart-menu-button, but always visible — no hover reveal. */
+.chart-zoom-button {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: 1px solid var(--color-border, #e5e7eb);
+  border-radius: 0.25em;
+  background: var(--color-bg-0, #fff);
+  color: var(--color-text-secondary, #555);
+  cursor: pointer;
+}
+
+.chart-zoom-button:hover:not(:disabled) {
+  background: var(--color-bg-1, rgba(0, 0, 0, 0.05));
+  color: var(--color-text);
+}
+
+.chart-zoom-button:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+</style>

package/src/_shared/annotations.ts

@@ -0,0 +1,106 @@
+/**
+ * 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;
+  /**
+   * Color of the legibility outline drawn behind the text, pointer/rule
+   * line, and arrow tip. Defaults to `var(--color-bg-0, #fff)` so it
+   * matches the page background out of the box.
+   */
+  outlineColor?: string;
+  /**
+   * Outline stroke width in pixels. Applied to the text (via paint-order
+   * stroke), and added to `lineWidth` for the pointer/rule line and
+   * arrow tip outline pass. Set to `0` to disable the outline. Default: 3.
+   */
+  outlineWidth?: number;
+  /**
+   * Horizontal alignment of the label relative to its anchor position.
+   * When omitted, derived from the sign of `offset.x`: positive →
+   * `"left"`, negative → `"right"`, zero → `"center"`.
+   */
+  align?: "left" | "center" | "right";
+  /** 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;
+}