@cfasim-ui/docs 0.4.1 → 0.4.2

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -1,3 +1,18 @@
+<script setup>
+import { computed } from "vue";
+import countiesTopoForPerf from "us-atlas/counties-10m.json";
+
+// Build one row per county (~3,143) with a deterministic-ish value so the
+// perf example can render every region with a custom tooltip.
+const denseCountyData = computed(() => {
+  const geoms = countiesTopoForPerf.objects.counties.geometries;
+  return geoms.map((g, i) => ({
+    id: String(g.id).padStart(5, "0"),
+    value: (i * 37) % 100,
+  }));
+});
+</script>
+
 # ChoroplethMap
 
 A US choropleth map using D3's Albers USA projection, which repositions Alaska and Hawaii to the bottom left. Supports state-level, county-level, and HSA-level (Health Service Areas) rendering via the `geoType` prop.
@@ -325,9 +340,8 @@ Set `geoType="hsas"` to render Health Service Area boundaries. HSAs are dissolve
 ### Custom tooltip number format
 
 Pass `tooltip-value-format` to format numeric values shown in the tooltip
-(both the native SVG `<title>` and the interactive HTML tooltip when
-`tooltip-trigger` is set). Use `tooltip-format` instead if you want full
-control over the tooltip's HTML.
+(both the native SVG `<title>` and the interactive HTML tooltip). Use the
+`#tooltip` slot if you want full control over the tooltip's content.
 
 <ComponentDemo>
   <ChoroplethMap
@@ -363,6 +377,110 @@ control over the tooltip's HTML.
   </template>
 </ComponentDemo>
 
+### Dense county map (~3,143 features) for tooltip perf profiling
+
+Renders every US county with a value and a custom tooltip slot. Useful as a
+manual perf harness — open DevTools Performance, record a hover/sweep across
+many counties, and inspect tooltip update cost. The tooltip element is
+mounted once and patched in place; `mousemove` writes the position
+straight to the DOM.
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="counties"
+    :data="denseCountyData"
+    :pan="true"
+    :zoom="true"
+    :color-scale="{ min: '#f0f5ff', max: '#08306b' }"
+    title="All US counties — tooltip perf demo"
+    :height="500"
+  >
+    <template #tooltip="{ id, name, value }">
+      <div style="font-weight: 600">{{ name }}</div>
+      <div style="opacity: 0.7; font-size: 0.85em">FIPS {{ id }}</div>
+      <div>Value: {{ value }}</div>
+    </template>
+  </ChoroplethMap>
+
+<template #code>
+
+```vue
+<script setup>
+import countiesTopo from "us-atlas/counties-10m.json";
+
+// One row per county
+const data = countiesTopo.objects.counties.geometries.map((g, i) => ({
+  id: String(g.id).padStart(5, "0"),
+  value: (i * 37) % 100,
+}));
+</script>
+
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  :data="data"
+  pan
+  zoom
+>
+  <template #tooltip="{ id, name, value }">
+    <div style="font-weight: 600">{{ name }}</div>
+    <div style="opacity: 0.7; font-size: 0.85em">FIPS {{ id }}</div>
+    <div>Value: {{ value }}</div>
+  </template>
+</ChoroplethMap>
+```
+
+  </template>
+</ComponentDemo>
+
+### Custom tooltip content (`#tooltip` slot)
+
+Use the `#tooltip` slot to render any Vue template — components, scoped
+styles, multi-line layouts — instead of the default `name: value`. The slot
+receives `{ id, name, value, feature }` for the hovered region. Providing the
+slot automatically enables interactive (HTML) tooltips, so you don't need to
+set `tooltip-trigger`.
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="statesTopo"
+    :data="[
+      { id: '06', value: 39538223 },
+      { id: '48', value: 29145505 },
+      { id: '12', value: 21538187 },
+      { id: '36', value: 20201249 },
+      { id: '17', value: 12812508 },
+    ]"
+    title="US population (2020)"
+    :height="300"
+  >
+    <template #tooltip="{ name, value }">
+      <div style="font-weight:600">{{ name }}</div>
+      <div v-if="typeof value === 'number'">
+        Pop: {{ value.toLocaleString('en-US') }}
+      </div>
+      <div v-else style="opacity:0.6">No data</div>
+    </template>
+  </ChoroplethMap>
+
+<template #code>
+
+```vue
+<ChoroplethMap :topology="statesTopo" :data="data" title="US population (2020)">
+  <template #tooltip="{ name, value }">
+    <div style="font-weight: 600">{{ name }}</div>
+    <div v-if="typeof value === 'number'">
+      Pop: {{ value.toLocaleString("en-US") }}
+    </div>
+    <div v-else style="opacity: 0.6">No data</div>
+  </template>
+</ChoroplethMap>
+```
+
+  </template>
+</ComponentDemo>
+
 ## Props
 
 | Prop | Type | Required | Default |

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -5,11 +5,11 @@ import {
   watch,
   onMounted,
   onUnmounted,
-  useId,
   toRaw,
+  useSlots,
 } from "vue";
 import { geoPath, geoAlbersUsa } from "d3-geo";
-import { zoom as d3Zoom } from "d3-zoom";
+import { zoom as d3Zoom, zoomIdentity } from "d3-zoom";
 import { select } from "d3-selection";
 import { feature, mesh, merge } from "topojson-client";
 import type { Topology, GeometryCollection } from "topojson-specification";
@@ -18,6 +18,9 @@ import ChartMenu from "../ChartMenu/ChartMenu.vue";
 import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
 import { saveSvg, savePng } from "../ChartMenu/download.js";
 import { placeTooltip } from "../tooltip-position.js";
