@fundar/data-chart-telling 0.0.14 → 0.0.16

package/dist/plots/utils/geoAccessors.js

@@ -0,0 +1,188 @@
+function flattenCoords(geom, out) {
+    switch (geom.type) {
+        case 'Point':
+            out.push(geom.coordinates);
+            break;
+        case 'MultiPoint':
+        case 'LineString':
+            for (const c of geom.coordinates)
+                out.push(c);
+            break;
+        case 'MultiLineString':
+        case 'Polygon':
+            for (const ring of geom.coordinates) {
+                for (const c of ring)
+                    out.push(c);
+            }
+            break;
+        case 'MultiPolygon':
+            for (const poly of geom.coordinates) {
+                for (const ring of poly) {
+                    for (const c of ring)
+                        out.push(c);
+                }
+            }
+            break;
+        case 'GeometryCollection':
+            for (const g of geom.geometries)
+                flattenCoords(g, out);
+            break;
+    }
+}
+function boundsCenter(coords) {
+    if (coords.length === 0)
+        return [0, 0];
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minY = Infinity;
+    let maxY = -Infinity;
+    for (const [x, y] of coords) {
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    }
+    return [(minX + maxX) / 2, (minY + maxY) / 2];
+}
+/**
+ * Bounding-box center of a geometry's flattened coordinates — a cheap
+ * approximation used for default label placement, not a true
+ * geographic/area centroid (no polygon-hole or geodesic-area weighting).
+ * For hover-matching specifically, see `geometryPartCentroids` instead —
+ * this single combined point can land far from every actual part of a
+ * multi-part geometry whose pieces are geographically spread out.
+ */
+export function geometryCentroid(geometry) {
+    const coords = [];
+    flattenCoords(geometry, coords);
+    return boundsCenter(coords);
+}
+/**
+ * Splits a geometry into its disjoint parts: one `Polygon` per element of a
+ * `MultiPolygon`'s `coordinates`, one `LineString` per element of a
+ * `MultiLineString`'s, `GeometryCollection` recursed and flattened, and any
+ * other geometry type returned unchanged as its own single-element array.
+ * The shared building block behind `geometryPartCentroids` (one centroid per
+ * part) and `filterGeometryParts` (keep/drop whole parts).
+ */
+export function splitGeometryParts(geometry) {
+    switch (geometry.type) {
+        case 'MultiPolygon':
+            return geometry.coordinates.map((polygon) => ({ type: 'Polygon', coordinates: polygon }));
+        case 'MultiLineString':
+            return geometry.coordinates.map((line) => ({ type: 'LineString', coordinates: line }));
+        case 'GeometryCollection':
+            return geometry.geometries.flatMap((g) => splitGeometryParts(g));
+        default:
+            return [geometry];
+    }
+}
+/**
+ * Like `geometryCentroid`, but returns one point per disjoint part instead
+ * of a single bounding-box center across all of them. A `MultiPolygon`
+ * whose parts are geographically far apart — e.g. Argentina's "Tierra del
+ * Fuego, Antártida e Islas del Atlántico Sur" province, whose `MultiPolygon`
+ * spans the mainland island, the Antarctic sector, and the South Atlantic
+ * islands in one feature — would otherwise get a single hover point
+ * stranded somewhere between all of them, matching hovers over *none* of
+ * the actually-rendered shapes. Multiple points attributed to the same
+ * feature is fine for hover-matching (nearest point wins, whichever part
+ * that is); it's only label placement (`geometryCentroid`) that needs a
+ * single point.
+ */
+export function geometryPartCentroids(geometry) {
+    return splitGeometryParts(geometry).map((part) => geometryCentroid(part));
+}
+/**
+ * Keeps or drops each disjoint part of a geometry (see `splitGeometryParts`)
+ * based on a per-part predicate, reassembling a geometry of the same type
+ * from whatever survives — `null` if nothing does. Used to let a single
+ * feature's geometry be split between the main map and an `inset` marker
+ * (see `GeoDataProps.excludeParts`/`GeoInsetMarker.featurePartsFilter`)
+ * without preprocessing the source data: e.g. a province whose `MultiPolygon`
+ * spans both a mainland part and a far-flung part can have the main map
+ * exclude the latter while an inset shows only it.
+ */
+export function filterGeometryParts(geometry, keep) {
+    const parts = splitGeometryParts(geometry);
+    const keptParts = parts.filter((part) => keep({ centroid: geometryCentroid(part), geometry: part }));
+    if (keptParts.length === parts.length)
+        return geometry;
+    if (keptParts.length === 0)
+        return null;
+    if (parts.length === 1)
+        return keptParts[0];
+    switch (geometry.type) {
+        case 'MultiPolygon':
+            return { type: 'MultiPolygon', coordinates: keptParts.map((part) => part.coordinates) };
+        case 'MultiLineString':
+            return {
+                type: 'MultiLineString',
+                coordinates: keptParts.map((part) => part.coordinates),
+            };
+        case 'GeometryCollection':
+            return { type: 'GeometryCollection', geometries: keptParts };
+        default:
+            return geometry;
+    }
+}
+/** Default `featureId`: `feature.id`, else `properties.id`, else `properties.name`. */
+export function defaultFeatureId(f) {
+    const props = f.properties;
+    return String(f.id ?? props?.id ?? props?.name ?? '');
+}
+function toRad(deg) {
+    return (deg * Math.PI) / 180;
+}
+function toDeg(rad) {
+    return (rad * 180) / Math.PI;
+}
+/**
+ * Densifies a great-circle arc between two lon/lat points into `steps + 1`
+ * points via spherical linear interpolation (slerp) — used to draw a `link`
+ * marker's geodesic curve through the `Geo` mark (see `Plot.svelte`).
+ *
+ * Not delegated to svelteplot's own `Link` mark: its 0.14.2 projection
+ * integration (`Mark.svelte`'s paired-channel handling) reads a single
+ * `row.x`/`row.y` pair regardless of channel suffix, so a mark bound to
+ * `x1`/`y1`/`x2`/`y2` (never plain `x`/`y`) resolves every point as invalid
+ * whenever the plot has an active `projection` scale — which GeoPlot always
+ * does. `Geo` has no such limitation (geo marks are explicitly excluded from
+ * that code path), so a manually-interpolated `LineString` feature sidesteps
+ * the bug entirely while still producing the same geodesic visual.
+ */
+export function greatCircleInterpolate(lon1, lat1, lon2, lat2, steps = 64) {
+    const phi1 = toRad(lat1);
+    const lambda1 = toRad(lon1);
+    const phi2 = toRad(lat2);
+    const lambda2 = toRad(lon2);
+    const sinPhi1 = Math.sin(phi1);
+    const cosPhi1 = Math.cos(phi1);
+    const sinPhi2 = Math.sin(phi2);
+    const cosPhi2 = Math.cos(phi2);
+    const d = 2 *
+        Math.asin(Math.sqrt(Math.sin((phi2 - phi1) / 2) ** 2 + cosPhi1 * cosPhi2 * Math.sin((lambda2 - lambda1) / 2) ** 2));
+    if (!Number.isFinite(d) || d === 0) {
+        return [
+            [lon1, lat1],
+            [lon2, lat2],
+        ];
+    }
+    const points = [];
+    for (let i = 0; i <= steps; i++) {
+        const f = i / steps;
+        const a = Math.sin((1 - f) * d) / Math.sin(d);
+        const b = Math.sin(f * d) / Math.sin(d);
+        const x = a * cosPhi1 * Math.cos(lambda1) + b * cosPhi2 * Math.cos(lambda2);
+        const y = a * cosPhi1 * Math.sin(lambda1) + b * cosPhi2 * Math.sin(lambda2);
+        const z = a * sinPhi1 + b * sinPhi2;
+        const phi = Math.atan2(z, Math.sqrt(x * x + y * y));
+        const lambda = Math.atan2(y, x);
+        points.push([toDeg(lambda), toDeg(phi)]);
+    }
+    return points;
+}

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

