@fundar/data-chart-telling 0.0.13 → 0.0.15

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>[]>;

package/dist/plots/utils/topojson.js

@@ -0,0 +1,30 @@
+export function isTopology(data) {
+    return !!data && typeof data === 'object' && data.type === '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 async function topologyToGeoJson(topology, object) {
+    const obj = topology.objects[object];
+    if (!obj) {
+        throw new Error(`GeoPlot: topology.objects has no key "${object}".`);
+    }
+    let mod;
+    try {
+        // @ts-expect-error — topojson-client is an optional peer dependency; its
+        // type declarations are intentionally not resolved by our own build
+        // (`Topology` above is typed structurally instead), so this import is
+        // resolved purely at runtime.
+        mod = await import('topojson-client');
+    }
+    catch {
+        throw new Error("GeoPlot: `data` is a TopoJSON Topology, but 'topojson-client' isn't installed. " +
+            'Run `npm install topojson-client` (it\'s an optional peer dependency) or pass GeoJSON directly.');
+    }
+    const { feature } = mod;
+    const collection = feature(topology, obj);
+    return (collection.type === 'FeatureCollection' ? collection.features : [collection]);
+}

package/dist/types/charts/common.d.ts

@@ -1,5 +1,6 @@
 import type { Snippet } from 'svelte';
-import type { Accessor, AxisValue } from '../plots/common';
+import type { AxisValue } from '../plots/axis';
+import type { Accessor } from '../plots/data/common';
 import type { EasingName, EasingFn } from './interpolate';
 export type TimeValue = number;
 export type Orientation = 'horizontal' | 'vertical';

package/dist/types/charts/legend.d.ts

