@cfasim-ui/charts 0.8.0 → 0.8.1

package/docs/ChoroplethMap.md

@@ -27,6 +27,28 @@ const focused = ref(null);
 // "Outline a focused feature's parent" demo: focus is a county id;
 // we derive the parent HSA and add it to the focus array as a dashed
 // overlay so clicking a county also outlines its HSA.
+// "Mixing levels" demo: county data everywhere except California and Texas,
+// which report one whole-state estimate each (`geoType: "states"`).
+const MERGED_STATES = ["06", "48"];
+const mixedLevelData = computed(() => [
+  ...denseCountyData.value.filter(
+    (d) => !MERGED_STATES.includes(d.id.slice(0, 2)),
+  ),
+  { id: "06", value: 85, geoType: "states" },
+  { id: "48", value: 15, geoType: "states" },
+]);
+
+// The other direction: a state map where New York alone is broken out into
+// its counties.
+const splitStateData = computed(() => [
+  { id: "06", value: 70 },
+  { id: "48", value: 30 },
+  { id: "12", value: 55 },
+  ...denseCountyData.value
+    .filter((d) => d.id.slice(0, 2) === "36")
+    .map((d) => ({ ...d, geoType: "counties" })),
+]);
+
 const focusedCounty = ref(null);
 const parentFocus = computed(() => {
   const fips = focusedCounty.value;
@@ -499,7 +521,7 @@ Works on national state, county, and HSA maps — it's a no-op only in single-st
 
 ### City markers (`cities`)
 
-Pass a `cities` array to overlay decorative point markers with name labels. Each entry is `{ name, coordinates: [lng, lat], capital?, minZoom? }`. Every city is a dot; `capital` cities are labeled first (with a lightly emphasized label) and never dropped, while any other label that can't be placed without overlapping is dropped (its dot stays), so labels never collide. The overlay is non-interactive — the choropleth's own hover/click is unaffected — and the markers pan/zoom with the map while staying a constant on-screen size. It works with both the SVG and canvas (`renderer`) backends.
+Pass a `cities` array to overlay decorative point markers with name labels. Each entry is `{ name, coordinates: [lng, lat], capital?, minZoom? }`. Every city is a dot; `capital` cities are labeled first and never dropped, while any other label that can't be placed without overlapping is dropped (its dot stays), so labels never collide. The overlay is non-interactive — the choropleth's own hover/click is unaffected — and the markers pan/zoom with the map while staying a constant on-screen size. It works with both the SVG and canvas (`renderer`) backends.
 
 **Level-of-detail:** on a zoomable map (`zoom`), each city has a `minZoom` and shows only once the map is zoomed to `scaleK >= minZoom`, so you can reveal the biggest cities first and progressively add more as the user zooms in. `nationalCityMarkers()` / `stateCityMarkers()` assign these tiers by population automatically (the capital always shows). A city without its own `minZoom` falls back to the `cities-min-zoom` prop (default `2`) — set that to `1` for a flat "always visible" layer, or pass `{ tiered: false }` to the selectors. **The overview below shows the biggest cities; double-click to zoom in and reveal more:**
 
@@ -521,7 +543,7 @@ import { ChoroplethMap } from "@cfasim-ui/charts";
 import { nationalCityMarkers } from "@cfasim-ui/charts/us-cities";
 import statesTopo from "us-atlas/states-10m.json";
 
-// Washington, DC (emphasized) + the 100 most-populous US cities.
+// Washington, DC (flagged as the capital) + the 100 most-populous US cities.
 const cities = nationalCityMarkers();
 </script>
 
@@ -579,7 +601,7 @@ stateCityMarkers("48"); //=> Austin (capital) + top Texas cities
 usCities; //=> the raw UsCity[] to build your own selection
 ```
 
-Only the national capital is flagged on the national map; a state's own capital is flagged in its single-state view. A flagged capital's label is emphasized and never dropped for collisions — the marker itself is a plain dot like any other city.
+Only the national capital is flagged on the national map; a state's own capital is flagged in its single-state view. A flagged capital's label is placed first and never dropped for collisions; it carries a `.choropleth-city-label-capital` class if you want to style it, but by default it looks like every other label — the marker is a plain dot too.
 
 **Styling:** the default marker style is dark dots and labels with a thin white halo, which reads over any map fill in either color scheme. The `theme` prop's marker keys configure the layer — `markerColor` (dots + labels), `markerHalo` (the halo around both), `markerHaloWidth` (dot halo width in CSS px), and `markerOpacity` (the whole layer). Any CSS color works. A stylesheet can alternatively set the CSS custom properties on `.choropleth-cities` (`--choropleth-city-marker`, `--choropleth-city-label-color`, `--choropleth-city-halo`); theme keys win when both are set.
 
@@ -859,6 +881,106 @@ on top with a `FocusItem`.
   </template>
 </ComponentDemo>
 
+### Mixing levels on one map (`data[].geoType`)
+
+`dataGeoType` re-keys _all_ the data at once. When only some regions report at
+a different level — most of the country has county estimates, but California
+only published a statewide number — give those rows their own `geoType`
+instead. The state is then drawn at that level: one merged California shape
+carrying the state value, with every other state still split into counties.
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  :data="[
+    { id: '36061', value: 12 }, // county rows as usual
+    { id: '06', value: 85, geoType: 'states' }, // …and California as a whole
+  ]"
+/>
+```
+
+The substituted region is a normal feature: it fills from its own row, hovers
+and clicks as one unit, reports its own name (`California`) in the tooltip, and
+can be focused by its id.
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="counties"
+    renderer="canvas"
+    :data="mixedLevelData"
+    title="County estimates, with California and Texas reported statewide"
+    legend-title="Rate"
+    :height="420"
+  />
+
+<template #code>
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  renderer="canvas"
+  :data="[
+    ...countyRows,
+    { id: '06', value: 85, geoType: 'states' },
+    { id: '48', value: 15, geoType: 'states' },
+  ]"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+It works in the other direction too — a state-level map where one state is
+broken out into counties. The whole state is re-tiled, so its counties without
+a row of their own render as no-data:
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="states"
+    :data="splitStateData"
+    title="State estimates, with New York broken out by county"
+    legend-title="Rate"
+    :height="420"
+  />
+
+<template #code>
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="states"
+  :data="[
+    { id: '06', value: 70 },
+    { id: '48', value: 30 },
+    ...newYorkCountyRows.map((r) => ({ ...r, geoType: 'counties' })),
+  ]"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Rules to keep in mind:
+
+- **A whole state is the unit.** One off-level row re-tiles its entire state, so
+  a single county row on a state map splits all of that state's counties out.
+- **Any pair of levels works** (`states` / `counties` / `hsas`), in either
+  direction, as long as the topology can supply them — splitting a state into
+  counties or HSAs needs `counties-10m.json`, not `states-10m.json`. HSA
+  substitution waits for the lazily-loaded FIPS→HSA table and leaves the base
+  map untouched until it arrives.
+- **Off-level rows ignore `dataGeoType`.** They're looked up by their own id, so
+  a map can use `dataGeoType` for its base features and still mix.
+- **One level per state.** If two rows claim the same state at different levels,
+  the first wins and a warning is logged. A row whose id resolves to no state
+  is ignored (also with a warning) and the base map renders as usual.
+- Ids can be codes or feature names (`"06"` or `"California"`), resolved in the
+  row's own `geoType`.
+
 ### Outline a focused feature's parent
 
 Use `v-model:focus` together with a computed that derives a parent
