feat: Support pre-projected topologies in GeoLegend via referenceScale

Author: techniq

.changeset/geolegend-reference-scale.md

@@ -0,0 +1,7 @@
+---
+'layerchart': minor
+---
+
+feat: Support pre-projected topologies in `GeoLegend` via `referenceScale`
+
+Add a `referenceScale` prop to `GeoLegend` for charts that render pre-projected data with `geoIdentity` (e.g. `us-atlas`'s `counties-albers-10m` / `states-albers-10m`, pre-projected with `geoAlbersUsa().scale(1300)`). When provided, pixels-per-distance is derived from the chart's fit scale and the supplied base scale, bypassing the `projection.invert` + `geoDistance` path which only works for real lon/lat projections. The `GeoPath` bubble-map example now renders a correct scale bar.

docs/src/content/components/GeoLegend.md

@@ -46,3 +46,15 @@ Use `labelPlacement="top"` to place labels above the bar so two legends with dif
 ## Reference point
 
 The pixels-per-unit ratio is measured at a single reference point on the projection — by default, the center of the chart's plot area (`[width / 2, height / 2]`). For conformal projections like Mercator where scale varies with latitude, the legend is only accurate at that reference point. Pass an explicit `referencePoint` in chart pixel coordinates to anchor the measurement elsewhere (e.g. near the legend itself, or over your region of interest).
+
+## Pre-projected data (`geoIdentity`)
+
+When rendering a topology whose coordinates have already been run through a projection (e.g. `us-atlas`'s `counties-albers-10m` / `states-albers-10m`), the chart uses `geoIdentity` as its projection. In that case `projection.invert` returns topology pixel coordinates rather than `[lon, lat]`, so the default distance calculation (which relies on `geoDistance` on inverted points) cannot work.
+
+Pass `referenceScale` with the scale of the original projection used to pre-project the data to opt into a direct calculation that combines the chart's fit scale with the known base scale. For the `us-atlas` albers topologies, that value is `1300`:
+
+```svelte
+<GeoLegend units="mi" referenceScale={1300} />
+```
+
+See the [`GeoPath` bubble map example](/docs/components/GeoPath#bubble-map) for a full setup.

docs/src/examples/components/GeoPath/bubble-map.svelte

@@ -145,7 +145,7 @@
 
 		<CircleLegend title="Population" tickFormat="metric" placement="bottom-right" />
 
-		<GeoLegend units="mi" placement="bottom-left" class="m-2" />
+		<GeoLegend units="mi" referenceScale={1300} placement="bottom-left" class="m-2" />
 
 		<Tooltip.Root>
 			{#snippet children({ data })}

packages/layerchart/src/lib/components/GeoLegend.svelte

@@ -84,6 +84,18 @@
      */
     referencePoint?: [number, number];
 
+    /**
+     * Scale of the projection originally used to pre-project the data, for
+     * charts that render pre-projected topologies via `geoIdentity`. For
+     * example, the `us-atlas` `counties-albers-10m` / `states-albers-10m`
+     * topologies are pre-projected with `geoAlbersUsa().scale(1300)`, so pass
+     * `referenceScale={1300}`. When provided, pixels-per-distance is derived
+     * directly from the chart's `geoIdentity` fit scale and this reference
+     * scale, bypassing the `projection.invert` + `geoDistance` path which
+     * does not work for pre-projected data.
+     */
+    referenceScale?: number;
+
     /**
      * The placement of the legend.
      */
@@ -141,6 +153,7 @@
     height = 4,
     title = '',
     referencePoint,
+    referenceScale,
     placement,
     color = 'currentColor',
     classes = {},
@@ -163,19 +176,37 @@
   // `null` if no projection or invert is unavailable (or numerically degenerate).
   const pixelsPerUnit = $derived.by(() => {
     const projection = ctx.geo?.projection;
-    if (!projection || typeof projection.invert !== 'function') return null;
-
-    const refPx: [number, number] = referencePoint ?? [ctx.width / 2, ctx.height / 2];
-    const a = projection.invert(refPx);
-    const b = projection.invert([refPx[0] + 1, refPx[1]]);
-    if (!a || !b) return null;
-    if (!Number.isFinite(a[0]) || !Number.isFinite(b[0])) return null;
-
-    const radiansPerPx = geoDistance(a, b);
-    if (!Number.isFinite(radiansPerPx) || radiansPerPx === 0) return null;
-
-    const unitsPerPx = radiansPerPx * earthRadius;
-    let pxPerUnit = 1 / unitsPerPx;
+    if (!projection) return null;
+
+    let pxPerUnit: number;
+
+    if (referenceScale != null) {
+      // Pre-projected data path (e.g. `geoIdentity` + us-atlas
+      // `counties-albers-10m`): `projection.invert` returns topology pixel
+      // coordinates, not lon/lat, so `geoDistance` can't be used. Instead,
+      // combine the chart's fit scale with the known base projection scale:
+      //   topology units per chart px = 1 / fitScale
+      //   radians per topology unit   = 1 / referenceScale
+      //   units (mi/km) per radian    = earthRadius
+      // => px per unit = (fitScale * referenceScale) / earthRadius
+      const fitScale = typeof projection.scale === 'function' ? projection.scale() : null;
+      if (fitScale == null || !Number.isFinite(fitScale) || fitScale === 0) return null;
+      pxPerUnit = (fitScale * referenceScale) / earthRadius;
+    } else {
+      if (typeof projection.invert !== 'function') return null;
+
+      const refPx: [number, number] = referencePoint ?? [ctx.width / 2, ctx.height / 2];
+      const a = projection.invert(refPx);
+      const b = projection.invert([refPx[0] + 1, refPx[1]]);
+      if (!a || !b) return null;
+      if (!Number.isFinite(a[0]) || !Number.isFinite(b[0])) return null;
+
+      const radiansPerPx = geoDistance(a, b);
+      if (!Number.isFinite(radiansPerPx) || radiansPerPx === 0) return null;
+
+      const unitsPerPx = radiansPerPx * earthRadius;
+      pxPerUnit = 1 / unitsPerPx;
+    }
 
     // In `canvas` transform mode the projection itself is not re-scaled — the
     // rendered output is visually scaled by `ctx.transform.scale`, so we need