@@ -0,0 +1,14 @@
+import type { Segment } from '../../types/plots/segments/config';
+import type { SegmentsConfig } from '../../types/plots/props';
+/** Feature-specific segments listed after 'default' so they override it on merge (see `resolveFeatureStyle`). */
+export declare function resolveSegmentsForFeature<TStyle>(segments: SegmentsConfig<TStyle>, featureId: string): Segment<TStyle>[];
+/**
+ * A geo feature is atomic — `Segment.areas` (x/y range restriction) doesn't
+ * apply, so every entry under a key is treated as a flat style patch applied
+ * in order: `'default'` entries apply first, feature-specific entries
+ * override. This intentionally does NOT reuse `segments.ts`'s
+ * `validateSegments` — its "only the first catch-all wins" warning assumes
+ * area-based semantics that don't hold here, since every geo segment entry
+ * merges rather than being dropped.
+ */
+export declare function resolveFeatureStyle<TStyle extends object>(segments: SegmentsConfig<TStyle>, featureId: string): TStyle;

package/dist/plots/utils/geoSegments.js

@@ -0,0 +1,17 @@
+const DEFAULT_KEY = 'default';
+/** Feature-specific segments listed after 'default' so they override it on merge (see `resolveFeatureStyle`). */
+export function resolveSegmentsForFeature(segments, featureId) {
+    return [...(segments[DEFAULT_KEY] ?? []), ...(segments[featureId] ?? [])];
+}
+/**
+ * A geo feature is atomic — `Segment.areas` (x/y range restriction) doesn't
+ * apply, so every entry under a key is treated as a flat style patch applied
+ * in order: `'default'` entries apply first, feature-specific entries
+ * override. This intentionally does NOT reuse `segments.ts`'s
+ * `validateSegments` — its "only the first catch-all wins" warning assumes
+ * area-based semantics that don't hold here, since every geo segment entry
+ * merges rather than being dropped.
+ */
+export function resolveFeatureStyle(segments, featureId) {
+    return resolveSegmentsForFeature(segments, featureId).reduce((acc, seg) => ({ ...acc, ...(seg.style ?? {}) }), {});
+}

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

