@cfasim-ui/docs 0.3.17 → 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/components/NumberInput/NumberInput.md

@@ -16,6 +16,12 @@ const ageRange = ref([18, 65])
 const coverageRange = ref([0.2, 0.8])
 const minAge = ref(18)
 const maxAge = ref(65)
+const dayMs = 24 * 60 * 60 * 1000
+const dateStart = Date.UTC(2024, 0, 1)
+const dateEnd = Date.UTC(2024, 11, 31)
+const dateRange = ref([Date.UTC(2024, 2, 1), Date.UTC(2024, 8, 30)])
+const formatDate = (ms) =>
+  new Date(ms).toLocaleDateString("en-US", { month: "short", day: "numeric" })
 </script>
 
 <ComponentDemo>
@@ -226,6 +232,51 @@ Range mode works with `percent` and `live` as well:
   </template>
 </ComponentDemo>
 
+### Custom slider display
+
+Pass `slider-display` (a `(value: number) => string` function) to format the
+thumb labels and the min/max labels however you like. The internal model is
+still a number — only the displayed text changes. This applies to single
+sliders and ranges; the regular text input is unaffected.
+
+<ComponentDemo>
+  <div style="width: 300px">
+    <NumberInput
+      v-model:range="dateRange"
+      label="Date range"
+      :min="dateStart"
+      :max="dateEnd"
+      :step="dayMs"
+      :slider-display="formatDate"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<script setup>
+import { ref } from "vue";
+const dayMs = 24 * 60 * 60 * 1000;
+const dateStart = Date.UTC(2024, 0, 1);
+const dateEnd = Date.UTC(2024, 11, 31);
+const dateRange = ref([Date.UTC(2024, 2, 1), Date.UTC(2024, 8, 30)]);
+const formatDate = (ms) =>
+  new Date(ms).toLocaleDateString("en-US", { month: "short", day: "numeric" });
+</script>
+
+<NumberInput
+  v-model:range="dateRange"
+  label="Date range"
+  :min="dateStart"
+  :max="dateEnd"
+  :step="dayMs"
+  :slider-display="formatDate"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Live slider
 
 With `live`, the model updates while dragging the slider thumb rather than only on release.
@@ -415,4 +466,5 @@ the input visually.
 | `numberType` | `"integer" \| "float"` | No | — |
 | `required` | `boolean` | No | — |
 | `decimals` | `number` | No | — |
+| `sliderDisplay` | `(value: number) =&gt; string` | No | — |
 

package/components/NumberInput/NumberInput.vue

@@ -29,6 +29,10 @@ const props = defineProps<{
   numberType?: "integer" | "float";
   required?: boolean;
   decimals?: number;
+  // Custom formatter for slider thumb labels and min/max labels. Overrides
+  // the default percent/decimal formatting when provided. Only consulted in
+  // slider/range mode — the text input keeps its own number-shaped formatting.
+  sliderDisplay?: (value: number) => string;
 }>();
 
 function isRangeValue(v: unknown): v is NumberRange {
@@ -109,6 +113,7 @@ function roundToDecimals(v: number, d: number): number {
 
 function formatSliderValue(v: number | undefined) {
   if (v == null) return "";
+  if (props.sliderDisplay) return props.sliderDisplay(v);
   const d = displayDecimals.value;
   if (props.percent) return (v * 100).toFixed(d) + "%";
   return v.toLocaleString("en-US", {

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.17",
+  "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.17",
+  "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";