+import ChoroplethTooltip from "./ChoroplethTooltip.vue";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
 
 export type GeoType = "states" | "counties" | "hsas";
 
@@ -76,7 +79,12 @@ const props = withDefaults(
     pan?: boolean;
     /** Tooltip activation mode */
     tooltipTrigger?: "hover" | "click";
-    /** Custom tooltip formatter. Receives { id, name, value } and returns HTML string. */
+    /**
+     * @deprecated Use the `#tooltip` slot instead, which gives you full Vue
+     * rendering (components, scoped styles, reactivity). This HTML-string
+     * formatter is kept for backwards compatibility and will be removed in a
+     * future release.
+     */
     tooltipFormat?: (data: {
       id: string;
       name: string;
@@ -119,21 +127,67 @@ const emit = defineEmits<{
   ): void;
 }>();
 
-const uid = useId();
-const gradientId = `choropleth-gradient-${uid}`;
+type ChoroplethFeature = GeoJSON.Feature<
+  GeoJSON.Geometry | null,
+  { name?: string }
+>;
+
+/** Public payload shape — slot props, hover/click emits, tooltip cache. */
+interface TooltipPayload {
+  id: string;
+  name: string;
+  value?: number | string;
+  feature: ChoroplethFeature;
+}
+
+defineSlots<{
+  tooltip?(props: TooltipPayload): unknown;
+}>();
+
+// The child types `feature` as `unknown` (it has no map-specific knowledge);
+// we always store a ChoroplethFeature, so narrow it back at the single point
+// where we forward the slot.
+const narrowSlotProps = (
+  raw: { feature: unknown } & Omit<TooltipPayload, "feature">,
+): TooltipPayload => raw as TooltipPayload;
+
 const containerRef = ref<HTMLElement | null>(null);
 const svgRef = ref<SVGSVGElement | null>(null);
 const mapGroupRef = ref<SVGGElement | null>(null);
-const measuredWidth = ref(0);
+const tooltipChildRef = ref<InstanceType<typeof ChoroplethTooltip> | null>(
+  null,
+);
+const slots = useSlots();
+// Slot/prop presence doesn't change at runtime, so this is effectively
+// computed once. Used to gate the teleported tooltip and the SVG <title>
+// fallback.
+const hasInteractiveTooltip = computed(
+  () => !!props.tooltipTrigger || !!props.tooltipFormat || !!slots.tooltip,
+);
+// Imperative path bookkeeping. Plain Maps rather than refs — Vue never reads
+// these from a render scope, so mutating them does not trigger re-renders.
+const pathsByFeatureId = new Map<string, SVGPathElement>();
+const tooltipDataById = new Map<string, TooltipPayload>();
+let bordersPathEl: SVGPathElement | null = null;
 let hoveredEl: SVGPathElement | null = null;
-let tooltipEl: HTMLDivElement | null = null;
 let isZooming = false;
 // TODO: map hover/tooltip causes performance issues on mobile (SVG stroke-width
 // changes + compositing layers degrade zoom/pan). Disabled on touch devices.
 const isTouchDevice = typeof window !== "undefined" && "ontouchstart" in window;
-let observer: ResizeObserver | null = null;
+let tooltipObserver: ResizeObserver | null = null;
+const lastTooltipSize = { width: 0, height: 0 };
+let lastPointer: { x: number; y: number } | null = null;
+let tooltipVisible = false;
 let zoomBehavior: ReturnType<typeof d3Zoom<SVGSVGElement, unknown>> | null =
   null;
+// True once the user has zoomed or panned away from the identity transform.
+// Drives the visibility of the reset button.
+const isZoomed = ref(false);
+// rAF-throttled cursor coords for moveTooltip; we coalesce many mousemove
+// events into one transform write per animation frame.
+let pendingMoveX = 0;
+let pendingMoveY = 0;
+let pendingMoveFrame = 0;
 
 function setupInteraction() {
   if (isTouchDevice) return;
@@ -154,24 +208,34 @@ function teardownInteraction() {
   g.removeEventListener("mouseout", onDelegatedMouseOut);
 }
 
+// Scroll / resize don't reliably emit mouseout on the underlying path even
+// though the cursor's relationship to the map has changed — the tooltip
+// would otherwise get stuck at its old `position: fixed` coordinates.
+function dismissOnViewportChange() {
+  clearHover();
+}
+
 onMounted(() => {
-  if (containerRef.value) {
-    measuredWidth.value = containerRef.value.clientWidth;
-    observer = new ResizeObserver((entries) => {
-      const entry = entries[0];
-      if (entry) measuredWidth.value = entry.contentRect.width;
-    });
-    observer.observe(containerRef.value);
-  }
   setupZoom();
   setupInteraction();
+  rebuildPaths();
+  attachTooltipObserver();
+  window.addEventListener("scroll", dismissOnViewportChange, {
+    passive: true,
+    capture: true,
+  });
+  window.addEventListener("resize", dismissOnViewportChange, { passive: true });
 });
 
 onUnmounted(() => {
-  observer?.disconnect();
+  tooltipObserver?.disconnect();
+  if (pendingMoveFrame) cancelAnimationFrame(pendingMoveFrame);
   teardownZoom();
   teardownInteraction();
-  hideTooltip();
+  window.removeEventListener("scroll", dismissOnViewportChange, {
+    capture: true,
+  });
+  window.removeEventListener("resize", dismissOnViewportChange);
 });
 
 function setupZoom() {
@@ -189,6 +253,8 @@ function setupZoom() {
       if (mapGroupRef.value) {
         mapGroupRef.value.setAttribute("transform", event.transform);
       }
+      const t = event.transform;
+      isZoomed.value = t.k !== 1 || t.x !== 0 || t.y !== 0;
     })
     .on("end", () => {
       isZooming = false;
@@ -210,6 +276,13 @@ function teardownZoom() {
   }
 }
 
+function resetZoom() {
+  if (!svgRef.value || !zoomBehavior) return;
+  // Snap straight back to identity; the zoom callback fires and clears
+  // isZoomed, which hides the button.
+  zoomBehavior.transform(select(svgRef.value), zoomIdentity);
+}
+
 watch(
   () => [props.zoom, props.pan],
   () => {
@@ -220,12 +293,23 @@ watch(
   },
 );
 
-const width = computed(() => props.width ?? (measuredWidth.value || 600));
+// Canonical internal coordinate system. All layout (projection, legend,
+// title) is computed at this size; the SVG's viewBox makes the browser
+// scale the entire canvas to whatever the container provides, so there's no
+// JS work on container resize. `props.width` / `props.height`, when set,
+// drive the rendered SVG element size but not these canonical coords.
+const CANONICAL_WIDTH = 1000;
 const aspectRatio = computed(() => {
   if (props.width && props.height) return props.height / props.width;
   return 0.625;
 });
-const height = computed(() => width.value * aspectRatio.value);
+const width = computed(() => CANONICAL_WIDTH);
+const height = computed(() => CANONICAL_WIDTH * aspectRatio.value);
+
+// Layout is fluid: the wrapper fills its parent's width and the SVG fills
+// the wrapper via CSS. `props.width` / `props.height`, when both are
+// passed, only shape the viewBox aspect ratio — they don't pin a display
+// size, so the map always scales to the available width without overflow.
 
 type NamedGeometry = GeometryCollection<{ name: string }>;
 type StatesTopo = Topology<{ states: NamedGeometry }>;
@@ -279,8 +363,8 @@ const stateBordersPath = computed(() => {
 const projection = computed(() =>
   geoAlbersUsa().fitExtent(
     [
-      [0, topOffset.value],
-      [width.value, height.value + topOffset.value],
+      [0, 0],
+      [width.value, height.value],
     ],
     featuresGeo.value,
   ),
@@ -294,15 +378,26 @@ const effectiveStrokeWidth = computed(() =>
     : props.strokeWidth,
 );
 
+// O(features + data) name→id index, so `dataMap` doesn't fall back to a
+// linear scan per data point (previously O(features × data)).
+const nameToFeatureId = computed(() => {
+  const m = new Map<string, string>();
+  for (const f of featuresGeo.value.features) {
+    if (f.properties?.name != null && f.id != null) {
+      m.set(f.properties.name, String(f.id));
+    }
+  }
+  return m;
+});
+
 const dataMap = computed(() => {
   const map = new Map<string, number | string>();
   if (!props.data) return map;
+  const nameIdx = nameToFeatureId.value;
   for (const d of props.data) {
     map.set(d.id, d.value);
-    const geo = featuresGeo.value.features.find(
-      (f) => f.properties?.name === d.id,
-    );
-    if (geo?.id != null) map.set(String(geo.id), d.value);
+    const fid = nameIdx.get(d.id);
+    if (fid) map.set(fid, d.value);
   }
   return map;
 });
@@ -362,41 +457,44 @@ function interpolateColor(t: number): string {
   return `rgb(${r},${g},${b})`;
 }
 
-function thresholdColor(value: number): string {
-  const stops = (props.colorScale as ThresholdStop[])
-    .slice()
-    .sort((a, b) => b.min - a.min);
-  for (const stop of stops) {
-    if (value >= stop.min) return stop.color;
-  }
-  return props.noDataColor!;
-}
+// Sorted high-to-low so the first match wins (highest threshold ≤ value).
+// Cached so we don't re-sort 3k+ times during a rebuild.
+const thresholdStopsDesc = computed(() =>
+  isThreshold.value
+    ? (props.colorScale as ThresholdStop[])
+        .slice()
+        .sort((a, b) => b.min - a.min)
+    : null,
+);
 
-function categoricalColor(value: string | number): string {
-  const stops = props.colorScale as CategoricalStop[];
-  const match = stops.find((s) => s.value === String(value));
-  return match ? match.color : props.noDataColor!;
-}
+const categoricalByValue = computed(() => {
+  if (!isCategorical.value) return null;
+  const m = new Map<string, string>();
+  for (const s of props.colorScale as CategoricalStop[])
+    m.set(s.value, s.color);
+  return m;
+});
 
-function stateColor(id: string | number): string {
-  const value = dataMap.value.get(String(id));
-  if (value == null) return props.noDataColor!;
-  if (isCategorical.value) return categoricalColor(value);
-  if (isThreshold.value) return thresholdColor(value as number);
+/** Single color-resolution path. Returns the noData color for missing rows. */
+function colorFor(id: string): string {
+  const value = dataMap.value.get(id);
+  const noData = props.noDataColor!;
+  if (value == null) return noData;
+  const cat = categoricalByValue.value;
+  if (cat) return cat.get(String(value)) ?? noData;
+  const thresholds = thresholdStopsDesc.value;
+  if (thresholds) {
+    const n = value as number;
+    for (const stop of thresholds) if (n >= stop.min) return stop.color;
+    return noData;
+  }
   const { min, max } = extent.value;
-  const t = ((value as number) - min) / (max - min);
-  return interpolateColor(t);
-}
-
-function stateName(feat: (typeof featuresGeo.value.features)[number]): string {
-  return feat.properties?.name ?? String(feat.id);
+  return interpolateColor(((value as number) - min) / (max - min));
 }
 
-function stateValue(
+const featureName = (
   feat: (typeof featuresGeo.value.features)[number],
-): number | string | undefined {
-  return dataMap.value.get(String(feat.id));
-}
+): string => feat.properties?.name ?? String(feat.id);
 
 function formatTooltipValue(value: number | string | undefined): string {
   if (value == null) return "";
@@ -406,77 +504,112 @@ function formatTooltipValue(value: number | string | undefined): string {
   return String(value);
 }
 
-const featMap = computed(() => {
-  const m = new Map<string, (typeof featuresGeo.value.features)[number]>();
-  for (const f of featuresGeo.value.features) m.set(String(f.id), f);
-  return m;
-});
+/** "Name" or "Name: formatted-value" — used for the SVG <title> fallback. */
+function titleText(name: string, value: number | string | undefined): string {
+  return value == null ? name : `${name}: ${formatTooltipValue(value)}`;
+}
 
-function resolveTarget(el: Element | null): {
-  pathEl: SVGPathElement;
-  feat: (typeof featuresGeo.value.features)[number];
-} | null {
-  let target = el;
-  while (target && !(target as HTMLElement).dataset?.featId) {
-    target = target.parentElement;
-  }
-  if (!target) return null;
-  const feat = featMap.value.get((target as HTMLElement).dataset.featId!);
-  if (!feat) return null;
-  return { pathEl: target as SVGPathElement, feat };
+// ─── Tooltip (fully synchronous; positioning uses cached size) ───────────
+//
+// The flow is:
+//   1. mouseover  → setData (Vue patches slot props on the *child*) → position
+//      using lastTooltipSize (possibly stale by one frame) → visibility:visible
+//   2. tooltipObserver fires when the slot DOM has actually committed → we
+//      refresh lastTooltipSize and re-apply the position if still visible.
+//   3. mousemove  → rAF-throttled direct DOM write of transform; no reactivity.
+//   4. mouseout (leaving the map) → visibility:hidden.
+//
+// There is no `await` and no token: out-of-order completion is impossible
+// because every step is synchronous from the event handler's perspective.
+
+function attachTooltipObserver() {
+  const el = tooltipChildRef.value?.getEl();
+  if (!el) return;
+  tooltipObserver?.disconnect();
+  // First measurement bootstraps placement (the very first hover used the
+  // 0×0 fallback). After that we just silently refresh the cached size —
+  // every hover uses whatever was measured on the previous render, so
+  // switching between hover targets never causes the tooltip to re-flip
+  // mid-hover.
+  let primed = false;
+  tooltipObserver = new ResizeObserver((entries) => {
+    const r = entries[0]?.contentRect;
+    if (!r) return;
+    lastTooltipSize.width = r.width;
+    lastTooltipSize.height = r.height;
+    if (!primed && tooltipVisible && lastPointer) {
+      primed = true;
+      applyTooltipPosition(lastPointer.x, lastPointer.y);
+    } else {
+      primed = true;
+    }
+  });
+  tooltipObserver.observe(el);
 }
 
-function showTooltip(
-  feat: (typeof featuresGeo.value.features)[number],
-  clientX: number,
-  clientY: number,
-) {
-  if (!tooltipEl) {
-    tooltipEl = document.createElement("div");
-    tooltipEl.className = "chart-tooltip-content";
-    tooltipEl.style.position = "fixed";
-    tooltipEl.style.transform = "translateY(-50%)";
-    document.body.appendChild(tooltipEl);
-  }
-  const name = stateName(feat);
-  const value = stateValue(feat);
-  const data = { id: String(feat.id), name, value };
-  if (props.tooltipFormat) {
-    tooltipEl.innerHTML = props.tooltipFormat(data);
-  } else if (value == null) {
-    tooltipEl.textContent = name;
-  } else {
-    tooltipEl.textContent = `${name}: ${formatTooltipValue(value)}`;
-  }
+function applyTooltipPosition(clientX: number, clientY: number) {
+  const el = tooltipChildRef.value?.getEl();
+  if (!el) return;
+  // Use the cached size — accurate after the first ResizeObserver tick. On
+  // the very first show before the observer has fired, this falls through
+  // placeTooltip's no-flip path (size 0 → no flip), which simply pins the
+  // tooltip to the right of the cursor.
   const chartRect = containerRef.value?.getBoundingClientRect();
   const { left, top } = placeTooltip(
     clientX,
     clientY,
-    tooltipEl.offsetWidth,
-    tooltipEl.offsetHeight,
+    lastTooltipSize.width,
+    lastTooltipSize.height,
     props.tooltipClamp,
     chartRect,
   );
-  tooltipEl.style.left = `${left}px`;
-  tooltipEl.style.top = `${top}px`;
+  el.style.transform = `translate3d(${left}px, ${top}px, 0) translateY(-50%)`;
+}
+
+function showTooltip(featId: string, clientX: number, clientY: number) {
+  const data = tooltipDataById.get(featId);
+  if (!data) return;
+  const child = tooltipChildRef.value;
+  const el = child?.getEl();
+  if (!child || !el) return;
+  child.setData(data);
+  lastPointer = { x: clientX, y: clientY };
+  tooltipVisible = true;
+  applyTooltipPosition(clientX, clientY);
+  el.style.visibility = "visible";
+}
+
+function moveTooltip(clientX: number, clientY: number) {
+  if (!tooltipVisible) return;
+  pendingMoveX = clientX;
+  pendingMoveY = clientY;
+  if (pendingMoveFrame) return;
+  pendingMoveFrame = requestAnimationFrame(() => {
+    pendingMoveFrame = 0;
+    const el = tooltipChildRef.value?.getEl();
+    if (!el || !tooltipVisible) return;
+    lastPointer = { x: pendingMoveX, y: pendingMoveY };
+    // Mid-hover: don't re-run flip/clamp on every pixel; just translate.
+    el.style.transform = `translate3d(${pendingMoveX + 16}px, ${pendingMoveY}px, 0) translateY(-50%)`;
+  });
 }
 
 function hideTooltip() {
-  if (tooltipEl) {
-    tooltipEl.remove();
-    tooltipEl = null;
-  }
+  if (!tooltipVisible) return;
+  tooltipVisible = false;
+  lastPointer = null;
+  const el = tooltipChildRef.value?.getEl();
+  if (el) el.style.visibility = "hidden";
 }
 
-function setHover(
-  pathEl: SVGPathElement,
-  feat: (typeof featuresGeo.value.features)[number],
-) {
-  if (hoveredEl && hoveredEl !== pathEl) {
+function setHover(pathEl: SVGPathElement) {
+  if (hoveredEl === pathEl) return;
+  if (hoveredEl) {
     hoveredEl.setAttribute("stroke-width", String(effectiveStrokeWidth.value));
     hoveredEl.setAttribute("stroke", props.strokeColor);
   }
   hoveredEl = pathEl;
+  // Bring hovered path to top so its thicker border is not clipped by neighbors.
   pathEl.parentNode?.appendChild(pathEl);
   pathEl.setAttribute("stroke-width", String(effectiveStrokeWidth.value + 1));
   pathEl.setAttribute("stroke", "#555");
@@ -492,33 +625,35 @@ function clearHover() {
   hideTooltip();
 }
 
-// Delegated event handlers (native DOM, attached to <g>)
+// ─── Delegated event handlers (single set of listeners on the <g>) ───────
+
+function eventToFeatureId(target: EventTarget | null): string | null {
+  let el = target as Element | null;
+  while (el && !(el as HTMLElement).dataset?.featId) el = el.parentElement;
+  return el ? ((el as HTMLElement).dataset.featId ?? null) : null;
+}
+
 function onDelegatedEvent(event: Event) {
   if (isZooming) return;
   const me = event as MouseEvent;
-  const hit = resolveTarget(me.target as Element);
-  if (!hit) return;
+  const featId = eventToFeatureId(me.target);
+  if (!featId) return;
+  const data = tooltipDataById.get(featId);
+  if (!data) return;
+  const payload = { id: data.id, name: data.name, value: data.value };
   if (event.type === "click") {
-    emit("stateClick", {
-      id: String(hit.feat.id),
-      name: stateName(hit.feat),
-      value: stateValue(hit.feat),
-    });
+    emit("stateClick", payload);
   } else if (event.type === "mouseover") {
-    setHover(hit.pathEl, hit.feat);
-    if (props.tooltipTrigger) showTooltip(hit.feat, me.clientX, me.clientY);
-    emit("stateHover", {
-      id: String(hit.feat.id),
-      name: stateName(hit.feat),
-      value: stateValue(hit.feat),
-    });
+    setHover(pathsByFeatureId.get(featId)!);
+    if (hasInteractiveTooltip.value)
+      showTooltip(featId, me.clientX, me.clientY);
+    emit("stateHover", payload);
   }
 }
 
 function onDelegatedMouseMove(event: MouseEvent) {
-  if (isZooming || !tooltipEl) return;
-  tooltipEl.style.left = `${event.clientX + 16}px`;
-  tooltipEl.style.top = `${event.clientY}px`;
+  if (isZooming) return;
+  moveTooltip(event.clientX, event.clientY);
 }
 
 function onDelegatedMouseOut(event: MouseEvent) {
@@ -527,6 +662,109 @@ function onDelegatedMouseOut(event: MouseEvent) {
   clearHover();
 }
 
+// ─── Imperative SVG path management ──────────────────────────────────────
+//
+// 3,000+ counties are too many to round-trip through Vue's render scheduler
+// on every reactive change. We build the SVG path tree once per feature set
+// and mutate attributes directly when data/styling changes.
+
+function makePath(d: string | null): SVGPathElement {
+  const p = document.createElementNS(SVG_NS, "path") as SVGPathElement;
+  if (d) p.setAttribute("d", d);
+  return p;
+}
+
+function rebuildPaths() {
+  const g = mapGroupRef.value;
+  if (!g) return;
+  while (g.firstChild) g.removeChild(g.firstChild);
+  pathsByFeatureId.clear();
+  tooltipDataById.clear();
+  bordersPathEl = null;
+  hoveredEl = null;
+
+  const path = pathGenerator.value;
+  const features = featuresGeo.value.features;
+  const stroke = props.strokeColor;
+  const sw = String(effectiveStrokeWidth.value);
+  const wantsTitleFallback = !hasInteractiveTooltip.value;
+
+  // Single DocumentFragment append → one layout flush for the whole batch.
+  const frag = document.createDocumentFragment();
+  for (const feat of features) {
+    const id = String(feat.id);
+    const name = featureName(feat);
+    const value = dataMap.value.get(id);
+    const p = makePath(path(feat));
+    p.setAttribute("class", "state-path");
+    p.setAttribute("data-feat-id", id);
+    p.setAttribute("fill", colorFor(id));
+    p.setAttribute("stroke", stroke);
+    p.setAttribute("stroke-width", sw);
+    // Keep stroke width pixel-accurate regardless of how the browser scales
+    // the viewBox to fit the container — otherwise borders appear thicker
+    // as the map is enlarged.
+    p.setAttribute("vector-effect", "non-scaling-stroke");
+    if (wantsTitleFallback) {
+      const title = document.createElementNS(SVG_NS, "title");
+      title.textContent = titleText(name, value);
+      p.appendChild(title);
+    }
+    frag.appendChild(p);
+    pathsByFeatureId.set(id, p);
+    tooltipDataById.set(id, {
+      id,
+      name,
+      value,
+      feature: feat as ChoroplethFeature,
+    });
+  }
+
+  // State-borders overlay (counties / hsas mode).
+  const borders = stateBordersPath.value;
+  if (borders) {
+    const b = makePath(path(borders));
+    b.setAttribute("fill", "none");
+    b.setAttribute("stroke", stroke);
+    b.setAttribute("stroke-width", "1");
+    b.setAttribute("stroke-linejoin", "round");
+    b.setAttribute("pointer-events", "none");
+    b.setAttribute("vector-effect", "non-scaling-stroke");
+    frag.appendChild(b);
+    bordersPathEl = b;
+  }
+  g.appendChild(frag);
+}
+
+function updateFills() {
+  const refreshTitle = !hasInteractiveTooltip.value;
+  for (const [id, p] of pathsByFeatureId) {
+    const value = dataMap.value.get(id);
+    const entry = tooltipDataById.get(id);
+    p.setAttribute("fill", colorFor(id));
+    // Refresh cached tooltip payload so a later hover (or the SVG <title>
+    // fallback below) reflects the new value.
+    if (entry) entry.value = value;
+    if (refreshTitle && entry) {
+      // First child is the <title> appended in rebuildPaths when fallback
+      // mode is active.
+      const title = p.firstElementChild;
+      if (title) title.textContent = titleText(entry.name, value);
+    }
+  }
+}
+
+function updateStrokes() {
+  const stroke = props.strokeColor;
+  const sw = String(effectiveStrokeWidth.value);
+  for (const p of pathsByFeatureId.values()) {
+    if (p === hoveredEl) continue;
+    p.setAttribute("stroke", stroke);
+    p.setAttribute("stroke-width", sw);
+  }
+  if (bordersPathEl) bordersPathEl.setAttribute("stroke", stroke);
+}
+
 function menuFilename() {
   return typeof props.menu === "string" ? props.menu : "choropleth";
 }
@@ -540,14 +778,6 @@ const sortedThresholdStops = computed(() =>
   (props.colorScale as ThresholdStop[]).slice().sort((a, b) => a.min - b.min),
 );
 
-const titleHeight = computed(() => (props.title ? 24 : 0));
-const legendHeight = computed(() => (showLegend.value ? 28 : 0));
-const topOffset = computed(() => titleHeight.value + legendHeight.value);
-
-const svgHeight = computed(() => height.value + topOffset.value);
-
-const legendY = computed(() => titleHeight.value + 18);
-
 const gradientStops = computed(() => {
   const steps = 10;
   const result: { offset: string; color: string }[] = [];
@@ -561,6 +791,13 @@ const gradientStops = computed(() => {
   return result;
 });
 
+// Compact formatter so legend ticks for large ranges (e.g. populations in
+// the millions) don't render wide enough to collide with each other.
+const compactTickFormat = new Intl.NumberFormat("en-US", {
+  notation: "compact",
+  maximumFractionDigits: 1,
+});
+
 const continuousTicks = computed(() => {
   const { min, max } = extent.value;
   const range = max - min;
@@ -569,9 +806,12 @@ const continuousTicks = computed(() => {
   for (let i = 1; i <= count; i++) {
     const t = i / (count + 1);
     const v = min + range * t;
-    const formatted = Number.isInteger(v)
-      ? String(v)
-      : v.toFixed(1).replace(/\.0$/, "");
+    const formatted =
+      Math.abs(v) >= 1000
+        ? compactTickFormat.format(v)
+        : Number.isInteger(v)
+          ? String(v)
+          : v.toFixed(1).replace(/\.0$/, "");
     ticks.push({ value: formatted, pct: t * 100 });
   }
   return ticks;
@@ -595,32 +835,13 @@ const discreteLegendItems = computed(() => {
   return items;
 });
 
-const discreteLegendTotalWidth = computed(() => {
-  const titleWidth = props.legendTitle ? props.legendTitle.length * 8 + 12 : 0;
-  let w = titleWidth;
-  for (const item of discreteLegendItems.value) {
-    w += 16 + item.label.length * 7 + 12;
-  }
-  return w - (discreteLegendItems.value.length > 0 ? 12 : 0);
-});
-
-const discreteLegendPositions = computed(() => {
-  const titleWidth = props.legendTitle ? props.legendTitle.length * 8 + 12 : 0;
-  let x = titleWidth;
-  return discreteLegendItems.value.map((item) => {
-    const pos = x;
-    x += 16 + item.label.length * 7 + 12;
-    return pos;
-  });
-});
-
-const legendXOffset = computed(() => {
-  if (isCategorical.value || isThreshold.value) {
-    return (width.value - discreteLegendTotalWidth.value) / 2;
-  }
-  const barWidth = 160;
-  const titleWidth = props.legendTitle ? props.legendTitle.length * 8 + 12 : 0;
-  return (width.value - titleWidth - barWidth) / 2;
+// Linear-gradient CSS for the continuous legend bar, derived from the same
+// stops the SVG version used.
+const gradientCss = computed(() => {
+  const stops = gradientStops.value
+    .map((s) => `${s.color} ${s.offset}`)
+    .join(", ");
+  return `linear-gradient(to right, ${stops})`;
 });
 
 const menuItems = computed<ChartMenuItem[]>(() => {
@@ -640,145 +861,133 @@ const menuItems = computed<ChartMenuItem[]>(() => {
     },
   ];
 });
+
+// ─── Reactive triggers for the imperative SVG tree ───────────────────────
+// Registered last so the eagerly-evaluated source getters can read every
+// computed defined above without hitting a TDZ.
+
+// Geometry / projection / tooltip-mode → full rebuild.
+watch(
+  () => [pathGenerator.value, hasInteractiveTooltip.value],
+  () => rebuildPaths(),
+);
+
+// Data or scale → repaint fills (and refresh fallback <title>s).
+watch(
+  () => [dataMap.value, props.colorScale, props.noDataColor],
+  () => updateFills(),
+);
+
+// Stroke styling → refresh stroke attrs (skipping the currently hovered path).
+watch(
+  () => [props.strokeColor, effectiveStrokeWidth.value],
+  () => updateStrokes(),
+);
 </script>
 
 <template>
   <div ref="containerRef" :class="['choropleth-wrapper', { pannable: pan }]">
     <ChartMenu v-if="menu" :items="menuItems" />
-    <svg ref="svgRef" :width="width" :height="svgHeight">
-      <g ref="mapGroupRef">
-        <path
-          v-for="feat in featuresGeo.features"
-          :key="String(feat.id)"
-          :data-feat-id="String(feat.id)"
-          :d="pathGenerator(feat) ?? undefined"
-          :fill="stateColor(feat.id!)"
-          :stroke="strokeColor"
-          :stroke-width="effectiveStrokeWidth"
-          class="state-path"
-        >
-          <title v-if="!tooltipTrigger">
-            {{ stateName(feat)
-            }}{{
-              stateValue(feat) != null
-                ? `: ${formatTooltipValue(stateValue(feat))}`
-                : ""
-            }}
-          </title>
-        </path>
-        <path
-          v-if="stateBordersPath"
-          :d="pathGenerator(stateBordersPath) ?? undefined"
-          fill="none"
-          :stroke="strokeColor"
-          :stroke-width="1"
-          stroke-linejoin="round"
-          pointer-events="none"
-        />
-      </g>
-      <!-- Legend -->
-      <g
-        v-if="showLegend"
-        class="choropleth-legend"
-        :transform="`translate(${legendXOffset},${legendY})`"
-      >
-        <!-- Categorical or Threshold: dots with labels -->
+    <!--
+      Title + legend live as an HTML overlay on top of the SVG so they keep
+      their intrinsic px sizes regardless of how the browser scales the
+      viewBox to fit the container.
+    -->
+    <div v-if="title || showLegend" class="choropleth-header">
+      <div v-if="title" class="choropleth-title">{{ title }}</div>
+      <div v-if="showLegend" class="choropleth-legend">
+        <span v-if="legendTitle" class="choropleth-legend-title">
+          {{ legendTitle }}
+        </span>
         <template v-if="isCategorical || isThreshold">
-          <text
-            v-if="legendTitle"
-            :y="5"
-            font-size="13"
-            font-weight="600"
-            fill="currentColor"
+          <span
+            v-for="item in discreteLegendItems"
+            :key="item.key"
+            class="choropleth-legend-item"
           >
-            {{ legendTitle }}
-          </text>
-          <template v-for="(item, i) in discreteLegendItems" :key="item.key">
-            <rect
-              :x="discreteLegendPositions[i]"
-              :y="-5"
-              width="12"
-              height="12"
-              rx="3"
-              :fill="item.color"
+            <span
+              class="choropleth-legend-swatch"
+              :style="{ background: item.color }"
             />
-            <text
-              :x="discreteLegendPositions[i] + 16"
-              :y="5"
-              font-size="13"
-              fill="currentColor"
-            >
-              {{ item.label }}
-            </text>
-          </template>
+            {{ item.label }}
+          </span>
         </template>
-        <!-- Continuous: gradient bar with ticks -->
-        <template v-else>
-          <text
-            v-if="legendTitle"
-            :y="5"
-            font-size="13"
-            font-weight="600"
-            fill="currentColor"
-          >
-            {{ legendTitle }}
-          </text>
-          <defs>
-            <linearGradient :id="gradientId" x1="0" x2="1" y1="0" y2="0">
-              <stop
-                v-for="s in gradientStops"
-                :key="s.offset"
-                :offset="s.offset"
-                :stop-color="s.color"
-              />
-            </linearGradient>
-          </defs>
-          <rect
-            :x="legendTitle ? legendTitle.length * 8 + 12 : 0"
-            :y="-6"
-            :width="160"
-            :height="12"
-            rx="2"
-            :fill="`url(#${gradientId})`"
+        <div v-else class="choropleth-legend-continuous">
+          <div
+            class="choropleth-legend-gradient"
+            :style="{ background: gradientCss }"
           />
-          <text
-            v-for="tick in continuousTicks"
-            :key="tick.value"
-            :x="
-              (legendTitle ? legendTitle.length * 8 + 12 : 0) +
-              (tick.pct / 100) * 160
-            "
-            :y="20"
-            font-size="11"
-            fill="currentColor"
-            opacity="0.7"
-            text-anchor="middle"
-          >
-            {{ tick.value }}
-          </text>
-        </template>
-      </g>
-      <text
-        v-if="title"
-        :x="width / 2"
-        :y="18"
-        text-anchor="middle"
-        font-size="14"
-        font-weight="600"
-        fill="currentColor"
-      >
-        {{ title }}
-      </text>
+          <div class="choropleth-legend-ticks">
+            <span
+              v-for="tick in continuousTicks"
+              :key="tick.value"
+              :style="{ left: tick.pct + '%' }"
+            >
+              {{ tick.value }}
+            </span>
+          </div>
+        </div>
+      </div>
+    </div>
+    <svg
+      ref="svgRef"
+      :viewBox="`0 0 ${width} ${height}`"
+      preserveAspectRatio="xMidYMid meet"
+    >
+      <!--
+        Path elements are created imperatively in `rebuildPaths()`; Vue never
+        diffs the per-feature subtree so reactive state changes don't walk
+        thousands of vnodes. This <g> is the mount point + event delegation
+        target.
+      -->
+      <g ref="mapGroupRef" />
     </svg>
+    <button
+      v-if="(zoom || pan) && isZoomed"
+      type="button"
+      class="choropleth-reset"
+      aria-label="Reset zoom"
+      @click="resetZoom"
+    >
+      Reset
+    </button>
+    <ChoroplethTooltip v-if="hasInteractiveTooltip" ref="tooltipChildRef">
+      <template #default="raw">
+        <slot name="tooltip" v-bind="narrowSlotProps(raw)">
+          <span v-if="tooltipFormat" v-html="tooltipFormat(raw)" />
+          <template v-else-if="raw.value == null">{{ raw.name }}</template>
+          <template v-else>
+            {{ raw.name }}: {{ formatTooltipValue(raw.value) }}
+          </template>
+        </slot>
+      </template>
+    </ChoroplethTooltip>
   </div>
 </template>
 
 <style scoped>
 .choropleth-wrapper {
+  /*
+   * Override at the consumer level to change the legend/title panel fill:
+   *   .my-map { --choropleth-legend-bg: rgba(0, 0, 0, 0.6); }
+   * Defaults to the theme's page background so the panel reads as a
+   * floating extension of the page surface.
+   */
+  --choropleth-legend-bg: var(--color-bg-0, #fff);
+
   position: relative;
   width: 100%;
 }
 
+.choropleth-wrapper svg {
+  display: block;
+  /* Fluid scaling via viewBox: the SVG fills its container's width and the
+   * browser derives height from the viewBox aspect ratio. Overridden when
+   * `props.width` / `props.height` are explicitly set on the component. */
+  width: 100%;
+  height: auto;
+}
+
 .choropleth-wrapper.pannable svg {
   cursor: grab;
 }
@@ -794,4 +1003,101 @@ const menuItems = computed<ChartMenuItem[]>(() => {
 .state-path {
   cursor: pointer;
 }
+
+.choropleth-reset {
+  position: absolute;
+  bottom: 8px;
+  left: 8px;
+  padding: 4px 10px;
+  font: inherit;
+  font-size: 12px;
+  color: var(--color-text-secondary, #555);
+  background: var(--color-bg-0, #fff);
+  border: 1px solid var(--color-border, #e5e7eb);
+  border-radius: 4px;
+  cursor: pointer;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+}
+
+.choropleth-reset:hover {
+  background: var(--color-bg-1, #f8f9fa);
+  color: var(--color-text, #212529);
+}
+
+/*
+ * Title + legend overlay. Lives in HTML so its sizes are independent of
+ * the SVG viewBox scaling — text stays at its declared px size at any
+ * container width.
+ */
+.choropleth-header {
+  /*
+   * In-flow above the map — the map gets its full canvas, no overlap to
+   * worry about. Centered via `width: fit-content` + `margin: auto`.
+   */
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+  width: fit-content;
+  margin: 0 auto;
+  padding: 8px 14px;
+  border-radius: 4px;
+  background: var(--choropleth-legend-bg);
+  color: currentColor;
+}
+
+.choropleth-title {
+  font-size: 14px;
+  font-weight: 600;
+  line-height: 1.2;
+}
+
+.choropleth-legend {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  font-size: 13px;
+  line-height: 1.2;
+}
+
+.choropleth-legend-title {
+  font-weight: 600;
+}
+
+.choropleth-legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.choropleth-legend-swatch {
+  width: 12px;
+  height: 12px;
+  border-radius: 3px;
+  display: inline-block;
+}
+
+.choropleth-legend-continuous {
+  display: flex;
+  flex-direction: column;
+  width: 160px;
+}
+
+.choropleth-legend-gradient {
+  height: 12px;
+  border-radius: 2px;
+}
+
+.choropleth-legend-ticks {
+  position: relative;
+  height: 14px;
+  margin-top: 4px;
+  font-size: 11px;
+  opacity: 0.7;
+}
+
+.choropleth-legend-ticks > span {
+  position: absolute;
+  transform: translateX(-50%);
+}
 </style>

package/charts/ChoroplethMap/ChoroplethTooltip.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import { ref, useTemplateRef } from "vue";
+
+export interface ChoroplethTooltipData {
+  id: string;
+  name: string;
+  value?: number | string;
+  feature: unknown;
+}
+
+defineSlots<{
+  default?(props: ChoroplethTooltipData): unknown;
+}>();
+
+// Local reactive state. Held inside the child so the parent's render scope
+// never subscribes to it — hover updates re-render only this small tree,
+// not the parent's 3,000+ paths.
+const data = ref<ChoroplethTooltipData | null>(null);
+const rootRef = useTemplateRef<HTMLDivElement>("root");
+
+defineExpose({
+  setData(next: ChoroplethTooltipData | null) {
+    data.value = next;
+  },
+  getEl(): HTMLDivElement | null {
+    return rootRef.value;
+  },
+});
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      ref="root"
+      class="chart-tooltip-content"
+      style="
+        position: fixed;
+        left: 0;
+        top: 0;
+        visibility: hidden;
+        will-change: transform;
+        pointer-events: none;
+        transform: translateY(-50%);
+      "
+    >
+      <slot v-if="data" v-bind="data" />
+    </div>
+  </Teleport>
+</template>

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.1",
+  "version": "0.4.2",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [

package/package.json

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