@@ -0,0 +1,15 @@
+import type { LegendDisabledStyle } from '../../types/charts/legend';
+import type { StrokeStyle, DotStyle } from '../../types/plots/styling';
+/**
+ * The three per-mark override layers a legend "disabled" state can apply,
+ * derived once from a {@link LegendDisabledStyle}. Each is `undefined` when
+ * there's no active override, so call sites can slot the result in as just
+ * one more `??` layer ahead of their existing segment-style/default-color
+ * chain — no branching needed at the call site.
+ */
+export declare function disabledStrokeOverride(disabled: LegendDisabledStyle | undefined): StrokeStyle | undefined;
+export declare function disabledDotsOverride(disabled: LegendDisabledStyle | undefined): DotStyle | undefined;
+export declare function disabledFillOverride(disabled: LegendDisabledStyle | undefined): {
+    fill?: string;
+    fillOpacity?: number;
+} | undefined;

package/dist/plots/utils/legendDisabled.js

@@ -0,0 +1,41 @@
+/**
+ * The three per-mark override layers a legend "disabled" state can apply,
+ * derived once from a {@link LegendDisabledStyle}. Each is `undefined` when
+ * there's no active override, so call sites can slot the result in as just
+ * one more `??` layer ahead of their existing segment-style/default-color
+ * chain — no branching needed at the call site.
+ */
+export function disabledStrokeOverride(disabled) {
+    if (!disabled)
+        return undefined;
+    return {
+        stroke: disabled.stroke?.stroke,
+        strokeWidth: disabled.stroke?.strokeWidth,
+        strokeOpacity: disabled.stroke?.strokeOpacity ?? disabled.opacity,
+        strokeDasharray: disabled.stroke?.strokeDasharray,
+        strokeLinecap: disabled.stroke?.strokeLinecap,
+        strokeLinejoin: disabled.stroke?.strokeLinejoin,
+    };
+}
+export function disabledDotsOverride(disabled) {
+    if (!disabled)
+        return undefined;
+    return {
+        dotRadius: disabled.dots?.dotRadius,
+        dotFill: disabled.dots?.dotFill,
+        dotFillOpacity: disabled.dots?.dotFillOpacity ?? disabled.opacity,
+        dotSymbol: disabled.dots?.dotSymbol,
+        dotStroke: disabled.dots?.dotStroke,
+        dotStrokeWidth: disabled.dots?.dotStrokeWidth,
+        dotStrokeOpacity: disabled.dots?.dotStrokeOpacity ?? disabled.opacity,
+        dotStrokeDasharray: disabled.dots?.dotStrokeDasharray,
+    };
+}
+export function disabledFillOverride(disabled) {
+    if (!disabled)
+        return undefined;
+    return {
+        fill: disabled.fill,
+        fillOpacity: disabled.fillOpacity ?? disabled.opacity,
+    };
+}

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

