@cfasim-ui/charts 0.7.8 → 0.8.1

package/src/_shared/touch.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether the current device has a touch screen. A function (not a
+ * module-level constant) so unit tests can mock it per-case and so SSR
+ * evaluation is deferred until an event actually needs the answer.
+ */
+export function isTouchDevice(): boolean {
+  return typeof window !== "undefined" && "ontouchstart" in window;
+}

package/src/_shared/useChartFoundation.ts

@@ -0,0 +1,175 @@
+import { computed } from "vue";
+import { formatNumber, type NumberFormat } from "@cfasim-ui/shared";
+import { formatTick } from "./axes.js";
+import { useChartSize } from "./useChartSize.js";
+import { useChartPadding, type ChartPadding } from "./useChartPadding.js";
+import { useChartTooltip } from "./useChartTooltip.js";
+import type { TooltipClamp } from "../tooltip-position.js";
+import { useChartMenu } from "./useChartMenu.js";
+import type { TitleStyle } from "./chartProps.js";
+
+const DEFAULT_WIDTH_FALLBACK = 400;
+const DEFAULT_HEIGHT = 200;
+
+export interface ChartFoundationOptions {
+  // Reactive getters for the shared chart props.
+  width: () => number | undefined;
+  height: () => number | undefined;
+  title: () => string | undefined;
+  titleStyle: () => TitleStyle | undefined;
+  xLabel: () => string | undefined;
+  yLabel: () => string | undefined;
+  debounce: () => number | undefined;
+  menu: () => boolean | string | undefined;
+  tooltipTrigger: () => "hover" | "click" | undefined;
+  tooltipClamp: () => TooltipClamp | undefined;
+  filename: () => string | undefined;
+  downloadLink: () => boolean | string | undefined;
+  downloadButton: () => boolean | string | undefined;
+  fullscreenTarget: () => string | HTMLElement | undefined;
+  chartPadding: () => ChartPadding | undefined;
+  // Chart-specific hooks that the composable can't infer.
+  /**
+   * Labels for the inline legend in render order. Empty array = no
+   * legend strip. Drives wrapping into multiple rows and the resulting
+   * top-padding reservation.
+   */
+  inlineLegendLabels: () => readonly string[];
+  hasTooltipSlot: () => boolean;
+  getCsv: () => string;
+  pointerToIndex: (clientX: number, clientY: number) => number | null;
+  onHover: (payload: { index: number } | null) => void;
+  /**
+   * Axis a finger drags along to scrub the tooltip on touch; the
+   * orthogonal direction is left to the browser for page scrolling.
+   * Defaults to `"x"`.
+   */
+  scrubAxis?: () => "x" | "y";
+  /**
+   * Extra height (in px) the chart adds *below* the SVG plot area
+   * (e.g. LineChart's area-section labels). Used to keep the SVG total
+   * height matched to the container when fullscreen.
+   */
+  extraBelowHeight?: () => number;
+}
+
+/**
+ * Wires up the shared chart plumbing — size measurement, padding, tooltip
+ * interaction, and the menu/download wiring — that every cartesian chart
+ * needs. Returns the reactive values and refs each chart's template
+ * consumes.
+ */
+export function useChartFoundation(opts: ChartFoundationOptions) {
+  const { containerRef, measuredWidth, measuredHeight } = useChartSize({
+    debounce: opts.debounce,
+  });
+
+  const {
+    svgRef,
+    items: menuItems,
+    downloadLinkText,
+    csvHref,
+    downloadButtonText,
+    triggerCsvDownload,
+    resolvedFilename: menuFilename,
+    isFullscreen,
+    fullscreenStyle,
+    teleportTarget,
+    exitFullscreen,
+  } = useChartMenu({
+    filename: opts.filename,
+    legacyMenuLabel: opts.menu,
+    getCsv: opts.getCsv,
+    downloadLink: opts.downloadLink,
+    downloadButton: opts.downloadButton,
+    fullscreen: true,
+    fullscreenTarget: opts.fullscreenTarget,
+  });
+
+  const width = computed(() => {
+    if (isFullscreen.value && measuredWidth.value > 0) {
+      return measuredWidth.value;
+    }
+    return opts.width() ?? (measuredWidth.value || DEFAULT_WIDTH_FALLBACK);
+  });
+
+  const height = computed(() => {
+    if (isFullscreen.value && measuredHeight.value > 0) {
+      const extra = opts.extraBelowHeight?.() ?? 0;
+      return measuredHeight.value - extra;
+    }
+    return opts.height() ?? DEFAULT_HEIGHT;
+  });
+
+  const { padding, legendY, inlineLegendLayout, innerW, innerH, bounds } =
+    useChartPadding({
+      title: opts.title,
+      titleStyle: opts.titleStyle,
+      xLabel: opts.xLabel,
+      yLabel: opts.yLabel,
+      inlineLegendLabels: opts.inlineLegendLabels,
+      width: () => width.value,
+      height: () => height.value,
+      extraPadding: opts.chartPadding,
+    });
+
+  const {
+    hoverIndex,
+    tooltipRef,
+    tooltipPos,
+    handlers: tooltipHandlers,
+  } = useChartTooltip({
+    enabled: opts.hasTooltipSlot,
+    trigger: opts.tooltipTrigger,
+    clamp: () => opts.tooltipClamp() ?? "window",
+    pointerToIndex: opts.pointerToIndex,
+    containerRef,
+    scrubAxis: opts.scrubAxis,
+    onHover: opts.onHover,
+  });
+
+  return {
+    containerRef,
+    svgRef,
+    width,
+    height,
+    padding,
+    legendY,
+    inlineLegendLayout,
+    innerW,
+    innerH,
+    bounds,
+    hoverIndex,
+    tooltipRef,
+    tooltipPos,
+    tooltipHandlers,
+    menuItems,
+    downloadLinkText,
+    csvHref,
+    downloadButtonText,
+    triggerCsvDownload,
+    menuFilename,
+    isFullscreen,
+    fullscreenStyle,
+    teleportTarget,
+    exitFullscreen,
+  };
+}
+
+/**
+ * Build a tooltip value formatter that prefers `tooltipValueFormat`,
+ * falls back to the chart's axis tick formatter, and finally to
+ * `formatTick`. Both chart components use the same precedence order.
+ */
+export function makeTooltipValueFormatter(
+  tooltipFormat: () => NumberFormat | undefined,
+  axisFormat: () => NumberFormat | undefined,
+): (v: number) => string {
+  return (v: number) => {
+    const tf = tooltipFormat();
+    if (tf !== undefined) return formatNumber(v, tf);
+    const af = axisFormat();
+    if (af !== undefined) return formatNumber(v, af);
+    return formatTick(v);
+  };
+}

