@cfasim-ui/docs 0.7.0 → 0.7.2

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -263,36 +263,39 @@ exploration (see the state-map pattern below); a parent driving `focus`
 provides its own way back (e.g. a "Back" button that clears the focus).
 
 Add the `zoom` prop to enable the interaction. The map is then **static
-until activated** — the scroll wheel never zooms inline, so the map can't
-hijack page scrolling. A grey hint overlaid on the top of the map ("Double
-click to zoom" / "Tap to zoom") advertises the gesture until it's been
-used; pass `:zoom-hint="false"` to hide it.
+until the first zoom** — clicks and taps only ever select; it's the first
+zoom gesture that switches panning on. The scroll wheel never zooms
+inline, so the map can't hijack page scrolling. A grey hint overlaid on
+the top of the map ("Double click to zoom" / "Double tap to zoom")
+advertises the gesture until it's been used; pass `:zoom-hint="false"` to
+hide it.
 
 - **Desktop:** double-click zooms in place (shift+double-click zooms out),
   or press **+** in the always-present **+ / − / reset** control stack in
-  the top-left corner. Any of these — or clicking a feature — starts the
-  pan/zoom mode; from then on, drag pans the map. The reset button (a
-  counterclockwise arrow) animates back to the full extent (clearing any
-  `focus`); − and reset are disabled while the map is at its full extent.
-- **Touch:** a tap expands the map to fill the window, zoomed in on the
-  tapped point. Inside, one finger pans, a pinch zooms, and a tap selects a
-  feature; the +/−/reset controls sit top-left and a close (✕) button
-  top-right returns to the inline map at full extent. The inline map ignores
-  touch gestures entirely, so the page always scrolls freely.
+  the top-left corner. The first zoom — including a programmatic `focus`
+  zoom — starts the pan/zoom mode; from then on, drag pans the map. The
+  reset button (a counterclockwise arrow) animates back to the full extent
+  (clearing any `focus`); − and reset are disabled while the map is at its
+  full extent.
+- **Touch:** a **double tap** expands the map to fill the window, zoomed
+  in on the tapped point; single taps select features inline. Inside the
+  expanded view, one finger pans, a pinch zooms, and a tap selects; the
+  +/−/reset controls sit top-left and a close (✕) button top-right returns
+  to the inline map at full extent. A single finger over the inline map
+  still scrolls the page.
 
 Filling the window is always an activated state: whether entered via the
-menu's **Fullscreen** item or a tap, pan/zoom works immediately and the
-controls are present — no double-click needed first. The scroll wheel (and
-trackpad pinch) zooms there too, since page scrolling is locked while the
-map fills the window.
-
-Prefer in-place zooming on touch? Set `:touch-expand="false"` — the first
-tap zooms the inline map in on the tapped point (the touch analogue of a
-desktop double-click) instead of expanding it. From there one finger pans,
-a pinch zooms, and taps select; the +/−/reset controls render inline, and
-reset restores the original static, page-scrollable state. Fullscreen is
-unaffected: that view stays continuously interactive and its reset only
-recenters.
+menu's **Fullscreen** item or a double tap, pan/zoom works immediately and
+the controls are present — no double-click needed first. The scroll wheel
+(and trackpad pinch) zooms there too, since page scrolling is locked while
+the map fills the window.
+
+Prefer in-place zooming on touch? Set `:touch-expand="false"` — a double
+tap (or a pinch) zooms the inline map on that point instead of expanding
+it. From there one finger pans, a pinch zooms, and taps keep selecting;
+the +/−/reset controls render inline, and reset restores the original
+static, page-scrollable state. Fullscreen is unaffected: that view stays
+continuously interactive and its reset only recenters.
 
 #### Full-page mode (`zoom-mode="scroll"`)
 
@@ -314,7 +317,7 @@ pans, and touch gestures work inline with no tap-to-expand step. The
 
 ### County-level map
 
-Set `geoType="counties"` to render county-level data using 5-digit FIPS codes. State borders are drawn on top for context. Double-click (or tap on touch) to explore — useful for dense county data.
+Set `geoType="counties"` to render county-level data using 5-digit FIPS codes. State borders are drawn on top for context. Double-click (or double-tap on touch) to explore — useful for dense county data.
 
 <ComponentDemo>
   <ChoroplethMap
@@ -420,8 +423,8 @@ can stay national; only features inside the selected state are drawn and
 colored.
 
 This demo also opts for the quieter touch flow: `:touch-expand="false"` makes
-a tap zoom in place instead of expanding to fill the window, and
-`:zoom-hint="false"` drops the grey gesture hint.
+a double tap (or pinch) zoom in place instead of expanding to fill the
+window, and `:zoom-hint="false"` drops the grey gesture hint.
 
 <ComponentDemo>
   <ChoroplethMap
@@ -482,18 +485,27 @@ shows that feature's tooltip. Users can keep exploring around the focused
 area; the built-in **reset** button clears focus and snaps back to the full
 extent.
 
+Each focus target's outline can be styled by passing a `FocusItem` object:
+`style` picks the dash pattern (`"solid" | "dashed" | "dotted"`), `stroke`
+the color, and `strokeWidth` the width in CSS px. In-place highlights
+default to pure black/white following the theme (`light-dark(#000, #fff)`);
+cross-geoType overlays default to white.
+
 Set `:focus-zoom="false"` to highlight (and draw cross-geoType overlays)
 **without** panning or zooming — useful for a click-to-select interaction
 where the map should stay put while a side panel shows the details.
 
-On touch, selection happens inside the tap-to-expand view: a single-finger
-**tap** on a feature there emits `stateClick` and toggles focus. (With
-`:zoom="false"` a tap selects directly on the inline map instead.) Hover
-tooltips stay off on touch for performance.
+Selection works the same on touch: a single-finger **tap** on a feature
+emits `stateClick` and toggles focus, inline or inside the expanded view.
+(Inline with `zoom` on, the selection fires after the brief double-tap
+window.) A tap also stands in for hover — it applies the hover highlight,
+emits `stateHover`, and shows the feature's tooltip at the tapped point;
+only continuous hover _tracking_ is off on touch, for performance.
 
 Click-to-focus interactions usually pair best with `:touch-expand="false"`,
-as in the demos below — the first tap zooms in place and the next tap
-selects, so the map stays in your layout instead of taking over the window.
+as in the demos below — a double tap zooms in place while taps keep
+selecting, so the map stays in your layout instead of taking over the
+window.
 
 Counties are tiny without a zoom — focus is a natural fit for drill-down.
 

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -90,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;
@@ -163,13 +167,13 @@ const props = withDefaults(
     /**
      * 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.
+     * programmatic `focus` zoom still applies). When enabled, clicks and
+     * taps still only select; the first *zoom* is what switches panning
+     * on: desktop double-click (or the always-visible +/−/reset controls,
+     * or a programmatic focus zoom) zooms in place, and on touch a double
+     * 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;
     /**
@@ -183,20 +187,21 @@ const props = withDefaults(
      */
     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
+     * On touch devices, expand the map to fill the window on a double
+     * tap. Default `true`. Set `false` to zoom in place instead: a double
+     * tap (or pinch) zooms the inline map on that point, after which
+     * one-finger pan / pinch work and the +/−/reset controls render
+     * inline. Single taps select in both modes. Note the zoomed in-place
+     * 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.
+     * Show the grey "Double click to zoom" / "Double 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.
      */
     zoomHint?: boolean;
     /** Tooltip activation mode */
@@ -381,14 +386,18 @@ 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;
 let tooltipObserver: ResizeObserver | null = null;
 const lastTooltipSize = { width: 0, height: 0 };
@@ -406,27 +415,22 @@ const scaleK = ref(1);
 // 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).
+// The first *zoom* is what activates the pan/zoom interaction — plain
+// clicks/taps only select. Latched true the first time the transform
+// leaves identity (double-click, double-tap/pinch zoom, +/− press, or a
+// programmatic focus zoom) and sticky except in the inline touch flow,
+// where reset restores the pre-zoom static mode by clearing it.
 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.
+// Inline touch gestures (one-finger pan, pinch-to-continue) go to the map
+// instead of the page: always in scroll mode, and — with tap-to-expand
+// opted out — once the first zoom has activated the interaction.
 const touchGesturesInline = computed(
   () =>
     props.zoom &&
-    (isScrollMode.value || (!props.touchExpand && isActivated.value)),
+    (isScrollMode.value || (!props.touchExpand && hasZoomed.value)),
 );
 // rAF-throttled cursor coords for moveTooltip; we coalesce many mousemove
 // events into one transform write per animation frame.
@@ -449,12 +453,18 @@ 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.
+// Click/tap-vs-double: with the zoom interaction on, a click or tap can be
+// the first half of a double-click/double-tap zoom, so selection defers by
+// this window and the second click/tap cancels it.
 const CLICK_SELECT_DELAY_MS = 250;
 let pendingSelectTimer = 0;
 
+// Double-tap detection for the inline touch map (the zoom gesture there).
+// Two taps landing this close together within the select-defer window
+// count as one double tap.
+const DOUBLE_TAP_SLOP = 30;
+let lastTap: { x: number; y: number; time: number } | null = null;
+
 function setupInteraction() {
   const svg = svgRef.value;
   const g = mapGroupRef.value;
@@ -467,7 +477,9 @@ function setupInteraction() {
   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).
+  // Continuous hover tracking stays off on touch (stroke-width churn
+  // degrades zoom/pan); taps provide the one-shot hover + tooltip instead
+  // (see touchHover).
   if (isTouchDevice()) return;
   g.addEventListener("click", onDelegatedEvent);
   g.addEventListener("mouseover", onDelegatedEvent);
@@ -584,10 +596,19 @@ function setupZoom() {
           if (isTouchDevice()) return false;
           break;
         case "mousedown":
-          if (!expanded && !isActivated.value) return false;
+          if (!expanded && !hasZoomed.value) return false;
           break;
         case "touchstart":
-          if (!expanded && !touchGesturesInline.value) return false;
+          if (!expanded && !touchGesturesInline.value) {
+            // In-place touch mode: a pinch (second finger) is itself the
+            // zoom entry gesture; single-finger drags stay with the page
+            // until the first zoom.
+            const pinchEntry =
+              !props.touchExpand &&
+              props.zoomMode !== "scroll" &&
+              (event as TouchEvent).touches.length >= 2;
+            if (!pinchEntry) return false;
+          }
           break;
       }
     }
@@ -665,22 +686,27 @@ 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.
@@ -766,9 +792,9 @@ 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);
     }
   }
