@cfasim-ui/docs 0.6.1 → 0.6.2

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -258,6 +258,8 @@ Use an array of `CategoricalStop` objects to map string values to colors. Each s
 
 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.
 
+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.
+
 <ComponentDemo>
   <ChoroplethMap
     :topology="countiesTopo"
@@ -356,6 +358,58 @@ Set `geoType="hsas"` to render Health Service Area boundaries. HSAs are dissolve
   </template>
 </ComponentDemo>
 
+### Single-state map (`state`)
+
+Set the `state` prop to render just one state's outline with its `counties` or
+`hsas` inside it — no surrounding states — and the projection zooms to fit it.
+Accepts a state **name** (`"California"`) or a 2-digit **FIPS code** (`"06"`).
+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.
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="counties"
+    state="California"
+    :data="[
+      { id: '06037', value: 100 },
+      { id: '06073', value: 80 },
+      { id: '06059', value: 65 },
+      { id: '06065', value: 55 },
+      { id: '06001', value: 45 },
+      { id: '06085', value: 40 },
+    ]"
+    title="California cases by county"
+    :legend-title="'Cases'"
+    :height="400"
+  />
+
+<template #code>
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  state="California"
+  :data="[
+    { id: '06037', value: 100 }, // Los Angeles
+    { id: '06073', value: 80 }, // San Diego
+    { id: '06059', value: 65 }, // Orange
+  ]"
+  title="California cases by county"
+  :legend-title="'Cases'"
+  :height="400"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Switch `geo-type="hsas"` to fill the same state with Health Service Areas
+instead. An unrecognized `state` value logs a warning and falls back to the
+full national map.
+
 ### Click to focus (`v-model:focus`)
 
 Bind the `focus` prop to pan and zoom to a specific feature. Pass a feature
@@ -365,6 +419,10 @@ 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.
 
+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.
@@ -695,6 +753,7 @@ set `tooltip-trigger`.
 | `data` | `StateData[]` | No | — |
 | `geoType` | `GeoType` | No | `"states"` |
 | `dataGeoType` | `GeoType` | No | — |
+| `state` | `string` | No | — |
 | `width` | `number` | No | — |
 | `height` | `number` | No | — |
 | `colorScale` | `ChoroplethColorScale \| ThresholdStop[] \| CategoricalStop[]` | No | — |
@@ -709,6 +768,7 @@ set `tooltip-trigger`.
 | `legendTitle` | `string` | No | — |
 | `zoom` | `boolean` | No | `false` |
 | `pan` | `boolean` | No | `false` |
+| `twoFingerPan` | `boolean` | No | `false` |
 | `tooltipTrigger` | `"hover" \| "click"` | No | — |
 | `tooltipFormat` | `(data: {
       id: string` | No | — |
@@ -718,6 +778,7 @@ set `tooltip-trigger`.
 | `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
 | `focus` | `FocusValue` | No | — |
 | `focusZoomLevel` | `number` | No | `4` |
+| `focusZoom` | `boolean` | No | `true` |
 | `fullscreenTarget` | `string \| HTMLElement` | No | — |
 
 

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -8,7 +8,7 @@ import {
   toRaw,
   useSlots,
 } from "vue";
-import { geoPath, geoAlbersUsa } from "d3-geo";
+import { geoPath, geoAlbersUsa, geoMercator } from "d3-geo";
 import { zoom as d3Zoom, zoomIdentity } from "d3-zoom";
 import { select } from "d3-selection";
 // Side-effect import: enables `selection.transition()` on d3 selections so
@@ -107,6 +107,15 @@ const props = withDefaults(
      * When unset, data ids must match the base `geoType`.
      */
     dataGeoType?: GeoType;
+    /**
+     * Scope the map to a single state: render only that state's outline with
+     * its `counties` or `hsas` inside it (no surrounding states), and refit
+     * the projection to zoom to it. Accepts a state name ("California") or a
+     * 2-digit FIPS code ("06"). Requires a counties topology when `geoType`
+     * is `"counties"` or `"hsas"`. If the value matches no state, the full
+     * national map is rendered and a warning is logged.
+     */
+    state?: string;
     width?: number;
     height?: number;
     colorScale?: ChoroplethColorScale | ThresholdStop[] | CategoricalStop[];
@@ -131,6 +140,14 @@ const props = withDefaults(
     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.
+     */
+    twoFingerPan?: boolean;
     /** Tooltip activation mode */
     tooltipTrigger?: "hover" | "click";
     /**
@@ -174,6 +191,14 @@ const props = withDefaults(
     focus?: FocusValue;
     /** Scale factor applied when `focus` is set. Default: 4 */
     focusZoomLevel?: number;
+    /**
+     * Whether setting `focus` pans/zooms to fit the focused feature.
+     * 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.
+     */
+    focusZoom?: boolean;
     /**
      * Where to teleport the map while expanded (the Expand menu item). A
      * CSS selector or element; defaults to `body`. Moving it to the
@@ -193,8 +218,10 @@ const props = withDefaults(
     legend: true,
     zoom: false,
     pan: false,
+    twoFingerPan: false,
     tooltipClamp: "chart",
     focusZoomLevel: 4,
+    focusZoom: true,
   },
 );
 
@@ -425,16 +452,28 @@ function setupZoom() {
   // 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`.
