@cfasim-ui/charts 0.7.8 → 0.8.1

package/src/_shared/useChartPadding.ts

@@ -0,0 +1,235 @@
+import { computed } from "vue";
+import type { LabelStyle, TitleStyle } from "./chartProps.js";
+
+/** Vertical space reserved per row of the inline legend strip. */
+export const INLINE_LEGEND_ROW_HEIGHT = 20;
+/** Default line height (px) for the chart title; overridable per chart. */
+export const TITLE_LINE_HEIGHT = 18;
+/** Default font size (px) for the chart title; overridable per chart. */
+export const TITLE_FONT_SIZE = 14;
+/** Default font weight for the chart title; overridable per chart. */
+export const TITLE_FONT_WEIGHT: number | string = 600;
+/** Default font size (px) for axis labels (`xLabel` / `yLabel`). */
+export const AXIS_LABEL_FONT_SIZE = 13;
+/** Default font size (px) for axis tick labels (the numbers on each axis). */
+export const TICK_LABEL_FONT_SIZE = 10;
+/** Default fill-opacity for tick labels when no custom color is set. */
+export const TICK_LABEL_OPACITY = 0.6;
+/** Default font size (px) for inline legend item labels. */
+export const LEGEND_FONT_SIZE = 11;
+/** Vertical space below the title's last baseline before the next element. */
+const TITLE_BOTTOM_GAP = 8;
+
+/**
+ * Resolve a `LabelStyle` against per-element defaults. Returns the
+ * fields the chart's `<text>` element needs. When `style.color` is set,
+ * the default fill-opacity is dropped so the exact color renders.
+ */
+export function resolveLabelStyle(
+  style: LabelStyle | undefined,
+  defaults: { fontSize: number; fillOpacity?: number },
+): {
+  fontSize: number;
+  fill: string;
+  fontWeight: number | string | undefined;
+  fillOpacity: number | undefined;
+} {
+  return {
+    fontSize: style?.fontSize ?? defaults.fontSize,
+    fill: style?.color ?? "currentColor",
+    fontWeight: style?.fontWeight,
+    fillOpacity: style?.color != null ? undefined : defaults.fillOpacity,
+  };
+}
+/**
+ * Estimated character width at font-size 11 used by inline-legend
+ * measurement. Matches the value used by LineChart's area-section labels
+ * so wrapping behaves consistently across the chart's text overlays.
+ */
+const LEGEND_CHAR_WIDTH = 7;
+/** X offset of legend text from the start of its row slot. */
+const LEGEND_TEXT_INDENT = 18;
+/** Horizontal gap between adjacent legend items on the same row. */
+const LEGEND_ITEM_GAP = 16;
+
+/**
+ * Extra space added around the chart's standard layout. A number applies
+ * the same amount to all four sides; an object lets you pad sides
+ * independently (e.g. `{ top: 24 }` to make room for annotations above
+ * the plot). Named to match Altair's `padding` (outer view padding).
+ */
+export type ChartPadding =
+  | number
+  | {
+      top?: number;
+      right?: number;
+      bottom?: number;
+      left?: number;
+    };
+
+export interface ChartPaddingOptions {
+  title: () => string | undefined;
+  titleStyle?: () => TitleStyle | undefined;
+  xLabel: () => string | undefined;
+  yLabel: () => string | undefined;
+  /**
+   * Labels for the inline legend items, in render order. Empty array
+   * (or omitted) means no legend strip. Drives both row-count for
+   * reserving top padding and per-item wrap positions.
+   */
+  inlineLegendLabels: () => readonly string[];
+  width: () => number;
+  height: () => number;
+  /** Extra pixels added on top of the standard axis spacing. */
+  extraPadding?: () => ChartPadding | undefined;
+}
+
+/** Position of a single legend item within the legend strip. */
+export interface PositionedLegendItem {
+  /** X offset relative to `padding.left`. */
+  x: number;
+  /** Row index, 0-based. */
+  row: number;
+}
+
+function resolvePadding(p: ChartPadding | undefined) {
+  if (p == null) return { top: 0, right: 0, bottom: 0, left: 0 };
+  if (typeof p === "number") return { top: p, right: p, bottom: p, left: p };
+  return {
+    top: p.top ?? 0,
+    right: p.right ?? 0,
+    bottom: p.bottom ?? 0,
+    left: p.left ?? 0,
+  };
+}
+
+/**
+ * Estimated rendered width (in px) of a single legend item — indicator,
+ * text, and surrounding spacing. Used to flow items into rows.
+ */
+function estimateLegendItemWidth(label: string): number {
+  return LEGEND_TEXT_INDENT + label.length * LEGEND_CHAR_WIDTH;
+}
+
+/**
+ * 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. `extraPadding` adds extra space outside the plot — useful
+ * for annotations that need to extend past the data area without
+ * clipping.
+ *
+ * The inline legend wraps to multiple rows when items don't fit in the
+ * available width; `padding.top` grows by `INLINE_LEGEND_ROW_HEIGHT` per
+ * row so the plot stays clear of the legend strip.
+ */
+export function useChartPadding(opts: ChartPaddingOptions) {
+  // Horizontal padding is computed first because `innerW` depends only
+  // on left/right (not on legend row count). Splitting padding this way
+  // keeps the legend layout — which depends on `innerW` — out of the
+  // reactivity cycle for left/right.
+  const horizontalPadding = computed(() => {
+    const extra = resolvePadding(opts.extraPadding?.());
+    return {
+      left: (opts.yLabel() ? 56 : 50) + extra.left,
+      right: 10 + extra.right,
+    };
+  });
+
+  const innerW = computed(
+    () =>
+      opts.width() -
+      horizontalPadding.value.left -
+      horizontalPadding.value.right,
+  );
+
+  const inlineLegendLayout = computed<{
+    positions: PositionedLegendItem[];
+    rowCount: number;
+  }>(() => {
+    const labels = opts.inlineLegendLabels();
+    if (labels.length === 0) return { positions: [], rowCount: 0 };
+    const available = Math.max(0, innerW.value);
+    const positions: PositionedLegendItem[] = [];
+    let row = 0;
+    let x = 0;
+    for (const label of labels) {
+      const w = estimateLegendItemWidth(label);
+      // Wrap to a new row when the item won't fit, except when we're
+      // already at row-start (`x === 0`): a single oversized label gets
+      // its own row instead of triggering an infinite-wrap loop.
+      if (x > 0 && x + w > available) {
+        row++;
+        x = 0;
+      }
+      positions.push({ x, row });
+      x += w + LEGEND_ITEM_GAP;
+    }
+    return { positions, rowCount: row + 1 };
+  });
+
+  // Title height in px. `\n` in the title creates additional lines, each
+  // adding `titleStyle.lineHeight` (default 18). When there is no title,
+  // reserve a small top margin so the plot doesn't hug the top edge.
+  const titleHeight = computed(() => {
+    const t = opts.title();
+    if (!t) return 10;
+    const lineHeight = opts.titleStyle?.()?.lineHeight ?? TITLE_LINE_HEIGHT;
+    const lineCount = t.split("\n").length;
+    return lineCount * lineHeight + TITLE_BOTTOM_GAP;
+  });
+
+  const padding = computed(() => {
+    const extra = resolvePadding(opts.extraPadding?.());
+    const rowCount = inlineLegendLayout.value.rowCount;
+    return {
+      top: titleHeight.value + rowCount * INLINE_LEGEND_ROW_HEIGHT + extra.top,
+      bottom: (opts.xLabel() ? 38 : 30) + extra.bottom,
+      left: horizontalPadding.value.left,
+      right: horizontalPadding.value.right,
+    };
+  });
+
+  // Y-center of the first inline-legend row. Sits at the top of the
+  // padding band (just below any title), so any user-supplied
+  // `extraPadding.top` becomes empty room between the legend and the
+  // plot. Subsequent rows are offset by `INLINE_LEGEND_ROW_HEIGHT`.
+  const legendY = computed(
+    () => titleHeight.value + INLINE_LEGEND_ROW_HEIGHT / 2,
+  );
+
+  const innerH = computed(
+    () => opts.height() - padding.value.top - padding.value.bottom,
+  );
+  // Pixel-space rect of the plot area. Single source of truth for any
+  // consumer that needs to span the full plot (e.g. rule annotations,
+  // background fills, clip paths).
+  const bounds = computed(() => {
+    const p = padding.value;
+    return {
+      left: p.left,
+      top: p.top,
+      right: p.left + innerW.value,
+      bottom: p.top + innerH.value,
+      width: innerW.value,
+      height: innerH.value,
+    };
+  });
+  return {
+    padding,
+    legendY,
+    inlineLegendLayout,
+    innerW,
+    innerH,
+    bounds,
+  };
+}
+
+export type ChartBounds = {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  width: number;
+  height: number;
+};

