@cfasim-ui/docs 0.6.4 → 0.7.0

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -254,18 +254,73 @@ Use an array of `CategoricalStop` objects to map string values to colors. Each s
   </template>
 </ComponentDemo>
 
-### County-level map with pan and zoom
+### Pan and zoom
+
+Maps are **fully static by default** — tooltips, hover, click-select, and
+programmatic `focus` zoom all work, but there are no zoom gestures and no
+controls. That's the right mode when clicks mean navigation instead of
+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.
+
+- **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.
+
+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.
+
+#### Full-page mode (`zoom-mode="scroll"`)
+
+When the map _is_ the page — a dedicated map route, a dashboard panel, a
+kiosk — the activation step just gets in the way, and there's no page
+scroll to protect. Pair `zoom` with `zoom-mode="scroll"` to make the map
+immediately interactive: the wheel (and trackpad pinch) zooms, dragging
+pans, and touch gestures work inline with no tap-to-expand step. The
++/−/reset controls are always shown and the hint is suppressed.
 
-Set `geoType="counties"` to render county-level data using 5-digit FIPS codes. State borders are drawn on top for context. Use `pan` and `zoom` props to enable interactive navigation — useful for dense county data.
+```vue
+<ChoroplethMap
+  :topology="statesTopo"
+  :data="stateData"
+  zoom
+  zoom-mode="scroll"
+/>
+```
+
+### County-level map
 
-On touch devices, add `two-finger-pan` so a single finger scrolls the page (the map sets `touch-action: pan-y`) and two fingers pan/pinch-zoom the map — tap-to-select still works with one finger.
+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.
 
 <ComponentDemo>
   <ChoroplethMap
     :topology="countiesTopo"
     geo-type="counties"
-    :pan="true"
-    :zoom="true"
+    zoom
     :data="[
       { id: '06037', value: 100 },
       { id: '06073', value: 80 },