+  // 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.
   zoomBehavior.filter((event) => {
-    const focused = normalizedFocus.value.length > 0;
+    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;
+      }
     } else if (!allowZoom && !allowPan) {
       return false;
     }
@@ -541,6 +580,13 @@ function applyFocus() {
     return;
   }
 
+  // Highlight-only mode: the strokes + overlays above are applied; skip the
+  // pan/zoom transform so the current view stays put (click-to-select).
+  if (props.focusZoom === false) {
+    focusApplied = true;
+    return;
+  }
+
   const svg = select(svgRef.value);
   // Always cancel any in-flight transition first — d3-transition queues
   // same-named transitions rather than replacing them, so rapid focus
@@ -667,6 +713,19 @@ watch(
   },
 );
 
+// Switching the scoped `state` refits the projection to a different region,
+// so any leftover pan/zoom transform would leave the new map off-center.
+// Reset it instantly (no animation) when the region changes.
+watch(
+  () => props.state,
+  () => {
+    if (!svgRef.value || !zoomBehavior) return;
+    const svg = select(svgRef.value);
+    svg.interrupt();
+    zoomBehavior.transform(svg, zoomIdentity);
+  },
+);
+
 // Canonical internal coordinate system. All layout (projection, legend,
 // title) is computed at this size; the SVG's viewBox makes the browser
 // scale the entire canvas to whatever the container provides, so there's no
@@ -692,6 +751,58 @@ type CountiesTopo = Topology<{
   states: NamedGeometry;
 }>;
 
+type StateFeature = GeoJSON.Feature<GeoJSON.Geometry | null, { name?: string }>;
+
+// ─── Single-state scoping (`state` prop) ─────────────────────────────────
+//
+// Resolved directly from the topology's `states` object (not from
+// featuresByGeoType) so it stays free of the featuresGeo → featuresById →
+// featuresByGeoType chain — that chain reads `stateFips`, so depending on it
+// here would form a reactive cycle.
+const statesFeatures = computed<StateFeature[]>(() => {
+  const topo = toRaw(props.topology) as unknown as {
+    objects?: { states?: NamedGeometry };
+  };
+  const statesObj = topo?.objects?.states;
+  if (!statesObj) return [];
+  const fc = feature(topo as unknown as Topology, statesObj) as
+    | GeoJSON.FeatureCollection<GeoJSON.Geometry | null, { name?: string }>
+    | StateFeature;
+  return fc.type === "FeatureCollection" ? fc.features : [fc];
+});
+
+// 2-digit FIPS for the active `state` prop, or null when unset/unresolved.
+const stateFips = computed<string | null>(() => {
+  const s = props.state?.trim();
+  if (!s) return null;
+  if (/^\d{1,2}$/.test(s)) return s.padStart(2, "0");
+  const match = statesFeatures.value.find((f) => f.properties?.name === s);
+  return match?.id != null ? String(match.id).padStart(2, "0") : null;
+});
+
+// The single state's GeoJSON feature — drives the outline path and the
+// projection fit in single-state mode.
+const stateOutlineFeature = computed<StateFeature | null>(() => {
+  const fips = stateFips.value;
+  if (!fips) return null;
+  return (
+    statesFeatures.value.find((f) => String(f.id).padStart(2, "0") === fips) ??
+    null
+  );
+});
+
+watch(
+  () => [props.state, stateFips.value] as const,
+  ([state, fips]) => {
+    if (state && state.trim() && !fips) {
+      console.warn(
+        `[ChoroplethMap] state="${state}" matched no state name or FIPS code; rendering the full map.`,
+      );
+    }
+  },
+  { immediate: true },
+);
+
 // HSA mapping is loaded lazily — it's ~25KB gzipped and only needed when
 // geoType or dataGeoType is "hsas". Keeps the main bundle small for users
 // who only need states/counties maps.