package/src/_shared/useChartFullscreen.ts

@@ -0,0 +1,254 @@
+import { computed, onMounted, onUnmounted, ref } from "vue";
+import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
+import { isTouchDevice } from "./touch.js";
+
+/**
+ * Module-level refcount so multiple expanded charts on the same page
+ * share one body-scroll lock — the last one to collapse restores the
+ * original `overflow` value.
+ */
+let bodyLockCount = 0;
+let savedBodyOverflow = "";
+
+function lockBodyScroll() {
+  if (typeof document === "undefined") return;
+  if (bodyLockCount === 0) {
+    savedBodyOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+  }
+  bodyLockCount++;
+}
+
+function unlockBodyScroll() {
+  if (typeof document === "undefined") return;
+  if (bodyLockCount === 0) return;
+  bodyLockCount--;
+  if (bodyLockCount === 0) {
+    document.body.style.overflow = savedBodyOverflow;
+  }
+}
+
+/**
+ * Pinch-zoom lock (touch devices): a `position: fixed` overlay covers the
+ * *layout* viewport, so if the user has pinch-zoomed the page, the
+ * expanded chart's corners (controls, ✕) sit outside the visible area.
+ * Tightening the viewport meta to `maximum-scale=1` snaps the page zoom
+ * back to 1× and holds it while expanded — a pinch should zoom the chart,
+ * not the page. The last chart to collapse restores the original content
+ * so page zoom (an accessibility feature) comes back. No-op without a
+ * viewport meta or on mouse-only devices.
+ */
+let viewportLockCount = 0;
+let savedViewportContent: string | null = null;
+
+function viewportMeta(): HTMLMetaElement | null {
+  return document.querySelector<HTMLMetaElement>('meta[name="viewport"]');
+}
+
+function lockViewportZoom() {
+  if (typeof document === "undefined" || !isTouchDevice()) return;
+  const meta = viewportMeta();
+  if (!meta) return;
+  if (viewportLockCount === 0) {
+    savedViewportContent = meta.getAttribute("content");
+    // Append rather than replace so app directives (e.g. viewport-fit for
+    // safe-area insets) survive while expanded; a later duplicate key wins.
+    const base = savedViewportContent || "width=device-width, initial-scale=1";
+    meta.setAttribute("content", `${base}, maximum-scale=1`);
+  }
+  viewportLockCount++;
+}
+
+function unlockViewportZoom() {
+  if (typeof document === "undefined") return;
+  if (viewportLockCount === 0) return;
+  viewportLockCount--;
+  if (viewportLockCount === 0) {
+    const meta = viewportMeta();
+    if (meta && savedViewportContent != null) {
+      meta.setAttribute("content", savedViewportContent);
+    }
+    savedViewportContent = null;
+  }
+}
+
+export interface ChartFullscreenOptions {
+  /**
+   * Reactive getter for where to teleport the expanded chart. A CSS
+   * selector or element; resolves to `"body"` when unset. Teleporting
+   * out to the document root is what makes `position: fixed` reliable:
+   * a `transform`/`filter`/`contain`/`perspective` on any ancestor would
+   * otherwise become the containing block and trap the "fullscreen" box
+   * inside it.
+   */
+  target?: () => string | HTMLElement | undefined;
+}
+
+/**
+ * Tracks whether the chart is in "expanded" mode (fills the window). The
+ * browser Fullscreen API isn't used — avoiding its restrictions
+ * (user-gesture requirement, permission policy, iframe sandboxing) and
+ * keeping the chart inside the document so the rest of the page stays
+ * keyboard-navigable.
+ *
+ * Resilience is the whole point here, so the layout is driven two ways
+ * that don't depend on the CSS cascade:
+ *  - `fullscreenStyle` returns the critical layout as an *inline* style
+ *    object. Inline styles outrank any class rule regardless of stylesheet
+ *    source order, so they beat each chart's scoped `position: relative`
+ *    base rule (equal specificity, and the scoped rule often loads last)
+ *    and still work even if the consumer never imported the package CSS.
+ *  - `teleportTarget` moves the node to the document root so the fixed
+ *    positioning resolves against the viewport, not a transformed ancestor.
+ * The `.is-fullscreen` class remains on the wrapper only as a hook for the
+ * one rule inline styles can't express (ChoroplethMap's SVG stretch).
+ */
+export function useChartFullscreen(opts: ChartFullscreenOptions = {}) {
+  const isFullscreen = ref(false);
+  let locked = false;
+
+  // Visual-viewport pinning. A fixed overlay covers the *layout* viewport,
+  // but on a pinch-zoomed page only part of that is visible — and iOS
+  // refuses to programmatically reset page zoom (the viewport-meta clamp
+  // above is best-effort; it works on Android and older iOS). While
+  // expanded, track the visual viewport and pin the overlay to exactly the
+  // visible box instead of `inset: 0`, so the chart and its controls are
+  // always fully on screen whatever the page zoom.
+  const visualBox = ref<Record<string, string> | null>(null);
+
+  function updateVisualBox() {
+    const vv = typeof window !== "undefined" ? window.visualViewport : null;
+    if (!vv) return;
+    // Always box off the visual viewport while it's observable — at 1×
+    // this equals inset: 0, and it additionally tracks mobile URL-bar
+    // collapse. `inset: 0` remains only as the no-API fallback.
+    visualBox.value = {
+      top: `${vv.offsetTop}px`,
+      left: `${vv.offsetLeft}px`,
+      width: `${vv.width}px`,
+      height: `${vv.height}px`,
+    };
+  }
+
+  function watchVisualViewport(on: boolean) {
+    const vv = typeof window !== "undefined" ? window.visualViewport : null;
+    if (!vv) return;
+    if (on) {
+      vv.addEventListener("resize", updateVisualBox);
+      vv.addEventListener("scroll", updateVisualBox);
+      updateVisualBox();
+    } else {
+      vv.removeEventListener("resize", updateVisualBox);
+      vv.removeEventListener("scroll", updateVisualBox);
+      visualBox.value = null;
+    }
+  }
+
+  function setExpanded(value: boolean) {
+    if (value === isFullscreen.value) return;
+    isFullscreen.value = value;
+    if (value && !locked) {
+      lockBodyScroll();
+      lockViewportZoom();
+      watchVisualViewport(true);
+      locked = true;
+    } else if (!value && locked) {
+      unlockBodyScroll();
+      unlockViewportZoom();
+      watchVisualViewport(false);
+      locked = false;
+    }
+  }
+
+  function onKey(e: KeyboardEvent) {
+    if (e.key !== "Escape" || !isFullscreen.value) return;
+    // Skip when Esc is closing a menu/dialog layered on top of us so we
+    // don't collapse the chart at the same time. Reka's dropdown menu
+    // uses a document-level Esc listener and doesn't call preventDefault,
+    // so checking the event target is the most reliable signal.
+    const t = e.target;
+    if (t instanceof Element && t.closest('[role="menu"], [role="dialog"]')) {
+      return;
+    }
+    setExpanded(false);
+  }
+
+  function enter() {
+    setExpanded(true);
+  }
+  function exit() {
+    setExpanded(false);
+  }
+  function toggle() {
+    setExpanded(!isFullscreen.value);
+  }
+
+  onMounted(() => {
+    if (typeof document === "undefined") return;
+    document.addEventListener("keydown", onKey);
+  });
+  onUnmounted(() => {
+    if (typeof document === "undefined") return;
+    document.removeEventListener("keydown", onKey);
+    // Component torn down while expanded — release the locks so the body
+    // doesn't stay frozen and page zoom comes back.
+    if (locked) {
+      unlockBodyScroll();
+      unlockViewportZoom();
+      watchVisualViewport(false);
+      locked = false;
+    }
+  });
+
+  /**
+   * Returns a reactive ChartMenuItem ref that flips between Expand and
+   * Collapse — shared by useChartMenu and any chart (e.g. ChoroplethMap)
+   * that builds its menu list directly.
+   */
+  const menuItem = computed<ChartMenuItem>(() => ({
+    label: isFullscreen.value ? "Collapse" : "Fullscreen",
+    action: toggle,
+    ariaPressed: isFullscreen.value,
+  }));
+
+  /**
+   * Critical fullscreen layout as inline styles (only while expanded).
+   * Bound via `:style` on the chart wrapper so it always wins over the
+   * scoped base rule and survives a missing stylesheet import.
+   */
+  const fullscreenStyle = computed<Record<string, string> | undefined>(() =>
+    isFullscreen.value
+      ? {
+          position: "fixed",
+          // Pinned to the visual viewport when the page is pinch-zoomed;
+          // identical to inset: 0 otherwise.
+          ...(visualBox.value ?? { inset: "0" }),
+          "z-index": "var(--cfasim-z-fullscreen, 1000)",
+          background: "var(--color-bg-0, #fff)",
+          color: "var(--color-text, inherit)",
+          // Edge-to-edge on touch — padding just frames slivers of the
+          // page underneath on small screens; desktop keeps modal-style
+          // breathing room.
+          padding: isTouchDevice() ? "0" : "2em",
+          "box-sizing": "border-box",
+          display: "flex",
+          "flex-direction": "column",
+          "justify-content": "center",
+        }
+      : undefined,
+  );
+
+  const teleportTarget = computed<string | HTMLElement>(
+    () => opts.target?.() || "body",
+  );
+
+  return {
+    isFullscreen,
+    toggle,
+    enter,
+    exit,
+    menuItem,
+    fullscreenStyle,
+    teleportTarget,
+  };
+}