@@ -1169,6 +1291,11 @@ interface StateData {
   /** FIPS code (e.g. "06" for California, "06037" for LA County) or name */
   id: string;
   value: number | string;
+  /**
+   * Level of *this row*, when it differs from the map's `geoType`. The row's
+   * state is re-tiled at this level — see "Mixing levels on one map".
+   */
+  geoType?: GeoType;
 }
 ```
 

package/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.8.0",
+  "version": "0.8.1",
   "package": "@cfasim-ui/charts",
   "content": {
     "charts": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/charts",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "type": "module",
   "description": "Chart visualization components for cfasim-ui",
   "license": "Apache-2.0",
@@ -46,7 +46,7 @@
     "d3-zoom": "3.0.0",
     "reka-ui": "2.10.1",
     "topojson-client": "3.1.0",
-    "@cfasim-ui/shared": "0.8.0"
+    "@cfasim-ui/shared": "0.8.1"
   },
   "peerDependencies": {
     "vue": "^3.5.0"

package/src/ChoroplethMap/ChoroplethMap.md

@@ -27,6 +27,28 @@ const focused = ref(null);
 // "Outline a focused feature's parent" demo: focus is a county id;
 // we derive the parent HSA and add it to the focus array as a dashed
 // overlay so clicking a county also outlines its HSA.
+// "Mixing levels" demo: county data everywhere except California and Texas,
+// which report one whole-state estimate each (`geoType: "states"`).
+const MERGED_STATES = ["06", "48"];
+const mixedLevelData = computed(() => [
+  ...denseCountyData.value.filter(
+    (d) => !MERGED_STATES.includes(d.id.slice(0, 2)),
+  ),
+  { id: "06", value: 85, geoType: "states" },
+  { id: "48", value: 15, geoType: "states" },
+]);
+
+// The other direction: a state map where New York alone is broken out into
+// its counties.
+const splitStateData = computed(() => [
+  { id: "06", value: 70 },
+  { id: "48", value: 30 },
+  { id: "12", value: 55 },
+  ...denseCountyData.value
+    .filter((d) => d.id.slice(0, 2) === "36")
+    .map((d) => ({ ...d, geoType: "counties" })),
+]);
+
 const focusedCounty = ref(null);
 const parentFocus = computed(() => {
   const fips = focusedCounty.value;
@@ -499,7 +521,7 @@ Works on national state, county, and HSA maps — it's a no-op only in single-st
 
 ### City markers (`cities`)
 
-Pass a `cities` array to overlay decorative point markers with name labels. Each entry is `{ name, coordinates: [lng, lat], capital?, minZoom? }`. Every city is a dot; `capital` cities are labeled first (with a lightly emphasized label) and never dropped, while any other label that can't be placed without overlapping is dropped (its dot stays), so labels never collide. The overlay is non-interactive — the choropleth's own hover/click is unaffected — and the markers pan/zoom with the map while staying a constant on-screen size. It works with both the SVG and canvas (`renderer`) backends.
+Pass a `cities` array to overlay decorative point markers with name labels. Each entry is `{ name, coordinates: [lng, lat], capital?, minZoom? }`. Every city is a dot; `capital` cities are labeled first and never dropped, while any other label that can't be placed without overlapping is dropped (its dot stays), so labels never collide. The overlay is non-interactive — the choropleth's own hover/click is unaffected — and the markers pan/zoom with the map while staying a constant on-screen size. It works with both the SVG and canvas (`renderer`) backends.
 
 **Level-of-detail:** on a zoomable map (`zoom`), each city has a `minZoom` and shows only once the map is zoomed to `scaleK >= minZoom`, so you can reveal the biggest cities first and progressively add more as the user zooms in. `nationalCityMarkers()` / `stateCityMarkers()` assign these tiers by population automatically (the capital always shows). A city without its own `minZoom` falls back to the `cities-min-zoom` prop (default `2`) — set that to `1` for a flat "always visible" layer, or pass `{ tiered: false }` to the selectors. **The overview below shows the biggest cities; double-click to zoom in and reveal more:**
 
@@ -521,7 +543,7 @@ import { ChoroplethMap } from "@cfasim-ui/charts";
 import { nationalCityMarkers } from "@cfasim-ui/charts/us-cities";
 import statesTopo from "us-atlas/states-10m.json";
 
-// Washington, DC (emphasized) + the 100 most-populous US cities.
+// Washington, DC (flagged as the capital) + the 100 most-populous US cities.
 const cities = nationalCityMarkers();
 </script>
 
@@ -579,7 +601,7 @@ stateCityMarkers("48"); //=> Austin (capital) + top Texas cities
 usCities; //=> the raw UsCity[] to build your own selection
 ```
 
