@cfasim-ui/docs 0.3.18 → 0.4.0

package/charts/_shared/useChartMenu.ts

@@ -0,0 +1,72 @@
+import { computed, ref, type Ref } from "vue";
+import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
+import { saveSvg, savePng, downloadCsv } from "../ChartMenu/download.js";
+
+export interface ChartMenuOptions {
+  filename: () => string | undefined;
+  /** Used as the menu's filename fallback when `filename` is unset. */
+  legacyMenuLabel: () => boolean | string | undefined;
+  /** Builds the CSV content for downloads. */
+  getCsv: () => string;
+  /** Whether a separate download link is rendered (and the CSV menu item should be hidden). */
+  downloadLink: () => boolean | string | undefined;
+}
+
+/**
+ * Computes the standard chart menu items (SVG / PNG / CSV) plus the
+ * CSV-download-link state shared by every chart.
+ */
+export function useChartMenu(opts: ChartMenuOptions) {
+  const svgRef = ref<SVGSVGElement | null>(null);
+
+  function resolvedFilename(): string {
+    const f = opts.filename();
+    if (f) return f;
+    const menu = opts.legacyMenuLabel();
+    return typeof menu === "string" ? menu : "chart";
+  }
+
+  const items = computed<ChartMenuItem[]>(() => {
+    const fname = resolvedFilename();
+    const out: ChartMenuItem[] = [
+      {
+        label: "Save as SVG",
+        action: () => {
+          if (svgRef.value) saveSvg(svgRef.value, fname);
+        },
+      },
+      {
+        label: "Save as PNG",
+        action: () => {
+          if (svgRef.value) savePng(svgRef.value, fname);
+        },
+      },
+    ];
+    if (!opts.downloadLink()) {
+      out.push({
+        label: "Download CSV",
+        action: () => downloadCsv(opts.getCsv(), fname),
+      });
+    }
+    return out;
+  });
+
+  const downloadLinkText = computed<string | null>(() => {
+    const v = opts.downloadLink();
+    if (!v) return null;
+    return typeof v === "string" ? v : "Download data (CSV)";
+  });
+
+  const csvHref = computed<string | null>(() => {
+    if (!opts.downloadLink()) return null;
+    return `data:text/csv;charset=utf-8,${encodeURIComponent(opts.getCsv())}`;
+  });
+
+  return {
+    svgRef: svgRef as Ref<SVGSVGElement | null>,
+    items,
+    downloadLinkText,
+    csvHref,
+    resolvedFilename,
+  };
+}

package/charts/_shared/useChartPadding.ts

@@ -0,0 +1,37 @@
+import { computed } from "vue";
+
+/** Vertical space reserved at the top of the chart for inline legend swatches. */
+export const INLINE_LEGEND_HEIGHT = 20;
+
+export interface ChartPaddingOptions {
+  title: () => string | undefined;
+  xLabel: () => string | undefined;
+  yLabel: () => string | undefined;
+  hasInlineLegend: () => boolean;
+  width: () => number;
+  height: () => number;
+}
+
+/**
+ * Computes the standard chart padding (top/right/bottom/left) and the
+ * derived inner plotting region (innerW, innerH). Shared by LineChart
+ * and BarChart so the axis label spacing and inline legend strip stay
+ * consistent.
+ */
+export function useChartPadding(opts: ChartPaddingOptions) {
+  const padding = computed(() => ({
+    top:
+      (opts.title() ? 30 : 10) +
+      (opts.hasInlineLegend() ? INLINE_LEGEND_HEIGHT : 0),
+    right: 10,
+    bottom: opts.xLabel() ? 46 : 30,
+    left: opts.yLabel() ? 66 : 50,
+  }));
+  const innerW = computed(
+    () => opts.width() - padding.value.left - padding.value.right,
+  );
+  const innerH = computed(
+    () => opts.height() - padding.value.top - padding.value.bottom,
+  );
+  return { padding, innerW, innerH };
+}

package/charts/_shared/useChartSize.ts

