@fundar/data-chart-telling 0.0.21 → 0.0.22

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 `Plot.svelte`'s `dataLonLatBounds`. */
+    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 `Plot.svelte`'s `dataLonLatBounds`. */
+    dataLonLatBounds?: [number, number, number, number] | null;
     children: Snippet;
 };
 declare const GeoLayout: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/plots/geo/Plot.svelte

@@ -5,6 +5,7 @@
   import { resolveFeatureStyle } from '../utils/geoSegments';
   import {
     geometryCentroid,
+    geometryLonLatBounds,
     geometryPartCentroids,
     filterGeometryParts,
     defaultFeatureId,
@@ -156,6 +157,23 @@
     }
   });
 
+  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];
+  });
+
   // ── Choropleth color scale (mirrors heatmap's styles.colors/scales.z) ────
   const minColor = $derived(styles.colors?.min ?? cfg.continuous.min);
   const maxColor = $derived(styles.colors?.max ?? cfg.continuous.max);
@@ -534,7 +552,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

@@ -26,12 +26,15 @@
     top,
     width,
     height,
+    dataLonLatBounds,
   }: {
     config: GeoTileLayerConfig;
     left: number;
     top: number;
     width: number;
     height: number;
+    /** Forwarded to `visibleTiles`/`buildMercatorFit` — see `Plot.svelte`'s `dataLonLatBounds`. */
+    dataLonLatBounds?: [number, number, number, number] | null;
   } = $props();
 
   const plot = usePlot();
@@ -46,7 +49,14 @@
 
   const tiles = $derived.by(() => {
     if (!projection) return [];
-    return visibleTiles(projection, { left, top, width, height }, tileSize, config.minZoom ?? 0, config.maxZoom ?? 19);
+    return visibleTiles(
+      projection,
+      { left, top, width, height },
+      tileSize,
+      config.minZoom ?? 0,
+      config.maxZoom ?? 19,
+      dataLonLatBounds,
+    );
   });
 
   // One affine fit per zoom level, shared across every tile in `tiles` — see
@@ -54,7 +64,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, { left, top, width, height }, tiles[0].z, dataLonLatBounds);
   });
 </script>
 

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

@@ -5,6 +5,8 @@ type $$ComponentProps = {
     top: number;
     width: number;
     height: number;
+    /** Forwarded to `visibleTiles`/`buildMercatorFit` — see `Plot.svelte`'s `dataLonLatBounds`. */
+    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

@@ -47,6 +47,14 @@ export declare function filterGeometryParts(geometry: GeoJSON.Geometry, keep: (p
 }) => boolean): GeoJSON.Geometry | null;
 /** Default `featureId`: `feature.id`, else `properties.id`, else `properties.name`. */
 export declare function defaultFeatureId<TProps extends Record<string, unknown>>(f: GeoFeature<TProps>): string;
+/**
+ * `[minLon, minLat, maxLon, maxLat]` across every coordinate of a geometry —
+ * `null` for one with none (an empty `GeometryCollection`). Used by
+ * `Plot.svelte`'s `dataLonLatBounds` to cap how far a tile layer's
+ * letterboxed margin reaches (see `clampBoundsToDataPadding` in
+ * `$lib/plots/utils/tiles`).
+ */
+export declare function geometryLonLatBounds(geometry: GeoJSON.Geometry): [number, number, number, number] | null;
 /**
  * Densifies a great-circle arc between two lon/lat points into `steps + 1`
  * points via spherical linear interpolation (slerp) — used to draw a `link`

package/dist/plots/utils/geoAccessors.js

@@ -135,6 +135,34 @@ export function defaultFeatureId(f) {
     const props = f.properties;
     return String(f.id ?? props?.id ?? props?.name ?? '');
 }
+/**
+ * `[minLon, minLat, maxLon, maxLat]` across every coordinate of a geometry —
+ * `null` for one with none (an empty `GeometryCollection`). Used by
+ * `Plot.svelte`'s `dataLonLatBounds` to cap how far a tile layer's
+ * letterboxed margin reaches (see `clampBoundsToDataPadding` in
+ * `$lib/plots/utils/tiles`).
+ */
+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];
+}
 function toRad(deg) {
     return (deg * Math.PI) / 180;
 }

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