-Only the national capital is flagged on the national map; a state's own capital is flagged in its single-state view. A flagged capital's label is emphasized and never dropped for collisions — the marker itself is a plain dot like any other city.
+Only the national capital is flagged on the national map; a state's own capital is flagged in its single-state view. A flagged capital's label is placed first and never dropped for collisions; it carries a `.choropleth-city-label-capital` class if you want to style it, but by default it looks like every other label — the marker is a plain dot too.
 
 **Styling:** the default marker style is dark dots and labels with a thin white halo, which reads over any map fill in either color scheme. The `theme` prop's marker keys configure the layer — `markerColor` (dots + labels), `markerHalo` (the halo around both), `markerHaloWidth` (dot halo width in CSS px), and `markerOpacity` (the whole layer). Any CSS color works. A stylesheet can alternatively set the CSS custom properties on `.choropleth-cities` (`--choropleth-city-marker`, `--choropleth-city-label-color`, `--choropleth-city-halo`); theme keys win when both are set.
 
@@ -859,6 +881,106 @@ on top with a `FocusItem`.
   </template>
 </ComponentDemo>
 
+### Mixing levels on one map (`data[].geoType`)
+
+`dataGeoType` re-keys _all_ the data at once. When only some regions report at
+a different level — most of the country has county estimates, but California
+only published a statewide number — give those rows their own `geoType`
+instead. The state is then drawn at that level: one merged California shape
+carrying the state value, with every other state still split into counties.
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  :data="[
+    { id: '36061', value: 12 }, // county rows as usual
+    { id: '06', value: 85, geoType: 'states' }, // …and California as a whole
+  ]"
+/>
+```
+
+The substituted region is a normal feature: it fills from its own row, hovers
+and clicks as one unit, reports its own name (`California`) in the tooltip, and
+can be focused by its id.
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="counties"
+    renderer="canvas"
+    :data="mixedLevelData"
+    title="County estimates, with California and Texas reported statewide"
+    legend-title="Rate"
+    :height="420"
+  />
+
+<template #code>
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  renderer="canvas"
+  :data="[
+    ...countyRows,
+    { id: '06', value: 85, geoType: 'states' },
+    { id: '48', value: 15, geoType: 'states' },
+  ]"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+It works in the other direction too — a state-level map where one state is
+broken out into counties. The whole state is re-tiled, so its counties without
+a row of their own render as no-data:
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="states"
+    :data="splitStateData"
+    title="State estimates, with New York broken out by county"
+    legend-title="Rate"
+    :height="420"
+  />
+
+<template #code>
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="states"
+  :data="[
+    { id: '06', value: 70 },
+    { id: '48', value: 30 },
+    ...newYorkCountyRows.map((r) => ({ ...r, geoType: 'counties' })),
+  ]"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Rules to keep in mind:
+
+- **A whole state is the unit.** One off-level row re-tiles its entire state, so
+  a single county row on a state map splits all of that state's counties out.
+- **Any pair of levels works** (`states` / `counties` / `hsas`), in either
+  direction, as long as the topology can supply them — splitting a state into
+  counties or HSAs needs `counties-10m.json`, not `states-10m.json`. HSA
+  substitution waits for the lazily-loaded FIPS→HSA table and leaves the base
+  map untouched until it arrives.
+- **Off-level rows ignore `dataGeoType`.** They're looked up by their own id, so
+  a map can use `dataGeoType` for its base features and still mix.
+- **One level per state.** If two rows claim the same state at different levels,
+  the first wins and a warning is logged. A row whose id resolves to no state
+  is ignored (also with a warning) and the base map renders as usual.
+- Ids can be codes or feature names (`"06"` or `"California"`), resolved in the
+  row's own `geoType`.
+
 ### Outline a focused feature's parent
 
 Use `v-model:focus` together with a computed that derives a parent
@@ -1129,6 +1251,11 @@ interface StateData {
   /** FIPS code (e.g. "06" for California, "06037" for LA County) or name */
   id: string;
   value: number | string;
+  /**
+   * Level of *this row*, when it differs from the map's `geoType`. The row's
+   * state is re-tiled at this level — see "Mixing levels on one map".
+   */
+  geoType?: GeoType;
 }
 ```