@cfasim-ui/docs 0.3.18 → 0.4.1

package/charts/LineChart/LineChart.vue

@@ -1,9 +1,18 @@
 <script setup lang="ts">
-import { computed, ref, watch, onMounted, onUnmounted } from "vue";
+import { computed, ref } from "vue";
 import ChartMenu from "../ChartMenu/ChartMenu.vue";
-import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
-import { saveSvg, savePng, downloadCsv } from "../ChartMenu/download.js";
-import { placeTooltip } from "../tooltip-position.js";
+import {
+  snap,
+  formatTick,
+  computeTickValues,
+  seriesToCsv,
+  useChartSize,
+  useChartTooltip,
+  useChartMenu,
+  useChartPadding,
+  INLINE_LEGEND_HEIGHT,
+  type ChartData,
+} from "../_shared/index.js";
 
 /**
  * Numeric input accepted by the chart. `number[]` and any standard numeric
@@ -11,17 +20,7 @@ import { placeTooltip } from "../tooltip-position.js";
  * `ModelOutput.column('x')` (e.g. a `Float64Array`) can be passed directly
  * without copying into a plain array.
  */
-export type LineChartData =
-  | readonly number[]
-  | Float64Array
-  | Float32Array
-  | Int32Array
-  | Uint32Array
-  | Int16Array
-  | Uint16Array
-  | Int8Array
-  | Uint8Array
-  | Uint8ClampedArray;
+export type LineChartData = ChartData;
 
 export interface Series {
   /**
@@ -129,6 +128,11 @@ const props = withDefaults(
     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
@@ -139,8 +143,12 @@ const props = withDefaults(
     menu?: boolean | string;
     xGrid?: boolean;
     yGrid?: boolean;
-    /** Custom per-index data passed to the tooltip slot */
-    tooltipData?: unknown[];
+    /**
+     * 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";
     /**
@@ -180,64 +188,30 @@ defineSlots<{
   }): unknown;
 }>();
 
-const containerRef = ref<HTMLElement | null>(null);
-const svgRef = ref<SVGSVGElement | null>(null);
-const measuredWidth = ref(0);
-let observer: ResizeObserver | null = null;
-let resizeTimeout: ReturnType<typeof setTimeout> | null = null;
-
-onMounted(() => {
-  if (containerRef.value) {
-    measuredWidth.value = containerRef.value.clientWidth;
-    observer = new ResizeObserver((entries) => {
-      const entry = entries[0];
-      if (!entry) return;
-      if (props.debounce) {
-        if (resizeTimeout) clearTimeout(resizeTimeout);
-        resizeTimeout = setTimeout(() => {
-          measuredWidth.value = entry.contentRect.width;
-        }, props.debounce);
-      } else {
-        measuredWidth.value = entry.contentRect.width;
-      }
-    });
-    observer.observe(containerRef.value);
-  }
-});
-
-onUnmounted(() => {
-  observer?.disconnect();
-  if (resizeTimeout) clearTimeout(resizeTimeout);
+const { containerRef, measuredWidth } = useChartSize({
+  debounce: () => props.debounce,
 });
 
 const width = computed(() => props.width ?? (measuredWidth.value || 400));
 const height = computed(() => props.height ?? 200);
 
-const INLINE_LEGEND_HEIGHT = 20;
-
 const hasInlineLegend = computed(
   () =>
     allSeries.value.some((s) => s.legend) ||
     props.areaSections?.some(
       (s) => s.legend === "inline" && (s.label || s.description),
-    ),
+    ) ||
+    false,
 );
 
-const padding = computed(() => ({
-  top:
-    (props.title ? 30 : 10) +
-    (hasInlineLegend.value ? INLINE_LEGEND_HEIGHT : 0),
-  right: 10,
-  bottom: props.xLabel ? 46 : 30,
-  left: props.yLabel ? 66 : 50,
-}));
-
-const innerW = computed(
-  () => width.value - padding.value.left - padding.value.right,
-);
-const innerH = computed(
-  () => height.value - padding.value.top - padding.value.bottom,
-);
+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.
@@ -251,6 +225,12 @@ 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 allSeries = computed<ResolvedSeries[]>(() => {
   if (props.series && props.series.length > 0)
     return props.series.map(resolveSeries);
@@ -607,47 +587,6 @@ const sectionLabelBaseY = computed(
     SECTION_LABEL_TOP_MARGIN,
 );
 
-function niceStep(range: number, targetTicks: number): number {
-  const rough = range / targetTicks;
-  const mag = Math.pow(10, Math.floor(Math.log10(rough)));
-  const norm = rough / mag;
-  let step: number;
-  if (norm <= 1.5) step = 1;
-  else if (norm <= 3) step = 2;
-  else if (norm <= 7) step = 5;
-  else step = 10;
-  return step * mag;
-}
-
-/** Round to nearest half-pixel so 1px SVG strokes stay sharp. */
-function snap(v: number): number {
-  return Math.round(v) + 0.5;
-}
-
-const numFmt = new Intl.NumberFormat();
-function formatTick(v: number): string {
-  if (Math.abs(v) >= 1000) return numFmt.format(v);
-  if (Number.isInteger(v)) return v.toString();
-  return v.toFixed(1);
-}
-
-/** Generate interval-spaced values in [min, max], inclusive. */
-function intervalValues(min: number, max: number, step: number): number[] {
-  if (!(step > 0) || !isFinite(step)) return [];
-  const out: number[] = [];
-  const start = Math.ceil(min / step) * step;
-  // Cap iteration to avoid runaway loops from pathological inputs.
-  const maxIterations = 1000;
-  for (
-    let i = 0, v = start;
-    v <= max + 1e-9 && i < maxIterations;
-    i++, v = start + i * step
-  ) {
-    out.push(v);
-  }
-  return out;
-}
-
 const yTickItems = computed(() => {
   const { min, max } = extent.value;
   const toY = (v: number) =>
@@ -663,15 +602,12 @@ const yTickItems = computed(() => {
     return [{ value: fmt(min), y: snap(padding.value.top + innerH.value / 2) }];
   }
 
-  let values: number[];
-  if (Array.isArray(props.yTicks)) {
-    values = props.yTicks.filter((v) => v >= min && v <= max);
-  } else if (typeof props.yTicks === "number") {
-    values = intervalValues(min, max, props.yTicks);
-  } else {
-    const targetTicks = Math.max(3, Math.floor(innerH.value / 50));
-    values = intervalValues(min, max, niceStep(max - min, targetTicks));
-  }
+  const values = computeTickValues({
+    min,
+    max,
+    ticks: props.yTicks,
+    targetTickCount: innerH.value / 50,
+  });
   return values.map((v) => ({ value: fmt(v), y: toY(v) }));
 });
 
@@ -698,32 +634,26 @@ const xTickItems = computed(() => {
   };
 
   let values: number[];
-  if (Array.isArray(props.xTicks)) {
-    // User supplies display-space values; shift to data-space.
-    values = props.xTicks
-      .map((v) => v - offset)
-      .filter((v) => v >= xMin && v <= xMax);
-  } else if (typeof props.xTicks === "number") {
-    // Align to multiples of the step in display space (preserves
-    // e.g. `xMin: 3, xTicks: 5` → display ticks 5, 10, 15 behavior).
-    values = intervalValues(xMin + offset, xMax + offset, props.xTicks).map(
-      (v) => v - offset,
-    );
-  } else if (
+  if (
+    props.xTicks == null &&
     !hasExplicitX.value &&
     props.xLabels &&
     props.xLabels.length === len
   ) {
+    // xLabels fallback: pick evenly-spaced index ticks so every label
+    // bucket gets at most one tick.
     const targetTicks = Math.max(3, Math.floor(innerW.value / 80));
     const step = Math.max(1, Math.round((len - 1) / targetTicks));
     values = [];
     for (let i = 0; i < len; i += step) values.push(i);
   } else {
-    const targetTicks = Math.max(3, Math.floor(innerW.value / 80));
-    const step = niceStep(xMax - xMin, targetTicks);
-    values = intervalValues(xMin + offset, xMax + offset, step).map(
-      (v) => v - offset,
-    );
+    values = computeTickValues({
+      min: xMin,
+      max: xMax,
+      ticks: props.xTicks,
+      targetTickCount: innerW.value / 80,
+      displayOffset: offset,
+    });
   }
 
   const leftEdge = padding.value.left;
@@ -738,50 +668,12 @@ const xTickItems = computed(() => {
   });
 });
 
-function menuFilename() {
-  if (props.filename) return props.filename;
-  return typeof props.menu === "string" ? props.menu : "chart";
-}
-
-function getSvgEl(): SVGSVGElement | null {
-  return svgRef.value;
-}
-
 function toCsv(): string {
   if (typeof props.csv === "function") return props.csv();
   if (typeof props.csv === "string") return props.csv;
-  const series = allSeries.value;
-  if (series.length === 0) return "";
-  const len = maxLen.value;
-  // Use an `x` column when every series shares the same x source;
-  // otherwise fall back to `index`.
-  const sharedX = series.every((s) => s.x === series[0].x)
-    ? series[0].x
-    : undefined;
-  const xHeader = sharedX ? "x" : "index";
-  const headers =
-    series.length === 1
-      ? [xHeader, "value"]
-      : [xHeader, ...series.map((_, i) => `series_${i}`)];
-  const rows = [headers.join(",")];
-  for (let r = 0; r < len; r++) {
-    const xCell = sharedX ? String(sharedX[r]) : r.toString();
-    const cells = [xCell];
-    for (const s of series) {
-      cells.push(r < s.data.length ? String(s.data[r]) : "");
-    }
-    rows.push(cells.join(","));
-  }
-  return rows.join("\n");
+  return seriesToCsv(allSeries.value);
 }
 
-// Tooltip hover state
-const TOUCH_Y_OFFSET = 50;
-const hoverIndex = ref<number | null>(null);
-const isTouching = ref(false);
-const tooltipRef = ref<HTMLElement | null>(null);
-const pointer = ref<{ clientX: number; clientY: number } | null>(null);
-const tooltipPos = ref<{ left: number; top: number } | null>(null);
 const hasTooltipSlot = computed(
   () => !!props.tooltipData || !!props.tooltipTrigger,
 );
@@ -866,15 +758,6 @@ const hoverSlotProps = computed(() => {
   };
 });
 
-function pointerFromEvent(
-  event: MouseEvent | TouchEvent,
-): { clientX: number; clientY: number } | null {
-  if ("touches" in event) {
-    return event.touches[0] ?? null;
-  }
-  return event;
-}
-
 function indexFromPointer(clientX: number): number | null {
   const rect = containerRef.value?.getBoundingClientRect();
   if (!rect) return null;
@@ -887,114 +770,31 @@ function indexFromPointer(clientX: number): number | null {
   return nearestIndex(s0, targetX);
 }
 
-function updateHover(event: MouseEvent | TouchEvent) {
-  const pt = pointerFromEvent(event);
-  if (!pt) return;
-  const idx = indexFromPointer(pt.clientX);
-  if (idx === null) return;
-  hoverIndex.value = idx;
-  pointer.value = { clientX: pt.clientX, clientY: pt.clientY };
-  emit("hover", { index: idx });
-}
-
-watch(
-  [pointer, hoverIndex],
-  () => {
-    if (hoverIndex.value === null || !pointer.value) {
-      tooltipPos.value = null;
-      return;
-    }
-    const el = tooltipRef.value;
-    const container = containerRef.value;
-    if (!el || !container) return;
-    const rect = container.getBoundingClientRect();
-    const offset = isTouching.value ? TOUCH_Y_OFFSET : 0;
-    const { left, top } = placeTooltip(
-      pointer.value.clientX,
-      pointer.value.clientY - offset,
-      el.offsetWidth,
-      el.offsetHeight,
-      props.tooltipClamp,
-      rect,
-    );
-    tooltipPos.value = { left: left - rect.left, top: top - rect.top };
-  },
-  { flush: "post" },
-);
-
-function onChartMouseMove(event: MouseEvent) {
-  updateHover(event);
-}
-
-function onChartMouseLeave() {
-  if (props.tooltipTrigger !== "click") {
-    hoverIndex.value = null;
-    emit("hover", null);
-  }
-}
-
-function onChartClick(event: MouseEvent) {
-  if (props.tooltipTrigger !== "click") return;
-  const pt = pointerFromEvent(event);
-  if (!pt) return;
-  const idx = indexFromPointer(pt.clientX);
-  if (idx === null) return;
-  hoverIndex.value = hoverIndex.value === idx ? null : idx;
-  emit("hover", hoverIndex.value !== null ? { index: idx } : null);
-}
-
-function onTouchStart(event: TouchEvent) {
-  isTouching.value = true;
-  updateHover(event);
-}
-
-function onTouchMove(event: TouchEvent) {
-  updateHover(event);
-}
-
-function onTouchEnd() {
-  isTouching.value = false;
-  hoverIndex.value = null;
-  emit("hover", null);
-}
-
-const downloadLinkText = computed(() => {
-  if (!props.downloadLink) return null;
-  return typeof props.downloadLink === "string"
-    ? props.downloadLink
-    : "Download data (CSV)";
-});
-
-const csvHref = computed(() => {
-  if (!props.downloadLink) return null;
-  return `data:text/csv;charset=utf-8,${encodeURIComponent(toCsv())}`;
+const {
+  hoverIndex,
+  tooltipRef,
+  tooltipPos,
+  handlers: tooltipHandlers,
+} = useChartTooltip({
+  enabled: () => hasTooltipSlot.value,
+  trigger: () => props.tooltipTrigger,
+  clamp: () => props.tooltipClamp,
+  pointerToIndex: indexFromPointer,
+  containerRef,
+  onHover: (payload) => emit("hover", payload),
 });
 
-const menuItems = computed<ChartMenuItem[]>(() => {
-  const fname = menuFilename();
-  const items: ChartMenuItem[] = [
-    {
-      label: "Save as SVG",
-      action: () => {
-        const el = getSvgEl();
-        if (el) saveSvg(el, fname);
-      },
-    },
-    {
-      label: "Save as PNG",
-      action: () => {
-        const el = getSvgEl();
-        if (el) savePng(el, fname);
-      },
-    },
-  ];
-  if (!props.downloadLink) {
-    items.push({
-      label: "Download CSV",
-      action: () => downloadCsv(toCsv(), fname),
-    });
-  }
-  return items;
+const {
+  svgRef,
+  items: menuItems,
+  downloadLinkText,
+  csvHref,
+  resolvedFilename: menuFilename,
+} = useChartMenu({
+  filename: () => props.filename,
+  legacyMenuLabel: () => props.menu,
+  getCsv: toCsv,
+  downloadLink: () => props.downloadLink,
 });
 </script>
 
@@ -1272,12 +1072,7 @@ const menuItems = computed<ChartMenuItem[]>(() => {
         :height="innerH"
         fill="transparent"
         style="cursor: crosshair; touch-action: none"
-        @mousemove="onChartMouseMove"
-        @mouseleave="onChartMouseLeave"
-        @click="onChartClick"
-        @touchstart.prevent="onTouchStart"
-        @touchmove.prevent="onTouchMove"
-        @touchend="onTouchEnd"
+        v-on="tooltipHandlers"
       />
       <!-- area section labels -->
       <g v-for="(item, i) in sectionLabels.labels" :key="'seclab' + i">
@@ -1342,7 +1137,7 @@ const menuItems = computed<ChartMenuItem[]>(() => {
               class="line-chart-tooltip-swatch"
               :style="{ background: v.color }"
             />
-            {{ isFinite(v.value) ? formatTick(v.value) : "—" }}
+            {{ isFinite(v.value) ? formatTooltipValue(v.value) : "—" }}
           </div>
         </div>
       </slot>

package/charts/_shared/axes.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure helpers shared by chart components for axis tick math and value
+ * formatting. No Vue reactivity here; see `useAxisTicks` for the
+ * reactive wrapper.
+ */
+
+/** Round to nearest half-pixel so 1px SVG strokes stay sharp. */
+export function snap(v: number): number {
+  return Math.round(v) + 0.5;
+}
+
+export function niceStep(range: number, targetTicks: number): number {
+  const rough = range / targetTicks;
+  const mag = Math.pow(10, Math.floor(Math.log10(rough)));
+  const norm = rough / mag;
+  let step: number;
+  if (norm <= 1.5) step = 1;
+  else if (norm <= 3) step = 2;
+  else if (norm <= 7) step = 5;
+  else step = 10;
+  return step * mag;
+}
+
+/** Generate interval-spaced values in [min, max], inclusive. */
+export function intervalValues(
+  min: number,
+  max: number,
+  step: number,
+): number[] {
+  if (!(step > 0) || !isFinite(step)) return [];
+  const out: number[] = [];
+  const start = Math.ceil(min / step) * step;
+  // Cap iteration to avoid runaway loops from pathological inputs.
+  const maxIterations = 1000;
+  for (
+    let i = 0, v = start;
+    v <= max + 1e-9 && i < maxIterations;
+    i++, v = start + i * step
+  ) {
+    out.push(v);
+  }
+  return out;
+}
+
+const numFmt = new Intl.NumberFormat();
+
+export function formatTick(v: number): string {
+  if (Math.abs(v) >= 1000) return numFmt.format(v);
+  if (Number.isInteger(v)) return v.toString();
+  return v.toFixed(1);
+}
+
+/**
+ * Numeric input accepted by chart components. `number[]` and any standard
+ * numeric typed array are supported, so the output of
+ * `ModelOutput.column('x')` (e.g. a `Float64Array`) can be passed
+ * directly without copying.
+ */
+export type ChartData =
+  | readonly number[]
+  | Float64Array
+  | Float32Array
+  | Int32Array
+  | Uint32Array
+  | Int16Array
+  | Uint16Array
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray;

package/charts/_shared/computeTicks.ts

@@ -0,0 +1,42 @@
+import { intervalValues, niceStep } from "./axes.js";
+
+export interface TickValueOptions {
+  /** Data-space extent. */
+  min: number;
+  max: number;
+  /** Tick spec: number = interval, array = explicit values, undefined = auto. */
+  ticks?: number | number[];
+  /** Target tick count when auto-spacing (typically innerSize / 50 for y, /80 for x). */
+  targetTickCount?: number;
+  /**
+   * Display-space offset added to user-supplied explicit/interval values
+   * before they are interpreted. Used by LineChart's `xMin` semantics so
+   * users supply tick values in display coordinates.
+   */
+  displayOffset?: number;
+}
+
+/**
+ * Returns tick values in data-space ([min, max]) according to the spec.
+ * Display-space conversions (for labels) happen at the call site so
+ * each chart can layer its own formatting / fallback behavior.
+ */
+export function computeTickValues(opts: TickValueOptions): number[] {
+  const { min, max, ticks } = opts;
+  if (min === max) return [];
+  const offset = opts.displayOffset ?? 0;
+
+  if (Array.isArray(ticks)) {
+    return ticks.map((v) => v - offset).filter((v) => v >= min && v <= max);
+  }
+  if (typeof ticks === "number") {
+    return intervalValues(min + offset, max + offset, ticks).map(
+      (v) => v - offset,
+    );
+  }
+  const target = Math.max(3, Math.floor(opts.targetTickCount ?? 3));
+  const step = niceStep(max - min, target);
+  return intervalValues(min + offset, max + offset, step).map(
+    (v) => v - offset,
+  );
+}

package/charts/_shared/index.ts

@@ -0,0 +1,20 @@
+export {
+  snap,
+  niceStep,
+  intervalValues,
+  formatTick,
+  type ChartData,
+} from "./axes.js";
+export { computeTickValues, type TickValueOptions } from "./computeTicks.js";
+export { useChartSize, type ChartSizeOptions } from "./useChartSize.js";
+export {
+  useChartPadding,
+  INLINE_LEGEND_HEIGHT,
+  type ChartPaddingOptions,
+} from "./useChartPadding.js";
+export {
+  useChartTooltip,
+  type ChartTooltipOptions,
+} from "./useChartTooltip.js";
+export { useChartMenu, type ChartMenuOptions } from "./useChartMenu.js";
+export { seriesToCsv, categoricalToCsv, type CsvSeries } from "./seriesCsv.js";

package/charts/_shared/seriesCsv.ts

@@ -0,0 +1,68 @@
+import type { ChartData } from "./axes.js";
+
+export interface CsvSeries {
+  data: ChartData;
+  /** Optional parallel x-values; when all series share the same x, an `x` column is used. */
+  x?: ChartData;
+}
+
+/**
+ * Build a CSV string for one or more numeric series. When every series
+ * shares the same `x` reference an `x` column is emitted; otherwise
+ * rows are indexed.
+ */
+export function seriesToCsv(series: CsvSeries[]): string {
+  if (series.length === 0) return "";
+  let maxLen = 0;
+  for (const s of series) if (s.data.length > maxLen) maxLen = s.data.length;
+  const sharedX = series.every((s) => s.x === series[0].x)
+    ? series[0].x
+    : undefined;
+  const xHeader = sharedX ? "x" : "index";
+  const headers =
+    series.length === 1
+      ? [xHeader, "value"]
+      : [xHeader, ...series.map((_, i) => `series_${i}`)];
+  const rows = [headers.join(",")];
+  for (let r = 0; r < maxLen; r++) {
+    const xCell = sharedX ? String(sharedX[r]) : r.toString();
+    const cells = [xCell];
+    for (const s of series) {
+      cells.push(r < s.data.length ? String(s.data[r]) : "");
+    }
+    rows.push(cells.join(","));
+  }
+  return rows.join("\n");
+}
+
+/**
+ * Build a CSV for a categorical chart (BarChart vertical / horizontal):
+ * one row per category, one column per series.
+ */
+export function categoricalToCsv(
+  categories: readonly string[],
+  series: { label?: string; data: ChartData }[],
+  categoryHeader = "category",
+): string {
+  if (series.length === 0 || categories.length === 0) return "";
+  const headers =
+    series.length === 1
+      ? [categoryHeader, series[0].label || "value"]
+      : [categoryHeader, ...series.map((s, i) => s.label || `series_${i}`)];
+  const rows = [headers.join(",")];
+  for (let r = 0; r < categories.length; r++) {
+    const cells = [escapeCsv(categories[r])];
+    for (const s of series) {
+      cells.push(r < s.data.length ? String(s.data[r]) : "");
+    }
+    rows.push(cells.join(","));
+  }
+  return rows.join("\n");
+}
+
+function escapeCsv(value: string): string {
+  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}