@@ -777,25 +803,29 @@ function syncOverlayPaths(items: ResolvedFocus[]) {
   // 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 width itself lives on the overlay *group*
-  // (compensated by applyStrokeScale); the paths only carry color/dash.
+  // 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("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");
-    applyDasharray(el, item.style);
+    entry.el.setAttribute("stroke", item.stroke ?? "#fff");
+    applyDasharray(entry.el, item.style);
   }
+  applyStrokeScale();
 }
 
 function resetZoom() {
@@ -808,8 +838,8 @@ function resetZoom() {
   svg.interrupt();
   hideTooltip();
   // 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
+  // pre-zoom mode: once the zoom-out lands, deactivate so the page gets
+  // touch scrolling back and the zoom hint returns. Desktop stays
   // activated (sticky), and inside fullscreen the ✕ handles leaving.
   const deactivate =
     isTouchDevice() && !fullscreen.isFullscreen.value && !isScrollMode.value;
@@ -820,7 +850,6 @@ function resetZoom() {
   if (deactivate) {
     transition.on("end", () => {
       hasZoomed.value = false;
-      hasInteracted.value = false;
     });
   }
 }
@@ -854,24 +883,24 @@ const isPannable = computed(
   () =>
     props.zoom &&
     !isTouchDevice() &&
-    (isScrollMode.value || isActivated.value || fullscreen.isFullscreen.value),
+    (isScrollMode.value || hasZoomed.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
+// Grey affordance line shown while the zoom gesture is still the way in:
+// on desktop until the first zoom (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.
+// the first in-place 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),
+    ((isTouchDevice() && props.touchExpand) || !hasZoomed.value),
 );
 const zoomHintText = computed(() =>
-  isTouchDevice() ? "Tap to zoom" : "Double click to zoom",
+  isTouchDevice() ? "Double tap to zoom" : "Double click to zoom",
 );
 
 // Inline style for the map svg. `touch-action: none` hands pan/pinch to
@@ -885,9 +914,15 @@ const svgStyle = computed(() => {
   const style: Record<string, string> = {};
   if (fullscreen.isFullscreen.value || touchGesturesInline.value) {
     style["touch-action"] = "none";
+  } else if (props.zoom && !isScrollMode.value && isTouchDevice()) {
+    // Inline, pre-zoom: keep page panning but claim the zoom gestures.
+    // `manipulation` suppresses the browser's double-tap zoom (the expand
+    // gesture); in-place mode also blocks browser pinch-zoom so a pinch
+    // reaches d3-zoom as the entry gesture.
+    style["touch-action"] = props.touchExpand ? "manipulation" : "pan-x pan-y";
   }
   if (
-    isActivated.value ||
+    hasZoomed.value ||
     fullscreen.isFullscreen.value ||
     (props.zoom && isScrollMode.value)
   ) {
@@ -1550,37 +1585,56 @@ 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));
-  const hw = String((eff + 1) / d);
-  for (const [p] of focusedPathStyles) p.setAttribute("stroke-width", hw);
-  if (hoveredEl) hoveredEl.setAttribute("stroke-width", hw);
+  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,
-  style: FocusStyle = "solid",
-) {
+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) / strokeDivisor()),
+    String(highlightWidthFor(item) / strokeDivisor()),
   );
-  pathEl.setAttribute("stroke", "#555");
-  applyDasharray(pathEl, style);
+  pathEl.style.stroke = item?.stroke ?? HIGHLIGHT_STROKE;
+  applyDasharray(pathEl, item?.style);
 }
 
 function restoreDefaultStroke(pathEl: SVGPathElement) {
   // 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");
@@ -1594,18 +1648,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);
@@ -1628,9 +1684,6 @@ 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);
@@ -1704,38 +1757,80 @@ function onTouchEnd(event: TouchEvent) {
   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.
+  // Inline touch map with zoom on (activate mode): a *double tap*
+  // anywhere (features and background alike) is the zoom gesture —
+  // expanding to fill the window by default, or zooming in place with
+  // `touchExpand: false` (a pinch works there too). Single taps select,
+  // deferred by the double-tap window so the second tap of a double tap
+  // can cancel them — mirroring the desktop click debounce. Scroll mode
+  // and the expanded view skip all of this: taps there select directly.
   if (
     props.zoom &&
     !isScrollMode.value &&
     isTouchDevice() &&
     !fullscreen.isFullscreen.value
   ) {
-    if (props.touchExpand) {
-      event.preventDefault();
-      enterTouchZoom(t.clientX, t.clientY);
+    // Suppress the synthetic click/hover the browser would replay from
+    // this tap (and iOS's hover-first tap).
+    event.preventDefault();
+    const prev = lastTap;
+    lastTap = { x: t.clientX, y: t.clientY, time: event.timeStamp };
+    const isDoubleTap =
+      prev != null &&
+      event.timeStamp - prev.time <= CLICK_SELECT_DELAY_MS &&
+      Math.abs(t.clientX - prev.x) <= DOUBLE_TAP_SLOP &&
+      Math.abs(t.clientY - prev.y) <= DOUBLE_TAP_SLOP;
+    if (isDoubleTap) {
+      lastTap = null;
+      window.clearTimeout(pendingSelectTimer);
+      pendingSelectTimer = 0;
+      if (props.touchExpand) {
+        enterTouchZoom(t.clientX, t.clientY);
+      } else {
+        zoomInPlaceAt(t.clientX, t.clientY);
+      }
       return;
     }
-    if (!isActivated.value) {
-      event.preventDefault();
-      zoomInPlaceAt(t.clientX, t.clientY);
+    const data = start.featId ? tooltipDataById.get(start.featId) : undefined;
+    if (!data) {
+      // Background tap: dismiss any tap-hover state.
+      clearHover();
       return;
     }
+    // Highlight + tooltip respond instantly; only the selection emits
+    // wait out the double-tap window.
+    touchHover(data, t.clientX, t.clientY);
+    window.clearTimeout(pendingSelectTimer);
+    pendingSelectTimer = window.setTimeout(() => {
+      pendingSelectTimer = 0;
+      emitSelection(data);
+    }, CLICK_SELECT_DELAY_MS);
+    return;
+  }
+  if (!start.featId) {
+    clearHover();
+    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
   // tap, so selection fires exactly once and never via iOS's hover-first tap.
   event.preventDefault();
+  touchHover(data, t.clientX, t.clientY);
   emitSelection(data);
 }
 
+// A tap doubles as the touch replacement for hover: apply the hover-style
+// highlight, announce it, and show the tooltip at the tapped point.
+// (Continuous hover *tracking* stays off on touch — see setupInteraction —
+// this is the one-shot equivalent.)
+function touchHover(data: TooltipPayload, clientX: number, clientY: number) {
+  const pathEl = pathsByFeatureId.get(data.id);
+  if (pathEl) setHover(pathEl);
+  emit("stateHover", { id: data.id, name: data.name, value: data.value });
+  if (hasInteractiveTooltip.value) showTooltip(data.id, clientX, clientY);
+}
+
 function onTouchCancel() {
   tapStart = null;
 }
@@ -2154,6 +2249,8 @@ watch(
 
   position: relative;
   width: 100%;
+  /* Size container so the zoom hint can reposition on narrow maps. */
+  container-type: inline-size;
 }
 
 .choropleth-wrapper svg {
@@ -2188,11 +2285,13 @@ watch(
 
 /* 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. */
+   in the markup — without taking up flow space. The text carries a
+   page-color halo so it stays legible over map fills. */
 .choropleth-zoom-hint {
   position: absolute;
   left: 0;
   right: 0;
+  z-index: 1;
   padding-top: 6px;
   text-align: center;
   font-size: 12px;
@@ -2200,6 +2299,21 @@ watch(
   color: var(--color-text-secondary, #777);
   opacity: 0.6;
   pointer-events: none;
+  text-shadow:
+    1px 0 0 var(--color-bg-0, #fff),
+    -1px 0 0 var(--color-bg-0, #fff),
+    0 1px 0 var(--color-bg-0, #fff),
+    0 -1px 0 var(--color-bg-0, #fff),
+    0 0 3px var(--color-bg-0, #fff);
+}
+
+/* On narrow maps the overlay would cover content that matters — show the
+   hint in flow above the map instead (the wrapper is the container). */
+@container (max-width: 480px) {
+  .choropleth-zoom-hint {
+    position: static;
+    padding: 0;
+  }
 }
 
 /*

package/charts/_shared/useChartFullscreen.ts

@@ -1,5 +1,6 @@
 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
@@ -27,6 +28,50 @@ function unlockBodyScroll() {
   }
 }
 
+/**
+ * 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
@@ -62,14 +107,55 @@ 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;
     }
   }
@@ -104,10 +190,12 @@ export function useChartFullscreen(opts: ChartFullscreenOptions = {}) {
   onUnmounted(() => {
     if (typeof document === "undefined") return;
     document.removeEventListener("keydown", onKey);
-    // Component torn down while expanded — release the lock so the body
-    // doesn't stay frozen.
+    // 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;
     }
   });
@@ -132,11 +220,16 @@ export function useChartFullscreen(opts: ChartFullscreenOptions = {}) {
     isFullscreen.value
       ? {
           position: "fixed",
-          inset: "0",
+          // 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)",
-          padding: "2em",
+          // 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",

package/index.json

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

package/package.json

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