choropleth-kit 0.0.0-stage → 0.1.0

package/dist/drill-chain-DCiuiZKK.d.ts

@@ -0,0 +1,1247 @@
+import { FeatureCollection, Feature, Geometry } from 'geojson';
+import { Topology } from 'topojson-specification';
+import { GeoPath, geoEqualEarth, geoNaturalEarth1, geoMercator, geoAlbers, geoOrthographic, GeoProjection, GeoPermissibleObjects } from 'd3-geo';
+import { interpolateZoom } from 'd3-interpolate';
+import { interpolateBlues, interpolateGreens, interpolateGreys, interpolateOranges, interpolatePurples, interpolateReds, interpolateViridis, interpolateRdBu, interpolateBrBG, interpolatePiYG, interpolatePRGn, interpolatePuOr, interpolateRdYlBu, interpolateRdYlGn, interpolateSpectral } from 'd3-scale-chromatic';
+
+/** Already-loaded geometry. */
+type GeographyData = Topology | FeatureCollection;
+/**
+ * What the `geography` prop accepts: the data, a promise already in flight, or a
+ * function that loads it on demand (`() => import("…/world-110m")`; the whole module with `default` works).
+ */
+type GeographyInput = GeographyData | Promise<GeographyData | {
+    default: GeographyData;
+}> | (() => Promise<GeographyData | {
+    default: GeographyData;
+}>);
+/** An ES module (`import()`) brings the geometry in `default`. */
+declare const unwrapGeography: (value: GeographyData | {
+    default: GeographyData;
+}) => GeographyData;
+type ToFeatureCollectionOptions = {
+    geography: Topology | FeatureCollection;
+    /**
+     * Which topology object to use (e.g. "countries" or "land" in world-atlas).
+     * Ignored if `geography` is already GeoJSON.
+     */
+    objectName?: string;
+};
+/**
+ * Single entry point for geodata: accepts TopoJSON or GeoJSON and ALWAYS returns a
+ * `FeatureCollection`. Everything that follows (joining with the data, projection, SVG paths) can
+ * assume that shape and never ask again "what format was I given?".
+ *
+ * It is a pure, synchronous function: it does not fetch. The deferred load (`() => import(...)`) of
+ * `GeographyInput` is resolved in the React layer; here the data arrives already resolved.
+ */
+declare const toFeatureCollection: ({ geography, objectName, }: ToFeatureCollectionOptions) => FeatureCollection;
+
+declare const DEFAULT_MAX_RADIUS = 24;
+type RadiusScale = {
+    /** Value → radius in pixels. Area proportional to the value. */
+    getRadius: (value: number) => number;
+    /** Maximum value (radius = `maxRadius`). 0 if there are no positive values. */
+    max: number;
+    maxRadius: number;
+};
+type SizeLegendItem = {
+    value: number;
+    radius: number;
+    label: string;
+};
+/**
+ * SQUARE-ROOT radius scale: the eye compares areas, not radii. If a store sells twice
+ * as much, its circle must have twice the AREA (radius ×1.41), not twice the radius, which would be
+ * four times the area.
+ *
+ * The domain starts at 0 (not at the minimum): a circle of radius 0 represents 0. With a [min, max]
+ * domain the minimum value would vanish and the ratios between areas would be false.
+ */
+declare const createRadiusScale: ({ values, maxRadius, }: {
+    values: readonly (number | null | undefined)[];
+    maxRadius?: number;
+}) => RadiusScale;
+/** Three reference circles (¼, ½ and the maximum) to read the size. Empty without positive values. */
+declare const buildSizeLegend: ({ scale, formatValue, }: {
+    scale: RadiusScale;
+    formatValue?: (value: number) => string;
+}) => SizeLegendItem[];
+
+type Classification = {
+    method: "linear";
+} | {
+    method: "quantize";
+    classes?: number;
+} | {
+    method: "quantile";
+    classes?: number;
+} | {
+    method: "threshold";
+    thresholds: number[];
+};
+declare const DEFAULT_CLASSES = 5;
+/**
+ * Discards whatever is not a usable number: `null`, `undefined` and `NaN`/`Infinity`.
+ * It goes before any statistical computation: a single `NaN` in the array contaminates a minimum, a
+ * maximum or a whole quantile (they would all become `NaN`) and the map would come out in one color.
+ * A `0` IS kept: it is a datum, not an absence ("no data" ≠ 0).
+ */
+declare const finiteValues: (values: readonly (number | null | undefined)[]) => number[];
+/**
+ * Computes the **breaks** between classes: N classes ⇒ N-1 ascending numbers. A value `v` falls in
+ * class `i`, where `i` is the number of breaks `v` reaches or exceeds, so a value exactly on a break
+ * belongs to the class ABOVE (the behavior of `d3.scaleThreshold`).
+ *
+ * It returns numbers, not colors, on purpose: separating "which classes exist" from "what color
+ * each one is" lets the statistics be tested without looking at colors, and lets the legend (a later
+ * step) use the same breaks as the map without recomputing them.
+ *
+ * `values` must already be filtered with `finiteValues`. `domain` is the range `quantize` is split
+ * over; the caller decides it (in a diverging map it is symmetric around the midpoint, see scales.ts).
+ */
+declare const computeThresholds: ({ values, classification, domain, }: {
+    values: readonly number[];
+    classification: Classification;
+    domain: readonly [number, number];
+}) => number[];
+
+declare const SEQUENTIAL_PALETTES: {
+    readonly blues: typeof interpolateBlues;
+    readonly greens: typeof interpolateGreens;
+    readonly greys: typeof interpolateGreys;
+    readonly oranges: typeof interpolateOranges;
+    readonly purples: typeof interpolatePurples;
+    readonly reds: typeof interpolateReds;
+    readonly viridis: typeof interpolateViridis;
+};
+declare const DIVERGING_PALETTES: {
+    readonly rdbu: typeof interpolateRdBu;
+    readonly brbg: typeof interpolateBrBG;
+    readonly piyg: typeof interpolatePiYG;
+    readonly prgn: typeof interpolatePRGn;
+    readonly puor: typeof interpolatePuOr;
+    readonly rdylbu: typeof interpolateRdYlBu;
+    readonly rdylgn: typeof interpolateRdYlGn;
+    readonly spectral: typeof interpolateSpectral;
+};
+type SequentialPaletteName = keyof typeof SEQUENTIAL_PALETTES;
+type DivergingPaletteName = keyof typeof DIVERGING_PALETTES;
+/** Categorical palettes: loose colors with no order (unlike the ramps above). */
+declare const CATEGORICAL_PALETTES: {
+    readonly tableau10: readonly string[];
+    readonly set2: readonly string[];
+    readonly set3: readonly string[];
+    readonly accent: readonly string[];
+    readonly dark2: readonly string[];
+    readonly paired: readonly string[];
+    readonly pastel1: readonly string[];
+};
+type CategoricalPaletteName = keyof typeof CATEGORICAL_PALETTES;
+
+declare const DEFAULT_EMPTY_FILL = "#d4d4d4";
+type CommonOptions = {
+    /** One value per region (or per datum). `null`/`undefined`/`NaN` are treated as "no data". */
+    values: readonly (number | null | undefined)[];
+    classification?: Classification;
+    emptyFill?: string;
+};
+type ColorScaleOptions = CommonOptions & ({
+    variant: "sequential";
+    palette?: SequentialPaletteName;
+} | {
+    variant: "diverging";
+    palette?: DivergingPaletteName;
+    midpoint?: number;
+});
+type ColorScale = {
+    /** Value → CSS color. `null`/`undefined`/`NaN` → `emptyFill`. `0` is a datum and gets colored. */
+    getColor: (value: number | null | undefined) => string;
+    /** "classed": colors by bands. "continuous": a gradient with no classes (`linear`). */
+    kind: "classed" | "continuous";
+    /** Data range covered by the scale. In diverging it is symmetric around the midpoint. */
+    domain: readonly [number, number];
+    /** Breaks between classes (N-1). Empty in continuous. The legend will use these same ones. */
+    thresholds: readonly number[];
+    /** One color per class (N). Empty in continuous. */
+    colors: readonly string[];
+    emptyFill: string;
+};
+/**
+ * Creates the function that decides each region's color.
+ *
+ * The order of the steps matters because each one feeds the next:
+ * clean data → domain → breaks → colors → scale.
+ */
+declare const createColorScale: (options: ColorScaleOptions) => ColorScale;
+
+type LegendItem = {
+    color: string;
+    label: string;
+    /** Lower bound of the class (inclusive). Absent on the "no data" item. */
+    from?: number;
+    /** Upper bound of the class (exclusive, except on the last class). */
+    to?: number;
+    /** Number of regions in that class. */
+    count: number;
+    /** It is the "no data" item (not a class: it has no class index). */
+    empty?: true;
+};
+type BuildLegendOptions = {
+    scale: ColorScale;
+    /** One value per region. The same ones used to create the scale. `null`/`NaN` = no data. */
+    values: readonly (number | null | undefined)[];
+    formatValue?: (value: number) => string;
+    /** If given, a "no data" item with this text and the scale's `emptyFill` is appended at the end. */
+    emptyLabel?: string;
+};
+declare const defaultFormatValue: (value: number) => string;
+declare const classIndex: (thresholds: readonly number[], value: number) => number;
+/**
+ * Turns the scale into legend items reusing ITS breaks and colors (nothing is recomputed), and
+ * counts how many regions fall in each class.
+ *
+ * Continuous scale (`linear`): there are no classes, it returns [] (drawn as a gradient with `scale.domain`).
+ */
+declare const buildLegend: (options: BuildLegendOptions) => LegendItem[];
+
+type CategorySpec = {
+    id: string;
+    label?: string;
+    /** Fixed color. If missing, it is taken from the palette according to the category's position. */
+    color?: string;
+};
+type ResolvedCategory = {
+    id: string;
+    label: string;
+    color: string;
+};
+type CategoricalScale = {
+    /** Category → color. `null`/`undefined` and unknown categories → `emptyFill`. */
+    getColor: (category: string | null | undefined) => string;
+    getLabel: (category: string | null | undefined) => string;
+    categories: readonly ResolvedCategory[];
+    emptyFill: string;
+};
+type CreateCategoricalScaleOptions = {
+    values: readonly (string | null | undefined)[];
+    /** Fixed order and colors. Without this, categories come from the data, sorted alphabetically. */
+    categories?: readonly CategorySpec[];
+    palette?: CategoricalPaletteName;
+    emptyFill: string;
+};
+/**
+ * Assigns a color to each category.
+ *
+ * Without `categories`, the order is ALPHABETICAL and not order of appearance: if it depended on
+ * the data order, a reload with the rows in another order would change each category's color. For
+ * stable colors across screens (e.g. "Europe" always blue) pass `categories`.
+ *
+ * With more categories than colors in the palette, colors repeat (d3 does the same): two categories
+ * with the same color are indistinguishable, so better pass `categories` with `color`.
+ */
+declare const createCategoricalScale: ({ values, categories, palette, emptyFill, }: CreateCategoricalScaleOptions) => CategoricalScale;
+/** One item per category (in the scale's order) with its number of regions; optional "no data". */
+declare const buildCategoricalLegend: ({ scale, values, emptyLabel, }: {
+    scale: CategoricalScale;
+    values: readonly (string | null | undefined)[];
+    emptyLabel?: string;
+}) => LegendItem[];
+
+/** Point [x, y] in pixels or [lon, lat] in degrees, depending on context. */
+type Point = readonly [number, number];
+/**
+ * Configuration per `variant`. A discriminated union: each variant requires its
+ * own things (`categorical` asks for `getCategory`, `bubble` accepts `getCoordinates`…) and TypeScript
+ * rejects invalid combinations, such as a diverging palette on a sequential map.
+ */
+type VariantConfig<TDatum> = {
+    variant: "sequential";
+    getValue: (datum: TDatum) => number | null;
+    classification?: Classification;
+    palette?: SequentialPaletteName;
+} | {
+    variant: "diverging";
+    getValue: (datum: TDatum) => number | null;
+    classification?: Classification;
+    palette?: DivergingPaletteName;
+    midpoint?: number;
+} | {
+    variant: "categorical";
+    getCategory: (datum: TDatum) => string | null;
+    /** Fixed order and colors. */
+    categories?: readonly CategorySpec[];
+    palette?: CategoricalPaletteName;
+} | {
+    variant: "bubble";
+    /** ABSOLUTE value that gives the circle's AREA. `null`s and values ≤ 0 draw no circle. */
+    getValue: (datum: TDatum) => number | null;
+    /** Second metric → the bubble's color (bivariate, diverging scale). */
+    getColorValue?: (datum: TDatum) => number | null;
+    /** The datum's [lon, lat]. Without this, the bubble goes at its region's centroid. */
+    getCoordinates?: (datum: TDatum) => readonly [number, number] | null;
+    maxRadius?: number;
+    /** Single color when there is no `getColorValue`. */
+    color?: string;
+    classification?: Classification;
+    palette?: DivergingPaletteName;
+    midpoint?: number;
+};
+type VariantName = VariantConfig<unknown>["variant"];
+type VariantEntry<TDatum> = {
+    /** The region's id, or `undefined` if it has none. */
+    id: string | undefined;
+    /** Datum joined with the region, or `undefined` if there is none. */
+    datum: TDatum | undefined;
+};
+type Bubble<TDatum> = {
+    id: string;
+    x: number;
+    y: number;
+    r: number;
+    fill: string;
+    /** Value that gives the area. */
+    value: number;
+    colorValue: number | null;
+    datum: TDatum;
+    /**
+     * The datum's own [lon, lat] (`getCoordinates`), or `null` if the bubble is at its region's centroid.
+     * Tells a point (a store) apart from a region's bubble, for interaction purposes.
+     */
+    coordinates: Point | null;
+};
+type VariantResult<TDatum> = {
+    /** Color of each region, in the order of `entries`. */
+    fills: string[];
+    /** Value of each region: number, category (`categorical`) or `null`. */
+    values: (number | string | null)[];
+    /** `values` already formatted for display ("1.5 %", "Europe"); empty string if there is no value. */
+    labels: string[];
+    /** Numeric color scale. `null` in `categorical` and in `bubble` without `getColorValue`. */
+    scale: ColorScale | null;
+    legend: LegendItem[];
+    /**
+     * Index of the legend CLASS each region belongs to (same order as `fills`), or `null` if it belongs to none
+     * (no data, continuous scale, `bubble`). It is what makes it possible to highlight a class without re-rendering.
+     */
+    classes: (number | null)[];
+    bubbles: Bubble<TDatum>[];
+    sizeLegend: SizeLegendItem[];
+};
+type ResolveVariantOptions<TDatum> = {
+    config: VariantConfig<TDatum>;
+    entries: readonly VariantEntry<TDatum>[];
+    /** All data rows (bubbles with `getCoordinates` do not go through the regions). */
+    data: readonly TDatum[];
+    getId: (datum: TDatum) => string;
+    /** Projected centroid of each region, in the order of `entries` (only `bubble` uses it). */
+    centroids: readonly (Point | null)[];
+    /** [lon, lat] → [x, y] in pixels (only `bubble` uses it). */
+    project: (coordinates: Point) => Point | null;
+    emptyFill: string;
+    formatValue: (value: number) => string;
+    /** Text of the legend's "no data" item; without this, the legend does not include it. */
+    emptyLabel?: string;
+};
+declare const DEFAULT_BUBBLE_FILL = "#2563eb";
+/**
+ * Each variant's "preset": a PURE function that receives the data already joined with the
+ * regions and returns how it is painted (colors, legend, bubbles). The hook only orchestrates; adding
+ * a new variant means adding a branch here and a case in the type union.
+ */
+declare const resolveVariant: <TDatum>(options: ResolveVariantOptions<TDatum>) => VariantResult<TDatum>;
+
+/**
+ * The camera: an affine `transform` `{ k, x, y }` over the already-projected canvas.
+ * A canvas point `[px, py]` appears on screen at `[px·k + x, py·k + y]`. `k = 1` is the level's fit
+ * (the map fits the container exactly).
+ *
+ * This whole file is pure math, with no DOM or d3-zoom: it is tested without a browser. What writes
+ * the transform to the DOM (`use-zoom.ts`) comes in the next step.
+ */
+type CameraTransform = {
+    k: number;
+    x: number;
+    y: number;
+};
+/** The camera at the level's fit. */
+declare const FIT_TRANSFORM: CameraTransform;
+/** Is the camera (almost) at the fit? Used to disable "reset view". */
+declare const isFitTransform: (t: CameraTransform, epsilon?: number) => boolean;
+type Size = {
+    width: number;
+    height: number;
+};
+/** Rectangle [[x0, y0], [x1, y1]]. */
+type Extent = readonly [Point, Point];
+/** Canvas → screen. */
+declare const applyTransform: ({ k, x, y }: CameraTransform, [px, py]: Point) => Point;
+/** Screen → canvas. */
+declare const invertTransform: ({ k, x, y }: CameraTransform, [sx, sy]: Point) => Point;
+type ConstrainAxisParams = {
+    /** Current translation on this axis. */
+    t: number;
+    k: number;
+    /** Extremes of the content on the canvas (before scaling). */
+    c0: number;
+    c1: number;
+    /** Extremes of the view on screen. */
+    v0: number;
+    v1: number;
+    /** Elastic slack as a fraction of the view size. Defaults to 0 (hard limit). */
+    overscroll?: number;
+};
+/**
+ * Allowed translation on ONE axis. d3's default `constrain` leaves a map smaller
+ * than the view stuck in a corner; this one **centers** it if it fits and, if it does not fit,
+ * prevents its edges from entering the view (plus an optional elastic slack).
+ */
+declare const constrainAxis: ({ t, k, c0, c1, v0, v1, overscroll, }: ConstrainAxisParams) => number;
+type ConstrainTransformParams = {
+    transform: CameraTransform;
+    /** The canvas: normally [[0, 0], [width, height]]. */
+    content: Extent;
+    /** The view: normally [[0, 0], [width, height]]. */
+    view: Extent;
+    overscroll?: number;
+};
+/** `constrainAxis` on both axes. The scale `k` is not touched. */
+declare const constrainTransform: ({ transform, content, view, overscroll, }: ConstrainTransformParams) => CameraTransform;
+type PreserveViewParams = {
+    transform: CameraTransform;
+    oldSize: Size;
+    newSize: Size;
+    /** OLD canvas pixels → [lon, lat] (`oldProjection.invert`). */
+    invertOld: (point: Point) => Point | null;
+    /** [lon, lat] → NEW canvas pixels (`newProjection`). */
+    projectNew: (coordinates: Point) => Point | null;
+};
+/**
+ * Equivalent camera after a resize. When the size changes, the projection
+ * is refitted and the pixels change: without this, the view would "go back to the fit". The
+ * **geographic center** and `k` are preserved: it looks at which [lon, lat] was at the center of the
+ * view and places it at the center of the new view.
+ *
+ * If the center falls outside the projection (ocean beyond the globe) there is no geographic center
+ * to preserve: the fit is returned.
+ */
+declare const preserveView: ({ transform, oldSize, newSize, invertOld, projectNew, }: PreserveViewParams) => CameraTransform;
+/** Minimum and maximum duration of a flight, in ms. */
+declare const MIN_FLIGHT_MS = 350;
+declare const MAX_FLIGHT_MS = 1200;
+/** Default curvature (ρ) for dashboards (1.2–1.3): less "jump" than √2. */
+declare const DEFAULT_FLIGHT_CURVATURE = 1.25;
+/**
+ * The camera as a `interpolateZoom` "view" (van Wijk and Nuij): [center x, center y, visible width],
+ * all three in canvas coordinates.
+ */
+declare const transformToZoomView: ({ k, x, y }: CameraTransform, { width, height }: Size) => [number, number, number];
+declare const createZoomInterpolator: (rho: number) => typeof interpolateZoom;
+type FlightDurationParams = {
+    from: CameraTransform;
+    to: CameraTransform;
+    size: Size;
+    /** Speed multiplier (> 1 = slower). Defaults to 1. */
+    speed?: number;
+    curvature?: number;
+};
+/**
+ * Duration of a flight between two cameras: the "natural" one from `interpolateZoom` (depends on the
+ * distance and the scale change) × `speed`, clamped to [350, 1200] ms. Short flights are fast;
+ * long ones, readable.
+ */
+declare const flightDuration: ({ from, to, size, speed, curvature, }: FlightDurationParams) => number;
+/** Inertia time constant, in ms: iOS's. */
+declare const INERTIA_TAU_MS = 325;
+type InertiaOffsetParams = {
+    /** Release velocity on this axis, px/ms. */
+    velocity: number;
+    /** ms since release. */
+    elapsed: number;
+    tau?: number;
+};
+/**
+ * Accumulated displacement (px) `elapsed` ms after release, with exponential decay:
+ * `v·τ·(1 − e^(−t/τ))`. It tends to `v·τ` and never exceeds it; with negative or `NaN` `elapsed` it does not move.
+ */
+declare const inertiaOffset: ({ velocity, elapsed, tau, }: InertiaOffsetParams) => number;
+/** Minimum speed (px/ms) for releasing a drag to start inertia. */
+declare const INERTIA_MIN_VELOCITY = 0.3;
+/** Window of samples used to measure the release velocity, in ms. */
+declare const INERTIA_WINDOW_MS = 100;
+/** A camera position at an instant (ms, from `performance.now()`). */
+type CameraSample = {
+    time: number;
+    k: number;
+    x: number;
+    y: number;
+};
+type ReleaseVelocityParams = {
+    samples: readonly CameraSample[];
+    /** Instant of release. */
+    now: number;
+    windowMs?: number;
+    minVelocity?: number;
+};
+/**
+ * Velocity `[vx, vy]` (px/ms) at which a drag was released, or `null` if there must be no inertia:
+ *  - there was a zoom (`k` changed within the window): inertia is **pan** only;
+ *  - the hand stopped before releasing (the last sample is older than the window);
+ *  - there are no two samples in the window, or the velocity is below the threshold (0.3 px/ms).
+ */
+declare const releaseVelocity: ({ samples, now, windowMs, minVelocity, }: ReleaseVelocityParams) => Point | null;
+/**
+ * What bubbles do when zooming in:
+ *  - `"sqrt"` (default): they grow with √k (a sense of depth without covering the country);
+ *  - `"screen"`: constant size on screen;
+ *  - `"geo"`: they grow with the map (full scale).
+ */
+type BubbleScaling = "sqrt" | "screen" | "geo";
+/**
+ * The value of `--cm-bubble-scale` for a given `k`: the bubble is drawn inside the viewport (which
+ * already multiplies by `k`), so it is compensated with `1/√k`, `1/k` or `1`.
+ */
+declare const bubbleScale: (k: number, scaling: BubbleScaling) => number;
+/** Drill-down level. Same as `DrillLevelInfo` in `react/map-item.ts`. */
+type ViewLevel = {
+    id: string;
+    depth: number;
+};
+/** What `onViewChange` receives. */
+type ViewState = {
+    /** Camera transform, in level pixels. */
+    k: number;
+    x: number;
+    y: number;
+    /** = `k` (1 = the level's fit): a readable alias. */
+    zoom: number;
+    /** [lon, lat] of the view's center. */
+    center: Point;
+    /** Visible [[lonW, latS], [lonE, latN]]. Approximate: does not account for the antimeridian. */
+    bounds: readonly [Point, Point];
+    level: ViewLevel;
+};
+type ToViewStateParams = {
+    transform: CameraTransform;
+    size: Size;
+    /** Canvas pixels → [lon, lat] (`projection.invert`); `null` if it falls outside the globe. */
+    invert: (point: Point) => Point | null;
+    level?: ViewLevel;
+};
+/**
+ * Turns the camera into a `ViewState` with geographic coordinates. The view's corners often fall
+ * outside the globe (a world map in Equal Earth is not a rectangle), so the bounds are estimated by
+ * sampling a grid over the view and keeping the points that do project. If none does, it returns the
+ * whole world and the center `[0, 0]`.
+ */
+declare const toViewState: ({ transform, size, invert, level, }: ToViewStateParams) => ViewState;
+
+type GetFocusGeometryParams = {
+    feature: Feature;
+    /** An already-projected `geoPath`: areas and distances are measured in pixels, not degrees. */
+    path: GeoPath;
+    /**
+     * A polygon counts as part of the "main body" if the center of its bounds is closer than
+     * `near × diagonal(main)` to the center of the main polygon. Defaults to 0.5.
+     */
+    near?: number;
+};
+/**
+ * The "main" sub-geometry of a feature: the polygon with the largest projected area plus the ones
+ * close to it (Mallorca, Corsica or Sicily yes; Guyana, Hawaii or the Canary Islands no).
+ *
+ * Why it exists: `geoPath.bounds` / `centroid` of the whole feature include the
+ * distant territories. Zooming to "France" would show half the Atlantic, and its bubble would land
+ * in the Bay of Biscay. It is used to frame the view and to anchor bubbles and labels.
+ *
+ * Returns `null` if the feature has no geometry. Non-polygon geometries and lone polygons are
+ * returned as they are.
+ */
+declare const getFocusGeometry: ({ feature, path, near, }: GetFocusGeometryParams) => Geometry | null;
+/**
+ * Anchor point for bubbles and labels: the "pole of inaccessibility" (`polylabel`) of the largest
+ * projected polygon of `geometry`, i.e. the interior point farthest from the edge. Unlike the
+ * centroid, it always falls INSIDE the polygon (Chile, Croatia, France).
+ *
+ * `project` turns [lon, lat] into pixel [x, y] and returns `null` if it cannot. `precision` is in
+ * pixels. Returns `null` if there is no projectable polygon.
+ */
+declare const getAnchorPoint: ({ geometry, project, precision, }: {
+    geometry: Geometry | null;
+    project: (coordinates: Point) => Point | null;
+    precision?: number;
+}) => Point | null;
+type Padding = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** Default padding when fitting and when flying to a region, in px. */
+declare const DEFAULT_PADDING = 24;
+/** `number` = the same padding on all four sides. */
+declare const normalizePadding: (padding?: number | Padding) => Padding;
+type BoundsToTransformParams = {
+    /** What to fit, in canvas pixels: [[x0, y0], [x1, y1]]. */
+    bounds: Extent;
+    /** The view (the container). */
+    size: Size;
+    padding?: number | Padding;
+    /** [minimum, maximum] of `k`. Unbounded by default. */
+    scaleExtent?: readonly [number, number];
+};
+/**
+ * Camera that fits some bounds into the view, with padding in pixels. It is the
+ * target of "zoom to a country" and of the initial framing. It honors `scaleExtent`: if the country
+ * is so small that more zoom than allowed would be needed, it stays at the maximum (and the country
+ * is centered).
+ *
+ * Degenerate bounds (a single point): `k` rises up to the maximum instead of producing `Infinity`. If
+ * the padding eats the whole view, `k` drops to the minimum.
+ */
+declare const boundsToTransform: ({ bounds, size, padding, scaleExtent, }: BoundsToTransformParams) => CameraTransform;
+/** Geographic bounds [[lonW, latS], [lonE, latN]]. If `lonE < lonW`, they cross the antimeridian. */
+type LonLatBounds = readonly [Point, Point];
+/**
+ * Geographic rectangle → pixel rectangle that contains it. A lon/lat rectangle is NOT a rectangle on
+ * screen (parallels curve in Equal Earth, the globe narrows at the poles), so points are projected
+ * along its four sides and the minimum box containing them is taken. Points the projection cannot
+ * project are discarded; if none remain, it returns `null`.
+ *
+ * If `lonE < lonW` the rectangle crosses the antimeridian (Fiji, the Pacific). On a flat map that
+ * region appears split across both edges and **no rectangle contains both halves** (it would give a
+ * box as wide as the whole world): the wider half is framed, just as `getFocusGeometry` keeps the
+ * main body.
+ */
+declare const projectBounds: (bounds: LonLatBounds, project: (coordinates: Point) => Point | null) => Extent | null;
+type GetFocusExtentParams = GetFocusGeometryParams & {
+    /** [lon, lat] → canvas pixels; `null` if it does not project. */
+    project: (coordinates: Point) => Point | null;
+};
+/**
+ * Pixel bounds of a region's main body: what gets framed when flying to it. It is
+ * `getFocusGeometry` + its projected bounds, with one special case:
+ *
+ * **Antimeridian.** The main polygon of Russia (and Fiji's or Alaska's) crosses the ±180° line
+ * without being split, and `path.bounds` measures both halves: the framing would span the map from
+ * edge to edge, with Chukotka poking out on the opposite side. It is detected with `geoBounds` (which
+ * returns `west > east` when crossing) and the wider half is framed (`projectBounds`).
+ *
+ * Returns `null` if the feature has no geometry or its bounds are not finite.
+ */
+declare const getFocusExtent: ({ feature, path, project, near, }: GetFocusExtentParams) => Extent | null;
+
+/**
+ * Theme: a typed object that is translated into `--cm-*` CSS variables. **The
+ * variables remain the single source of truth**: the object is sugar so there is autocompletion and
+ * reusable themes.
+ *
+ * It is pure (no React or DOM) and lives in `core` even though it is consumed only by `react`:
+ * that way it is tested without rendering and a consumer without React can use `themeToCssVars`.
+ *
+ * It only has fields for what EXISTS today. `sphere`, `graticule`, `hover.effect`, `selected.glow`,
+ * `motion` and `empty.pattern` are planned and arrive with the layers and effects that consume
+ * them (adding a field breaks nobody; having one that does nothing does mislead).
+ */
+type ChoroplethTheme = {
+    /** Map background (the `.cm-root`). Transparent by default. */
+    background?: string;
+    /** Regions without data. `pattern`: a pattern over regions without data (not just color: they can be told apart without seeing it either). None by default. */
+    empty?: {
+        fill?: string;
+        pattern?: "none" | "hatch" | "dots";
+    };
+    /** The levels above in a drill: gray, with no data color. */
+    context?: {
+        fill?: string;
+        border?: string;
+    };
+    /** Borders between regions. */
+    border?: {
+        color?: string;
+        width?: number;
+    };
+    hover?: {
+        stroke?: string;
+        width?: number;
+    };
+    selected?: {
+        stroke?: string;
+        width?: number;
+    };
+    /** Keyboard focus ring: color and thickness (px). */
+    focus?: {
+        ring?: string;
+        width?: number;
+    };
+    /** Opacity of the rest of the map with `dimOthers`. */
+    dim?: {
+        opacity?: number;
+    };
+    bubble?: {
+        fill?: string;
+        stroke?: string;
+        opacity?: number;
+    };
+    font?: {
+        family?: string;
+        size?: number;
+        color?: string;
+    };
+    tooltip?: {
+        background?: string;
+        color?: string;
+        border?: string;
+        /** px */
+        radius?: number;
+        /** A `box-shadow` value. */
+        shadow?: string;
+    };
+    /** Zoom buttons and drill breadcrumbs. */
+    controls?: {
+        background?: string;
+        color?: string;
+        border?: string;
+        radius?: number;
+    };
+};
+type ThemeName = "light" | "dark" | "minimal" | "contrast";
+/** Identity: it exists to infer the type with autocompletion and to reuse a theme across maps. */
+declare const defineTheme: (theme: ChoroplethTheme) => ChoroplethTheme;
+declare const THEMES: Readonly<Record<ThemeName, ChoroplethTheme>>;
+declare const isThemeName: (value: unknown) => value is ThemeName;
+/** A theme's object by name, or the same object if it already is one. `undefined` = no theme. */
+declare const resolveTheme: (theme: ThemeName | ChoroplethTheme | undefined) => ChoroplethTheme | undefined;
+/**
+ * Starts from a theme (by name or object) and overlays adjustments, group by group: whatever you put in
+ * `border` replaces only those `border` fields, not the rest of the theme.
+ */
+declare const extendTheme: (base: ThemeName | ChoroplethTheme, overrides: ChoroplethTheme) => ChoroplethTheme;
+/**
+ * The `theme` object → CSS variables (`{ "--cm-border-color": "#fff", … }`), ready for a `style`. Pure:
+ * no DOM. Undefined fields produce no variable (whatever was there stays: the base CSS or yours).
+ */
+declare const themeToCssVars: (theme: ChoroplethTheme | undefined) => Record<string, string>;
+
+/**
+ * The library's UI texts (i18n). English by default; `es` for Spanish. Each phase adds its own
+ * (`drillHint`, `breadcrumbRoot`…). Console messages do NOT go through here: they are for the
+ * developer and are always in English.
+ */
+type ChoroplethLabels = {
+    /** Region without data: tooltip and legend. */
+    noData: string;
+    /** The asynchronous geometry could not be loaded. */
+    geographyError: string;
+    /** Zoom buttons (`aria-label`). */
+    zoomIn: string;
+    zoomOut: string;
+    resetView: string;
+    /** Hint for `wheel: "cooperative"`. The `Mac` variant is used on macOS and iOS (⌘ instead of Ctrl). */
+    gestureHintWheel: string;
+    gestureHintWheelMac: string;
+    gestureHintTouch: string;
+    /** Drill-down: `aria-label` of the breadcrumbs' `<nav>`, its root (if the first level has no `label`), the "←" button and the tooltip hint. */
+    breadcrumb: string;
+    breadcrumbRoot: string;
+    drillUp: string;
+    drillHint: string;
+    /** Touch: the tooltip hint after the first tap (the second one drills down). */
+    tapAgainHint: string;
+};
+declare const en: ChoroplethLabels;
+declare const es: ChoroplethLabels;
+/** Fills in any missing texts with the English ones. */
+declare const resolveLabels: (labels?: Partial<ChoroplethLabels>) => ChoroplethLabels;
+
+type JoinDataOptions<TDatum> = {
+    features: readonly Feature[];
+    data: readonly TDatum[];
+    /** Id of each user datum (e.g. `(d) => d.countryCode`). */
+    getId: (datum: TDatum) => string;
+    /**
+     * Id of each region if it is not `feature.id` (e.g. `(f) => f.properties?.iso_a2`).
+     * Returning `undefined` means "this region has no id": it cannot be joined and is ignored.
+     */
+    getFeatureId?: (feature: Feature) => string | undefined;
+};
+type JoinResult<TDatum> = {
+    /** region id → datum. Only contains joins that DID happen. */
+    joined: Map<string, TDatum>;
+    /** ids of data that do not match any region (e.g. "ES" when the geometry uses "724"). */
+    unmatchedData: string[];
+    /** ids of regions left without data (they will be painted with `emptyFill`). */
+    featuresWithoutData: string[];
+    /** repeated ids in `data`: only the first of each is kept. */
+    duplicateDataIds: string[];
+};
+/**
+ * Joins the user's data with the map's regions by a common identifier.
+ *
+ * This is the step where the #1 cause of "my map is gray" is born: the datum says "ES" and the
+ * geometry says "724". This function does NOT try to guess or fix ids (that would hide the error):
+ * it joins them as they are and **reports** what did not join. Whoever shows the warning to the
+ * developer (console.warn, `onJoinReport`) will do it with this result, in another layer.
+ *
+ * It is pure: it does not write to the console or read `process.env`. Complexity O(regions + data)
+ * thanks to Map/Set; with `data.find(...)` per region it would be O(regions × data).
+ */
+declare const joinData: <TDatum>({ features, data, getId, getFeatureId, }: JoinDataOptions<TDatum>) => JoinResult<TDatum>;
+
+declare const PROJECTIONS: {
+    readonly equalEarth: typeof geoEqualEarth;
+    readonly naturalEarth: typeof geoNaturalEarth1;
+    readonly mercator: typeof geoMercator;
+    readonly albers: typeof geoAlbers;
+    readonly orthographic: typeof geoOrthographic;
+};
+type ProjectionName = keyof typeof PROJECTIONS;
+/** The factory of a projection by name (each call, a new instance). */
+declare const projectionFactory: (name?: ProjectionName) => (() => GeoProjection);
+declare const DEFAULT_PROJECTION: ProjectionName;
+type CreateProjectionOptions = {
+    /** Projection by name. Defaults to `equalEarth`. */
+    name?: ProjectionName;
+    /** Container size in pixels. */
+    width: number;
+    height: number;
+    /** Geometry that must fit entirely in `width × height`. */
+    featureCollection: FeatureCollection;
+};
+/**
+ * Creates an already-fitted d3 projection (`fitSize`) so the geometry fits the container snugly.
+ *
+ * Without the fit, a d3 projection uses a fixed scale designed for 960×500: in a different
+ * container the map would come out cropped or tiny. `fitSize` computes scale and translation for us
+ * (no zoom or center math by hand).
+ */
+declare const createProjection: ({ name, width, height, featureCollection, }: CreateProjectionOptions) => GeoProjection;
+/** Aspect ratio used if the geometry cannot be measured (the world in Equal Earth). */
+declare const DEFAULT_ASPECT_RATIO: number;
+/**
+ * width / height the geometry takes up with that projection (`aspectRatio: "auto"`).
+ *
+ * Chile is very tall and Norway very wide: with a fixed ratio there would be too much or too little
+ * space. The projection is fitted to a reference width and the resulting rectangle is measured; the
+ * ratio does not depend on the chosen width. It is clamped to [0.2 – 5] so an odd datum (a single
+ * island) does not leave a container 1 px tall.
+ */
+declare const computeAspectRatio: ({ name, featureCollection, }: {
+    name?: ProjectionName;
+    featureCollection: FeatureCollection;
+}) => number;
+/**
+ * The affine map `R` such that `to(p) === R(from(p))` for every `p`, where `R(q) = k·q + (x, y)`.
+ *
+ * It only holds if `from` and `to` share EVERYTHING except `scale` and `translate` (same projection,
+ * rotation, center…). Then switching from one to the other is an affine transformation of the
+ * pixels, and so it can be expressed as a camera (`CameraTransform`): `R` is at once "how far the
+ * parent's camera must move" and "what separates the parent's pixels from the child's".
+ */
+declare const relativeTransform: (from: GeoProjection, to: GeoProjection) => CameraTransform;
+type RebaseParams = {
+    /** The parent level's projection (it is not modified). */
+    parent: GeoProjection;
+    /** Creates a new projection of the SAME type as `parent` (d3 projections are mutable). */
+    factory: () => GeoProjection;
+    /** The geometry that must fill the view: the region's main body (`getFocusGeometry`). */
+    focus: GeoPermissibleObjects;
+    width: number;
+    height: number;
+    padding: Padding;
+};
+type RebaseResult = {
+    /** The child's projection, fitted to `focus`. At `k = 1` the precision is full. */
+    projection: GeoProjection;
+    /** `projection(p) === relative(parent(p))`: the exact destination of the flight and of the context layer. */
+    relative: CameraTransform;
+};
+/**
+ * Child-level projection with perfect continuity.
+ *
+ * Two naive solutions fail: a single projection with a huge `k` (at `k ≈ 300` the 3 decimals of
+ * `geoPath` give jagged edges) and a new `fitSize` per level (the child appears at another scale and
+ * position: a visible jump). Here the child is the parent's projection with **the same rotation,
+ * center and other parameters** and only `scale`/`translate` readjusted (`fitExtent`). That is an
+ * affine map of the output, so if the flight ends exactly at `relative`, switching to the child
+ * projection with an identity camera paints the **same pixels**.
+ */
+declare const rebaseProjection: ({ parent, factory, focus, width, height, padding, }: RebaseParams) => RebaseResult;
+
+type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+type ZoomControlsOptions = {
+    /** Corner of the map. Defaults to `"bottom-right"` (the legend goes bottom-left by default). */
+    position?: Corner;
+    /** Show the "reset view" button. Defaults to `true`. */
+    reset?: boolean;
+};
+/**
+ * Where to move the camera: a region, some bounds or a center with zoom.
+ *  - `string`: id of a region on the map. Its **main body** is framed (France without Guiana).
+ *  - `{ bounds }`: [[lonW, latS], [lonE, latN]].
+ *  - `{ center, zoom }`: `zoom` relative to the fit (1 = fit).
+ */
+type ZoomTarget = string | {
+    bounds: LonLatBounds;
+} | {
+    center: readonly [number, number];
+    zoom: number;
+};
+type CameraOptions = {
+    /** ms. Without this, the flight's natural duration (350–1200 ms). `0` = no animation. */
+    duration?: number;
+    /** Margin when framing (px). Defaults to that of `zoom.padding` (24). */
+    padding?: number | Padding;
+};
+/**
+ * Explicit framings per region, in lon/lat. **Spain is framed with the Canary Islands by default**,
+ * even though the geometry's main body does not include them. It is merged with the consumer's
+ * `focusBounds`; with `{ ES: null }` it returns to the geometric framing (peninsula only).
+ */
+declare const DEFAULT_FOCUS_BOUNDS: Readonly<Record<string, LonLatBounds>>;
+/** Result of an animated camera move: `completed` is `false` if something interrupted it. */
+type TransitionResult = {
+    completed: boolean;
+};
+/**
+ * Zoom and pan options. Only the ones that already do something are here; `inertia`,
+ * `padding` and `initialView` are added in steps 26-27 with their behavior (declaring them earlier
+ * would promise what does not exist).
+ */
+type ZoomOptions = {
+    /** Minimum scale relative to the level's fit (1 = cannot zoom out further than the fit). Default 1. */
+    min?: number;
+    /** Maximum scale. Default 12. */
+    max?: number;
+    /**
+     * What the wheel does over the map. Default `"always"`: with the mouse over it, the wheel zooms.
+     *  - `"cooperative"`: only with Ctrl/⌘ + wheel (and touch with two fingers); the page keeps
+     *    scrolling. Recommended for maps inside a long page or a dashboard.
+     *  - `"never"`: the wheel does not zoom (dragging and pinching still work).
+     *
+     * ⚠️ With `"always"`, a map on a scrolling page "eats" the wheel when passed over
+     * (_scroll-jacking_). `"cooperative"` is the alternative; the default is `"always"`.
+     */
+    wheel?: "cooperative" | "always" | "never";
+    /** Two-finger pinch. Default `true`. (A trackpad pinch arrives as Ctrl + wheel.) */
+    pinch?: boolean;
+    /** Drag to pan. Default `true`. */
+    pan?: boolean;
+    /**
+     * Double click / double tap = zoom ×2. `"auto"` (default): active unless the click has another
+     * meaning (`onItemClick` or selection), so as not to do both at once.
+     */
+    doubleClick?: boolean | "auto";
+    /** Margin when framing a region or some bounds, in px. Default 24. */
+    padding?: number | Padding;
+    /**
+     * Initial view: the camera is placed there **without animating** on first render. `focusId` takes
+     * precedence over this. Useful for shareable URLs: `initialView: { center: [-3.7, 40.4], zoom: 4 }`.
+     */
+    initialView?: ZoomTarget;
+    /**
+     * Bubbles when zooming: `"sqrt"` (default, they grow with √k), `"screen"` (constant
+     * size on screen) or `"geo"` (they grow with the map).
+     */
+    bubbleScaling?: BubbleScaling;
+    /** When a fast drag is released, the map keeps sliding and slows down. Default `true`. */
+    inertia?: boolean;
+    /** `"contain"` (default): the content is not lost and is centered if it fits. `"free"`: no limits. */
+    constrain?: "contain" | "free";
+    /** Keyboard shortcuts with the map focused: `+`, `−` and `0`. Default `true`. */
+    keyboard?: boolean;
+    /**
+     * `+` / `−` / `⟲` buttons. **Opt-in** (default `false`): `true` or `{ position, reset }`. The preset
+     * draws them; with the compound, put `<Choropleth.ZoomControls>` wherever you like.
+     */
+    controls?: boolean | ZoomControlsOptions;
+    /** At the END of each gesture (never per frame). With programmatic flights, at the end of the flight. */
+    onViewChange?: (view: ViewState) => void;
+};
+type ResolvedZoom = {
+    min: number;
+    max: number;
+    wheel: "cooperative" | "always" | "never";
+    pinch: boolean;
+    pan: boolean;
+    /** Already resolved: `"auto"` becomes `true`/`false` depending on whether the click has another meaning. */
+    doubleClick: boolean;
+    constrain: "contain" | "free";
+    bubbleScaling: BubbleScaling;
+    inertia: boolean;
+    keyboard: boolean;
+    padding: number | Padding;
+    initialView: ZoomTarget | undefined;
+};
+declare const DEFAULT_ZOOM_MIN = 1;
+declare const DEFAULT_ZOOM_MAX = 12;
+/**
+ * `zoom` (the prop) → full options, or `null` if zoom is disabled (`zoom={false}`).
+ * `clickIsBusy`: the click already does something (`onItemClick`, selection), to resolve `doubleClick: "auto"`.
+ */
+declare const resolveZoomOptions: (zoom: boolean | ZoomOptions | undefined, { clickIsBusy }: {
+    clickIsBusy: boolean;
+}) => ResolvedZoom | null;
+/** `zoom.controls` → what to draw, or `null` if there are no controls (the default). */
+declare const resolveControls: (zoom: boolean | ZoomOptions | undefined) => Required<ZoomControlsOptions> | null;
+type ZoomKeyAction = "in" | "out" | "reset";
+/**
+ * What a key does on the focused map: `+` zooms in, `−` zooms out, `0` returns to the fit.
+ *
+ * With Ctrl, ⌘ or Alt it is NOT interpreted: Ctrl/⌘ + `+`, `−`, `0` is the browser's page zoom, and
+ * taking it from the user would be an accessibility failure.
+ */
+declare const zoomKeyAction: (event: {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}) => ZoomKeyAction | null;
+/** The minimum the filter needs from a DOM event (so it can be tested without a DOM). */
+type ZoomEventLike = {
+    type: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    button?: number;
+    touches?: {
+        length: number;
+    };
+};
+type ZoomFilterParams = Pick<ResolvedZoom, "wheel" | "pinch" | "pan" | "doubleClick"> & {
+    /** Called when a gesture does NOT zoom but could be taught how (the Ctrl/⌘ + wheel hint). */
+    onGestureHint?: (kind: "wheel" | "touch") => void;
+};
+/**
+ * Which events trigger zoom. Replaces d3-zoom's default filter, which is
+ * `(!ctrlKey || type === "wheel") && !button`.
+ *
+ * Returning `false` does NOT call `preventDefault`: in `cooperative` the wheel without a modifier and
+ * one-finger touch keep scrolling the page.
+ */
+declare const createZoomFilter: ({ wheel, pinch, pan, doubleClick, onGestureHint }: ZoomFilterParams) => (event: ZoomEventLike) => boolean;
+type ResolveZoomTargetParams = {
+    target: ZoomTarget;
+    size: Size;
+    padding?: number | Padding;
+    /** [minimum, maximum] of `k`. */
+    scaleExtent: readonly [number, number];
+    /** [lon, lat] → canvas pixels; `null` if it does not project. */
+    project: (coordinates: Point) => Point | null;
+    /** Pixel bounds of a region's main body, or `null` if it does not exist. */
+    getRegionExtent: (id: string) => Extent | null;
+    /** Framings per region (already merged with `DEFAULT_FOCUS_BOUNDS`). `null` = use the geometry. */
+    focusBounds?: Readonly<Record<string, LonLatBounds | null | undefined>>;
+};
+/**
+ * `ZoomTarget` → camera. Pure: the projection and geometry arrive as
+ * functions. Returns `null` if it cannot be resolved (nonexistent region, point outside the globe).
+ *
+ * It does not apply `constrain`: whoever moves the camera takes care of that, because d3-zoom only
+ * applies it to gestures, not to programmatic transitions.
+ */
+declare const resolveZoomTarget: ({ target, size, padding, scaleExtent, project, getRegionExtent, focusBounds, }: ResolveZoomTargetParams) => CameraTransform | null;
+
+/**
+ * Drill-down state machine. It is a pure _reducer_: no DOM, no timers, no promises.
+ * Whoever uses it (`react/`) translates the real world into events (click, end of flight, geometry
+ * ready…) and renders the resulting state. That way every edge case (click during a flight, error,
+ * going up before finishing going down…) is tested without jsdom.
+ *
+ * Vocabulary:
+ *  - **path**: ids from the root (`[]` = world, `["ES"]` = Spain). It is the "optimistic" target: it
+ *    changes the instant of the click.
+ *  - **settledPath**: the path of what is actually drawn as the active layer. Until the rebase,
+ *    `path` and `settledPath` differ.
+ *  - **layer**: the regions of one level. The layer at depth `d` shows the children of
+ *    `path[0..d)`. At `["ES"]` there are two: the world (`context`) and Spain's regions (`active`).
+ */
+type DrillPhase = "idle" | "flying" | "loading" | "revealing";
+/** `down`: one level deeper; `up`: to an ancestor; `lateral`: a sibling; `jump`: any other jump. */
+type DrillDirection = "down" | "up" | "lateral" | "jump";
+type DrillLayerRole = "active" | "context" | "entering" | "exiting";
+type DrillLayer = {
+    /** Layer identity: see `layerKey`. */
+    key: string;
+    depth: number;
+    role: DrillLayerRole;
+};
+type DrillMachineState = {
+    phase: DrillPhase;
+    /** Target (optimistic). */
+    path: readonly string[];
+    /** What is currently drawn as active. */
+    settledPath: readonly string[];
+    /** Direction of the transition in progress; `null` at rest. */
+    direction: DrillDirection | null;
+    layers: readonly DrillLayer[];
+    /** Is a camera flight pending? */
+    flight: "pending" | "done";
+    /** Identifies the current flight: a `FLIGHT_END` from another flight (already redirected) is ignored. */
+    flightId: number;
+    /** State of the new layer's geometry. `null` if there is nothing to load. */
+    geometry: "pending" | "ready" | "error" | null;
+    /** `key` of the layer whose geometry is awaited; any other geometry notices are stale. */
+    geometryKey: string | null;
+    /** Camera of each level when going down from it, by `layerKey`. Going up flies back to the saved one. */
+    savedCameras: Readonly<Record<string, CameraTransform>>;
+    /** Camera at the instant the transition started: where to return if it fails or is cancelled. */
+    returnCamera: CameraTransform | null;
+    /** `key` of the layer whose load failed, until the next `DRILL`. Feeds `onDrillError`. */
+    error: string | null;
+};
+type DrillMachineEvent = {
+    type: "DRILL";
+    to: readonly string[];
+    /** Only `"jump"` is honored (no animation); the rest is deduced from `settledPath` → `to`. */
+    direction?: DrillDirection;
+    /** The current camera: saved when going down, so that going up returns to it. */
+    camera?: CameraTransform;
+    /** The new layer's geometry is already cached: there is nothing to wait for. */
+    cached?: boolean;
+} | {
+    type: "FLIGHT_END";
+    id: number;
+    completed: boolean;
+} | {
+    type: "GEOMETRY_READY";
+    key: string;
+} | {
+    type: "GEOMETRY_ERROR";
+    key: string;
+} | {
+    type: "REVEAL_END";
+};
+/**
+ * Key of the layer at depth `depth` under `path`: the JSON of `path.slice(0, depth)`. With JSON there
+ * are no collisions even if an id contains `/` or `.`.
+ */
+declare const layerKey: (path: readonly string[], depth?: number) => string;
+/**
+ * How to get from `from` to `to`: `"equal"` if they are the same; `"down"` if `to` is `from` + one id;
+ * `"up"` if `to` is an ancestor (any number of steps); `"lateral"` if only the last id changes;
+ * `"jump"` in any other case (several levels down, another branch…).
+ */
+declare const classifyDrill: (from: readonly string[], to: readonly string[]) => DrillDirection | "equal";
+/** Resting state at `path` (the world by default). Mounting with a route from the URL does not animate. */
+declare const createDrillState: (path?: readonly string[]) => DrillMachineState;
+/** The camera to return to when going up to `path` (the one saved when going down from there), if any. */
+declare const savedCameraFor: (state: DrillMachineState, path: readonly string[]) => CameraTransform | null;
+declare const drillReducer: (state: DrillMachineState, event: DrillMachineEvent) => DrillMachineState;
+
+/**
+ * Pure drill-down pieces that depend on neither React nor the DOM: a route's
+ * context, the breadcrumbs, the geometry cache key, the LRU cache and level validation.
+ */
+type DrillContext = {
+    /** Ids from the root: [] = world, ["ES"] = Spain, ["ES", "ES-MD"] = Madrid. */
+    path: readonly string[];
+    /** `path.at(-1) ?? null`. */
+    parentId: string | null;
+    /** `path.length`. */
+    depth: number;
+};
+declare const contextOf: (path: readonly string[]) => DrillContext;
+/** The minimum needed from a level for these functions (so they can be tested without React). */
+type LevelShape = {
+    id: string;
+    label?: string;
+    /** Only whether it is `"inherit"` or a function matters; the rest is the geometry itself. */
+    geography: unknown;
+    geographyKey?: (ctx: DrillContext) => string;
+};
+/**
+ * Validates the list of levels when it is defined. Errors explain what to change (DX principle from
+ * the design): an empty list, repeated ids (the level id is used as a key) or a first level that
+ * "inherits" geometry from a parent that does not exist.
+ */
+declare const validateLevels: (levels: readonly LevelShape[]) => void;
+/**
+ * Trims a route to the depth the levels allow: with N levels, the longest path has N − 1 ids (the
+ * last level cannot be drilled into any further). `clamped` signals that trimming happened.
+ */
+declare const clampPath: (path: readonly string[], levelCount: number) => {
+    path: readonly string[];
+    clamped: boolean;
+};
+type DrillCrumb = {
+    depth: number;
+    /** `null` at the root. */
+    id: string | null;
+    label: string;
+};
+/**
+ * Breadcrumbs of the route: the root (with the first level's label or `rootLabel`) and one step per id.
+ * `getLabel` names each step (the id by default).
+ */
+declare const buildBreadcrumbs: ({ path, rootLabel, getLabel, }: {
+    path: readonly string[];
+    rootLabel: string;
+    getLabel?: (args: {
+        id: string;
+        depth: number;
+    }) => string;
+}) => DrillCrumb[];
+/**
+ * Cache key of the geometry of the level at `path.length`: the consumer's
+ * (`geographyKey`), or `${id}:${parentId}` if the geometry depends on the parent (it is a function),
+ * or just the id. With `"inherit"` the geometry is the parent's, so the key is too (stores over a
+ * country share the country's geometry).
+ */
+declare const geographyKeyFor: (levels: readonly LevelShape[], path: readonly string[]) => string;
+/**
+ * `data` as a list or as a selector for the current level. `undefined` means "loading" and is
+ * respected: the map keeps the previous layer, with no warnings.
+ */
+declare const resolveDrillData: <TDatum>(data: readonly TDatum[] | undefined | ((ctx: DrillContext) => readonly TDatum[] | undefined), ctx: DrillContext) => readonly TDatum[] | undefined;
+/** Which drill event is a route change; `null` if it does not change. */
+declare const drillDirectionBetween: (from: readonly string[], to: readonly string[]) => DrillDirection | null;
+type LruCache<V> = {
+    /** Returns the value and marks it as the most recent. */
+    get: (key: string) => V | undefined;
+    /** Does not mark it as recent (to check without altering the order). */
+    has: (key: string) => boolean;
+    /** Inserts; if capacity is exceeded, evicts the least recent. */
+    set: (key: string, value: V) => void;
+    delete: (key: string) => void;
+    clear: () => void;
+    readonly size: number;
+};
+/** Cache of the levels already computed (8 entries). Going up recomputes nothing. */
+declare const DEFAULT_LEVEL_CACHE_SIZE = 8;
+declare const createLruCache: <V>(capacity?: number) => LruCache<V>;
+
+/** What is drawn at each depth: the (already filtered) features and how they are identified. */
+type ChainLevel = {
+    features: readonly Feature[];
+    idOf: (feature: Feature) => string | undefined;
+};
+type BuildProjectionChainParams = {
+    /** `levels[d]` = what is shown at depth `d`. It has `path.length + 1` elements. */
+    levels: readonly ChainLevel[];
+    /** Ids from the root: `path[d]` is the region of `levels[d]` that is entered. */
+    path: readonly string[];
+    name?: ProjectionName;
+    width: number;
+    height: number;
+    padding?: number | Padding;
+    /** Explicit framings by id in lon/lat (Spain with the Canary Islands). Overrides the main body. */
+    focusBounds?: Readonly<Record<string, LonLatBounds | null | undefined>>;
+};
+type ProjectionChain = {
+    /** `projections[d]` frames region `path[d − 1]` within `projections[d − 1]` (0 being the world). */
+    projections: GeoProjection[];
+    /**
+     * Id of the region that could not be framed (it is not in the parent level, or has no extent).
+     * From there on, the projections repeat the last valid one, so the map does not break.
+     */
+    missing: string | null;
+};
+/**
+ * The projection chain for the whole route: the root is fitted to the world and each
+ * level is its parent's with `scale`/`translate` readjusted to the chosen region's main body
+ * (`rebaseProjection`). A pure function of (levels, route, size, padding). On resize it is
+ * recomputed entirely: one `fitExtent` per level.
+ */
+declare const buildProjectionChain: ({ levels, path, name, width, height, padding, focusBounds, }: BuildProjectionChainParams) => ProjectionChain;
+
+export { INERTIA_TAU_MS as $, DEFAULT_LEVEL_CACHE_SIZE as A, type BoundsToTransformParams as B, CATEGORICAL_PALETTES as C, DEFAULT_ASPECT_RATIO as D, DEFAULT_MAX_RADIUS as E, DEFAULT_PADDING as F, DEFAULT_PROJECTION as G, DEFAULT_ZOOM_MAX as H, DEFAULT_ZOOM_MIN as I, DIVERGING_PALETTES as J, type DivergingPaletteName as K, type DrillContext as L, type DrillCrumb as M, type DrillDirection as N, type DrillLayer as O, type DrillLayerRole as P, type DrillMachineEvent as Q, type DrillMachineState as R, type DrillPhase as S, type Extent as T, FIT_TRANSFORM as U, type FlightDurationParams as V, type GeographyData as W, type GeographyInput as X, type GetFocusExtentParams as Y, type GetFocusGeometryParams as Z, INERTIA_MIN_VELOCITY as _, type Bubble as a, createLruCache as a$, INERTIA_WINDOW_MS as a0, type InertiaOffsetParams as a1, type JoinDataOptions as a2, type JoinResult as a3, type LegendItem as a4, type LevelShape as a5, type LonLatBounds as a6, type LruCache as a7, MAX_FLIGHT_MS as a8, MIN_FLIGHT_MS as a9, type ViewLevel as aA, type ViewState as aB, type ZoomControlsOptions as aC, type ZoomEventLike as aD, type ZoomFilterParams as aE, type ZoomKeyAction as aF, type ZoomOptions as aG, type ZoomTarget as aH, applyTransform as aI, boundsToTransform as aJ, bubbleScale as aK, buildBreadcrumbs as aL, buildCategoricalLegend as aM, buildLegend as aN, buildProjectionChain as aO, buildSizeLegend as aP, clampPath as aQ, classIndex as aR, classifyDrill as aS, computeAspectRatio as aT, computeThresholds as aU, constrainAxis as aV, constrainTransform as aW, contextOf as aX, createCategoricalScale as aY, createColorScale as aZ, createDrillState as a_, type Padding as aa, type Point as ab, type PreserveViewParams as ac, type ProjectionChain as ad, type ProjectionName as ae, type RadiusScale as af, type RebaseParams as ag, type RebaseResult as ah, type ReleaseVelocityParams as ai, type ResolveVariantOptions as aj, type ResolveZoomTargetParams as ak, type ResolvedCategory as al, type ResolvedZoom as am, SEQUENTIAL_PALETTES as an, type SequentialPaletteName as ao, type Size as ap, type SizeLegendItem as aq, THEMES as ar, type ThemeName as as, type ToFeatureCollectionOptions as at, type ToViewStateParams as au, type TransitionResult as av, type VariantConfig as aw, type VariantEntry as ax, type VariantName as ay, type VariantResult as az, type BubbleScaling as b, createProjection as b0, createRadiusScale as b1, createZoomFilter as b2, createZoomInterpolator as b3, defaultFormatValue as b4, defineTheme as b5, drillDirectionBetween as b6, drillReducer as b7, en as b8, es as b9, resolveZoomTarget as bA, savedCameraFor as bB, themeToCssVars as bC, toFeatureCollection as bD, toViewState as bE, transformToZoomView as bF, unwrapGeography as bG, validateLevels as bH, zoomKeyAction as bI, extendTheme as ba, finiteValues as bb, flightDuration as bc, geographyKeyFor as bd, getAnchorPoint as be, getFocusExtent as bf, getFocusGeometry as bg, inertiaOffset as bh, invertTransform as bi, isFitTransform as bj, isThemeName as bk, joinData as bl, layerKey as bm, normalizePadding as bn, preserveView as bo, projectBounds as bp, projectionFactory as bq, rebaseProjection as br, relativeTransform as bs, releaseVelocity as bt, resolveControls as bu, resolveDrillData as bv, resolveLabels as bw, resolveTheme as bx, resolveVariant as by, resolveZoomOptions as bz, type BuildLegendOptions as c, type BuildProjectionChainParams as d, type CameraOptions as e, type CameraSample as f, type CameraTransform as g, type CategoricalPaletteName as h, type CategoricalScale as i, type CategorySpec as j, type ChainLevel as k, type ChoroplethLabels as l, type ChoroplethTheme as m, type Classification as n, type ColorScale as o, type ColorScaleOptions as p, type ConstrainAxisParams as q, type ConstrainTransformParams as r, type Corner as s, type CreateCategoricalScaleOptions as t, type CreateProjectionOptions as u, DEFAULT_BUBBLE_FILL as v, DEFAULT_CLASSES as w, DEFAULT_EMPTY_FILL as x, DEFAULT_FLIGHT_CURVATURE as y, DEFAULT_FOCUS_BOUNDS as z };