@@ -0,0 +1,49 @@
+import { ref, onMounted, onUnmounted, type Ref } from "vue";
+
+export interface ChartSizeOptions {
+  /** Fallback width when measurement is not yet available. */
+  fallbackWidth?: number;
+  /** Optional debounce in ms applied to ResizeObserver updates. */
+  debounce?: () => number | undefined;
+}
+
+/**
+ * Watches an element ref for size changes and exposes the measured width.
+ * Mirrors the per-chart ResizeObserver wiring previously inlined in each
+ * chart component.
+ */
+export function useChartSize(opts: ChartSizeOptions = {}) {
+  const containerRef = ref<HTMLElement | null>(null);
+  const measuredWidth = ref(0);
+  let observer: ResizeObserver | null = null;
+  let resizeTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  onMounted(() => {
+    if (!containerRef.value) return;
+    measuredWidth.value = containerRef.value.clientWidth;
+    observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+      const debounce = opts.debounce?.();
+      if (debounce) {
+        if (resizeTimeout) clearTimeout(resizeTimeout);
+        resizeTimeout = setTimeout(() => {
+          measuredWidth.value = entry.contentRect.width;
+        }, debounce);
+      } else {
+        measuredWidth.value = entry.contentRect.width;
+      }
+    });
+    observer.observe(containerRef.value);
+  });
+
+  onUnmounted(() => {
+    observer?.disconnect();
+    if (resizeTimeout) clearTimeout(resizeTimeout);
+  });
+
+  return {
+    containerRef,
+    measuredWidth,
+  } as { containerRef: Ref<HTMLElement | null>; measuredWidth: Ref<number> };
+}

package/charts/_shared/useChartTooltip.ts

@@ -0,0 +1,152 @@
+import { ref, computed, watch, type Ref } from "vue";
+import { placeTooltip, type TooltipClamp } from "../tooltip-position.js";
+
+export interface ChartTooltipOptions {
+  /** Whether tooltip interactions are wired up at all. */
+  enabled: () => boolean;
+  /** Tooltip activation mode. */
+  trigger?: () => "hover" | "click" | undefined;
+  /** Boundary for tooltip flip/clamp. */
+  clamp?: () => TooltipClamp;
+  /**
+   * Maps a client (x, y) pointer location to a data index, or null when
+   * the pointer is outside the chart. Most charts only need `clientX`
+   * (categorical or x-indexed), but horizontal bar charts also need
+   * `clientY`.
+   */
+  pointerToIndex: (clientX: number, clientY: number) => number | null;
+  /** The chart's container element (used to compute relative position). */
+  containerRef: Ref<HTMLElement | null>;
+  /** Pointer-vertical offset applied for touch interactions. */
+  touchYOffset?: number;
+  /**
+   * Emit hover events. The first arg is `{ index }` while hovering and
+   * `null` when leaving.
+   */
+  onHover?: (payload: { index: number } | null) => void;
+}
+
+/**
+ * Shared tooltip state + pointer/touch handlers used by chart components.
+ * The caller wires the returned `handlers` to its hit-test overlay and
+ * places the floating tooltip with `tooltipPos`.
+ */
+export function useChartTooltip(opts: ChartTooltipOptions) {
+  const TOUCH_Y_OFFSET = opts.touchYOffset ?? 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);
+
+  function pointerFromEvent(
+    event: MouseEvent | TouchEvent,
+  ): { clientX: number; clientY: number } | null {
+    if ("touches" in event) {
+      return event.touches[0] ?? null;
+    }
+    return event;
+  }
+
+  function updateHover(event: MouseEvent | TouchEvent) {
+    const pt = pointerFromEvent(event);
+    if (!pt) return;
+    const idx = opts.pointerToIndex(pt.clientX, pt.clientY);
+    if (idx === null) return;
+    hoverIndex.value = idx;
+    pointer.value = { clientX: pt.clientX, clientY: pt.clientY };
+    opts.onHover?.({ index: idx });
+  }
+
+  watch(
+    [pointer, hoverIndex],
+    () => {
+      if (hoverIndex.value === null || !pointer.value) {
+        tooltipPos.value = null;
+        return;
+      }
+      const el = tooltipRef.value;
+      const container = opts.containerRef.value;
+      if (!el || !container) return;
+      const rect = container.getBoundingClientRect();
+      const offset = isTouching.value ? TOUCH_Y_OFFSET : 0;
+      const clamp = opts.clamp?.() ?? "chart";
+      const { left, top } = placeTooltip(
+        pointer.value.clientX,
+        pointer.value.clientY - offset,
+        el.offsetWidth,
+        el.offsetHeight,
+        clamp,
+        rect,
+      );
+      tooltipPos.value = { left: left - rect.left, top: top - rect.top };
+    },
+    { flush: "post" },
+  );
+
+  function onMouseMove(event: MouseEvent) {
+    if (!opts.enabled()) return;
+    updateHover(event);
+  }
+
+  function onMouseLeave() {
+    if (!opts.enabled()) return;
+    if (opts.trigger?.() !== "click") {
+      hoverIndex.value = null;
+      opts.onHover?.(null);
+    }
+  }
+
+  function onClick(event: MouseEvent) {
+    if (!opts.enabled()) return;
+    if (opts.trigger?.() !== "click") return;
+    const pt = pointerFromEvent(event);
+    if (!pt) return;
+    const idx = opts.pointerToIndex(pt.clientX, pt.clientY);
+    if (idx === null) return;
+    hoverIndex.value = hoverIndex.value === idx ? null : idx;
+    opts.onHover?.(hoverIndex.value !== null ? { index: idx } : null);
+  }
+
+  function onTouchStart(event: TouchEvent) {
+    if (!opts.enabled()) return;
+    event.preventDefault();
+    isTouching.value = true;
+    updateHover(event);
+  }
+
+  function onTouchMove(event: TouchEvent) {
+    if (!opts.enabled()) return;
+    event.preventDefault();
+    updateHover(event);
+  }
+
+  function onTouchEnd() {
+    if (!opts.enabled()) return;
+    isTouching.value = false;
+    hoverIndex.value = null;
+    opts.onHover?.(null);
+  }
+
+  // Note: when binding via `v-on="handlers"`, Vue expects event names
+  // *without* the `on` prefix. Touch events default to passive in some
+  // contexts; consumers using touch overlays should still bind the
+  // touch handlers individually with `.prevent`.
+  const handlers = {
+    mousemove: onMouseMove,
+    mouseleave: onMouseLeave,
+    click: onClick,
+    touchstart: onTouchStart,
+    touchmove: onTouchMove,
+    touchend: onTouchEnd,
+  };
+
+  return {
+    hoverIndex,
+    isTouching,
+    pointer,
+    tooltipRef,
+    tooltipPos,
+    handlers,
+  };
+}

