@fundar/data-chart-telling 0.0.17 → 0.0.19

package/dist/layout/geo/GeoLayout.svelte

@@ -22,6 +22,7 @@
     numericMargins,
     zoomTransform,
     tileLayer,
+    dataLonLatBounds,
     children,
   }: {
     width: number;
@@ -29,6 +30,8 @@
     numericMargins: { top: number; right: number; bottom: number; left: number };
     zoomTransform: { x: number; y: number; k: number };
     tileLayer?: GeoTileLayerConfig;
+    /** Forwarded to `TileLayer` — see its own prop doc / `clipBoundsToData`. */
+    dataLonLatBounds?: [number, number, number, number] | null;
     children: Snippet;
   } = $props();
 </script>
@@ -41,6 +44,7 @@
       top={numericMargins.top}
       width={Math.max(0, width - numericMargins.left - numericMargins.right)}
       height={Math.max(0, height - numericMargins.top - numericMargins.bottom)}
+      {dataLonLatBounds}
     />
   {/if}
   {@render children()}

package/dist/layout/geo/GeoLayout.svelte.d.ts

@@ -15,6 +15,8 @@ type $$ComponentProps = {
         k: number;
     };
     tileLayer?: GeoTileLayerConfig;
+    /** Forwarded to `TileLayer` — see its own prop doc / `clipBoundsToData`. */
+    dataLonLatBounds?: [number, number, number, number] | null;
     children: Snippet;
 };
 declare const GeoLayout: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/layout/legend/ContinuousSection.svelte

@@ -26,24 +26,32 @@
   // ── Drag-to-narrow-margins ────────────────────────────────────────────────
   const interaction = getLegendInteraction() ?? createLegendInteraction();
 
-  // Seeded once from the section's own bounds (deliberately untracked — a
-  // later `section.min`/`max` change re-clamps the existing lo/hi instead of
-  // resetting them back out to the new full range, see below).
+  // Seeded once from the section's own bounds (deliberately untracked — see
+  // the tracking/clamping effect below for how later prop changes are
+  // handled instead).
   let lo = $state(untrack(() => section.min));
   let hi = $state(untrack(() => section.max));
 
-  // `section.min`/`max` can shift under an already-active selection — e.g. a
-  // consumer swaps `data` for a different year on its own timeline, and the
-  // value that used to be the max is no longer present. Re-clamping (instead
-  // of leaving lo/hi at their old absolute values) keeps the handles inside
-  // whatever range now actually exists: the lower handle can only move up to
-  // meet a risen min, the upper handle can only move down to meet a fallen
-  // max. Clamping each bound against *both* of the new min/max first (not
-  // just its own side) keeps lo/hi from inverting if the domain shifts
-  // entirely past the old selection.
+  // Whether the user has actually dragged *that* handle off its default
+  // position — tracked per handle, not as one combined flag, so dragging one
+  // doesn't freeze the other: until the other is touched, it must keep
+  // tracking `section.min`/`max` exactly, since a consumer's domain routinely
+  // changes with no interaction at all (e.g. a different year picked on its
+  // own timeline), and with nothing to protect there the legend should
+  // always read the true current extent rather than some earlier domain's
+  // stale numbers.
+  let loAdjusted = $state(false);
+  let hiAdjusted = $state(false);
+
+  // Once a handle *has* been dragged, a later domain change (same scenario as
+  // above, but now with a selection to protect) instead re-clamps it to stay
+  // valid: the lower handle only moves up to meet a risen min, the upper
+  // handle only moves down to meet a fallen max. Clamping against *both* of
+  // the new min/max first (not just its own side) keeps a handle from
+  // crossing the other if the domain shifts entirely past its old position.
   $effect(() => {
-    lo = Math.min(Math.max(lo, section.min), section.max);
-    hi = Math.max(Math.min(hi, section.max), section.min);
+    lo = loAdjusted ? Math.min(Math.max(lo, section.min), section.max) : section.min;
+    hi = hiAdjusted ? Math.max(Math.min(hi, section.max), section.min) : section.max;
   });
 
   function toT(v: number): number {
@@ -89,6 +97,8 @@
     return (event: PointerEvent) => {
       if (!section.interactive) return;
       event.preventDefault();
+      if (which === 'lo') loAdjusted = true;
+      else hiAdjusted = true;
       const target = event.currentTarget as SVGElement;
       target.setPointerCapture(event.pointerId);
       const startX = event.clientX;
@@ -117,8 +127,13 @@
 
   function resetHandle(which: 'lo' | 'hi') {
     return () => {
-      if (which === 'lo') lo = section.min;
-      else hi = section.max;
+      if (which === 'lo') {
+        lo = section.min;
+        loAdjusted = false;
+      } else {
+        hi = section.max;
+        hiAdjusted = false;
+      }
     };
   }
 </script>

package/dist/plots/geo/Plot.svelte

@@ -5,6 +5,7 @@
   import { resolveFeatureStyle } from '../utils/geoSegments';
   import {
     geometryCentroid,
+    geometryLonLatBounds,
     geometryPartCentroids,
     filterGeometryParts,
     defaultFeatureId,
@@ -144,6 +145,28 @@
     });
   });
 