@@ -1,4 +1,4 @@
-import type { SymbolType, LineStyle } from '../plots/styles';
+import type { SymbolType, LineStyle } from '../plots/constants';
 export type LegendSectionType = 'discrete' | 'continuous';
 export type LegendItem = {
     name: string;

package/dist/types/charts/props.d.ts

@@ -1,7 +1,10 @@
 import type { Snippet } from 'svelte';
-import type { Accessor, AxisValue, ScalesConfig, MarginConfig } from '../plots/common';
-import type { PlotStyles, Segments } from '../plots/styles';
-import type { Marker } from '../plots/markers';
+import type { AxisValue } from '../plots/axis';
+import type { Accessor } from '../plots/data/common';
+import type { AxisBasedScalesConfig } from '../plots/props';
+import type { BasePlotStyles } from '../plots/styles/common';
+import type { SegmentsConfig, MarginConfig } from '../plots/props';
+import type { Marker } from '../markers/common';
 import type { TooltipProp } from '../layout/tooltip';
 import type { LegendSection } from './legend';
 import type { FacetConfig, TimelineConfig } from './common';
@@ -27,10 +30,10 @@ export type ChartProps<TRow extends Record<string, unknown>, TSegmentStyle exten
     x: Accessor<TRow, AxisValue>;
     y: Accessor<TRow, AxisValue>;
     z?: Accessor<TRow, unknown>;
-    styles?: PlotStyles;
-    segments?: Segments<TSegmentStyle>;
+    styles?: BasePlotStyles;
+    segments?: SegmentsConfig<TSegmentStyle>;
     markers?: Marker[];
-    scales?: ScalesConfig;
+    scales?: AxisBasedScalesConfig<TRow>;
     margins?: MarginConfig;
     facet?: FacetConfig<TRow>;
     timeline?: TimelineConfig<TRow>;

package/dist/types/configuration/styling.d.ts

@@ -1,4 +1,4 @@
-import type { StrokeStyle, DotStyle, FontStyle } from '../plots/styles';
+import type { StrokeStyle, DotStyle, FontStyle } from '../plots/styling';
 export type TextStyle = {
     /** font-family */
     font: string;
@@ -57,11 +57,17 @@ export type ChartConfig = {
         radius: string;
         border: string;
     };
+    /**
+     * Per-side plot margin. `'auto'` (the default) lets svelteplot size that
+     * side to fit whatever it actually renders there — tick labels, an axis
+     * title, rotated ticks — instead of clipping content or leaving unused
+     * space. A number pins that side exactly, opting out of auto-sizing.
+     */
     margins: {
-        top: number;
-        right: number;
-        bottom: number;
-        left: number;
+        top: number | 'auto';
+        right: number | 'auto';
+        bottom: number | 'auto';
+        left: number | 'auto';
     };
     /** Discrete categorical palette (grouped series). */
     palette: string[];

package/dist/types/layout/tooltip.d.ts

@@ -1,9 +1,9 @@
 import type { Snippet } from 'svelte';
-import type { AxisValue } from '../plots/common';
+import type { AxisValue } from '../plots/axis';
 /**
  * How the hover highlight finds related points within a facet.
- * - `'x'`        all points sharing the hovered x (default for line / bar).
- * - `'y'`        all points sharing the hovered y (default for pyramid).
+ * - `'x'` all points sharing the hovered x (default for line / bar).
+ * - `'y'` all points sharing the hovered y (default for pyramid).
  * - `'punctual'` exact XY match — one cell at a time (default for heatmap).
  */
 export type HoverStrategy = 'x' | 'y' | 'punctual';
@@ -27,27 +27,10 @@ export type TooltipOptions<TRow extends Record<string, unknown>> = {
 };
 /** Either a bare on/off flag or the full option object. */
 export type TooltipProp<TRow extends Record<string, unknown>> = boolean | TooltipOptions<TRow>;
-/**
- * Resolved tooltip config handed from a chart kind down to a plot. Presence of
- * this object on a plot is what turns hovering on.
- */
-export type TooltipRuntime<TRow extends Record<string, unknown>> = {
-    format: (row: TRow) => string;
-    /** Identifies the originating facet (`''` when not faceted). */
-    facetId: string;
-    /** Strategy resolved by the chart; omitted → PlotLayout falls back to its own default. */
-    strategy?: HoverStrategy;
-    /** Whether to broadcast to other facets. */
-    sync: boolean;
-    series?: string[];
-    content?: Snippet<[{
-        rows: TRow[];
-    }]>;
-};
 /**
  * Shared hover state for cross-facet tooltip syncing.
  *
- * {@link Chart} provides one store via context; every faceted plot reads the
+ * {@link BaseChart} provides one store via context; every faceted plot reads the
  * same instance, so a hover detected in one facet (which writes `activeX/Y` and
  * stamps itself as `source`) is visible to the others. A standalone plot with no
  * provider falls back to its own {@link createHover} store.
@@ -83,6 +66,16 @@ export type HoverDisplayPoint = {
     series?: string;
     /** Resolved series color — used by HoverMarker when dotFill/fill is `'currentColor'`. */
     color?: string;
+    /**
+     * Pixel nudge applied on top of the scaled `x`/`y` position — for plot kinds
+     * where a series' visual position isn't fully captured by its data value
+     * (e.g. BarPlot's 'grouped' layout, where every series shares the same `x`
+     * category but is drawn at its own pixel slice within that category's band).
+     * Matching (`matchByStrategy`) still compares raw `x`/`y`, so this is
+     * display-only and never affects which points highlight together.
+     */
+    dx?: number;
+    dy?: number;
 };
 /** A candidate point for hover matching/highlighting — also carries its source row. */
 export type HoverPoint<T> = HoverDisplayPoint & {

package/dist/types/{plots/markers.d.ts → markers/common.d.ts}

@@ -1,17 +1,6 @@
-import type { AxisValue } from './common';
-import type { DotStyle, FontStyle, StrokeStyle } from './styles';
+import type { AxisValue } from '../plots/axis';
+import type { DotStyle, FontStyle, StrokeStyle } from '../plots/styling';
 import type { HoverStrategy, HoverDisplayPoint } from '../layout/tooltip';
-/**
- * Baseline props every marker component receives when mounted by a plot:
- * `data` for the points/values it draws, plus `series`/`seriesColor` when
- * mounted per-series via a `CustomComponentMarker`. Marker components extend
- * this with whatever else they need (e.g. PeakMarker's `mode`, `label`).
- */
-export interface MarkerProps<TData = Record<string, unknown>> {
-    data?: TData[];
-    series?: string;
-    seriesColor?: string;
-}
 export type RuleXMarker = {
     type: 'ruleX';
     x: AxisValue;
@@ -31,16 +20,12 @@ export type RuleYMarker = {
 export type HoverMarkerConfig = {
     type: 'hover';
     series?: string;
-    /** Whether to render per segment or for the full series. Defaults to `'series'`. */
     scope?: 'series' | 'segment';
-    /** Matching strategy — how related points are found. Defaults to the plot kind's own default. */
     strategy?: HoverStrategy;
-    /** Broadcast the hover to other facets. Defaults to `false`. */
     sync?: boolean;
     ruleX?: boolean;
     ruleY?: boolean;
     showLabels?: boolean;
-    /** Custom label formatter. Receives the matched point; return the string to display. */
     format?: (point: HoverDisplayPoint) => string;
     ruleStyle?: StrokeStyle;
     dotStyle?: DotStyle;
@@ -52,7 +37,6 @@ export type CustomComponentMarker = {
     component: any;
     props?: Record<string, unknown>;
     data?: any[];
-    /** Whether to render per segment or for the full series. Defaults to `'series'`. */
     scope?: 'series' | 'segment';
 };
 export type Marker = RuleXMarker | RuleYMarker | HoverMarkerConfig | CustomComponentMarker;