package/charts/index.ts

@@ -5,6 +5,11 @@ export {
   type Area,
   type AreaSection,
 } from "./LineChart/LineChart.vue";
+export {
+  default as BarChart,
+  type BarChartData,
+  type BarSeries,
+} from "./BarChart/BarChart.vue";
 export {
   default as ChoroplethMap,
   type GeoType,

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.18",
+  "version": "0.4.0",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [
@@ -120,6 +120,23 @@
       }
     ],
     "charts": [
+      {
+        "name": "BarChart",
+        "slug": "bar-chart",
+        "docs": "charts/BarChart/BarChart.md",
+        "source": "charts/BarChart/BarChart.vue",
+        "keywords": [
+          "bar",
+          "column",
+          "chart",
+          "categorical",
+          "grouped",
+          "stacked",
+          "vertical",
+          "horizontal",
+          "svg"
+        ]
+      },
       {
         "name": "ChoroplethMap",
         "slug": "choropleth-map",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/docs",
-  "version": "0.3.18",
+  "version": "0.4.0",
   "description": "LLM-friendly component and chart documentation for cfasim-ui",
   "license": "Apache-2.0",
   "repository": {

package/pyodide/index.ts

@@ -1,7 +1,9 @@
 export {
   asyncRunPython,
+  callPython,
   loadModule,
   loadModuleOnWorker,
+  warmWorkers,
   type WorkerName,
 } from "./pyodideWorkerApi.js";
 export { useModel } from "./useModel.js";

package/pyodide/pyodide.worker.ts

@@ -5,13 +5,25 @@ import {
 } from "@cfasim-ui/shared";
 import type { ColumnDescriptor, ModelOutputsWire } from "@cfasim-ui/shared";
 
-interface WorkerMessage {
+interface RunMessage {
   id: number;
-  type?: "run" | "loadModule";
-  python?: string;
-  module?: string;
+  type?: "run";
+  python: string;
   context?: Record<string, unknown>;
 }
+interface CallMessage {
+  id: number;
+  type: "call";
+  module: string;
+  fn: string;
+  kwargs?: Record<string, unknown>;
+}
+interface LoadModuleMessage {
+  id: number;
+  type: "loadModule";
+  module: string;
+}
+type WorkerMessage = RunMessage | CallMessage | LoadModuleMessage;
 
 let wheelMap: Record<string, string> = {};
 
@@ -92,24 +104,29 @@ function installAllWheels(): Promise<void> {
   return installPromise;
 }
 
-const modulePromises = new Map<string, Promise<void>>();
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const modulePromises = new Map<string, Promise<any>>();
 
 function ensureModule(
   pyodide: Awaited<typeof pyodideReadyPromise>,
   moduleName: string,
-): Promise<void> {
-  if (!modulePromises.has(moduleName)) {
-    if (!wheelMap[moduleName]) throw new Error(`Unknown module: ${moduleName}`);
-    const promise = (async () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Promise<any> {
+  let p = modulePromises.get(moduleName);
+  if (!p) {
+    if (!wheelMap[moduleName]) {
+      return Promise.reject(new Error(`Unknown module: ${moduleName}`));
+    }
+    p = (async () => {
       await installAllWheels();
-      pyodide.pyimport(moduleName);
+      return pyodide.pyimport(moduleName);
     })();
-    promise.catch(() => {
+    p.catch(() => {
       modulePromises.delete(moduleName);
     });
-    modulePromises.set(moduleName, promise);
+    modulePromises.set(moduleName, p);
   }
-  return modulePromises.get(moduleName)!;
+  return p;
 }
 
 // Map Python struct format characters to TypedArray constructors
@@ -127,18 +144,20 @@ const FORMAT_TO_TYPED_ARRAY: Record<
   d: Float64Array,
 };
 
+// Copy a Pyodide getBuffer() result into a JS-owned typed array. Releases the
+// underlying Python buffer; the returned view's ArrayBuffer is safe to transfer.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function extractNumpyBuffer(proxy: any): ArrayBuffer {
+function copyPyBuffer(proxy: any): ArrayBufferView {
   const pyBuffer = proxy.getBuffer();
   const Ctor = FORMAT_TO_TYPED_ARRAY[pyBuffer.format] ?? Float64Array;
-  const typed = new Ctor(
+  const view = new Ctor(
     pyBuffer.data.buffer.slice(
       pyBuffer.data.byteOffset,
       pyBuffer.data.byteOffset + pyBuffer.data.byteLength,
     ),
   );
   pyBuffer.release();
-  return typed.buffer as ArrayBuffer;
+  return view;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -161,7 +180,7 @@ function convertModelOutputs(jsResult: any): ModelOutputsWire | null {
     for (const buf of wire.buffers) {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       if (buf && typeof buf === "object" && (buf as any).getBuffer) {
-        buffers.push(extractNumpyBuffer(buf));
+        buffers.push(copyPyBuffer(buf).buffer as ArrayBuffer);
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         if ((buf as any).destroy) (buf as any).destroy();
       } else if (buf instanceof ArrayBuffer) {
@@ -187,76 +206,94 @@ function convertModelOutputs(jsResult: any): ModelOutputsWire | null {
   return { __modelOutputs: true, outputs };
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function convertResult(rawResult: any): unknown {
+  if (!rawResult || typeof rawResult.destroy !== "function") return rawResult;
+  try {
+    if (typeof rawResult.toJs === "function") {
+      return rawResult.toJs({ dict_converter: Object.fromEntries });
+    }
+    if (typeof rawResult.getBuffer === "function") {
+      return copyPyBuffer(rawResult);
+    }
+    return rawResult.toString();
+  } finally {
+    rawResult.destroy();
+  }
+}
+
+function send(id: number, result: unknown) {
+  const modelOutputs = convertModelOutputs(result);
+  if (modelOutputs) {
+    postModelOutputsWithTransfer(self, id, modelOutputs);
+  } else {
+    postWithTransfer(self, id, result);
+  }
+}
+
 self.onmessage = async (event: MessageEvent<WorkerMessage>) => {
   const pyodide = await pyodideReadyPromise;
-  const { id, type, python, module: moduleName, context } = event.data;
+  const msg = event.data;
+  const { id } = msg;
 
   try {
-    if (type === "loadModule" && moduleName) {
-      await ensureModule(pyodide, moduleName);
+    if (msg.type === "loadModule") {
+      await ensureModule(pyodide, msg.module);
       postWithTransfer(self, id, true);
       return;
     }
 
-    let globals;
-    if (context) {
-      const dict = pyodide.globals.get("dict");
-      globals = dict(Object.entries(context));
+    if (msg.type === "call") {
+      const mod = await ensureModule(pyodide, msg.module);
+      const t0 = performance.now();
+      // mod[fn] creates a fresh PyProxy on every access — release in finally.
+      const pyFn = mod[msg.fn];
+      let result: unknown;
+      try {
+        if (typeof pyFn !== "function") {
+          throw new Error(`Module ${msg.module} has no function ${msg.fn}`);
+        }
+        const rawResult = msg.kwargs ? pyFn.callKwargs(msg.kwargs) : pyFn();
+        result = convertResult(rawResult);
+      } finally {
+        if (pyFn && typeof pyFn.destroy === "function") pyFn.destroy();
+      }
+      const tEnd = performance.now();
+      console.log(
+        `[pyodide-worker] ${msg.module}.${msg.fn} ${
+          Math.round((tEnd - t0) * 10) / 10
+        }ms`,
+      );
+      send(id, result);
+      return;
     }
 
-    const t0 = performance.now();
-
-    // Use synchronous runPython (models don't use top-level await)
-    const rawResult = pyodide.runPython(
-      python!,
-      globals ? { globals } : undefined,
-    );
-
-    const tPython = performance.now();
-
-    // Destroy PyProxy if returned to prevent memory leaks
-    let result = rawResult;
-    if (rawResult && typeof rawResult === "object" && rawResult.destroy) {
-      if (rawResult.toJs) {
-        result = rawResult.toJs({ dict_converter: Object.fromEntries });
-      } else if (rawResult.getBuffer) {
-        // Single numpy array: use getBuffer() for direct typed array access
-        const pyBuffer = rawResult.getBuffer();
-        const Ctor = FORMAT_TO_TYPED_ARRAY[pyBuffer.format] ?? Float64Array;
-        result = new Ctor(
-          pyBuffer.data.buffer.slice(
-            pyBuffer.data.byteOffset,
-            pyBuffer.data.byteOffset + pyBuffer.data.byteLength,
-          ),
-        );
-        pyBuffer.release();
-      } else {
-        result = rawResult.toString();
+    // type === "run" or omitted
+    let globals;
+    if (msg.context) {
+      const dict = pyodide.globals.get("dict");
+      try {
+        globals = dict(Object.entries(msg.context));
+      } finally {
+        dict.destroy();
       }
-      rawResult.destroy();
     }
-
-    // Destroy globals proxy if created
-    if (globals && globals.destroy) {
-      globals.destroy();
+    const t0 = performance.now();
+    let result: unknown;
+    try {
+      const rawResult = pyodide.runPython(
+        msg.python,
+        globals ? { globals } : undefined,
+      );
+      result = convertResult(rawResult);
+    } finally {
+      if (globals && globals.destroy) globals.destroy();
     }
-
-    const tConvert = performance.now();
-    const bench = {
-      python_ms: Math.round((tPython - t0) * 10) / 10,
-      convert_ms: Math.round((tConvert - tPython) * 10) / 10,
-    };
+    const tEnd = performance.now();
     console.log(
-      `[pyodide-worker] python=${bench.python_ms}ms convert=${bench.convert_ms}ms`,
+      `[pyodide-worker] runPython ${Math.round((tEnd - t0) * 10) / 10}ms`,
     );
-
-    // Check for ModelOutputs wire format
-    const modelOutputs = convertModelOutputs(result);
-    if (modelOutputs) {
-      postModelOutputsWithTransfer(self, id, modelOutputs);
-    } else {
-      postWithTransfer(self, id, result);
-    }
+    send(id, result);
   } catch (error) {
     postErrorWithTransfer(self, id, error);
   }