@cfasim-ui/docs 0.6.4 → 0.7.1

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import {
   computed,
+  nextTick,
   ref,
   watch,
   onMounted,
@@ -9,7 +10,12 @@ import {
   useSlots,
 } from "vue";
 import { geoPath, geoAlbersUsa, geoMercator } from "d3-geo";
-import { zoom as d3Zoom, zoomIdentity } from "d3-zoom";
+import {
+  zoom as d3Zoom,
+  zoomIdentity,
+  zoomTransform,
+  type ZoomTransform,
+} from "d3-zoom";
 import { select } from "d3-selection";
 // Side-effect import: enables `selection.transition()` on d3 selections so
 // `applyFocus` can animate the zoom transform.
@@ -22,6 +28,9 @@ import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
 import { saveSvg, savePng } from "../ChartMenu/download.js";
 import {
   useChartFullscreen,
+  isTouchDevice,
+  ChartZoomControls,
+  resolveColorToRgb,
   TITLE_FONT_SIZE,
   TITLE_LINE_HEIGHT,
   TITLE_FONT_WEIGHT,
@@ -81,10 +90,14 @@ export interface FocusItem {
    * `"dashed"` uses long dashes; `"dotted"` uses small round dots —
    * useful when stacking multiple outlines of different geoTypes. */
   style?: FocusStyle;
-  /** Stroke color for the outline. Applies to cross-geoType overlay
-   * paths only (base-geoType highlights stay at the default focus
-   * color). Default: `"#fff"`. */
+  /** Stroke color for the outline. In-place highlights (items in the
+   * base geoType) default to pure black/white following the theme
+   * (`light-dark(#000, #fff)`); cross-geoType overlay paths default to
+   * `"#fff"`. */
   stroke?: string;
+  /** Outline width in CSS px. Defaults to the map's stroke width + 1
+   * for in-place highlights and + 1.5 for cross-geoType overlays. */
+  strokeWidth?: number;
 }
 
 export type FocusValue = string | FocusItem | Array<string | FocusItem> | null;
@@ -151,18 +164,45 @@ const props = withDefaults(
     legend?: boolean;
     /** Title displayed next to the legend */
     legendTitle?: string;
-    /** Enable mouse-wheel zooming. Default: false */
+    /**
+     * Enable the activate-to-zoom interaction. Default `false` — the map
+     * is fully static (tooltips and click-select still work, and
+     * programmatic `focus` zoom still applies). When enabled, the map
+     * stays static until the user double-clicks (desktop) or taps (touch):
+     * desktop double-click zooms in place alongside always-visible
+     * +/−/reset controls, with drag-pan once zoomed; on touch a tap
+     * expands the map to fill the window, where one finger pans, pinch
+     * zooms, and a tap selects. The scroll wheel never zooms inline, so
+     * the map can't hijack page scrolling.
+     */
     zoom?: boolean;
-    /** Enable click-and-drag panning. Default: false */
-    pan?: boolean;
     /**
-     * Require two fingers to pan/zoom on touch devices. Default `false`.
-     * When `true`, a single finger scrolls the page (the map sets
-     * `touch-action: pan-y` and ignores one-finger drags) while two fingers
-     * pan and pinch-zoom the map. Single-finger tap-to-select still works.
-     * Has no effect with a mouse.
+     * Interaction style when `zoom` is enabled. `"activate"` (default)
+     * keeps the map static until a double-click / tap / feature click, so
+     * the page scrolls freely past it. `"scroll"` makes the map immediately
+     * interactive — the wheel zooms, dragging pans, and touch gestures work
+     * inline with no tap-to-expand step. Use it for full-page experiences
+     * where the map is the main surface and there's no page scroll to
+     * hijack.
+     */
+    zoomMode?: "activate" | "scroll";
+    /**
+     * On touch devices, expand the map to fill the window when tapped.
+     * Default `true`. Set `false` to zoom in place instead: the first tap
+     * zooms the inline map in on the tapped point (like a desktop
+     * double-click), after which one-finger pan / pinch work and taps
+     * select features; the +/−/reset controls render inline. Note the
+     * activated map captures touch scrolling over it. No effect on desktop
+     * or when `zoom` is off; `zoom-mode="scroll"` already implies inline
+     * interaction.
+     */
+    touchExpand?: boolean;
+    /**
+     * Show the grey "Double click to zoom" / "Tap to zoom" affordance over
+     * the top of the map while the zoom gesture hasn't been used yet.
+     * Default `true`; set `false` to hide it. No effect when `zoom` is off.
      */
-    twoFingerPan?: boolean;
+    zoomHint?: boolean;
     /** Tooltip activation mode */
     tooltipTrigger?: "hover" | "click";
     /**
@@ -199,7 +239,7 @@ const props = withDefaults(
      * current pan/zoom transform is preserved; only the highlight is
      * removed. Works with `v-model:focus`: clicking an unfocused feature
      * (in the base geoType) emits its id; clicking the focused feature
-     * emits `null`. The built-in Reset button clears focus *and* resets
+     * emits `null`. The built-in reset button clears focus *and* resets
      * the zoom. If a tooltip is configured, focusing a feature in the
      * base geoType shows its tooltip.
      */
@@ -211,7 +251,7 @@ const props = withDefaults(
      * Default `true`. Set `false` to highlight (and draw cross-geoType
      * overlays) without changing the current pan/zoom — useful for a
      * click-to-select interaction where the map should stay put. The
-     * built-in Reset button is unaffected.
+     * built-in reset button is unaffected.
      */
     focusZoom?: boolean;
     /**
@@ -232,8 +272,9 @@ const props = withDefaults(
     menu: true,
     legend: true,
     zoom: false,
-    pan: false,
-    twoFingerPan: false,
+    zoomMode: "activate",
+    touchExpand: true,
+    zoomHint: true,
     tooltipClamp: "chart",
     focusZoomLevel: 4,
     focusZoom: true,
@@ -344,27 +385,57 @@ let hoveredEl: SVGPathElement | null = null;
 // Paths currently styled as focused. Tracked separately from hover so the
 // two states compose: hovering a focused path keeps the highlight on
 // un-hover, and clearing focus while still hovering keeps the hover style.
-// Maps each focused base-geoType path to the style it was given so a
-// repeat focus with a different style can re-apply without diffing the
+// Maps each focused base-geoType path to the FocusItem that styled it so
+// a repeat focus with different styling can re-apply without diffing the
 // attribute set manually.
-const focusedPathStyles = new Map<SVGPathElement, FocusStyle>();
+const focusedPathStyles = new Map<SVGPathElement, FocusItem>();
 // Cross-geoType focus items render as standalone outline paths layered on
 // top of the base map. Keyed by `${geoType}:${id}` so we can diff add /
-// remove / restyle on each applyFocus.
-const overlayPathEls = new Map<string, SVGPathElement>();
+// remove / restyle on each applyFocus. `strokeWidth` (visual CSS px) is
+// kept alongside so applyStrokeScale can re-compensate custom widths.
+const overlayPathEls = new Map<
+  string,
+  { el: SVGPathElement; strokeWidth?: number }
+>();
 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 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.
+// True while the transform is away from identity.
 const isZoomed = ref(false);
+// Current zoom scale — drives the +/− buttons' disabled states and the
+// stroke-width compensation in applyStrokeScale.
+const scaleK = ref(1);
+// How much the browser scales the canonical viewBox to fit the container
+// (rendered CSS width / CANONICAL_WIDTH). Tracked by a ResizeObserver so
+// stroke widths can stay visually constant without `vector-effect:
+// non-scaling-stroke` (see applyStrokeScale).
+const viewScale = ref(1);
+// Latched true the first time the transform leaves identity (double-click,
+// tap zoom, +/− press, or a focus zoom).
+const hasZoomed = ref(false);
+// Latched true when the user selects a feature while zooming is enabled —
+// engaging with the map's clickable elements counts as opting in.
+const hasInteracted = ref(false);
+// The pan/zoom interaction is "activated" once the user has zoomed or
+// engaged with the map. Activation is sticky (reset keeps it, except the
+// inline touch flow, where reset restores the pre-tap static mode by
+// clearing both latches).
+const isActivated = computed(() => hasZoomed.value || hasInteracted.value);
+// `zoom-mode="scroll"`: no activation step at all — the map owns wheel,
+// drag, and touch gestures from the start (for full-page experiences).
+const isScrollMode = computed(() => props.zoomMode === "scroll");
+// Inline touch gestures (one-finger pan, pinch) go to the map instead of
+// the page: always in scroll mode, and — with tap-to-expand opted out —
+// once the first tap has activated the interaction.
+const touchGesturesInline = computed(
+  () =>
+    props.zoom &&
+    (isScrollMode.value || (!props.touchExpand && isActivated.value)),
+);
 // rAF-throttled cursor coords for moveTooltip; we coalesce many mousemove
 // events into one transform write per animation frame.
 let pendingMoveX = 0;
@@ -386,18 +457,26 @@ let tapStart: {
   featId: string | null;
 } | null = null;
 
+// Desktop click-vs-double-click: with the zoom interaction on, a click can
+// be the first half of a double-click zoom, so selection defers by a
+// double-click-sized window and the second click cancels it.
+const CLICK_SELECT_DELAY_MS = 250;
+let pendingSelectTimer = 0;
+
 function setupInteraction() {
+  const svg = svgRef.value;
   const g = mapGroupRef.value;
-  if (!g) return;
-  // Tap-to-select is wired on every device. `touchend` is non-passive so a
-  // confirmed tap can preventDefault and suppress the compatibility
-  // click/hover the browser would otherwise synthesize (the double-fire and
-  // iOS first-tap-hover sources).
-  g.addEventListener("touchstart", onTouchStart, { passive: true });
-  g.addEventListener("touchend", onTouchEnd);
-  g.addEventListener("touchcancel", onTouchCancel, { passive: true });
+  if (!svg || !g) return;
+  // Tap handling is wired on every device, on the svg itself so taps on the
+  // map background (not just feature paths) can expand the touch map.
+  // `touchend` is non-passive so a confirmed tap can preventDefault and
+  // suppress the compatibility click/hover the browser would otherwise
+  // synthesize (the double-fire and iOS first-tap-hover sources).
+  svg.addEventListener("touchstart", onTouchStart, { passive: true });
+  svg.addEventListener("touchend", onTouchEnd);
+  svg.addEventListener("touchcancel", onTouchCancel, { passive: true });
   // Hover + tooltip stay off on touch (stroke-width churn degrades zoom/pan).
-  if (isTouchDevice) return;
+  if (isTouchDevice()) return;
   g.addEventListener("click", onDelegatedEvent);
   g.addEventListener("mouseover", onDelegatedEvent);
   g.addEventListener("mousemove", onDelegatedMouseMove);
@@ -405,11 +484,14 @@ function setupInteraction() {
 }
 
 function teardownInteraction() {
+  const svg = svgRef.value;
   const g = mapGroupRef.value;
+  if (svg) {
+    svg.removeEventListener("touchstart", onTouchStart);
+    svg.removeEventListener("touchend", onTouchEnd);
+    svg.removeEventListener("touchcancel", onTouchCancel);
+  }
   if (!g) return;
-  g.removeEventListener("touchstart", onTouchStart);
-  g.removeEventListener("touchend", onTouchEnd);
-  g.removeEventListener("touchcancel", onTouchCancel);
   g.removeEventListener("click", onDelegatedEvent);
   g.removeEventListener("mouseover", onDelegatedEvent);
   g.removeEventListener("mousemove", onDelegatedMouseMove);
@@ -423,12 +505,26 @@ function dismissOnViewportChange() {
   clearHover();
 }
 
+// Tracks the svg's rendered width so applyStrokeScale can compensate
+// stroke widths for the viewBox-to-CSS scale. Fires on container resizes
+// only — cheap, and the map itself never relayouts on zoom/pan.
+let svgResizeObserver: ResizeObserver | null = null;
+
 onMounted(() => {
   setupZoom();
   setupInteraction();
   rebuildPaths();
   applyFocus();
   attachTooltipObserver();
+  if (svgRef.value && typeof ResizeObserver !== "undefined") {
+    svgResizeObserver = new ResizeObserver((entries) => {
+      const w = entries[0]?.contentRect.width;
+      if (!w) return;
+      viewScale.value = w / CANONICAL_WIDTH;
+      applyStrokeScale();
+    });
+    svgResizeObserver.observe(svgRef.value);
+  }
   window.addEventListener("scroll", dismissOnViewportChange, {
     passive: true,
     capture: true,
@@ -438,7 +534,9 @@ onMounted(() => {
 
 onUnmounted(() => {
   tooltipObserver?.disconnect();
+  svgResizeObserver?.disconnect();
   if (pendingMoveFrame) cancelAnimationFrame(pendingMoveFrame);
+  window.clearTimeout(pendingSelectTimer);
   teardownZoom();
   teardownInteraction();
   window.removeEventListener("scroll", dismissOnViewportChange, {
@@ -451,12 +549,8 @@ function setupZoom() {
   if (!svgRef.value || !mapGroupRef.value) return;
 
   const svg = select(svgRef.value);
-  // Always span focusZoomLevel and at least the standard 12× ceiling so the
-  // user can wheel further in/out of a focused view. Programmatic
-  // `.transform()` calls are clamped to this range too.
-  const maxScale = Math.max(12, props.focusZoomLevel);
   zoomBehavior = d3Zoom<SVGSVGElement, unknown>()
-    .scaleExtent([1, maxScale])
+    .scaleExtent([1, maxScale.value])
     .on("start", () => {
       isZooming = true;
       clearHover();
@@ -466,41 +560,47 @@ function setupZoom() {
         mapGroupRef.value.setAttribute("transform", event.transform);
       }
       const t = event.transform;
+      scaleK.value = t.k;
+      applyStrokeScale();
       isZoomed.value = t.k !== 1 || t.x !== 0 || t.y !== 0;
+      if (isZoomed.value) hasZoomed.value = true;
     })
     .on("end", () => {
       isZooming = false;
     });
 
-  // Dynamic filter: re-evaluated per event, so toggling `focus`,
-  // `zoom`, or `pan` doesn't require tearing down the zoom behavior.
-  // When focus is active we always allow drag + wheel so users can
-  // explore away from the focused area regardless of `zoom`/`pan` — but
-  // not in highlight-only mode (`focusZoom=false`), where focus is purely
-  // visual and shouldn't grant interaction the props didn't ask for.
-  // Programmatic `.transform()` calls bypass this filter entirely.
+  // Dynamic filter deciding which pointer gestures d3-zoom may handle —
+  // re-evaluated per event, so mode/activation changes never require
+  // tearing down the zoom behavior. Programmatic `.transform()` calls
+  // (focus zoom, the +/− controls, reset) bypass it entirely. Scroll mode
+  // skips every gate; otherwise, per gesture:
+  //  - wheel: only while the map fills the window (body scroll is locked
+  //    there, so there's no page scroll to hijack);
+  //  - dblclick: desktop's activation + zoom-in gesture (touch uses taps);
+  //  - mousedown (drag-pan): once activated or while filling the window;
+  //  - touchstart (pan/pinch): while filling the window, or inline once
+  //    `touchGesturesInline` says the map owns touch gestures.
   zoomBehavior.filter((event) => {
-    const focused =
-      normalizedFocus.value.length > 0 && props.focusZoom !== false;
-    const allowZoom = !!props.zoom || focused;
-    const allowPan = !!props.pan || focused;
-    if (event.type === "wheel" || event.type === "dblclick") {
-      if (!allowZoom) return false;
-    } else if (event.type === "mousedown" || event.type === "touchstart") {
-      if (!allowPan) return false;
-      // Two-finger-only mode: ignore single-finger touches so the page can
-      // scroll; a second finger drives the map (pan + pinch-zoom).
-      if (
-        props.twoFingerPan &&
-        event.type === "touchstart" &&
-        (event as TouchEvent).touches.length < 2
-      ) {
-        return false;
+    if (!props.zoom) return false;
+    if (!isScrollMode.value) {
+      const expanded = fullscreen.isFullscreen.value;
+      switch (event.type) {
+        case "wheel":
+          if (!expanded) return false;
+          break;
+        case "dblclick":
+          if (isTouchDevice()) return false;
+          break;
+        case "mousedown":
+          if (!expanded && !isActivated.value) return false;
+          break;
+        case "touchstart":
+          if (!expanded && !touchGesturesInline.value) return false;
+          break;
       }
-    } else if (!allowZoom && !allowPan) {
-      return false;
     }
-    // Mirror d3-zoom's default rejections (ctrl-click, non-primary buttons).
+    // Mirror d3-zoom's default rejections (ctrl-click, non-primary
+    // buttons); ctrl+wheel is trackpad pinch, so it stays allowed.
     return (!event.ctrlKey || event.type === "wheel") && !event.button;
   });
 
@@ -556,7 +656,7 @@ function focusedBaseIds(items: FocusItem[]): Set<string> {
 
 // Duration (ms) of focus zoom-in and Reset-button zoom-out transitions.
 // Initial mount applies instantly; clearing focus is a no-op on the
-// transform (the Reset button is the only path back to identity).
+// transform (the reset button is the only path back to identity).
 const FOCUS_ANIM_MS = 450;
 // Tracks whether applyFocus has been called once — initial mount apply
 // is instant, subsequent focus-in calls animate.
@@ -573,29 +673,34 @@ function applyFocus() {
 
   // Diff base-geoType highlights, keyed by path element so we can
   // restyle on style change without churning unrelated paths.
-  const nextBaseStyles = new Map<SVGPathElement, FocusStyle>();
+  const nextBaseStyles = new Map<SVGPathElement, FocusItem>();
   for (const r of baseResolved) {
     const p = pathsByFeatureId.get(String(r.feature.id));
-    if (p) nextBaseStyles.set(p, r.item.style ?? "solid");
+    if (p) nextBaseStyles.set(p, r.item);
   }
   for (const [p] of focusedPathStyles) {
     if (nextBaseStyles.has(p) || p === hoveredEl) continue;
     restoreDefaultStroke(p);
   }
-  for (const [p, style] of nextBaseStyles) {
+  for (const [p, item] of nextBaseStyles) {
     const prev = focusedPathStyles.get(p);
-    if (prev === style && p !== hoveredEl) continue; // already styled
-    if (p !== hoveredEl) applyHighlightStroke(p, style);
+    const unchanged =
+      prev != null &&
+      prev.style === item.style &&
+      prev.stroke === item.stroke &&
+      prev.strokeWidth === item.strokeWidth;
+    if (unchanged && p !== hoveredEl) continue; // already styled
+    if (p !== hoveredEl) applyHighlightStroke(p, item);
   }
   focusedPathStyles.clear();
-  for (const [p, style] of nextBaseStyles) focusedPathStyles.set(p, style);
+  for (const [p, item] of nextBaseStyles) focusedPathStyles.set(p, item);
 
   // Cross-geoType outlines render as non-interactive paths on top of
   // the base layer.
   syncOverlayPaths(overlayResolved);
 
   // Clearing focus doesn't touch the zoom transform — the user keeps
-  // whatever pan/zoom they had. Only the Reset button snaps back to
+  // whatever pan/zoom they had. Only the reset button snaps back to
   // identity. Drop the highlight + tooltip and we're done.
   if (resolved.length === 0) {
     focusApplied = true;
@@ -674,38 +779,40 @@ function syncOverlayPaths(items: ResolvedFocus[]) {
   if (!g) return;
 
   const nextKeys = new Set(items.map((i) => i.key));
-  for (const [key, el] of overlayPathEls) {
+  for (const [key, entry] of overlayPathEls) {
     if (!nextKeys.has(key)) {
-      el.remove();
+      entry.el.remove();
       overlayPathEls.delete(key);
     }
   }
 
   const generator = pathGenerator.value;
-  // Overlay strokes need extra weight: they paint on top of the base
-  // map and the (optional) state-borders mesh, so a stroke that matches
-  // the in-place focused base path's weight would visually merge with
-  // the layers underneath.
-  const sw = effectiveStrokeWidth.value + 1.5;
+  // Overlay strokes need extra weight: they paint on top of the base map
+  // and the (optional) state-borders mesh, so a stroke that matches the
+  // in-place focused base path's weight would visually merge with the
+  // layers underneath. The default width lives on the overlay *group*;
+  // per-item `strokeWidth` overrides are written per path — both
+  // compensated by applyStrokeScale.
   for (const { item, feature: f, key } of items) {
-    let el = overlayPathEls.get(key);
-    if (!el) {
-      el = document.createElementNS(SVG_NS, "path") as SVGPathElement;
+    let entry = overlayPathEls.get(key);
+    if (!entry) {
+      const el = document.createElementNS(SVG_NS, "path") as SVGPathElement;
       el.setAttribute("d", generator(f) ?? "");
       el.setAttribute("fill", "none");
       el.setAttribute("pointer-events", "none");
-      el.setAttribute("vector-effect", "non-scaling-stroke");
       el.setAttribute("stroke-linejoin", "round");
       el.setAttribute("class", "focus-overlay");
       g.appendChild(el);
-      overlayPathEls.set(key, el);
+      entry = { el };
+      overlayPathEls.set(key, entry);
     }
+    entry.strokeWidth = item.strokeWidth;
     // White contrasts cleanly against the (typically dark) data-colored
     // fill; callers can override per-item via `FocusItem.stroke`.
-    el.setAttribute("stroke", item.stroke ?? "#fff");
-    el.setAttribute("stroke-width", String(sw));
-    applyDasharray(el, item.style);
+    entry.el.setAttribute("stroke", item.stroke ?? "#fff");
+    applyDasharray(entry.el, item.style);
   }
+  applyStrokeScale();
 }
 
 function resetZoom() {
@@ -717,20 +824,165 @@ function resetZoom() {
   const svg = select(svgRef.value);
   svg.interrupt();
   hideTooltip();
-  svg
+  // In the inline touch flow (no tap-to-expand step), reset restores the
+  // pre-tap mode: once the zoom-out lands, deactivate so the page gets
+  // touch scrolling back and the tap hint returns. Desktop stays
+  // activated (sticky), and inside fullscreen the ✕ handles leaving.
+  const deactivate =
+    isTouchDevice() && !fullscreen.isFullscreen.value && !isScrollMode.value;
+  const transition = svg
     .transition()
     .duration(FOCUS_ANIM_MS)
     .call(zoomBehavior.transform, zoomIdentity);
+  if (deactivate) {
+    transition.on("end", () => {
+      hasZoomed.value = false;
+      hasInteracted.value = false;
+    });
+  }
+}
+
+// Ceiling always spans focusZoomLevel and at least the standard 12× so the
+// user can zoom further in/out of a focused view. Programmatic
+// `.transform()` calls are clamped to this range too.
+const maxScale = computed(() => Math.max(12, props.focusZoomLevel));
+
+// Scale factor per +/− press and per desktop double-click (d3's built-in).
+const ZOOM_STEP = 2;
+
+// The +/−/reset controls — only ever shown while zooming is enabled. On
+// desktop they're always present (pressing + is itself an activation
+// path). On touch they render inline only when the inline map is (or can
+// become) interactive (scroll mode / in-place tap zoom), plus always in
+// the expanded view. With `zoom: false` the map never shows them; a
+// parent driving `focus` owns its own way back.
+const showZoomControls = computed(
+  () =>
+    props.zoom &&
+    (isTouchDevice()
+      ? fullscreen.isFullscreen.value ||
+        isScrollMode.value ||
+        !props.touchExpand
+      : true),
+);
+
+// Drag-pan cursor affordance — desktop only, once drag-pan is available.
+const isPannable = computed(
+  () =>
+    props.zoom &&
+    !isTouchDevice() &&
+    (isScrollMode.value || isActivated.value || fullscreen.isFullscreen.value),
+);
+
+// Grey affordance line shown while the activation gesture is still the way
+// in: on desktop until activation (the controls take over from there), on
+// touch whenever the inline map is showing (with tap-to-expand) or until
+// the first in-place tap zoom (without). Never while fullscreen or in
+// scroll mode — those are already interactive.
+const showZoomHint = computed(
+  () =>
+    props.zoom &&
+    props.zoomHint &&
+    !isScrollMode.value &&
+    !fullscreen.isFullscreen.value &&
+    ((isTouchDevice() && props.touchExpand) || !isActivated.value),
+);
+const zoomHintText = computed(() =>
+  isTouchDevice() ? "Tap to zoom" : "Double click to zoom",
+);
+
+// Inline style for the map svg. `touch-action: none` hands pan/pinch to
+// d3-zoom (and blocks scroll chaining) wherever touch gestures belong to
+// the map. `will-change: transform` gives the svg its own compositor
+// layer while the interaction is live — without it WebKit repaints the
+// surrounding page layer on every zoom/pan frame (~10× slower on iOS).
+// Scoped to active maps so a page of static maps doesn't pay a raster
+// layer apiece.
+const svgStyle = computed(() => {
+  const style: Record<string, string> = {};
+  if (fullscreen.isFullscreen.value || touchGesturesInline.value) {
+    style["touch-action"] = "none";
+  }
+  if (
+    isActivated.value ||
+    fullscreen.isFullscreen.value ||
+    (props.zoom && isScrollMode.value)
+  ) {
+    style["will-change"] = "transform";
+  }
+  return Object.keys(style).length ? style : undefined;
+});
+
+function zoomBy(factor: number) {
+  if (!svgRef.value || !zoomBehavior) return;
+  const svg = select(svgRef.value);
+  svg.interrupt();
+  hideTooltip();
+  // scaleBy centers on the viewBox extent's midpoint; scaleExtent clamps.
+  svg.transition().duration(250).call(zoomBehavior.scaleBy, factor);
+}
+
+// Zoom level a tap zooms to (expanding or in place).
+const TAP_ZOOM_SCALE = 2;
+
+// Target transform for a tap: TAP_ZOOM_SCALE× centered on the tapped
+// point. Falls back to the map center when the CTM is unavailable (jsdom).
+function tapZoomTransform(clientX: number, clientY: number): ZoomTransform {
+  const svgEl = svgRef.value!;
+  const k = TAP_ZOOM_SCALE;
+  let mx = width.value / 2;
+  let my = height.value / 2;
+  let ctm: DOMMatrix | null = null;
+  try {
+    ctm = svgEl.getScreenCTM();
+  } catch {
+    ctm = null;
+  }
+  if (ctm) {
+    // client → viewBox coords (the svg CTM covers viewBox scaling and
+    // letterboxing), then unwind the current zoom transform.
+    const inv = ctm.inverse();
+    const px = inv.a * clientX + inv.c * clientY + inv.e;
+    const py = inv.b * clientX + inv.d * clientY + inv.f;
+    [mx, my] = zoomTransform(svgEl).invert([px, py]);
+  }
+  return zoomIdentity
+    .translate(width.value / 2 - k * mx, height.value / 2 - k * my)
+    .scale(k);
+}
+
+function animateZoomTo(target: ZoomTransform) {
+  if (!svgRef.value || !zoomBehavior) return;
+  const svg = select(svgRef.value);
+  svg.interrupt();
+  svg.transition().duration(FOCUS_ANIM_MS).call(zoomBehavior.transform, target);
+}
+
+// Tap on the inline touch map: expand to fill the window, then zoom in
+// centered on the tapped point once the expanded layout has committed.
+function enterTouchZoom(clientX: number, clientY: number) {
+  if (!svgRef.value || !zoomBehavior) return;
+  // Resolve the tapped point to map coords before the layout changes.
+  const target = tapZoomTransform(clientX, clientY);
+  fullscreen.enter();
+  nextTick(() => animateZoomTo(target));
+}
+
+// `touchExpand: false`: the first tap zooms the inline map in place
+// instead of expanding it (the touch analogue of desktop double-click).
+function zoomInPlaceAt(clientX: number, clientY: number) {
+  if (!svgRef.value || !zoomBehavior) return;
+  animateZoomTo(tapZoomTransform(clientX, clientY));
 }
 
 // `focusZoomLevel` only affects scaleExtent + the next focus apply. The
-// d3-zoom filter reads `props.zoom` / `props.pan` dynamically, so we don't
-// need to tear down zoom on those changes.
+// d3-zoom filter reads `props.zoom` and the activation state dynamically,
+// so we don't need to tear down zoom on those changes.
 watch(
   () => props.focusZoomLevel,
   () => {
     if (zoomBehavior) {
-      zoomBehavior.scaleExtent([1, Math.max(12, props.focusZoomLevel)]);
+      zoomBehavior.scaleExtent([1, maxScale.value]);
     }
     applyFocus();
   },
@@ -1118,18 +1370,10 @@ const maxColor = computed(() =>
     : "",
 );
 
-function parseHex(hex: string): [number, number, number] {
-  const h = hex.replace("#", "");
-  return [
-    parseInt(h.slice(0, 2), 16),
-    parseInt(h.slice(2, 4), 16),
-    parseInt(h.slice(4, 6), 16),
-  ];
-}
-
+// Unresolvable endpoint colors fall back to the default scale endpoints.
 function interpolateColor(t: number): string {
-  const [r1, g1, b1] = parseHex(minColor.value);
-  const [r2, g2, b2] = parseHex(maxColor.value);
+  const [r1, g1, b1] = resolveColorToRgb(minColor.value) ?? [229, 240, 250];
+  const [r2, g2, b2] = resolveColorToRgb(maxColor.value) ?? [8, 81, 156];
   const r = Math.round(r1 + (r2 - r1) * t);
   const g = Math.round(g1 + (g2 - g1) * t);
   const b = Math.round(b1 + (b2 - b1) * t);
@@ -1309,21 +1553,70 @@ function applyDasharray(el: SVGPathElement, style?: FocusStyle) {
   }
 }
 
-function applyHighlightStroke(
-  pathEl: SVGPathElement,
-  style: FocusStyle = "solid",
-) {
+// ─── Stroke-width compensation (no `vector-effect`) ──────────────────────
+//
+// WebKit renders `vector-effect: non-scaling-stroke` across thousands of
+// paths dramatically slowly (the docs page dropped to ~3fps on iOS), so
+// visual stroke widths are compensated by hand instead: a width of `w`
+// CSS px is written as `w / (zoom scale × viewBox-to-CSS scale)`. Base
+// feature paths inherit one group-level width; only the borders mesh,
+// focus overlays (via their group), and highlighted paths carry their own.
+
+/** Divisor turning a visual CSS-px width into an attribute width. */
+function strokeDivisor(): number {
+  return scaleK.value * viewScale.value || 1;
+}
+
+// Highlight (hover + focus) outline color: pure black on light, pure
+// white on dark, following the theme's color-scheme (the same
+// light-dark() mechanism the theme tokens use). Applied via inline style
+// — SVG presentation attributes don't parse CSS functions.
+const HIGHLIGHT_STROKE = "light-dark(#000, #fff)";
+
+/** Visual outline width for an in-place highlight (hover or focus). */
+function highlightWidthFor(item?: FocusItem): number {
+  return item?.strokeWidth ?? effectiveStrokeWidth.value + 1;
+}
+
+function applyStrokeScale() {
+  const d = strokeDivisor();
+  const eff = effectiveStrokeWidth.value;
+  baseGroupRef.value?.setAttribute("stroke-width", String(eff / d));
+  bordersPathEl?.setAttribute("stroke-width", String(1 / d));
+  overlayGroupRef.value?.setAttribute("stroke-width", String((eff + 1.5) / d));
+  for (const { el, strokeWidth } of overlayPathEls.values()) {
+    if (strokeWidth != null) {
+      el.setAttribute("stroke-width", String(strokeWidth / d));
+    } else {
+      el.removeAttribute("stroke-width");
+    }
+  }
+  for (const [p, item] of focusedPathStyles) {
+    p.setAttribute("stroke-width", String(highlightWidthFor(item) / d));
+  }
+  if (hoveredEl && !focusedPathStyles.has(hoveredEl)) {
+    hoveredEl.setAttribute("stroke-width", String(highlightWidthFor() / d));
+  }
+}
+
+function applyHighlightStroke(pathEl: SVGPathElement, item?: FocusItem) {
   // Bring path to top so its thicker border isn't clipped by neighbors.
   // Skip for overlay paths (they live above everything and own their
   // own z-order via syncOverlayPaths).
   pathEl.parentNode?.appendChild(pathEl);
-  pathEl.setAttribute("stroke-width", String(effectiveStrokeWidth.value + 1));
-  pathEl.setAttribute("stroke", "#555");
-  applyDasharray(pathEl, style);
+  pathEl.setAttribute(
+    "stroke-width",
+    String(highlightWidthFor(item) / strokeDivisor()),
+  );
+  pathEl.style.stroke = item?.stroke ?? HIGHLIGHT_STROKE;
+  applyDasharray(pathEl, item?.style);
 }
 
 function restoreDefaultStroke(pathEl: SVGPathElement) {
-  pathEl.setAttribute("stroke-width", String(effectiveStrokeWidth.value));
+  // Dropping the attribute lets the path inherit the compensated width
+  // from the base group again.
+  pathEl.removeAttribute("stroke-width");
+  pathEl.style.stroke = "";
   pathEl.setAttribute("stroke", props.strokeColor);
   pathEl.removeAttribute("stroke-dasharray");
   pathEl.removeAttribute("stroke-linecap");
@@ -1337,18 +1630,20 @@ function setHover(pathEl: SVGPathElement) {
     restoreDefaultStroke(hoveredEl);
   }
   hoveredEl = pathEl;
-  // Hover style follows whatever focus style is in effect (or solid).
-  applyHighlightStroke(pathEl, focusedPathStyles.get(pathEl) ?? "solid");
+  // Hover styling follows whatever focus styling is in effect (or the
+  // defaults).
+  applyHighlightStroke(pathEl, focusedPathStyles.get(pathEl));
 }
 
 function clearHover() {
   if (hoveredEl) {
-    const focusStyle = focusedPathStyles.get(hoveredEl);
-    if (focusStyle == null) {
+    const focusItem = focusedPathStyles.get(hoveredEl);
+    if (focusItem == null) {
       restoreDefaultStroke(hoveredEl);
     } else {
-      // Restore the focused style (in case hover overwrote a dashed item).
-      applyHighlightStroke(hoveredEl, focusStyle);
+      // Restore the focused styling (in case hover overwrote a dashed
+      // or custom-styled item).
+      applyHighlightStroke(hoveredEl, focusItem);
     }
     hoveredEl = null;
     emit("stateHover", null);
@@ -1371,6 +1666,9 @@ function eventToFeatureId(target: EventTarget | null): string | null {
 // wanting fine-grained multi-select handle merging via `@update:focus`.
 // Shared by the mouse-click and touch-tap paths.
 function emitSelection(data: TooltipPayload) {
+  // Selecting a feature counts as engaging with the map — it switches the
+  // pan/zoom interaction on, same as a first zoom would.
+  if (props.zoom) hasInteracted.value = true;
   emit("stateClick", { id: data.id, name: data.name, value: data.value });
   const wasFocused = focusedBaseIds(normalizedFocus.value).has(data.id);
   emit("update:focus", wasFocused ? null : data.id);
@@ -1385,7 +1683,20 @@ function onDelegatedEvent(event: Event) {
   if (!data) return;
   const payload = { id: data.id, name: data.name, value: data.value };
   if (event.type === "click") {
-    emitSelection(data);
+    if (props.zoom) {
+      window.clearTimeout(pendingSelectTimer);
+      pendingSelectTimer = 0;
+      // detail > 1 is the second click of a double-click — that gesture is
+      // a zoom (handled by d3), not a select.
+      if (me.detail <= 1) {
+        pendingSelectTimer = window.setTimeout(() => {
+          pendingSelectTimer = 0;
+          emitSelection(data);
+        }, CLICK_SELECT_DELAY_MS);
+      }
+    } else {
+      emitSelection(data);
+    }
   } else if (event.type === "mouseover") {
     setHover(pathsByFeatureId.get(featId)!);
     if (hasInteractiveTooltip.value)
@@ -1423,14 +1734,38 @@ function onTouchStart(event: TouchEvent) {
 function onTouchEnd(event: TouchEvent) {
   const start = tapStart;
   tapStart = null;
-  // No feature under the initial touch, or a second finger joined in.
-  if (!start || !start.featId || event.touches.length > 0) return;
+  // A second finger joined in — that's a pinch, not a tap.
+  if (!start || event.touches.length > 0) return;
   const t = event.changedTouches[0];
   if (!t) return;
   // Moved too far (a pan) or held too long (a long-press) → not a tap.
   if (Math.abs(t.clientX - start.x) > TAP_SLOP) return;
   if (Math.abs(t.clientY - start.y) > TAP_SLOP) return;
   if (event.timeStamp - start.time > TAP_MAX_MS) return;
+  // Inline touch map with zoom on (activate mode): a tap anywhere
+  // (features and background alike) starts the interaction — expanding to
+  // fill the window by default, or zooming in place with
+  // `touchExpand: false`, after which taps fall through to selection.
+  // Scroll mode skips all of this: the inline map is already the
+  // interactive surface.
+  if (
+    props.zoom &&
+    !isScrollMode.value &&
+    isTouchDevice() &&
+    !fullscreen.isFullscreen.value
+  ) {
+    if (props.touchExpand) {
+      event.preventDefault();
+      enterTouchZoom(t.clientX, t.clientY);
+      return;
+    }
+    if (!isActivated.value) {
+      event.preventDefault();
+      zoomInPlaceAt(t.clientX, t.clientY);
+      return;
+    }
+  }
+  if (!start.featId) return;
   const data = tooltipDataById.get(start.featId);
   if (!data) return;
   // Suppress the synthetic click/hover the browser would replay from this
@@ -1476,11 +1811,17 @@ function rebuildPaths() {
 
   const path = pathGenerator.value;
   const features = featuresGeo.value.features;
+  // No features (e.g. geoType="hsas" before the lazy HSA module resolves)
+  // means the projection was fitted to an empty collection and yields NaN
+  // coordinates — skip drawing entirely, including the state-borders mesh,
+  // until real features arrive and re-trigger a rebuild.
+  if (features.length === 0) return;
   const stroke = props.strokeColor;
-  const sw = String(effectiveStrokeWidth.value);
   const wantsTitleFallback = !hasInteractiveTooltip.value;
 
   // Single DocumentFragment append → one layout flush for the whole batch.
+  // Feature paths carry no stroke-width of their own — they inherit the
+  // compensated group-level width from applyStrokeScale.
   const frag = document.createDocumentFragment();
   for (const feat of features) {
     const id = String(feat.id);
@@ -1491,11 +1832,6 @@ function rebuildPaths() {
     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);
@@ -1517,14 +1853,13 @@ function rebuildPaths() {
     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;
   }
   baseG.appendChild(frag);
+  applyStrokeScale();
 }
 
 function updateFills() {
@@ -1552,6 +1887,8 @@ function updateStrokes() {
     restoreDefaultStroke(p);
   }
   if (bordersPathEl) bordersPathEl.setAttribute("stroke", props.strokeColor);
+  // Group-level widths track effectiveStrokeWidth.
+  applyStrokeScale();
 }
 
 function menuFilename() {
@@ -1702,6 +2039,20 @@ watch(
   () => applyFocus(),
   { flush: "post" },
 );
+
+// Exiting the expanded touch view (✕, Escape) returns to the static inline
+// map at full extent — the inline map has no pan gestures, so a preserved
+// transform would strand the user off-center.
+watch(
+  () => fullscreen.isFullscreen.value,
+  (expanded) => {
+    if (expanded || !isTouchDevice()) return;
+    if (!svgRef.value || !zoomBehavior) return;
+    const svg = select(svgRef.value);
+    svg.interrupt();
+    zoomBehavior.transform(svg, zoomIdentity);
+  },
+);
 </script>
 
 <template>
@@ -1714,14 +2065,19 @@ watch(
       v-bind="$attrs"
       :class="[
         'choropleth-wrapper',
-        { pannable: pan, 'is-fullscreen': fullscreen.isFullscreen.value },
+        {
+          pannable: isPannable,
+          'is-fullscreen': fullscreen.isFullscreen.value,
+        },
       ]"
       :style="fullscreen.fullscreenStyle.value"
       :role="chartRole || undefined"
       :aria-label="chartAriaLabel || undefined"
     >
+      <!-- Rendered while expanded even with `menu` off — the ✕ close
+      button it swaps to is the way back from the tap-to-expand view. -->
       <ChartMenu
-        v-if="menu"
+        v-if="menu || fullscreen.isFullscreen.value"
         :items="menuItems"
         :is-fullscreen="fullscreen.isFullscreen.value"
         @close="fullscreen.exit"
@@ -1776,11 +2132,14 @@ watch(
           </div>
         </div>
       </div>
+      <div v-if="showZoomHint" class="choropleth-zoom-hint">
+        {{ zoomHintText }}
+      </div>
       <svg
         ref="svgRef"
         :viewBox="`0 0 ${width} ${height}`"
         preserveAspectRatio="xMidYMid meet"
-        :style="twoFingerPan ? { touchAction: 'pan-y' } : undefined"
+        :style="svgStyle"
       >
         <!--
         Path elements are created imperatively in `rebuildPaths()`; Vue never
@@ -1796,15 +2155,16 @@ watch(
           <g ref="overlayGroupRef" />
         </g>
       </svg>
-      <button
-        v-if="isZoomed"
-        type="button"
-        class="choropleth-reset"
-        aria-label="Reset zoom"
-        @click="resetZoom"
-      >
-        Reset
-      </button>
+      <ChartZoomControls
+        v-if="showZoomControls"
+        :can-zoom-in="scaleK < maxScale"
+        :can-zoom-out="scaleK > 1"
+        :can-reset="isZoomed"
+        :is-fullscreen="fullscreen.isFullscreen.value"
+        @zoom-in="zoomBy(ZOOM_STEP)"
+        @zoom-out="zoomBy(1 / ZOOM_STEP)"
+        @reset="resetZoom"
+      />
       <ChoroplethTooltip v-if="hasInteractiveTooltip" ref="tooltipChildRef">
         <template #default="raw">
           <slot name="tooltip" v-bind="narrowSlotProps(raw)">
@@ -1864,24 +2224,20 @@ watch(
   cursor: pointer;
 }
 
-.choropleth-reset {
+/* Overlays the top of the map: absolutely positioned with no `top`, the
+   box keeps its static position — the top edge of the svg that follows it
+   in the markup — without taking up flow space. */
+.choropleth-zoom-hint {
   position: absolute;
-  bottom: 8px;
-  left: 8px;
-  padding: 4px 10px;
-  font: inherit;
+  left: 0;
+  right: 0;
+  padding-top: 6px;
+  text-align: center;
   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);
+  line-height: 1.4;
+  color: var(--color-text-secondary, #777);
+  opacity: 0.6;
+  pointer-events: none;
 }
 
 /*
@@ -1925,6 +2281,17 @@ watch(
   font-weight: 600;
 }
 
+/* Continuous legend: the tick labels under the gradient unbalance the
+   row's vertical centering, so anchor items to the top and line the title
+   up with the gradient bar itself (line-height matches its 12px height). */
+.choropleth-legend:has(.choropleth-legend-continuous) {
+  align-items: flex-start;
+}
+
+.choropleth-legend:has(.choropleth-legend-continuous) .choropleth-legend-title {
+  line-height: 12px;
+}
+
 .choropleth-legend-item {
   display: inline-flex;
   align-items: center;