@fundar/data-chart-telling 0.0.20 → 0.0.22

package/dist/layout/geo/GeoLayout.svelte

@@ -30,7 +30,7 @@
     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`. */
+    /** Forwarded to `TileLayer` — see `Plot.svelte`'s `dataLonLatBounds`. */
     dataLonLatBounds?: [number, number, number, number] | null;
     children: Snippet;
   } = $props();

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

@@ -15,7 +15,7 @@ type $$ComponentProps = {
         k: number;
     };
     tileLayer?: GeoTileLayerConfig;
-    /** Forwarded to `TileLayer` — see its own prop doc / `clipBoundsToData`. */
+    /** Forwarded to `TileLayer` — see `Plot.svelte`'s `dataLonLatBounds`. */
     dataLonLatBounds?: [number, number, number, number] | null;
     children: Snippet;
 };

package/dist/plots/geo/Plot.svelte

@@ -6,7 +6,6 @@
   import {
     geometryCentroid,
     geometryLonLatBounds,
-    mercatorAspectRatio,
     geometryPartCentroids,
     filterGeometryParts,
     defaultFeatureId,
@@ -146,19 +145,20 @@
     });
   });
 
-  // ── Data footprint — the rendered geometry's own lon/lat extent. Powers
-  // two independent things below: `TileLayer`'s clip-to-data (see
-  // `clipBoundsToData`'s doc comment) and `containedSize`'s contain-and-center
-  // sizing. Only computed for a `domain: 'data'` fit (see `usesDataFit`) —
-  // that's the specific case where the projection's own scale was chosen to
-  // match *this* extent, so it's also the only case this bbox is a correct
-  // stand-in for "what the projection actually fit to". Cost is a single
-  // O(total coordinate count) pass. ────
-  const usesDataFit = $derived(
-    typeof scales.projection === 'object' && scales.projection?.domain === 'data',
-  );
+  // ── Tile-layer / projection compatibility ────────────────────────────────
+  $effect(() => {
+    if (!styles.tileLayer) return;
+    const proj = scales.projection;
+    const name = typeof proj === 'string' ? proj : proj?.type;
+    if (name && name !== 'mercator' && name !== 'transverse-mercator') {
+      console.warn(
+        `GeoPlot: styles.tileLayer only renders correctly with a mercator-family projection — got "${name}". Rendering anyway.`,
+      );
+    }
+  });
+
   const dataLonLatBounds = $derived.by((): [number, number, number, number] | null => {
-    if (!usesDataFit) return null;
+    if (!styles.tileLayer) return null;
     let minLon = Infinity;
     let maxLon = -Infinity;
     let minLat = Infinity;
@@ -174,50 +174,6 @@
     return minLon === Infinity ? null : [minLon, minLat, maxLon, maxLat];
   });
 
-  /**
-   * The box the map itself actually renders into — `width`/`height`
-   * shrunk (never grown) to `dataLonLatBounds`' own Mercator aspect ratio,
-   * the same way `object-fit: contain` sizes an image. Without this, a
-   * `domain: 'data'` fit already internally letterboxes the *projection*
-   * to preserve the data's true shape whenever the outer box's aspect
-   * doesn't match it (e.g. a tall/narrow country handed a short/wide facet
-   * cell) — but previously the outer SVG itself stayed stretched to the
-   * full box regardless, leaving that letterboxed margin as dead space
-   * (blank, or — before `clipBoundsToData` — filled with irrelevant tiles).
-   * Shrinking the actual rendered box to match removes that margin instead
-   * of just hiding what was in it; the template below centers this smaller
-   * box within the full `{width}×{height}` area so the map still occupies
-   * the same visual position within its facet cell.
-   *
-   * Margins (`margins`/`GEO_MARGIN_ESTIMATE`) are deliberately not netted
-   * out of this fit — they're small relative to typical facet-cell sizes,
-   * and doing this exactly would mean duplicating `BasePlotLayout`'s own
-   * private margin resolution here.
-   */
-  const containedSize = $derived.by((): { width: number; height: number } => {
-    const full = { width, height };
-    if (!dataLonLatBounds) return full;
-    const aspect = mercatorAspectRatio(dataLonLatBounds);
-    if (!aspect) return full;
-    const boxAspect = width / height;
-    if (!(boxAspect > 0)) return full;
-    return aspect > boxAspect
-      ? { width, height: width / aspect }
-      : { width: height * aspect, height };
-  });
-
-  // ── Tile-layer / projection compatibility ────────────────────────────────
-  $effect(() => {
-    if (!styles.tileLayer) return;
-    const proj = scales.projection;
-    const name = typeof proj === 'string' ? proj : proj?.type;
-    if (name && name !== 'mercator' && name !== 'transverse-mercator') {
-      console.warn(
-        `GeoPlot: styles.tileLayer only renders correctly with a mercator-family projection — got "${name}". Rendering anyway.`,
-      );
-    }
-  });
-
   // ── 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);
@@ -545,8 +501,8 @@
         {@const insetContentBox = {
           left: numericMargins.left,
           top: numericMargins.top,
-          width: Math.max(0, containedSize.width - numericMargins.left - numericMargins.right),
-          height: Math.max(0, containedSize.height - numericMargins.top - numericMargins.bottom),
+          width: Math.max(0, width - numericMargins.left - numericMargins.right),
+          height: Math.max(0, height - numericMargins.top - numericMargins.bottom),
         }}
         <InsetMarker
           marker={marker as GeoInsetMarker<TProps>}
@@ -574,10 +530,9 @@
   `equirectangular` projection, whose x/y truly are linear in lon/lat) and
   is a no-op for every other mark type.
 -->
-<div class="dct-geo-contain" style:width="{width}px" style:height="{height}px">
 <BasePlotLayout
-  width={containedSize.width}
-  height={containedSize.height}
+  {width}
+  {height}
   data={hoverCandidates}
   getX={hoverGetX}
   getY={hoverGetY}
@@ -598,8 +553,8 @@
 >
   {#snippet children({ matchedPoints, numericMargins })}
     <GeoLayout
-      width={containedSize.width}
-      height={containedSize.height}
+      {width}
+      {height}
       {numericMargins}
       zoomTransform={geoZoom.transform}
       tileLayer={styles.tileLayer}
@@ -645,17 +600,3 @@
     {/if}
   {/snippet}
 </BasePlotLayout>
-</div>
-
-<style>
-  /**
-   * Centers `BasePlotLayout`'s own (possibly smaller, `containedSize`-fit)
-   * box within the full area the facet grid actually allotted this plot —
-   * see `containedSize`'s doc comment.
-   */
-  .dct-geo-contain {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-  }
-</style>

package/dist/plots/geo/TileLayer.svelte

@@ -6,7 +6,6 @@
     tileScreenBounds,
     tileUrl,
     toProjectionLike,
-    clipBoundsToData,
     type StreamingProjection,
   } from '../utils/tiles';
   import type { GeoTileLayerConfig } from '../../types/plots/styles/geo';
@@ -34,7 +33,7 @@
     top: number;
     width: number;
     height: number;
-    /** The rendered geometry's own lon/lat extent — see `clipBoundsToData`. */
+    /** Forwarded to `visibleTiles`/`buildMercatorFit` — see `Plot.svelte`'s `dataLonLatBounds`. */
     dataLonLatBounds?: [number, number, number, number] | null;
   } = $props();
 
@@ -48,18 +47,16 @@
   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, clippedBounds, 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
@@ -67,7 +64,7 @@
   // each tile's own corners individually.
   const fit = $derived.by(() => {
     if (!projection || tiles.length === 0) return null;
-    return buildMercatorFit(projection, clippedBounds, tiles[0].z);
+    return buildMercatorFit(projection, { left, top, width, height }, tiles[0].z, dataLonLatBounds);
   });
 </script>
 

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

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

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

@@ -8,37 +8,6 @@ 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;
-/**
- * The width:height aspect ratio a Mercator(-family) projection naturally
- * produces for a `[minLon, minLat, maxLon, maxLat]` bounding box — i.e.
- * what a `domain: 'data'`-style projection fit (see `resolveProjection.ts`)
- * implicitly commits to before any letterboxing into a differently-shaped
- * box. `null` for a degenerate box: no lon or lat span, or a latitude
- * at/past ±90° where Mercator's `y` isn't finite.
- *
- * Longitude maps linearly to Mercator's `x`; latitude maps through the
- * standard `ln(tan(π/4 + φ/2))` transform to `y` — the same one
- * `tiles.ts`'s `latToTileY` uses, left unscaled by tile count here since
- * only the *ratio* between the two axes is wanted. Both axes share the same
- * scale by construction (Mercator is conformal), so this ratio is exactly
- * what a real `d3-geo` fit would produce for the same bbox — used by
- * `GeoPlot` to size itself down to its own data's footprint instead of
- * stretching into whatever box a facet grid happens to hand it (see
- * `Plot.svelte`'s `containedSize`).
- */
-export declare function mercatorAspectRatio(bounds: [number, 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
@@ -78,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

@@ -61,68 +61,6 @@ 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];
-}
-/**
- * The width:height aspect ratio a Mercator(-family) projection naturally
- * produces for a `[minLon, minLat, maxLon, maxLat]` bounding box — i.e.
- * what a `domain: 'data'`-style projection fit (see `resolveProjection.ts`)
- * implicitly commits to before any letterboxing into a differently-shaped
- * box. `null` for a degenerate box: no lon or lat span, or a latitude
- * at/past ±90° where Mercator's `y` isn't finite.
- *
- * Longitude maps linearly to Mercator's `x`; latitude maps through the
- * standard `ln(tan(π/4 + φ/2))` transform to `y` — the same one
- * `tiles.ts`'s `latToTileY` uses, left unscaled by tile count here since
- * only the *ratio* between the two axes is wanted. Both axes share the same
- * scale by construction (Mercator is conformal), so this ratio is exactly
- * what a real `d3-geo` fit would produce for the same bbox — used by
- * `GeoPlot` to size itself down to its own data's footprint instead of
- * stretching into whatever box a facet grid happens to hand it (see
- * `Plot.svelte`'s `containedSize`).
- */
-export function mercatorAspectRatio(bounds) {
-    const [minLon, minLat, maxLon, maxLat] = bounds;
-    if (minLat <= -90 || maxLat >= 90)
-        return null;
-    const toRad = (deg) => (deg * Math.PI) / 180;
-    const lonSpan = toRad(maxLon - minLon);
-    const mercatorY = (lat) => Math.log(Math.tan(Math.PI / 4 + toRad(lat) / 2));
-    const latSpan = Math.abs(mercatorY(maxLat) - mercatorY(minLat));
-    if (!(lonSpan > 0) || !(latSpan > 0) || !Number.isFinite(latSpan))
-        return null;
-    return lonSpan / latSpan;
-}
 /**
  * Splits a geometry into its disjoint parts: one `Polygon` per element of a
  * `MultiPolygon`'s `coordinates`, one `LineString` per element of a
@@ -197,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

@@ -36,32 +36,6 @@ 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
@@ -70,7 +44,7 @@ export declare function clipBoundsToData(projection: ProjectionLike, bounds: Scr
  * 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;
@@ -102,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

@@ -50,23 +50,9 @@ function estimateZoomLevel(projection, centerLon, centerLat, tileSize) {
     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.
+ * 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.
  */
 function clampBoundsToWorld(projection, bounds) {
     if (!projection.invert)
@@ -80,59 +66,66 @@ function clampBoundsToWorld(projection, bounds) {
     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)
+    const maxWidth = Math.abs(east[0] - west[0]) / 2;
+    if (!(maxWidth > 0) || bounds.width <= maxWidth)
         return bounds;
-    return { ...bounds, left: centerX - worldWidth / 2, width: worldWidth };
+    return { ...bounds, left: centerX - maxWidth / 2, width: maxWidth };
 }
 /**
- * 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.
+ * 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.
  *
- * 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.
+ * 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.
  */
-export function clipBoundsToData(projection, bounds, dataLonLatBounds) {
-    if (!dataLonLatBounds)
+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 [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)
+    const west = projection([minLon - CONTEXT_PADDING_DEGREES, centerLonLat[1]]);
+    const east = projection([maxLon + CONTEXT_PADDING_DEGREES, centerLonLat[1]]);
+    if (!west || !east)
         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))
+    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 { left, top, width: right - left, height: bottom - top };
+    return { ...bounds, left, width: right - left };
 }
 /**
  * Derives the visible XYZ tile grid from svelteplot's own already-fitted
@@ -142,10 +135,11 @@ export function clipBoundsToData(projection, bounds, dataLonLatBounds) {
  * 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],
@@ -155,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));
@@ -196,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.20",
+  "version": "0.0.22",
   "type": "module",
   "files": [
     "dist"