package/src/_shared/useChartMenu.ts

@@ -0,0 +1,111 @@
+import { computed, ref, type Ref } from "vue";
+import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
+import { saveSvg, savePng, downloadCsv } from "../ChartMenu/download.js";
+import { useChartFullscreen } from "./useChartFullscreen.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;
+  /** Whether a separate download button is rendered (and the CSV menu item should be hidden). */
+  downloadButton?: () => boolean | string | undefined;
+  /**
+   * When true, prepends a Fullscreen menu item that toggles the chart
+   * into a full-window view. The consumer binds the returned
+   * `isFullscreen` class plus `fullscreenStyle` to its wrapper and wraps
+   * it in a `<Teleport :to="teleportTarget" :disabled="!isFullscreen">`.
+   */
+  fullscreen?: boolean;
+  /** Forwarded to `useChartFullscreen` — see its `target` option. */
+  fullscreenTarget?: () => string | HTMLElement | undefined;
+}
+
+/**
+ * Computes the standard chart menu items (Fullscreen / 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 fullscreen = opts.fullscreen
+    ? useChartFullscreen({ target: opts.fullscreenTarget })
+    : null;
+
+  const items = computed<ChartMenuItem[]>(() => {
+    const fname = resolvedFilename();
+    const out: ChartMenuItem[] = [];
+    if (fullscreen) {
+      out.push(fullscreen.menuItem.value);
+    }
+    out.push(
+      {
+        label: "Save as SVG",
+        action: () => {
+          if (svgRef.value) saveSvg(svgRef.value, fname);
+        },
+      },
+      {
+        label: "Save as PNG",
+        action: () => {
+          if (svgRef.value) savePng(svgRef.value, fname);
+        },
+      },
+    );
+    const buttonOn = opts.downloadButton?.();
+    if (!opts.downloadLink() && !buttonOn) {
+      out.push({
+        label: "Download CSV",
+        action: () => downloadCsv(opts.getCsv(), fname),
+      });
+    }
+    return out;
+  });
+
+  const downloadLinkText = computed<string | null>(() => {
+    if (opts.downloadButton?.()) return null;
+    const v = opts.downloadLink();
+    if (!v) return null;
+    return typeof v === "string" ? v : "Download data (CSV)";
+  });
+
+  const csvHref = computed<string | null>(() => {
+    if (opts.downloadButton?.()) return null;
+    if (!opts.downloadLink()) return null;
+    return `data:text/csv;charset=utf-8,${encodeURIComponent(opts.getCsv())}`;
+  });
+
+  const downloadButtonText = computed<string | null>(() => {
+    const v = opts.downloadButton?.();
+    if (!v) return null;
+    return typeof v === "string" ? v : "Download data (CSV)";
+  });
+
+  function triggerCsvDownload() {
+    downloadCsv(opts.getCsv(), resolvedFilename());
+  }
+
+  return {
+    svgRef: svgRef as Ref<SVGSVGElement | null>,
+    items,
+    downloadLinkText,
+    csvHref,
+    downloadButtonText,
+    triggerCsvDownload,
+    resolvedFilename,
+    isFullscreen: fullscreen?.isFullscreen ?? ref(false),
+    fullscreenStyle: fullscreen?.fullscreenStyle ?? computed(() => undefined),
+    teleportTarget: fullscreen?.teleportTarget ?? computed(() => "body"),
+    exitFullscreen: fullscreen?.exit ?? (() => {}),
+  };
+}