@@ -1,11 +1,14 @@
-import type { AxisValue, Series } from '../../types/plots/common';
-import type { Segment, Segments, LineSegmentStyle, VisualGroup } from '../../types/plots/styles';
+import type { AxisValue } from '../../types/plots/axis';
+import type { Series } from '../../types/plots/data/common';
+import type { LineSegmentStyle } from '../../types/plots/segments/common';
+import type { Segment, VisualGroup } from '../../types/plots/segments/config';
+import type { SegmentsConfig } from '../../types/plots/props';
 /**
  * Returns the flat {@link Segment} list for one series.
  * Series-specific segments are added before `'default'` segments so that
  * series-specific catch-alls win over default catch-alls on tie-breaks.
  */
-export declare function resolveSegmentsForSeries<TStyle>(segments: Segments<TStyle>, seriesName: string): Segment<TStyle>[];
+export declare function resolveSegmentsForSeries<TStyle>(segments: SegmentsConfig<TStyle>, seriesName: string): Segment<TStyle>[];
 /** Returns true when `xVal` falls inside any of a segment's x ranges. */
 export declare function matchesSegmentX<TStyle>(xVal: AxisValue, seg: Segment<TStyle>): boolean;
 /**
@@ -22,10 +25,16 @@ export declare function getDataForSegments<TData, TStyle>(data: TData[], xAccess
  * (no `areas`) in the same series list. Since catch-alls are evaluated last
  * and in order, only the first one can ever match; later ones are dead code.
  */
-export declare function validateSegments<TStyle>(segments: Segments<TStyle>): void;
+export declare function validateSegments<TStyle>(segments: SegmentsConfig<TStyle>): void;
 /**
  * Builds the full list of visual groups — one per series — ready to render.
  * Each group's `visualSegments` is derived by resolving the flat segment list
  * for that series from all groups in `segments`.
+ *
+ * `connect` bridges adjacent visual segments so a *continuous* mark (line)
+ * has no visual gap at their boundary — the default, since `buildGroupedSeries`
+ * itself defaults `TStyle` to {@link LineSegmentStyle}. Discrete marks (bar,
+ * pyramid) have no gap to bridge; pass `connect: false` so boundary rows
+ * aren't duplicated as an extra, separately-styled mark.
  */
-export declare function buildGroupedSeries<S extends Series<any>, TStyle = LineSegmentStyle>(seriesList: S[], segments: Segments<TStyle>): VisualGroup<S, TStyle>[];
+export declare function buildGroupedSeries<S extends Series<any>, TStyle = LineSegmentStyle>(seriesList: S[], segments: SegmentsConfig<TStyle>, connect?: boolean): VisualGroup<S, TStyle>[];

package/dist/plots/utils/segments.js