package/src/_shared/useChartSize.ts

@@ -0,0 +1,58 @@
+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);
+  const measuredHeight = ref(0);
+  let observer: ResizeObserver | null = null;
+  let resizeTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  onMounted(() => {
+    if (!containerRef.value) return;
+    measuredWidth.value = containerRef.value.clientWidth;
+    measuredHeight.value = containerRef.value.clientHeight;
+    observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+      const apply = () => {
+        measuredWidth.value = entry.contentRect.width;
+        measuredHeight.value = entry.contentRect.height;
+      };
+      const debounce = opts.debounce?.();
+      if (debounce) {
+        if (resizeTimeout) clearTimeout(resizeTimeout);
+        resizeTimeout = setTimeout(apply, debounce);
+      } else {
+        apply();
+      }
+    });
+    observer.observe(containerRef.value);
+  });
+
+  onUnmounted(() => {
+    observer?.disconnect();
+    if (resizeTimeout) clearTimeout(resizeTimeout);
+  });
+
+  return {
+    containerRef,
+    measuredWidth,
+    measuredHeight,
+  } as {
+    containerRef: Ref<HTMLElement | null>;
+    measuredWidth: Ref<number>;
+    measuredHeight: Ref<number>;
+  };
+}

package/src/_shared/useChartTooltip.ts