@@ -727,10 +838,14 @@ const hsaFeaturesGeo = computed(() => {
   const { fipsToHsa, hsaNames } = mod;
   const topo = toRaw(props.topology) as unknown as CountiesTopo;
   const countyGeometries = topo.objects.counties.geometries;
+  const scopeFips = stateFips.value;
   const groups = new Map<string, typeof countyGeometries>();
 
   for (const geom of countyGeometries) {
     const fips = String(geom.id).padStart(5, "0");
+    // Single-state mode: drop counties outside the state before grouping, so
+    // the resulting HSAs only cover the selected state.
+    if (scopeFips && fips.slice(0, 2) !== scopeFips) continue;
     const hsaCode = fipsToHsa[fips];
     if (!hsaCode) continue;
     if (!groups.has(hsaCode)) groups.set(hsaCode, []);
@@ -751,30 +866,71 @@ const hsaFeaturesGeo = computed(() => {
 });
 
 const featuresGeo = computed(() => {
+  // hsaFeaturesGeo already honors `state` (it scopes the source counties).
   if (props.geoType === "hsas") return hsaFeaturesGeo.value;
+  const scopeFips = stateFips.value;
   if (props.geoType === "counties") {
     const topo = toRaw(props.topology) as unknown as CountiesTopo;
-    return feature(topo, topo.objects.counties);
+    const fc = feature(topo, topo.objects.counties);
+    if (!scopeFips) return fc;
+    return {
+      type: "FeatureCollection" as const,
+      features: fc.features.filter(
+        (f) => String(f.id).padStart(5, "0").slice(0, 2) === scopeFips,
+      ),
+    };
   }
   const topo = toRaw(props.topology) as unknown as StatesTopo;
-  return feature(topo, topo.objects.states);
+  const fc = feature(topo, topo.objects.states);
+  if (!scopeFips) return fc;
+  return {
+    type: "FeatureCollection" as const,
+    features: fc.features.filter(
+      (f) => String(f.id).padStart(2, "0") === scopeFips,
+    ),
+  };
 });
 
 const stateBordersPath = computed(() => {
   if (props.geoType !== "counties" && props.geoType !== "hsas") return null;
+  // Single-state mode: trace just the selected state's outline instead of
+  // the full national state-border mesh.
+  if (stateFips.value) return stateOutlineFeature.value;
   const topo = toRaw(props.topology) as unknown as CountiesTopo;
   return mesh(topo, topo.objects.states, (a, b) => a !== b);
 });
 
-const projection = computed(() =>
-  geoAlbersUsa().fitExtent(
+// Breathing room (canonical px) around a single state so its outline isn't
+// flush against the SVG edge. Only applied in single-state mode.
+const STATE_FIT_INSET = 12;
+
+const projection = computed(() => {
+  const outline = stateOutlineFeature.value;
+  if (stateFips.value && outline) {
+    const extent: [[number, number], [number, number]] = [
+      [STATE_FIT_INSET, STATE_FIT_INSET],
+      [width.value - STATE_FIT_INSET, height.value - STATE_FIT_INSET],
+    ];
+    const albers = geoAlbersUsa().fitExtent(extent, outline);
+    // geoAlbersUsa only covers the 50 states + DC (it handles Alaska and
+    // Hawaii via insets). The island territories — Puerto Rico, Guam, the
+    // US Virgin Islands, American Samoa, the N. Mariana Islands — fall
+    // outside it and project to null, so fitExtent yields a NaN transform
+    // and every path renders as "MNaN,NaN…". Detect that by projecting the
+    // outline's centroid and fall back to a plain Mercator that can render
+    // any region.
+    const c = geoPath(albers).centroid(outline);
+    if (Number.isFinite(c[0]) && Number.isFinite(c[1])) return albers;
+    return geoMercator().fitExtent(extent, outline);
+  }
+  return geoAlbersUsa().fitExtent(
     [
       [0, 0],
       [width.value, height.value],
     ],
     featuresGeo.value,
-  ),
-);
+  );
+});
 
 const pathGenerator = computed(() => geoPath(projection.value));
 
@@ -1481,9 +1637,12 @@ const menuItems = computed<ChartMenuItem[]>(() => {
 // Registered last so the eagerly-evaluated source getters can read every
 // computed defined above without hitting a TDZ.
 
-// Geometry / projection / tooltip-mode → full rebuild.
+// Geometry / projection / tooltip-mode → full rebuild. `featuresGeo` is
+// watched explicitly because in single-state mode the projection is pinned
+// to the static state outline, so an async change to the feature set (e.g.
+// the lazy HSA module resolving) wouldn't otherwise change `pathGenerator`.
 watch(
-  () => [pathGenerator.value, hasInteractiveTooltip.value],
+  () => [featuresGeo.value, pathGenerator.value, hasInteractiveTooltip.value],
   () => rebuildPaths(),
 );
 
@@ -1596,6 +1755,7 @@ watch(
         ref="svgRef"
         :viewBox="`0 0 ${width} ${height}`"
         preserveAspectRatio="xMidYMid meet"
+        :style="twoFingerPan ? { touchAction: 'pan-y' } : undefined"
       >
         <!--
         Path elements are created imperatively in `rebuildPaths()`; Vue never

package/index.json

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

package/package.json

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