@@ -90,7 +90,7 @@ function mergeStyles(base, override) {
     return result;
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function resolveSeriesSegments(series, segs) {
+function resolveSeriesSegments(series, segs, connect) {
     if (!segs.length) {
         return [{ data: series.data, style: {} }];
     }
@@ -147,14 +147,18 @@ function resolveSeriesSegments(series, segs) {
     for (let r = 0; r < runs.length; r++) {
         const run = runs[r];
         if (run.segIdx === -1) {
-            // Unmatched run: insert bridge points so the line connects to adjacent
-            // user segments without a gap.
-            const bridged = [];
-            if (r > 0)
-                bridged.push(runs[r - 1].data[runs[r - 1].data.length - 1]);
-            bridged.push(...run.data);
-            if (r < runs.length - 1)
-                bridged.push(runs[r + 1].data[0]);
+            // Unmatched run: for a continuous mark (line), insert bridge points so
+            // it connects to adjacent user segments without a visual gap. Discrete
+            // marks (bar, pyramid) have no such gap to bridge — bridging would just
+            // duplicate the neighboring runs' boundary rows as an extra, wrongly
+            // styled mark at that same category.
+            const bridged = [...run.data];
+            if (connect) {
+                if (r > 0)
+                    bridged.unshift(runs[r - 1].data[runs[r - 1].data.length - 1]);
+                if (r < runs.length - 1)
+                    bridged.push(runs[r + 1].data[0]);
+            }
             defaultVisual.push({ data: bridged, style: {} });
         }
         else {
@@ -170,9 +174,11 @@ function resolveSeriesSegments(series, segs) {
             // When the next run is also a user segment (no unmatched data between them),
             // insert a line-only connector so the lines join without a gap. Using a
             // separate mark (rather than appending a bridge point to the current run)
-            // avoids rendering an extra dot at the shared boundary point.
+            // avoids rendering an extra dot at the shared boundary point. Skipped
+            // entirely for discrete marks (see above) — it would duplicate both
+            // runs' boundary rows as an extra mark.
             const nextRun = runs[r + 1];
-            if (nextRun && nextRun.segIdx !== -1) {
+            if (connect && nextRun && nextRun.segIdx !== -1) {
                 connectors.push({
                     data: [run.data[run.data.length - 1], nextRun.data[0]],
                     style: connectorStyle,
@@ -190,10 +196,16 @@ function resolveSeriesSegments(series, segs) {
  * Builds the full list of visual groups — one per series — ready to render.
  * Each group's `visualSegments` is derived by resolving the flat segment list
  * for that series from all groups in `segments`.
+ *
+ * `connect` bridges adjacent visual segments so a *continuous* mark (line)
+ * has no visual gap at their boundary — the default, since `buildGroupedSeries`
+ * itself defaults `TStyle` to {@link LineSegmentStyle}. Discrete marks (bar,
+ * pyramid) have no gap to bridge; pass `connect: false` so boundary rows
+ * aren't duplicated as an extra, separately-styled mark.
  */
-export function buildGroupedSeries(seriesList, segments) {
+export function buildGroupedSeries(seriesList, segments, connect = true) {
     return seriesList.map((s) => ({
         series: s,
-        visualSegments: resolveSeriesSegments(s, resolveSegmentsForSeries(segments, s.name)),
+        visualSegments: resolveSeriesSegments(s, resolveSegmentsForSeries(segments, s.name), connect),
     }));
 }

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

@@ -0,0 +1,89 @@
+export type TileCoord = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type ScreenBounds = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/** The subset of a `d3-geo`-style projection this module needs. */
+export type ProjectionLike = {
+    (point: [number, number]): [number, number] | null;
+    invert?(point: [number, number]): [number, number] | null;
+};
+/** The minimal geometry-stream shape a projection's `.stream()` accepts — kept local instead of importing `d3-geo`'s own `GeoStream` type, so this module stays dependency-free. */
+type MinimalStream = {
+    point: (x: number, y: number, z?: number) => void;
+    lineStart: () => void;
+    lineEnd: () => void;
+    polygonStart: () => void;
+    polygonEnd: () => void;
+    sphere?: () => void;
+};
+/** What `toProjectionLike` needs from a svelteplot-resolved projection. */
+export type StreamingProjection = {
+    stream: (s: MinimalStream) => MinimalStream;
+    invert?: (point: [number, number]) => [number, number] | null;
+};
+/**
+ * Adapts a svelteplot-resolved projection (which exposes `.stream()`/
+ * `.invert()`, but — unlike a raw `d3-geo` projection instance — isn't
+ * itself callable as `(point) => [x, y]`) into a `ProjectionLike`, by
+ * feeding a single point through its stream pipeline and capturing the
+ * projected output.
+ */
+export declare function toProjectionLike(projection: StreamingProjection): ProjectionLike;
+/**
+ * Derives the visible XYZ tile grid from svelteplot's own already-fitted
+ * projection (rather than this package computing/duplicating a `d3-geo` fit
+ * itself) — see `TileLayer.svelte`. Only correct for Mercator-family
+ * projections, where a screen-space rectangle maps back to a lon/lat bbox
+ * 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[];
+/** 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;
+    screenLeft: number;
+    screenTop: number;
+    tileXAtLeft: number;
+    tileYAtTop: number;
+    pxPerTileX: number;
+    pxPerTileY: number;
+};
+/**
+ * Builds an affine tile-space → screen-space mapping from two reliable
+ * anchor points — `bounds`' own top-left/bottom-right corners, inverted
+ * back to lon/lat — rather than forward-projecting each tile's own corners
+ * individually (what this replaced). That per-tile approach broke under a
+ * projection whose scale/translate were fit to a *custom* domain rather
+ * than set via its own `.scale()`/`.translate()`: `d3-geo`'s cylindrical
+ * projections (mercator included) auto-install an internal `clipExtent`
+ * sized to whatever scale/translate they were constructed or last
+ * `.scale()`/`.translate()`-called with (guarding against the y → ±Infinity
+ * blowup near the poles); svelteplot's own domain-fitting wraps the
+ * *unmodified* projection instance in an external transform instead of
+ * calling those setters, so that internal clip keeps silently rejecting
+ * forward-projected points outside its stale bounds — nulling out most of
+ * a tile grid even for tiles nowhere near a pole. `.invert()` isn't routed
+ * through that clip, so anchoring to two known-good inverted corners
+ * sidesteps it entirely — sound because Mercator's tile space (longitude,
+ * and the standard log-tan latitude transform used by `latToTileY`) is
+ * 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;
+/** 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;
+/**
+ * Fills `{z}/{x}/{y}` placeholders in a tile URL template. Also supports
+ * `{-y}` for TMS-scheme sources (e.g. IGN's tile services), whose row index
+ * counts from the south instead of the north — the standard XYZ-to-TMS
+ * conversion `2^z - 1 - y`.
+ */
+export declare function tileUrl(template: string, tile: TileCoord): string;
+export {};

package/dist/plots/utils/tiles.js

@@ -0,0 +1,159 @@
+/**
+ * Adapts a svelteplot-resolved projection (which exposes `.stream()`/
+ * `.invert()`, but — unlike a raw `d3-geo` projection instance — isn't
+ * itself callable as `(point) => [x, y]`) into a `ProjectionLike`, by
+ * feeding a single point through its stream pipeline and capturing the
+ * projected output.
+ */
+export function toProjectionLike(projection) {
+    const fn = ((point) => {
+        let result = null;
+        const sink = {
+            point: (x, y) => {
+                result = [x, y];
+            },
+            lineStart() { },
+            lineEnd() { },
+            polygonStart() { },
+            polygonEnd() { },
+        };
+        projection.stream(sink).point(point[0], point[1]);
+        return result;
+    });
+    if (projection.invert)
+        fn.invert = (point) => projection.invert(point);
+    return fn;
+}
+function lonToTileX(lon, z) {
+    return ((lon + 180) / 360) * 2 ** z;
+}
+function latToTileY(lat, z) {
+    const rad = (lat * Math.PI) / 180;
+    return ((1 - Math.log(Math.tan(rad) + 1 / Math.cos(rad)) / Math.PI) / 2) * 2 ** z;
+}
+/**
+ * Picks an integer XYZ zoom level whose tile pixel density roughly matches
+ * the projection's *current* pixels-per-degree at the map center — so tiles
+ * neither look blurry (too coarse) nor waste bandwidth (too fine).
+ */
+function estimateZoomLevel(projection, centerLon, centerLat, tileSize) {
+    const eps = 0.01;
+    const p0 = projection([centerLon, centerLat]);
+    const p1 = projection([centerLon + eps, centerLat]);
+    if (!p0 || !p1)
+        return null;
+    const pixelsPerDegree = Math.abs(p1[0] - p0[0]) / eps;
+    const worldPixelsAtZ0 = tileSize / 360;
+    const ratio = pixelsPerDegree / worldPixelsAtZ0;
+    if (!Number.isFinite(ratio) || ratio <= 0)
+        return null;
+    return Math.round(Math.log2(ratio));
+}
+/**
+ * Derives the visible XYZ tile grid from svelteplot's own already-fitted
+ * projection (rather than this package computing/duplicating a `d3-geo` fit
+ * itself) — see `TileLayer.svelte`. Only correct for Mercator-family
+ * projections, where a screen-space rectangle maps back to a lon/lat bbox
+ * 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) {
+    if (!projection.invert)
+        return [];
+    const corners = [
+        [bounds.left, bounds.top],
+        [bounds.left + bounds.width, bounds.top],
+        [bounds.left, bounds.top + bounds.height],
+        [bounds.left + bounds.width, bounds.top + bounds.height],
+    ];
+    const lonLats = corners.map((c) => projection.invert(c)).filter((p) => p != null);
+    if (lonLats.length === 0)
+        return [];
+    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;
+    const lons = lonLats.map((p) => p[0]);
+    const lats = lonLats.map((p) => p[1]);
+    const minTileX = Math.floor(lonToTileX(Math.min(...lons), z));
+    const maxTileX = Math.floor(lonToTileX(Math.max(...lons), z));
+    const minTileY = Math.floor(latToTileY(Math.max(...lats), z));
+    const maxTileY = Math.floor(latToTileY(Math.min(...lats), z));
+    const maxTile = 2 ** z - 1;
+    const tiles = [];
+    for (let x = Math.max(0, minTileX); x <= Math.min(maxTile, maxTileX); x++) {
+        for (let y = Math.max(0, minTileY); y <= Math.min(maxTile, maxTileY); y++) {
+            tiles.push({ x, y, z });
+        }
+    }
+    return tiles;
+}
+/**
+ * Builds an affine tile-space → screen-space mapping from two reliable
+ * anchor points — `bounds`' own top-left/bottom-right corners, inverted
+ * back to lon/lat — rather than forward-projecting each tile's own corners
+ * individually (what this replaced). That per-tile approach broke under a
+ * projection whose scale/translate were fit to a *custom* domain rather
+ * than set via its own `.scale()`/`.translate()`: `d3-geo`'s cylindrical
+ * projections (mercator included) auto-install an internal `clipExtent`
+ * sized to whatever scale/translate they were constructed or last
+ * `.scale()`/`.translate()`-called with (guarding against the y → ±Infinity
+ * blowup near the poles); svelteplot's own domain-fitting wraps the
+ * *unmodified* projection instance in an external transform instead of
+ * calling those setters, so that internal clip keeps silently rejecting
+ * forward-projected points outside its stale bounds — nulling out most of
+ * a tile grid even for tiles nowhere near a pole. `.invert()` isn't routed
+ * through that clip, so anchoring to two known-good inverted corners
+ * sidesteps it entirely — sound because Mercator's tile space (longitude,
+ * and the standard log-tan latitude transform used by `latToTileY`) is
+ * affine in screen space by construction, so one linear fit applies
+ * uniformly to every tile in the grid.
+ */
+export function buildMercatorFit(projection, bounds, z) {
+    if (!projection.invert)
+        return null;
+    const topLeft = projection.invert([bounds.left, bounds.top]);
+    const bottomRight = projection.invert([bounds.left + bounds.width, bounds.top + bounds.height]);
+    if (!topLeft || !bottomRight)
+        return null;
+    const tileXAtLeft = lonToTileX(topLeft[0], z);
+    const tileXAtRight = lonToTileX(bottomRight[0], z);
+    const tileYAtTop = latToTileY(topLeft[1], z);
+    const tileYAtBottom = latToTileY(bottomRight[1], z);
+    if (tileXAtRight === tileXAtLeft || tileYAtBottom === tileYAtTop)
+        return null;
+    return {
+        z,
+        screenLeft: bounds.left,
+        screenTop: bounds.top,
+        tileXAtLeft,
+        tileYAtTop,
+        pxPerTileX: bounds.width / (tileXAtRight - tileXAtLeft),
+        pxPerTileY: bounds.height / (tileYAtBottom - tileYAtTop),
+    };
+}
+/** 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 function tileScreenBounds(fit, tile) {
+    if (tile.z !== fit.z)
+        return null;
+    return {
+        left: fit.screenLeft + (tile.x - fit.tileXAtLeft) * fit.pxPerTileX,
+        top: fit.screenTop + (tile.y - fit.tileYAtTop) * fit.pxPerTileY,
+        width: fit.pxPerTileX,
+        height: fit.pxPerTileY,
+    };
+}
+/**
+ * Fills `{z}/{x}/{y}` placeholders in a tile URL template. Also supports
+ * `{-y}` for TMS-scheme sources (e.g. IGN's tile services), whose row index
+ * counts from the south instead of the north — the standard XYZ-to-TMS
+ * conversion `2^z - 1 - y`.
+ */
+export function tileUrl(template, tile) {
+    return template
+        .replace('{z}', String(tile.z))
+        .replace('{x}', String(tile.x))
+        .replace('{-y}', String(2 ** tile.z - 1 - tile.y))
+        .replace('{y}', String(tile.y));
+}

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

@@ -0,0 +1,9 @@
+import type { GeoFeature, Topology } from '../../types/plots/data/geo';
+export declare function isTopology(data: unknown): data is Topology;
+/**
+ * Converts a TopoJSON `Topology` to GeoJSON via `topojson-client`'s
+ * `feature()`, loaded with a dynamic import so the package works perfectly
+ * for consumers who never install `topojson-client` — it's an optional peer
+ * dependency (see package.json), never statically imported.
+ */
+export declare function topologyToGeoJson<TProps extends Record<string, unknown>>(topology: Topology, object: string): Promise<GeoFeature<TProps>[]>;