@@ -289,7 +344,6 @@ On touch devices, add `two-finger-pan` so a single finger scrolls the page (the
 <ChoroplethMap
   :topology="countiesTopo"
   geo-type="counties"
-  pan
   zoom
   :data="[
     { id: '06037', value: 100 },
@@ -315,8 +369,7 @@ Set `geoType="hsas"` to render Health Service Area boundaries. HSAs are dissolve
   <ChoroplethMap
     :topology="countiesTopo"
     geo-type="hsas"
-    :pan="true"
-    :zoom="true"
+    zoom
     :data="[
       { id: '010259', value: 100 },
       { id: '060766', value: 90 },
@@ -340,7 +393,6 @@ Set `geoType="hsas"` to render Health Service Area boundaries. HSAs are dissolve
 <ChoroplethMap
   :topology="countiesTopo"
   geo-type="hsas"
-  pan
   zoom
   :data="[
     { id: '010259', value: 100 },
@@ -367,11 +419,18 @@ This needs a counties topology (the same `us-atlas/counties-10m.json`). `data`
 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.
+
 <ComponentDemo>
   <ChoroplethMap
     :topology="countiesTopo"
     geo-type="counties"
     state="California"
+    zoom
+    :touch-expand="false"
+    :zoom-hint="false"
     :data="[
       { id: '06037', value: 100 },
       { id: '06073', value: 80 },
@@ -392,6 +451,9 @@ colored.
   :topology="countiesTopo"
   geo-type="counties"
   state="California"
+  zoom
+  :touch-expand="false"
+  :zoom-hint="false"
   :data="[
     { id: '06037', value: 100 }, // Los Angeles
     { id: '06073', value: 80 }, // San Diego
@@ -416,16 +478,22 @@ Bind the `focus` prop to pan and zoom to a specific feature. Pass a feature
 id (FIPS code, HSA code, or name) — or an array of ids to focus on a region.
 With `v-model:focus`, clicking an unfocused feature focuses it and clicking
 the focused feature toggles back off. If a tooltip is configured, focusing
-shows that feature's tooltip. Users can pan/zoom freely around the focused
-area; the built-in **Reset** button clears focus and snaps back.
+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.
 
 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.
 
-Selection works on touch too: a single-finger **tap** on a feature emits
-`stateClick` and toggles focus, while drags (pan) and pinches (zoom) are left
-to the map. Hover tooltips stay off on touch for performance.
+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.
+
+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.
 
 Counties are tiny without a zoom — focus is a natural fit for drill-down.
 
@@ -435,6 +503,8 @@ Counties are tiny without a zoom — focus is a natural fit for drill-down.
     geo-type="counties"
     v-model:focus="focused"
     :focus-zoom-level="8"
+    zoom
+    :touch-expand="false"
     :data="[
       { id: '06037', value: 100 },
       { id: '06073', value: 80 },
@@ -469,6 +539,8 @@ const focused = ref(null);
   geo-type="counties"
   v-model:focus="focused"
   :focus-zoom-level="8"
+  zoom
+  :touch-expand="false"
   :data="data"
   title="Click a county to focus"
 >
@@ -496,8 +568,8 @@ on top with a `FocusItem`.
     :topology="countiesTopo"
     geo-type="counties"
     data-geo-type="hsas"
-    :pan="true"
-    :zoom="true"
+    zoom
+    :touch-expand="false"
     :data="[
       { id: '060737', value: 80 },
       { id: '060723', value: 60 },
@@ -523,6 +595,8 @@ on top with a `FocusItem`.
   :topology="countiesTopo"
   geo-type="counties"
   data-geo-type="hsas"
+  zoom
+  :touch-expand="false"
   :data="hsaData"
   :focus="[{ id: '06043' }, { id: '060737', geoType: 'hsas', style: 'dashed' }]"
   title="HSA-keyed data on a county map"
@@ -549,8 +623,8 @@ subpath so consumers that don't need HSA lookups don't pay for the
     :topology="countiesTopo"
     geo-type="counties"
     data-geo-type="hsas"
-    :pan="true"
-    :zoom="true"
+    zoom
+    :touch-expand="false"
     :focus="parentFocus"
     @update:focus="focusedCounty = typeof $event === 'string' ? $event : null"
     :data="[
@@ -595,6 +669,8 @@ const focus = computed(() => {
   :topology="countiesTopo"
   geo-type="counties"
   data-geo-type="hsas"
+  zoom
+  :touch-expand="false"
   :data="hsaData"
   :focus="focus"
   @update:focus="focusedCounty = typeof $event === 'string' ? $event : null"
@@ -654,8 +730,7 @@ Renders every US county with a value and a custom tooltip slot.
     :topology="countiesTopo"
     geo-type="counties"
     :data="denseCountyData"
-    :pan="true"
-    :zoom="true"
+    zoom
     :color-scale="{ min: '#f0f5ff', max: '#08306b' }"
     title="All US counties — tooltip perf demo"
     :height="500"
@@ -680,13 +755,7 @@ const data = countiesTopo.objects.counties.geometries.map((g, i) => ({
 }));
 </script>
 
-<ChoroplethMap
-  :topology="countiesTopo"
-  geo-type="counties"
-  :data="data"
-  pan
-  zoom
->
+<ChoroplethMap :topology="countiesTopo" geo-type="counties" :data="data" zoom>
   <template #tooltip="{ id, name, value }">
     <div style="font-weight: 600">{{ name }}</div>
     <div style="opacity: 0.7; font-size: 0.85em">FIPS {{ id }}</div>
@@ -793,8 +862,9 @@ tech).
 | `legend` | `boolean` | No | `true` |
 | `legendTitle` | `string` | No | — |
 | `zoom` | `boolean` | No | `false` |
-| `pan` | `boolean` | No | `false` |
-| `twoFingerPan` | `boolean` | No | `false` |
+| `zoomMode` | `"activate" \| "scroll"` | No | `"activate"` |
+| `touchExpand` | `boolean` | No | `true` |
+| `zoomHint` | `boolean` | No | `true` |
 | `tooltipTrigger` | `"hover" \| "click"` | No | — |
 | `tooltipFormat` | `(data: {
       id: string` | No | — |