@@ -44,7 +44,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, rawBounds: ScreenBounds, tileSize?: number, minZoom?: number, maxZoom?: number): TileCoord[];
+export declare function visibleTiles(projection: ProjectionLike, rawBounds: ScreenBounds, tileSize?: number, minZoom?: number, maxZoom?: number, dataLonLatBounds?: [number, number, number, number] | null): 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 +76,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, rawBounds: ScreenBounds, z: number): MercatorFit | null;
+export declare function buildMercatorFit(projection: ProjectionLike, rawBounds: ScreenBounds, z: number, dataLonLatBounds?: [number, number, number, number] | null): 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

@@ -53,31 +53,6 @@ function estimateZoomLevel(projection, centerLon, centerLat, tileSize) {
  * Clamps `bounds`' horizontal extent to at most *half* a world-width (180°
  * of longitude), 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 imply more of the earth than actually exists.
- *
- * The cap is *half* a world rather than a full one specifically so the two
- * edges of an extreme letterboxed margin can never reach all the way out to
- * the region exactly opposite the map's own — a full-world cap's two edges
- * meet exactly at that antipode (e.g. Argentina's own facet map, letterboxed
- * enough to hit a full-world cap, would show Buenos Aires' antipode —
- * Australia — prominently at both edges). Halving it keeps every visible
- * tile within one quarter-turn of the data's own center, which for any real
- * facet-grid cell is already a deliberately generous amount of basemap
- * context (ocean, neighboring countries) — typical facet aspect ratios don't
- * come close to needing the full 180° this still allows before clamping
- * kicks in at all.
  */
 function clampBoundsToWorld(projection, bounds) {
     if (!projection.invert)
@@ -96,6 +71,62 @@ function clampBoundsToWorld(projection, bounds) {
         return bounds;
     return { ...bounds, left: centerX - maxWidth / 2, width: maxWidth };
 }
+/**
+ * How far a letterboxed tile margin may reach beyond the data's own
+ * bounding box (see `Plot.svelte`'s `dataLonLatBounds`), on either side —
+ * the product-level cap on how much basemap "context" gets shown, well
+ * inside `clampBoundsToWorld`'s own (much looser) antimeridian-safety cap.
+ *
+ * Picked to comfortably clear the nearest *other* landmass in any direction
+ * from Argentina — this package's one real-world `domain: 'data'` +
+ * tile-layer consumer. The tightest real constraint is the Atlantic side:
+ * Argentina's own east edge sits at -53°, and the nearest land across it
+ * (West Africa) starts around -17° — a 36°-wide ocean gap. A flat 20° here
+ * stays comfortably inside that gap on the tight side, while every other
+ * direction (west into the Pacific, especially) has far more real ocean to
+ * spare than this uses.
+ */
+const CONTEXT_PADDING_DEGREES = 20;
+/**
+ * A raster tile is atomic — one straddling the padding boundary above still
+ * renders in full, so at a low enough zoom a single tile can overshoot
+ * `CONTEXT_PADDING_DEGREES` by tens of degrees (confirmed empirically: a
+ * small facet cell naturally estimates z≈1–2, where a tile is 90°–180°
+ * wide, dragging in all of Africa well past the intended padding). Flooring
+ * the zoom to at least this, whenever `clampBoundsToDataPadding` actually
+ * reduced the bounds, guarantees a tile is at most 360/2⁶ = 5.625° wide —
+ * comfortably under half of `CONTEXT_PADDING_DEGREES`, so the worst-case
+ * overshoot still lands well short of real land.
+ */
+const MIN_ZOOM_WHEN_CONTEXT_CLAMPED = 6;
+/**
+ * Clamps `bounds`' horizontal extent to the data's own lon/lat bbox padded
+ * by `CONTEXT_PADDING_DEGREES` on each side, at the box's own center
+ * latitude — a no-op when `dataLonLatBounds` isn't supplied (a plot with no
+ * tile-layer-relevant data footprint, e.g. not a `domain: 'data'` fit; see
+ * `Plot.svelte`'s `usesDataFit`). Independent of, and applied on top of,
+ * `clampBoundsToWorld`'s own antimeridian-safety cap — that cap alone still
+ * permits up to a quarter-turn of the globe each way, comfortably reaching
+ * an unrelated continent instead of just nearby ocean (see `GeoPlot/Facet`
+ * stories' `Rows2Cols2` for the regression this fixes).
+ */
+function clampBoundsToDataPadding(projection, bounds, dataLonLatBounds) {
+    if (!dataLonLatBounds || !projection.invert)
+        return bounds;
+    const [minLon, , maxLon] = dataLonLatBounds;
+    const centerLonLat = projection.invert([bounds.left + bounds.width / 2, bounds.top + bounds.height / 2]);
+    if (!centerLonLat)
+        return bounds;
+    const west = projection([minLon - CONTEXT_PADDING_DEGREES, centerLonLat[1]]);
+    const east = projection([maxLon + CONTEXT_PADDING_DEGREES, centerLonLat[1]]);
+    if (!west || !east)
+        return bounds;
+    const left = Math.max(bounds.left, Math.min(west[0], east[0]));
+    const right = Math.min(bounds.left + bounds.width, Math.max(west[0], east[0]));
+    if (!(right > left))
+        return bounds;
+    return { ...bounds, left, width: right - left };
+}
 /**
  * Derives the visible XYZ tile grid from svelteplot's own already-fitted
  * projection (rather than this package computing/duplicating a `d3-geo` fit
@@ -104,10 +135,11 @@ function clampBoundsToWorld(projection, bounds) {
  * whose tile coverage is well-defined; callers are responsible for the
  * projection-compatibility check (see `Plot.svelte`'s validation effect).
  */
-export function visibleTiles(projection, rawBounds, tileSize = 256, minZoom = 0, maxZoom = 19) {
+export function visibleTiles(projection, rawBounds, tileSize = 256, minZoom = 0, maxZoom = 19, dataLonLatBounds) {
     if (!projection.invert)
         return [];
-    const bounds = clampBoundsToWorld(projection, rawBounds);
+    const bounds = clampBoundsToDataPadding(projection, clampBoundsToWorld(projection, rawBounds), dataLonLatBounds);
+    const contextClamped = bounds.width < rawBounds.width;
     const corners = [
         [bounds.left, bounds.top],
         [bounds.left + bounds.width, bounds.top],
@@ -117,11 +149,12 @@ export function visibleTiles(projection, rawBounds, tileSize = 256, minZoom = 0,
     const lonLats = corners.map((c) => projection.invert(c)).filter((p) => p != null);
     if (lonLats.length === 0)
         return [];
+    const effectiveMinZoom = contextClamped ? Math.max(minZoom, MIN_ZOOM_WHEN_CONTEXT_CLAMPED) : minZoom;
     const centerScreen = [bounds.left + bounds.width / 2, bounds.top + bounds.height / 2];
     const center = projection.invert(centerScreen);
     const z = center
-        ? Math.max(minZoom, Math.min(maxZoom, estimateZoomLevel(projection, center[0], center[1], tileSize) ?? minZoom))
-        : minZoom;
+        ? Math.max(effectiveMinZoom, Math.min(maxZoom, estimateZoomLevel(projection, center[0], center[1], tileSize) ?? effectiveMinZoom))
+        : effectiveMinZoom;
     const lons = lonLats.map((p) => p[0]);
     const lats = lonLats.map((p) => p[1]);
     const minTileX = Math.floor(lonToTileX(Math.min(...lons), z));
@@ -158,10 +191,10 @@ export function visibleTiles(projection, rawBounds, tileSize = 256, minZoom = 0,
  * affine in screen space by construction, so one linear fit applies
  * uniformly to every tile in the grid.
  */
-export function buildMercatorFit(projection, rawBounds, z) {
+export function buildMercatorFit(projection, rawBounds, z, dataLonLatBounds) {
     if (!projection.invert)
         return null;
-    const bounds = clampBoundsToWorld(projection, rawBounds);
+    const bounds = clampBoundsToDataPadding(projection, clampBoundsToWorld(projection, rawBounds), dataLonLatBounds);
     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.21",
+  "version": "0.0.22",
   "type": "module",
   "files": [
     "dist"