@cfasim-ui/docs 0.7.1 → 0.7.3

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
@@ -492,14 +495,17 @@ 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

@@ -167,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;
     /**
@@ -187,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 */
@@ -414,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.
@@ -457,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;
@@ -475,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);
@@ -551,11 +555,20 @@ function setupZoom() {
   const svg = select(svgRef.value);
   zoomBehavior = d3Zoom<SVGSVGElement, unknown>()
     .scaleExtent([1, maxScale.value])
+    // d3-zoom swallows the click after any mousedown→mouseup movement
+    // beyond this distance. The default of 0 makes clicks unreliable the
+    // moment drag-pan is live (a pixel of hand jitter reads as a drag),
+    // so allow a few pixels of slack.
+    .clickDistance(6)
     .on("start", () => {
       isZooming = true;
-      clearHover();
     })
     .on("zoom", (event) => {
+      // Cleared here, not on gesture start: a plain mousedown opens a
+      // gesture once drag-pan is live, and hiding the tooltip on every
+      // click press felt broken. The tooltip only needs to go once the
+      // map actually moves under the cursor.
+      clearHover();
       if (mapGroupRef.value) {
         mapGroupRef.value.setAttribute("transform", event.transform);
       }
@@ -592,10 +605,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;
       }
     }
@@ -825,8 +847,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;
@@ -837,7 +859,6 @@ function resetZoom() {
   if (deactivate) {
     transition.on("end", () => {
       hasZoomed.value = false;
-      hasInteracted.value = false;
     });
   }
 }
@@ -871,24 +892,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
@@ -902,9 +923,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)
   ) {
@@ -1666,16 +1693,16 @@ 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);
 }
 
 function onDelegatedEvent(event: Event) {
-  if (isZooming) return;
+  // Only hover is suppressed mid-gesture (stroke churn while the map
+  // moves); clicks stay live — even during zoom animations — since d3
+  // already swallows genuine post-drag clicks via clickDistance.
+  if (event.type === "mouseover" && isZooming) return;
   const me = event as MouseEvent;
   const featId = eventToFeatureId(me.target);
   if (!featId) return;
@@ -1742,38 +1769,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;
 }
@@ -2192,6 +2261,8 @@ watch(
 
   position: relative;
   width: 100%;
+  /* Size container so the zoom hint can reposition on narrow maps. */
+  container-type: inline-size;
 }
 
 .choropleth-wrapper svg {
@@ -2226,11 +2297,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;
@@ -2238,6 +2311,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.1",
+  "version": "0.7.3",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [

package/package.json

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