+  // ── Tile-layer clipping — the rendered geometry's own lon/lat extent, so
+  // `TileLayer` can clip its raster grid to where the map actually is
+  // instead of a `domain: 'data'` fit's full (possibly letterboxed) box —
+  // see `clipBoundsToData`'s doc comment. Only computed when a tile layer is
+  // actually configured, since it's an O(total coordinate count) pass. ────
+  const dataLonLatBounds = $derived.by((): [number, number, number, number] | null => {
+    if (!styles.tileLayer) return null;
+    let minLon = Infinity;
+    let maxLon = -Infinity;
+    let minLat = Infinity;
+    let maxLat = -Infinity;
+    for (const f of features) {
+      const b = geometryLonLatBounds(f.geometry);
+      if (!b) continue;
+      if (b[0] < minLon) minLon = b[0];
+      if (b[2] > maxLon) maxLon = b[2];
+      if (b[1] < minLat) minLat = b[1];
+      if (b[3] > maxLat) maxLat = b[3];
+    }
+    return minLon === Infinity ? null : [minLon, minLat, maxLon, maxLat];
+  });
+
   // ── Tile-layer / projection compatibility ────────────────────────────────
   $effect(() => {
     if (!styles.tileLayer) return;
@@ -534,7 +557,14 @@
   bind:containerEl
 >
   {#snippet children({ matchedPoints, numericMargins })}
-    <GeoLayout {width} {height} {numericMargins} zoomTransform={geoZoom.transform} tileLayer={styles.tileLayer}>
+    <GeoLayout
+      {width}
+      {height}
+      {numericMargins}
+      zoomTransform={geoZoom.transform}
+      tileLayer={styles.tileLayer}
+      {dataLonLatBounds}
+    >
       {#each markers as marker, i (marker.type + '-' + i)}
         {#if isBehindMarker(marker)}
           {@render marker_(marker, numericMargins)}

package/dist/plots/geo/TileLayer.svelte

@@ -6,6 +6,7 @@
     tileScreenBounds,
     tileUrl,
     toProjectionLike,
+    clipBoundsToData,
     type StreamingProjection,
   } from '../utils/tiles';
   import type { GeoTileLayerConfig } from '../../types/plots/styles/geo';
@@ -26,12 +27,15 @@
     top,
     width,
     height,
+    dataLonLatBounds,
   }: {
     config: GeoTileLayerConfig;
     left: number;
     top: number;
     width: number;
     height: number;
+    /** The rendered geometry's own lon/lat extent — see `clipBoundsToData`. */
+    dataLonLatBounds?: [number, number, number, number] | null;
   } = $props();
 
   const plot = usePlot();
@@ -44,9 +48,18 @@
   const rawProjection = $derived(plot.scales.projection as unknown as StreamingProjection | undefined);
   const projection = $derived(rawProjection ? toProjectionLike(rawProjection) : undefined);
 
+  // Clipped to where the map's own geometry actually is — see
+  // `clipBoundsToData`'s doc comment for why the raw `{left,top,width,height}`
+  // box alone isn't safe to hand to `visibleTiles`/`buildMercatorFit`.
+  const clippedBounds = $derived.by(() => {
+    const full = { left, top, width, height };
+    if (!projection) return full;
+    return clipBoundsToData(projection, full, dataLonLatBounds);
+  });
+
   const tiles = $derived.by(() => {
     if (!projection) return [];
-    return visibleTiles(projection, { left, top, width, height }, tileSize, config.minZoom ?? 0, config.maxZoom ?? 19);
+    return visibleTiles(projection, clippedBounds, tileSize, config.minZoom ?? 0, config.maxZoom ?? 19);
   });
 
   // One affine fit per zoom level, shared across every tile in `tiles` — see
@@ -54,7 +67,7 @@
   // each tile's own corners individually.
   const fit = $derived.by(() => {
     if (!projection || tiles.length === 0) return null;
-    return buildMercatorFit(projection, { left, top, width, height }, tiles[0].z);
+    return buildMercatorFit(projection, clippedBounds, tiles[0].z);
   });
 </script>
 

package/dist/plots/geo/TileLayer.svelte.d.ts

@@ -5,6 +5,8 @@ type $$ComponentProps = {
     top: number;
     width: number;
     height: number;
+    /** The rendered geometry's own lon/lat extent — see `clipBoundsToData`. */
+    dataLonLatBounds?: [number, number, number, number] | null;
 };
 declare const TileLayer: import("svelte").Component<$$ComponentProps, {}, "">;
 type TileLayer = ReturnType<typeof TileLayer>;

package/dist/plots/utils/geoAccessors.d.ts

@@ -8,6 +8,18 @@ import type { GeoFeature } from '../../types/plots/data/geo';
  * multi-part geometry whose pieces are geographically spread out.
  */
 export declare function geometryCentroid(geometry: GeoJSON.Geometry): [number, number];
+/**
+ * A geometry's flattened lon/lat bounding box — `[minLon, minLat, maxLon,
+ * maxLat]`, or `null` for a geometry with no coordinates at all. Same
+ * bbox-not-geodesic caveat as `geometryCentroid` (no antimeridian handling),
+ * acceptable for the same reason: real feature sets fed through this
+ * package (Argentina's provinces, etc.) don't straddle it. Used to derive
+ * `GeoPlot`'s rendered data's own screen-space extent (see `Plot.svelte`'s
+ * `dataLonLatBounds`), so `TileLayer` can clip its raster grid to where the
+ * map's own geometry actually is instead of a projection's full letterboxed
+ * fit box (see `clipBoundsToData`).
+ */
+export declare function geometryLonLatBounds(geometry: GeoJSON.Geometry): [number, number, number, number] | null;
 /**
  * Splits a geometry into its disjoint parts: one `Polygon` per element of a
  * `MultiPolygon`'s `coordinates`, one `LineString` per element of a

package/dist/plots/utils/geoAccessors.js

@@ -61,6 +61,38 @@ export function geometryCentroid(geometry) {
     flattenCoords(geometry, coords);
     return boundsCenter(coords);
 }
+/**
+ * A geometry's flattened lon/lat bounding box — `[minLon, minLat, maxLon,
+ * maxLat]`, or `null` for a geometry with no coordinates at all. Same
+ * bbox-not-geodesic caveat as `geometryCentroid` (no antimeridian handling),
+ * acceptable for the same reason: real feature sets fed through this
+ * package (Argentina's provinces, etc.) don't straddle it. Used to derive
+ * `GeoPlot`'s rendered data's own screen-space extent (see `Plot.svelte`'s
+ * `dataLonLatBounds`), so `TileLayer` can clip its raster grid to where the
+ * map's own geometry actually is instead of a projection's full letterboxed
+ * fit box (see `clipBoundsToData`).
+ */
+export function geometryLonLatBounds(geometry) {
+    const coords = [];
+    flattenCoords(geometry, coords);
+    if (coords.length === 0)
+        return null;
+    let minLon = Infinity;
+    let maxLon = -Infinity;
+    let minLat = Infinity;
+    let maxLat = -Infinity;
+    for (const [lon, lat] of coords) {
+        if (lon < minLon)
+            minLon = lon;
+        if (lon > maxLon)
+            maxLon = lon;
+        if (lat < minLat)
+            minLat = lat;
+        if (lat > maxLat)
+            maxLat = lat;
+    }
+    return [minLon, minLat, maxLon, maxLat];
+}
 /**
  * Splits a geometry into its disjoint parts: one `Polygon` per element of a
  * `MultiPolygon`'s `coordinates`, one `LineString` per element of a

package/dist/plots/utils/tiles.d.ts

@@ -36,6 +36,32 @@ export type StreamingProjection = {
  * projected output.
  */
 export declare function toProjectionLike(projection: StreamingProjection): ProjectionLike;
+/**
+ * Clips `bounds` down to the screen-space box its actual geo data occupies
+ * — `dataLonLatBounds`' four extremes, forward-projected — intersected with
+ * `bounds` itself.
+ *
+ * A `domain: 'data'`-fitted Mercator projection scales to the *constraining*
+ * axis of its box (see `clampBoundsToWorld`'s doc comment): a tall/narrow
+ * region (Argentina) fit into a short/wide facet cell only fills a fraction
+ * of the box's width, and the letterboxed margin on either side is real,
+ * inverts to real (if occasionally distant) lon/lat, and so gets real tiles
+ * drawn under it — `clampBoundsToWorld` only stops that margin from
+ * wrapping *more* than one world-width once inverted, it doesn't stop a
+ * *single* world-width's worth of legitimate-but-irrelevant coverage from
+ * rendering there. For Argentina specifically that margin is wide enough to
+ * reach Argentina's own antipodal region — Australia — which is what a
+ * viewer actually sees. Clipping to the data's own footprint removes the
+ * letterboxed margin's tiles entirely rather than trying to pick a
+ * "more correct" set of tiles to show there.
+ *
+ * Only valid for a Mercator-family projection, same as the rest of this
+ * module: `x` is assumed to depend only on longitude and `y` only on
+ * latitude, so each axis's screen extent can be found by projecting just
+ * two opposite corners of the lon/lat bbox rather than tracing its full
+ * outline.
+ */
+export declare function clipBoundsToData(projection: ProjectionLike, bounds: ScreenBounds, dataLonLatBounds: [number, number, number, number] | null | undefined): ScreenBounds;
 /**
  * Derives the visible XYZ tile grid from svelteplot's own already-fitted
  * projection (rather than this package computing/duplicating a `d3-geo` fit
@@ -44,7 +70,7 @@ export declare function toProjectionLike(projection: StreamingProjection): Proje
  * whose tile coverage is well-defined; callers are responsible for the
  * projection-compatibility check (see `Plot.svelte`'s validation effect).
  */
-export declare function visibleTiles(projection: ProjectionLike, bounds: ScreenBounds, tileSize?: number, minZoom?: number, maxZoom?: number): TileCoord[];
+export declare function visibleTiles(projection: ProjectionLike, rawBounds: ScreenBounds, tileSize?: number, minZoom?: number, maxZoom?: number): TileCoord[];
 /** An affine tile-space → screen-space mapping (see `buildMercatorFit`), reused across every tile in a grid instead of forward-projecting each one individually. */
 export type MercatorFit = {
     z: number;
@@ -76,7 +102,7 @@ export type MercatorFit = {
  * affine in screen space by construction, so one linear fit applies
  * uniformly to every tile in the grid.
  */
-export declare function buildMercatorFit(projection: ProjectionLike, bounds: ScreenBounds, z: number): MercatorFit | null;
+export declare function buildMercatorFit(projection: ProjectionLike, rawBounds: ScreenBounds, z: number): MercatorFit | null;
 /** Places a tile on screen via a `MercatorFit` — `null` only if `tile` is from a different zoom level than the fit was built for. */
 export declare function tileScreenBounds(fit: MercatorFit, tile: TileCoord): ScreenBounds | null;
 /**

package/dist/plots/utils/tiles.js

@@ -49,6 +49,91 @@ function estimateZoomLevel(projection, centerLon, centerLat, tileSize) {
         return null;
     return Math.round(Math.log2(ratio));
 }
+/**
+ * Clamps `bounds`' horizontal extent to at most one world-width, centered on
+ * the box's own center, before any corner of it gets inverted.
+ *
+ * A Mercator(-family) projection wraps a single world onto a *finite* pixel
+ * span at any given scale. `visibleTiles`/`buildMercatorFit` invert `bounds`'
+ * corners and assume the result increases monotonically left-to-right — true
+ * only up to one world-width. Past that, the inverted longitude wraps around
+ * the antimeridian and comes back the other way, silently reversing the
+ * corner ordering (`buildMercatorFit` was seen to compute a *negative*
+ * `pxPerTileX` from this). This bites specifically when a plot's actual
+ * geographic content occupies far less of its box than the box's own aspect
+ * ratio does — e.g. a tall, narrow country's choropleth fit into a short,
+ * wide facet-grid cell: the fit shrinks scale to match the constraining
+ * (height) axis, and the *unconstrained* (width) axis's letterboxed margin
+ * can then span more of the earth than actually exists. Clamping first means
+ * that margin still renders tiles (real basemap, not blank) up to a full
+ * world, and simply stops there instead of wrapping into a bogus repeat.
+ */
+function clampBoundsToWorld(projection, bounds) {
+    if (!projection.invert)
+        return bounds;
+    const centerX = bounds.left + bounds.width / 2;
+    const centerY = bounds.top + bounds.height / 2;
+    const centerLonLat = projection.invert([centerX, centerY]);
+    if (!centerLonLat)
+        return bounds;
+    const west = projection([-180, centerLonLat[1]]);
+    const east = projection([180, centerLonLat[1]]);
+    if (!west || !east)
+        return bounds;
+    const worldWidth = Math.abs(east[0] - west[0]);
+    if (!(worldWidth > 0) || bounds.width <= worldWidth)
+        return bounds;
+    return { ...bounds, left: centerX - worldWidth / 2, width: worldWidth };
+}
+/**
+ * Clips `bounds` down to the screen-space box its actual geo data occupies
+ * — `dataLonLatBounds`' four extremes, forward-projected — intersected with
+ * `bounds` itself.
+ *
+ * A `domain: 'data'`-fitted Mercator projection scales to the *constraining*
+ * axis of its box (see `clampBoundsToWorld`'s doc comment): a tall/narrow
+ * region (Argentina) fit into a short/wide facet cell only fills a fraction
+ * of the box's width, and the letterboxed margin on either side is real,
+ * inverts to real (if occasionally distant) lon/lat, and so gets real tiles
+ * drawn under it — `clampBoundsToWorld` only stops that margin from
+ * wrapping *more* than one world-width once inverted, it doesn't stop a
+ * *single* world-width's worth of legitimate-but-irrelevant coverage from
+ * rendering there. For Argentina specifically that margin is wide enough to
+ * reach Argentina's own antipodal region — Australia — which is what a
+ * viewer actually sees. Clipping to the data's own footprint removes the
+ * letterboxed margin's tiles entirely rather than trying to pick a
+ * "more correct" set of tiles to show there.
+ *
+ * Only valid for a Mercator-family projection, same as the rest of this
+ * module: `x` is assumed to depend only on longitude and `y` only on
+ * latitude, so each axis's screen extent can be found by projecting just
+ * two opposite corners of the lon/lat bbox rather than tracing its full
+ * outline.
+ */
+export function clipBoundsToData(projection, bounds, dataLonLatBounds) {
+    if (!dataLonLatBounds)
+        return bounds;
+    const [minLon, minLat, maxLon, maxLat] = dataLonLatBounds;
+    const midLon = (minLon + maxLon) / 2;
+    const midLat = (minLat + maxLat) / 2;
+    const west = projection([minLon, midLat]);
+    const east = projection([maxLon, midLat]);
+    const south = projection([midLon, minLat]);
+    const north = projection([midLon, maxLat]);
+    if (!west || !east || !south || !north)
+        return bounds;
+    const dataLeft = Math.min(west[0], east[0]);
+    const dataRight = Math.max(west[0], east[0]);
+    const dataTop = Math.min(north[1], south[1]);
+    const dataBottom = Math.max(north[1], south[1]);
+    const left = Math.max(bounds.left, dataLeft);
+    const top = Math.max(bounds.top, dataTop);
+    const right = Math.min(bounds.left + bounds.width, dataRight);
+    const bottom = Math.min(bounds.top + bounds.height, dataBottom);
+    if (!(right > left) || !(bottom > top))
+        return bounds;
+    return { left, top, width: right - left, height: bottom - top };
+}
 /**
  * Derives the visible XYZ tile grid from svelteplot's own already-fitted
  * projection (rather than this package computing/duplicating a `d3-geo` fit
@@ -57,9 +142,10 @@ function estimateZoomLevel(projection, centerLon, centerLat, tileSize) {
  * whose tile coverage is well-defined; callers are responsible for the
  * projection-compatibility check (see `Plot.svelte`'s validation effect).
  */
-export function visibleTiles(projection, bounds, tileSize = 256, minZoom = 0, maxZoom = 19) {
+export function visibleTiles(projection, rawBounds, tileSize = 256, minZoom = 0, maxZoom = 19) {
     if (!projection.invert)
         return [];
+    const bounds = clampBoundsToWorld(projection, rawBounds);
     const corners = [
         [bounds.left, bounds.top],
         [bounds.left + bounds.width, bounds.top],
@@ -110,9 +196,10 @@ export function visibleTiles(projection, bounds, tileSize = 256, minZoom = 0, ma
  * affine in screen space by construction, so one linear fit applies
  * uniformly to every tile in the grid.
  */
-export function buildMercatorFit(projection, bounds, z) {
+export function buildMercatorFit(projection, rawBounds, z) {
     if (!projection.invert)
         return null;
+    const bounds = clampBoundsToWorld(projection, rawBounds);
     const topLeft = projection.invert([bounds.left, bounds.top]);
     const bottomRight = projection.invert([bounds.left + bounds.width, bounds.top + bounds.height]);
     if (!topLeft || !bottomRight)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fundar/data-chart-telling",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "files": [
     "dist"