@@ -0,0 +1,205 @@
+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;
+  /**
+   * Axis a finger drags *along* to scrub the tooltip. On touch, a drag in
+   * the orthogonal direction is left to the browser so the page can still
+   * scroll. Defaults to `"x"` (horizontal scrub, vertical page scroll) —
+   * correct for time-series line charts and vertical bar charts.
+   */
+  scrubAxis?: () => "x" | "y";
+  /**
+   * 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;
+  // Pixels a finger must travel before we commit a touch drag to either
+  // scrubbing the tooltip or scrolling the page.
+  const TOUCH_SLOP = 10;
+  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);
+
+  // Touch-gesture tracking (plain locals — they don't drive rendering).
+  // "pending" until the drag direction is known; then "scrub" (we own the
+  // gesture and move the tooltip) or "scroll" (the browser scrolls the page).
+  let touchStart: { x: number; y: number } | null = null;
+  let touchMode: "pending" | "scrub" | "scroll" = "pending";
+
+  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?.() ?? "window";
+      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;
+    const pt = pointerFromEvent(event);
+    if (!pt) return;
+    // Don't preventDefault here: that would cancel the browser's scroll for
+    // the whole gesture before we know its direction. We decide on the
+    // first move instead. (`touch-action` on the overlay caps which
+    // direction the browser may still claim.)
+    touchStart = { x: pt.clientX, y: pt.clientY };
+    touchMode = "pending";
+    isTouching.value = true;
+    updateHover(event);
+  }
+
+  function onTouchMove(event: TouchEvent) {
+    if (!opts.enabled()) return;
+    // The page owns this gesture — let it scroll, leave the tooltip hidden.
+    if (touchMode === "scroll") return;
+
+    if (touchMode === "pending") {
+      const pt = pointerFromEvent(event);
+      if (!pt || !touchStart) return;
+      const dx = Math.abs(pt.clientX - touchStart.x);
+      const dy = Math.abs(pt.clientY - touchStart.y);
+      if (dx + dy < TOUCH_SLOP) {
+        // Too small to classify — track under the finger, but don't yet
+        // preventDefault so the browser can still start a scroll.
+        updateHover(event);
+        return;
+      }
+      const scrubAxis = opts.scrubAxis?.() ?? "x";
+      const isScrub = scrubAxis === "x" ? dx >= dy : dy >= dx;
+      if (!isScrub) {
+        // Drag is across the scrub axis — hand the gesture to the browser.
+        touchMode = "scroll";
+        hoverIndex.value = null;
+        opts.onHover?.(null);
+        return;
+      }
+      touchMode = "scrub";
+    }
+
+    // Scrubbing: we own the gesture, so suppress the native scroll.
+    event.preventDefault();
+    updateHover(event);
+  }
+
+  function onTouchEnd() {
+    if (!opts.enabled()) return;
+    isTouching.value = false;
+    touchStart = null;
+    touchMode = "pending";
+    hoverIndex.value = null;
+    opts.onHover?.(null);
+  }
+
+  // Note: when binding via `v-on="handlers"`, Vue expects event names
+  // *without* the `on` prefix. The touch handlers call `preventDefault`
+  // internally (only while scrubbing), so the overlay must NOT bind them
+  // passively, and should set `touch-action` to the scroll direction it
+  // wants to keep (e.g. `pan-y` when `scrubAxis` is `"x"`).
+  const handlers = {
+    mousemove: onMouseMove,
+    mouseleave: onMouseLeave,
+    click: onClick,
+    touchstart: onTouchStart,
+    touchmove: onTouchMove,
+    touchend: onTouchEnd,
+  };
+
+  return {
+    hoverIndex,
+    isTouching,
+    pointer,
+    tooltipRef,
+    tooltipPos,
+    handlers,
+  };
+}

package/src/env.d.ts

@@ -0,0 +1,4 @@
+// Ambient declaration for side-effect CSS imports (e.g. `import "./x.css"`).
+// Required since TypeScript 6, which errors (TS2882) on side-effect imports
+// without a module declaration.
+declare module "*.css";

package/src/hsa-mapping.ts

@@ -0,0 +1 @@
+export { fipsToHsa, hsaNames } from "./ChoroplethMap/hsaMapping.js";

package/src/index.ts

@@ -0,0 +1,41 @@
+export {
+  default as LineChart,
+  type LineChartData,
+  type Series,
+  type Area,
+  type AreaSection,
+} from "./LineChart/LineChart.vue";
+export {
+  default as BarChart,
+  type BarChartData,
+  type BarSeries,
+  type BarSummaryLine,
+} from "./BarChart/BarChart.vue";
+export {
+  default as ChoroplethMap,
+  type GeoType,
+  type StateData,
+  type ChoroplethColorScale,
+  type ThresholdStop,
+  type CategoricalStop,
+  type FocusItem,
+  type FocusValue,
+  type FocusStyle,
+} from "./ChoroplethMap/ChoroplethMap.vue";
+export { default as ChartTooltip } from "./ChartTooltip/ChartTooltip.vue";
+export {
+  default as DataTable,
+  type TableData,
+  type TableRecord,
+  type ColumnAlign,
+  type ColumnConfig,
+  type ColumnWidth,
+} from "./DataTable/DataTable.vue";
+export type { CityMarker, PlacedCity } from "./ChoroplethMap/cityLayout.js";
+export {
+  mapThemeDefaults,
+  type MapTheme,
+  type ResolvedMapTheme,
+} from "./_shared/mapTheme.js";
+export type { ChartAnnotation } from "./_shared/annotations.js";
+export type { BlendMode, LineMarkStyle } from "./_shared/chartProps.js";

package/src/tooltip-position.ts

@@ -0,0 +1,55 @@
+export type TooltipClamp = "none" | "chart" | "window";
+
+const GAP = 16;
+const PAD = 8;
+
+/**
+ * Computes a tooltip position in client coordinates, flipping to the opposite
+ * side of the pointer and clamping vertically when the preferred placement
+ * would overflow the clamp boundary.
+ *
+ * The tooltip is assumed to be anchored with `transform: translateY(-50%)`,
+ * so `top` is the vertical center.
+ */
+export function placeTooltip(
+  clientX: number,
+  centerY: number,
+  tipW: number,
+  tipH: number,
+  clamp: TooltipClamp,
+  chartRect?: DOMRect,
+): { left: number; top: number } {
+  if (clamp === "none") {
+    return { left: clientX + GAP, top: centerY };
+  }
+
+  const bounds =
+    clamp === "chart" && chartRect
+      ? {
+          left: chartRect.left,
+          right: chartRect.right,
+          top: chartRect.top,
+          bottom: chartRect.bottom,
+        }
+      : {
+          left: 0,
+          right: window.innerWidth,
+          top: 0,
+          bottom: window.innerHeight,
+        };
+
+  const flip = clientX + GAP + tipW > bounds.right - PAD;
+  const rawLeft = flip ? clientX - GAP - tipW : clientX + GAP;
+  // Clamp horizontally too: a left-flip near a narrow boundary's left edge
+  // (or a right placement in a chart narrower than the tooltip) must not
+  // overflow the far side. The upper bound is floored to the lower one so a
+  // tooltip wider than the bounds still pins to the left edge.
+  const maxLeft = Math.max(bounds.left + PAD, bounds.right - PAD - tipW);
+  const left = Math.min(Math.max(rawLeft, bounds.left + PAD), maxLeft);
+  const halfH = tipH / 2;
+  const top = Math.min(
+    Math.max(centerY, bounds.top + PAD + halfH),
+    bounds.bottom - PAD - halfH,
+  );
+  return { left, top };
+}