choropleth-kit 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1186 @@
+import * as react from 'react';
+import { MouseEventHandler, PointerEventHandler, Dispatch, ReactNode, RefObject, CSSProperties, Ref, ReactElement } from 'react';
+import { Feature, FeatureCollection } from 'geojson';
+import { ab as Point, X as GeographyInput, L as DrillContext, aw as VariantConfig, ae as ProjectionName, N as DrillDirection, g as CameraTransform, aH as ZoomTarget, e as CameraOptions, av as TransitionResult, aB as ViewState, M as DrillCrumb, W as GeographyData, l as ChoroplethLabels, a3 as JoinResult, a6 as LonLatBounds, aG as ZoomOptions, am as ResolvedZoom, aa as Padding, a4 as LegendItem, aq as SizeLegendItem, a as Bubble, o as ColorScale, k as ChainLevel, R as DrillMachineState, Q as DrillMachineEvent, ad as ProjectionChain, s as Corner, as as ThemeName, m as ChoroplethTheme } from './drill-chain-DCiuiZKK.js';
+export { ar as THEMES, b5 as defineTheme, ba as extendTheme, bC as themeToCssVars } from './drill-chain-DCiuiZKK.js';
+import { GeoProjection } from 'd3-geo';
+import 'topojson-specification';
+import 'd3-interpolate';
+import 'd3-scale-chromatic';
+
+/** Drill-down level an item belongs to. Without drill: always the root. */
+type DrillLevelInfo = {
+    id: string;
+    depth: number;
+};
+/** Default level while the drill-down does not exist. */
+declare const ROOT_LEVEL: DrillLevelInfo;
+type RegionItem<TDatum> = {
+    kind: "region";
+    id: string;
+    feature: Feature;
+    /** `undefined` = region without data. */
+    datum: TDatum | undefined;
+    level: DrillLevelInfo;
+    /** There is a level below for this region. */
+    drillable: boolean;
+};
+type PointItem<TDatum> = {
+    kind: "point";
+    id: string;
+    /** The datum's [lon, lat]. */
+    coordinates: Point;
+    /** The region underneath, if the datum's id joins with one. */
+    feature: Feature | undefined;
+    datum: TDatum;
+    level: DrillLevelInfo;
+    drillable: boolean;
+};
+/**
+ * ONE type for everything interactive. `kind` discriminates: a store is not a
+ * region, but the consumer wants a single handler and a single tooltip.
+ */
+type MapItem<TDatum> = RegionItem<TDatum> | PointItem<TDatum>;
+/** Which item it is, without carrying its data: what the `map-store` keeps. */
+type ItemRef = {
+    kind: MapItem<unknown>["kind"];
+    id: string;
+};
+/** `MapItem` + what the tooltip needs to render. */
+type ItemContext<TDatum> = MapItem<TDatum> & {
+    /** Number, category (`categorical`) or `null` if there is no datum. */
+    value: number | string | null;
+    /** `value` formatted; empty string if there is no value. */
+    formattedValue: string;
+    /** Color the item is painted with. */
+    color: string;
+    /** Readable name: the region's `properties.name`, or the id. */
+    label: string;
+};
+
+/**
+ * A drill-down level: geometry + data + visual encoding of ONE depth (world, country,
+ * region…). Levels are described ONCE; the library takes care of the flight, the loading, the fade, the
+ * breadcrumbs and the keyboard.
+ */
+type DrillLevel<TDatum> = {
+    /** `"country"`, `"region"`, `"store"`… Unique within the list; it is the level's key. */
+    id: string;
+    /** Name of the LEVEL ("Countries"): root of the breadcrumbs and accessibility announcements. */
+    label?: string;
+    geography: GeographyInput | "inherit" | ((ctx: DrillContext) => GeographyInput);
+    objectName?: string;
+    /** Subset for this parent: a world admin-1 filtered by country. */
+    filterFeatures?: (feature: Feature, ctx: DrillContext) => boolean;
+    getFeatureId?: (feature: Feature) => string | undefined;
+    /** Geometry cache key. Default: `${id}:${parentId}` if `geography` is a function. */
+    geographyKey?: (ctx: DrillContext) => string;
+    /** Visual encoding of THIS level. If missing, the map's props are used (variant, getValue…). */
+    encoding?: VariantConfig<TDatum> & {
+        getId?: (datum: TDatum) => string;
+    };
+    /** Can you drill down from this item? Default: `true` if a next level exists. */
+    canDrill?: boolean | ((item: MapItem<TDatum>) => boolean);
+    /** `"inherit"` (default): perfect continuity (§11.2.4). Anything else: a fade after the flight. */
+    projection?: "inherit" | ProjectionName | (() => GeoProjection);
+    /** What stays visible of the parent. Default `"siblings"`. */
+    context?: "siblings" | "none";
+    /** Explicit framing by id in [lon, lat] (Spain with or without the Canary Islands…). */
+    focusBounds?: Readonly<Record<string, [[number, number], [number, number]]>>;
+};
+/**
+ * Identity with validation: it exists so TypeScript infers `TDatum` without annotations
+ * (`defineDrillLevels<Row>([...])`) and so a malformed list (empty, repeated ids) fails when it is
+ * DEFINED, with a message saying what to change, and not in the middle of a click.
+ */
+declare const defineDrillLevels: <TDatum>(levels: readonly DrillLevel<TDatum>[]) => readonly DrillLevel<TDatum>[];
+/** What `onDrill` and `onDrillEnd` receive. */
+type DrillEvent<TDatum> = {
+    direction: DrillDirection;
+    from: DrillContext;
+    to: DrillContext;
+    /** The clicked item, if any (there is none for the breadcrumb, the keyboard or the URL). */
+    item?: MapItem<TDatum>;
+};
+/** The event of going from `from` to `to`, or `null` if the route does not change. */
+declare const buildDrillEvent: <TDatum>({ from, to, item, }: {
+    from: readonly string[];
+    to: readonly string[];
+    item?: MapItem<TDatum>;
+}) => DrillEvent<TDatum> | null;
+/**
+ * Can you drill down from this item? (`data-drillable`, cursor, tooltip hint.) It needs a level below
+ * the current one, and the level's `canDrill` (boolean or function) must not forbid it.
+ */
+declare const isDrillable: <TDatum>(levels: readonly DrillLevel<TDatum>[], depth: number, item: MapItem<TDatum>) => boolean;
+/**
+ * Depth whose geometry is drawn at `depth`: an `"inherit"` level draws its parent's, so it climbs up to
+ * the first one that does not inherit. Two depths with the same source draw the same regions (stores
+ * over a country), and no separate context layer is needed.
+ */
+declare const sourceDepth: <TDatum>(levels: readonly DrillLevel<TDatum>[], depth: number) => number;
+
+/**
+ * What the buttons, the keyboard and (step 26) the imperative handle can ask of the zoom. It is
+ * registered by `use-zoom` when installing `d3-zoom`; each move returns a `Promise` that resolves when
+ * done (`completed: false` if a user gesture interrupted it).
+ */
+type ZoomApi = {
+    /**
+     * Flies to a region, some bounds or a center with zoom. `silent` (only with `duration: 0`) places the
+     * camera without notifying `onViewChange`: it is what `focusId` and `initialView` do on first render.
+     */
+    zoomTo: (target: ZoomTarget, options?: CameraOptions & {
+        silent?: boolean;
+    }) => Promise<TransitionResult>;
+    /**
+     * Flies to an EXACT camera (without `constrain` or `k` limits): the drill-down needs to end exactly at
+     * `R` so the projection change is invisible. `duration: 0` places the camera;
+     * with `silent` it does not notify `onViewChange`.
+     */
+    flyTo: (camera: CameraTransform, options?: {
+        duration?: number;
+        silent?: boolean;
+    }) => Promise<TransitionResult>;
+    /** Multiplies the current zoom (×2 zooms in, ×0.5 zooms out) centered on the view. */
+    zoomBy: (factor: number, options?: {
+        duration?: number;
+    }) => Promise<TransitionResult>;
+    /** Flight to the level's fit. `silent` (only with `duration: 0`) does not notify `onViewChange`. */
+    resetView: (options?: {
+        duration?: number;
+        silent?: boolean;
+    }) => Promise<TransitionResult>;
+    /** The current view (the real one, also mid-flight). */
+    getView: () => ViewState;
+};
+/**
+ * What the handle can ask of the drill (step 34). Registered by `useChoropleth` when the map has
+ * `drill`; each navigation returns a `Promise` that resolves on returning to rest at the requested
+ * route (`completed: false` if it was cancelled, failed, another navigation replaced it or the request was invalid).
+ */
+type DrillApi = {
+    drillDown: (id: string) => Promise<TransitionResult>;
+    drillUp: (steps?: number) => Promise<TransitionResult>;
+    drillTo: (path: readonly string[]) => Promise<TransitionResult>;
+};
+type PointerPosition = {
+    x: number;
+    y: number;
+};
+/** The map's interaction state. It lives OUTSIDE React. */
+type MapState = {
+    /** Item (region or point) under the cursor or with the first tap (touch). */
+    hovered: ItemRef | null;
+    /** Cursor position relative to the container; `null` if outside. */
+    pointer: PointerPosition | null;
+    /** Type of the last pointer that touched the map: decides whether the drill asks for one or two taps. */
+    pointerType: "mouse" | "pen" | "touch";
+    /** A zoom/pan gesture is in progress (mouse, touch or wheel). It does not include programmatic flights. */
+    interacting: boolean;
+    /**
+     * "Confirmed" camera: the one from the last time a gesture ENDED. During the gesture `d3-zoom` writes
+     * it straight to the DOM and this does not change (nothing per frame in React).
+     */
+    camera: CameraTransform;
+    /** Hint on how to zoom (Ctrl/⌘ + wheel, two fingers). It turns itself off. */
+    gestureHint: "wheel" | "touch" | null;
+};
+type MapStore = {
+    subscribe: (listener: () => void) => () => void;
+    getState: () => MapState;
+    /** Merges a patch. It does not notify if no field changes (same reference / same value). */
+    setState: (patch: Partial<MapState>) => void;
+    /** Shows the gesture hint and removes it on its own after `GESTURE_HINT_MS`. Repeating it extends the hint. */
+    showGestureHint: (kind: "wheel" | "touch") => void;
+    /** Cancels the hint timer (on unmount). */
+    dispose: () => void;
+    /** `use-zoom` registers its API here on install and `null` on uninstall. */
+    registerZoom: (api: ZoomApi | null) => void;
+    /** The zoom API, or `null` if zoom is disabled or not yet installed. */
+    getZoom: () => ZoomApi | null;
+    /** `useChoropleth` registers the drill API here (`null` without `drill` or on unmount). */
+    registerDrill: (api: DrillApi | null) => void;
+    /** The drill API, or `null` if the map has no `drill`. */
+    getDrill: () => DrillApi | null;
+    /** `Root` registers how to compute the view when there is NO zoom (`zoom={false}`): always the fit. */
+    registerFallbackView: (read: (() => ViewState) | null) => void;
+    /** The fallback view, or `null` if not yet registered. */
+    getFallbackView: () => ViewState | null;
+};
+/**
+ * Hover, pointer, confirmed camera, `interacting` and the gesture hint. (Keyboard focus arrives with
+ * accessibility.)
+ *
+ * If this were `useState` in `Root`, every region change or every `mousemove` would re-render `Root`
+ * and recompute join, scale, legend and bubbles. Here only whoever subscribes with
+ * `useMapStore(store, selector)` re-renders, and only when its selector returns a different value.
+ */
+declare const createMapStore: () => MapStore;
+/**
+ * Reads a slice of the store. The selector must return a stable value (a primitive or the same
+ * reference while it does not change): if it creates a new object on every call, React will
+ * re-render in a loop.
+ */
+declare const useMapStore: <T>(store: MapStore, selector: (state: MapState) => T) => T;
+
+/** Choreography phases the map reports to the hook (computed by `drillReducer`). */
+type DrillStatus = "idle" | "flying" | "loading" | "revealing";
+/**
+ * Channel through which the MAP writes `status` and the hook reads it with `useSyncExternalStore`. It
+ * lives outside React for the same reason as the `map-store`: the consumer's tree must not be
+ * rendered on every phase change.
+ */
+type DrillBridge = {
+    getStatus: () => DrillStatus;
+    setStatus: (status: DrillStatus) => void;
+    subscribe: (listener: () => void) => () => void;
+};
+declare const createDrillBridge: () => DrillBridge;
+/** Key (symbol) of the channel on the controller: for the map's internal use, not public API. */
+declare const DRILL_BRIDGE: unique symbol;
+type DrillBreadcrumb = DrillCrumb;
+type DrillController<TDatum> = {
+    levels: readonly DrillLevel<TDatum>[];
+    /** Ids from the root. Already trimmed to the levels that exist. */
+    path: readonly string[];
+    context: DrillContext;
+    /** The current level: `levels[path.length]`. */
+    level: DrillLevel<TDatum>;
+    breadcrumbs: readonly DrillBreadcrumb[];
+    /** Written by the map; while no map is mounted, `"idle"`. */
+    status: DrillStatus;
+    canDrillUp: boolean;
+    /**
+     * Goes down one level to child `id`. With no level below, it does nothing (and warns in development).
+     * Returns the route that ended up requested (already trimmed): the map uses it to know where it
+     * expects to arrive.
+     */
+    drillDown: (id: string) => readonly string[];
+    /** Goes up `steps` levels (1 by default); more than the depth = to the root. */
+    drillUp: (steps?: number) => readonly string[];
+    /** Any route: lateral, jumps, the URL. */
+    drillTo: (path: readonly string[]) => readonly string[];
+    /** Back to the root. */
+    reset: () => readonly string[];
+    /** @internal The channel through which the map publishes `status`. */
+    readonly [DRILL_BRIDGE]: DrillBridge;
+};
+type UseDrillDownOptions<TDatum> = {
+    levels: readonly DrillLevel<TDatum>[];
+    /** Controlled: you are in charge (e.g. from the URL). The hook only notifies via `onPathChange`. */
+    path?: readonly string[];
+    /** No controlado: ruta inicial. */
+    defaultPath?: readonly string[];
+    /** Called on every requested route change (click, keyboard, breadcrumbs, `drillTo`), controlled or not. */
+    onPathChange?: (path: readonly string[]) => void;
+    /**
+     * Name of each breadcrumb step. The id by default. (The hook does not see the geometry: the region's
+     * name, `properties.name`, is set by the map when it exists; here `feature` and `datum` are empty.)
+     */
+    getLabel?: (args: {
+        id: string;
+        depth: number;
+        feature?: Feature;
+        datum?: TDatum;
+    }) => string;
+};
+/**
+ * Drill-down navigation state: the route, in controlled or uncontrolled mode, and
+ * what is deduced from it (level, context, breadcrumbs). It loads no geometry and moves no camera:
+ * the map does that, and it also reports its phase back (`status`).
+ *
+ * Controlled = `path` present (the `<input value>` pattern). The route is trimmed to the levels that
+ * exist: with N levels, N − 1 ids at most.
+ */
+declare const useDrillDown: <TDatum>({ levels, path: controlledPath, defaultPath, onPathChange, getLabel, }: UseDrillDownOptions<TDatum>) => DrillController<TDatum>;
+/**
+ * The `drill` prop accepts a list of levels (uncontrolled) or a `useDrillDown` controller
+ * (controlled). This tells one from the other.
+ */
+declare const isDrillController: <TDatum>(drill: readonly DrillLevel<TDatum>[] | DrillController<TDatum>) => drill is DrillController<TDatum>;
+
+type GeographyStatus = "loading" | "ready" | "error";
+type UseGeographyResult = {
+    geography: GeographyData | undefined;
+    status: GeographyStatus;
+};
+/**
+ * Resolves the `geography` prop. Synchronous data is returned in the same render (no flicker and no
+ * effect); a promise or a loader is awaited in an effect (async loading = a real effect) and in the
+ * meantime `geography` is `undefined` and the status is `loading`.
+ *
+ * If it changes to another geometry that has not loaded yet, the previous one is kept until it arrives.
+ */
+declare const useGeography: (input: GeographyInput, key: string | undefined, onError?: (error: Error) => void) => UseGeographyResult;
+/** For tests only: empties the cache between tests. */
+declare const clearGeographyCache: () => void;
+
+/** A region ready to paint. */
+type Region<TDatum> = {
+    id: string;
+    feature: Feature;
+    /** `undefined` = region without data. */
+    datum: TDatum | undefined;
+    /** The `<path>`'s `d` attribute. */
+    path: string;
+    fill: string;
+    /** The datum's value: number, category (`categorical`) or `null` if there is no datum. */
+    value: number | string | null;
+    /** `value` ready to display ("1.5 %", "Europe"); empty string if there is no value. */
+    formattedValue: string;
+    /** There is a level below and `canDrill` allows it (always `false` without `drill`). */
+    drillable: boolean;
+    /** 0…1: how much its entrance is delayed in the reveal (distance from the center). Only while revealing. */
+    wave: number | undefined;
+    /** From `getRegionStyle`; `undefined` = the CSS one (1). */
+    opacity: number | undefined;
+    /** From `getRegionStyle`: a class of its own for this region. */
+    className: string | undefined;
+    /** From `getRegionStyle`: a pattern drawn ON TOP of the color (`"hatch"`, `"dots"` or the name of your own in `<Choropleth.Defs>`). */
+    pattern: string | undefined;
+    /** Legend class it belongs to (`data-class`), or `null` (no data, continuous scale, `bubble`). */
+    classIndex: number | null;
+};
+/**
+ * Per-region style: data-based exceptions the scale cannot express. It is evaluated in
+ * render and its fields reach the `<path>` as primitives, so it does not break the regions' `memo`.
+ */
+type RegionStyle = {
+    /** Replaces the scale's color (and `emptyFill`). */
+    fill?: string;
+    opacity?: number;
+    /** A class of its own; it is added to `classNames.region`. */
+    className?: string;
+    /**
+     * Pattern drawn over the color (the datum still shows through): `"hatch"` or `"dots"`, or the name of
+     * your own `<pattern>` defined in `<Choropleth.Defs>` with `useDefId(name)`. It needs `<Choropleth.Defs>`
+     * and `<Choropleth.Patterns>` (the preset and `Choropleth.Svg` already include them).
+     */
+    pattern?: "hatch" | "dots" | (string & {});
+};
+/**
+ * A drill layer that is NOT the active one. `context`: the levels above, in gray and
+ * with no data (the parent's scale and the child's are not comparable). `exiting`: the level that was
+ * just left, fading out. The paths are in the pixels of THEIR projection; `transform` carries them to
+ * those of the active level (it is the affine map `R` between the two projections), so the cached paths are reused.
+ */
+type DrillLayerView = {
+    key: string;
+    role: "context" | "exiting";
+    depth: number;
+    transform: CameraTransform;
+    paths: {
+        id: string | undefined;
+        d: string;
+        focus: boolean;
+        drillable: boolean;
+        /** `exiting` only: the color the region had (it fades with it). */
+        fill: string | undefined;
+    }[];
+};
+/** A crumb of the drill route. */
+type DrillNavItem = {
+    depth: number;
+    /** `null` at the root. */
+    id: string | null;
+    label: string;
+    /** The last one: the level being gone to (or being at). */
+    current: boolean;
+};
+/** What a breadcrumb needs (the preset's or yours). `null` without `drill`. */
+type DrillNav = {
+    items: DrillNavItem[];
+    canDrillUp: boolean;
+    /** Goes to the crumb at that depth (0 = root). */
+    drillTo: (depth: number) => void;
+    drillUp: (steps?: number) => void;
+};
+type JoinReport = Omit<JoinResult<unknown>, "joined">;
+/** What is dimmed when there is a selection or hover. */
+type DimOthers = "never" | "selection" | "hover-and-selection";
+type BaseOptions<TDatum> = {
+    /**
+     * TopoJSON or GeoJSON, a promise, or `() => import("…")`. Already-loaded data must have a stable
+     * reference (a module constant or `useMemo`).
+     */
+    geography?: GeographyInput;
+    /** Cache key for an async geometry (otherwise the function's identity is used). */
+    geographyKey?: string;
+    objectName?: string;
+    /** Discards regions before anything else (e.g. Antarctica: `(f) => f.id !== "010"`). */
+    filterFeatures?: (feature: Feature) => boolean;
+    /**
+     * `undefined` = loading (the previous data is kept, no warnings); `[]` = loaded and empty. With `drill`
+     * it can be a selector for the current level: `({ depth, parentId }) => rows.filter(…)`.
+     */
+    data: readonly TDatum[] | undefined | ((ctx: DrillContext) => readonly TDatum[] | undefined);
+    /**
+     * Drill-down: the list of levels (uncontrolled) or a `useDrillDown` (controlled).
+     * With `drill`, the geometry comes from the levels and `geography` is ignored.
+     */
+    drill?: readonly DrillLevel<TDatum>[] | DrillController<TDatum>;
+    /** When a level change STARTS (the route is already updated). */
+    onDrill?: (event: DrillEvent<TDatum>) => void;
+    /** When the new level has finished being shown. */
+    onDrillEnd?: (event: DrillEvent<TDatum>) => void;
+    /** If a level's geometry fails (or has 0 regions): it goes back to the previous level. */
+    onDrillError?: (event: {
+        error: unknown;
+        ctx: DrillContext;
+    }) => void;
+    /**
+     * The pointer has stayed 150 ms over a region you can drill into (or, on touch, it was tapped once):
+     * `ctx` is that of the level it would go down to. Use it to preload data (`queryClient.prefetchQuery`);
+     * that level's geometry is already preloaded by the map. Called once per dwell.
+     */
+    onDrillIntent?: (ctx: DrillContext) => void;
+    /** Forces the data loading state (pulse) even if `data` is defined. */
+    loading?: boolean;
+    getId: (datum: TDatum) => string;
+    /** The region's id if it is not `feature.id` (e.g. `(f) => f.properties?.iso_a2`). */
+    getFeatureId?: (feature: Feature) => string | undefined;
+    projection?: ProjectionName;
+    /**
+     * Width / height of the map. `"auto"` derives it from the geometry's bounds (Chile comes out tall,
+     * Norway wide). 960 / 500 by default, the world's proportion.
+     */
+    aspectRatio?: number | "auto";
+    emptyFill?: string;
+    formatValue?: (value: number) => string;
+    /** If given, the legend includes a "no data" item with this text. */
+    emptyLabel?: string;
+    /** UI texts (i18n). English by default; `es` is exported. */
+    labels?: Partial<ChoroplethLabels>;
+    /**
+     * Microstates that do not exist in the geometry (Andorra, Monaco…): `{ AD: [1.52, 42.51] }`. A datum
+     * whose id joins no region but is listed here is painted as a dot, with the datum's color. In
+     * `bubble`, as a bubble.
+     */
+    fallbackPoints?: Readonly<Record<string, Point>>;
+    /** Fixed size. If missing, the container (`containerRef`) is measured. */
+    width?: number;
+    height?: number;
+    /** Controlled: you are in charge. `null` = nothing selected. Without this, the library holds the state. */
+    selectedId?: string | null;
+    /** Uncontrolled: the initial selection. */
+    defaultSelectedId?: string | null;
+    /** Called when the selection changes (click on a region; click on the selected one = `null`). */
+    onSelectedIdChange?: (id: string | null) => void;
+    /** Dims the rest of the map. Defaults to `"selection"`. */
+    dimOthers?: DimOthers;
+    /** Click on a region or a point (`item.kind`). */
+    onItemClick?: (item: MapItem<TDatum>) => void;
+    /** Hover (or first tap, on touch). `null` on leaving. Only called when the item changes. */
+    onItemHover?: (item: MapItem<TDatum> | null) => void;
+    /**
+     * Per-region style based on its data: `(r) => r.datum?.estimated ? { opacity: 0.6 } : undefined`. Priority:
+     * `getRegionStyle` > scale color > `emptyFill`. Do not define `fill` on `.cm-region` in CSS: it would beat the datum.
+     */
+    getRegionStyle?: (region: Region<TDatum>) => RegionStyle | undefined;
+    /** Called every time the data↔regions join result changes (also in production). */
+    onJoinReport?: (report: JoinReport) => void;
+    /**
+     * Flies to this region (id) when it changes; with `null` it returns to the fit. On the **first render**
+     * it does not fly: it places the camera directly. It is the declarative form of `zoomTo`.
+     */
+    focusId?: string | null;
+    /**
+     * Explicit framings per region, in [[lonW, latS], [lonE, latN]]. They are merged with the library's
+     * (`DEFAULT_FOCUS_BOUNDS`: Spain **with the Canary Islands**). `{ ES: null }` returns to the geometric
+     * framing (main body) for that region.
+     */
+    focusBounds?: Readonly<Record<string, LonLatBounds | null>>;
+    /**
+     * Zoom and pan. On by default; `false` = static map. The wheel zooms with the mouse over
+     * the map (`wheel: "always"`); for maps inside a long page use `wheel: "cooperative"`.
+     */
+    zoom?: boolean | ZoomOptions;
+    /** Called if the async geometry load fails. Without this, a console warning is issued. */
+    onGeographyError?: (error: Error) => void;
+    /** Console warning about ids that did not join. Outside production only. Defaults to `true`. */
+    diagnostics?: boolean;
+};
+/** Common options + those of each `variant` (a discriminated union, see `core/variants.ts`). */
+type UseChoroplethOptions<TDatum> = BaseOptions<TDatum> & VariantConfig<TDatum>;
+/** Props ready to spread onto a region's `<path>` (`<path {...getRegionProps(r)} />`). */
+type RegionProps = {
+    "data-region-id": string;
+    "data-selected": true | undefined;
+    onClick: MouseEventHandler;
+    onPointerEnter: PointerEventHandler;
+    onPointerLeave: PointerEventHandler;
+};
+/** Props for the `<circle>` of a bubble with its own coordinates (a point). */
+type PointProps = {
+    "data-point-id": string;
+    onClick: MouseEventHandler;
+    onPointerEnter: PointerEventHandler;
+    onPointerLeave: PointerEventHandler;
+};
+/** A microstate painted as a dot (`fallbackPoints`) outside `bubble`. */
+type FallbackPoint<TDatum> = {
+    id: string;
+    x: number;
+    y: number;
+    r: number;
+    fill: string;
+    datum: TDatum;
+    value: number | string | null;
+    formattedValue: string;
+    coordinates: Point;
+};
+/** Radius in pixels of a fallback point. */
+declare const FALLBACK_POINT_RADIUS = 4;
+type UseChoroplethResult<TDatum> = {
+    /** Put this ref on the container so the map adapts to its width. */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    width: number;
+    height: number;
+    /** Phase of the drill choreography (`null` without `drill`). Published as `data-drill-phase`. */
+    drillPhase: "idle" | "flying" | "loading" | "revealing" | null;
+    /** Region being drilled into while the flight / load lasts (the rest is dimmed). */
+    drillFocusId: string | null;
+    /** Context layers (levels above, in gray) and the one that leaves. Empty without `drill`. */
+    drillLayers: DrillLayerView[];
+    /** Click on a region of a context layer (lateral navigation or jump). */
+    selectContextItem: (depth: number, id: string) => void;
+    /** Drill breadcrumbs and navigation (`null` without `drill`). */
+    drillNav: DrillNav | null;
+    /** `loading` while the async geometry arrives; `error` if it failed. */
+    status: GeographyStatus;
+    /** `true` while `data` is `undefined` (or `loading`): the last data is kept. */
+    dataLoading: boolean;
+    regions: Region<TDatum>[];
+    /** `d` of the regions WITHOUT an id: they are painted with `emptyFill`, with no interaction (Kosovo in world-atlas). */
+    anonymousPaths: string[];
+    /** Already-resolved "no data" color (`emptyFill` or the CSS variable). */
+    emptyFill: string;
+    /** Microstates painted as a dot (empty in `bubble`: there they are bubbles). */
+    fallbackPoints: FallbackPoint<TDatum>[];
+    labels: ChoroplethLabels;
+    /** Already-resolved zoom options; `null` if `zoom={false}`. */
+    zoom: ResolvedZoom | null;
+    /** The user's `onViewChange` (not part of `zoom`: it must not reinstall the behavior). */
+    onViewChange: ZoomOptions["onViewChange"];
+    /** Canvas pixels → [lon, lat] (`projection.invert`); `null` if it falls outside the globe. */
+    invert: (point: Point) => Point | null;
+    /** [lon, lat] → canvas pixels; `null` if it does not project. */
+    project: (coordinates: Point) => Point | null;
+    /** `focusId` as is, so `useZoom` applies it (fly or place the camera). */
+    focusId: string | null | undefined;
+    /**
+     * `ZoomTarget` → camera (already limited by `constrain`), or `null` if it cannot be resolved
+     * (nonexistent region). It is what `zoomTo`, `focusId` and `initialView` use.
+     */
+    resolveCamera: (target: ZoomTarget, options?: {
+        padding?: number | Padding;
+    }) => CameraTransform | null;
+    /** Interior borders (a `<path>`'s `d`). `null` with GeoJSON: use `stroke` on each region. */
+    borders: string | null;
+    /** Color legend (swatches with counts). Empty in `bubble` without `getColorValue`. */
+    legend: LegendItem[];
+    /** Size reference circles (`bubble` only). */
+    sizeLegend: SizeLegendItem[];
+    /** Already-positioned bubbles, from largest to smallest (`bubble` only). */
+    bubbles: Bubble<TDatum>[];
+    /** Numeric color scale. `null` in `categorical` and in `bubble` without `getColorValue`. */
+    scale: ColorScale | null;
+    joinReport: JoinReport;
+    /** Effective formatter (the user's or the default), for tooltip and legend. */
+    formatValue: (value: number) => string;
+    /** `true` if there is `onItemClick`: components set a `pointer` cursor. */
+    clickable: boolean;
+    /**
+     * Interaction state (hover, pointer) outside React. Read it with `useMapStore(store, s => s.hoveredId)`:
+     * that way changing region does not re-render the component that calls `useChoropleth`.
+     */
+    store: MapStore;
+    selectedId: string | null;
+    /** Selects a region (`null` clears it). It respects controlled mode: it only notifies. */
+    setSelectedId: (id: string | null) => void;
+    /** Hover of an item (or `null`). Updates the store and calls `onItemHover` only if it changes. */
+    hoverItem: (ref: ItemRef | null) => void;
+    /** Clic en un item: llama a `onItemClick`. */
+    clickItem: (ref: ItemRef) => void;
+    /** The complete item (with value, color and name) for the tooltip; `undefined` if it no longer exists. */
+    getItemContext: (ref: ItemRef) => ItemContext<TDatum> | undefined;
+    getRegionProps: (region: Region<TDatum>) => RegionProps;
+    getPointProps: (point: {
+        id: string;
+    }) => PointProps;
+};
+/**
+ * Level 3 (headless) and the engine of the other two: `<Choropleth.Root>` and `<ChoroplethMap>` call it
+ * and distribute its result. It returns data, not elements: you decide how to paint them.
+ *
+ * What is memoized and why: only what is expensive and what must have a stable identity.
+ *  - Geometry (`features`, `borders`): depends only on `geography` (and on the filter, by its RESULT).
+ *  - SVG paths: depend on geometry, projection and size. NOT on the data, so changing indicator or
+ *    `variant` recomputes not a single path (an acceptance criterion).
+ * The join and the scale are O(regions) and are recomputed on every render: memoizing them would
+ * require the consumer to stabilize `getId`/`getValue`/`classification`, and almost nobody does.
+ */
+declare const useChoropleth: <TDatum>(rawOptions: UseChoroplethOptions<TDatum>) => UseChoroplethResult<TDatum>;
+
+/**
+ * The drill-down engine inside the map. To the rest of the `useChoropleth` hook, a map
+ * with `drill` is a ONE-level map (the one being shown) with different options: this engine decides
+ * which level that is, loads its geometry (and that of its ancestors, for the projection chain) and
+ * hands over the effective options. That way the join, the scale, the bubbles and the legend know nothing about it.
+ *
+ * **The choreography is governed by `drillReducer`** (`core/drill.ts`, pure). This hook is the glue with
+ * the real world: it translates what happens (the consumer changes the route, geometry arrives, a load
+ * fails) into reducer events, and renders the resulting state. The camera flight and the reveal timer
+ * live in `use-drill-choreography.ts`, because they need the size and the projections.
+ *
+ *  - **Down / lateral:** the flight starts NOW (optimistic) and the load runs in parallel; the new
+ *    level is not shown until both are done.
+ *  - **Up / jump:** they are not requested until geometry and data are available (usually immediate: it is cached).
+ *  - **While loading** the previous level keeps showing with ITS data (never new data over old geometry).
+ */
+type DrillEngineParams<TDatum> = {
+    drill: readonly DrillLevel<TDatum>[] | DrillController<TDatum> | undefined;
+    /** `data` as is: a list, `undefined` (loading) or a level selector. */
+    data: readonly TDatum[] | undefined | ((ctx: DrillContext) => readonly TDatum[] | undefined);
+    /** The map's filter (Antarctica…). Applied only to the root geometry and whatever inherits it. */
+    filterFeatures: ((feature: Feature) => boolean) | undefined;
+    /** To read the camera when starting to go down (saved to return to it when going up). */
+    store: MapStore;
+    onDrill: ((event: DrillEvent<TDatum>) => void) | undefined;
+    onDrillEnd: ((event: DrillEvent<TDatum>) => void) | undefined;
+    onDrillError: ((event: {
+        error: unknown;
+        ctx: DrillContext;
+    }) => void) | undefined;
+};
+/** What was drawn before the last level change: the exiting layers (`exiting`) need it. */
+type DrillPrevious = {
+    path: readonly string[];
+    chain: readonly ChainLevel[];
+    /** Color each region was painted with: the exiting layer fades WITH its color, not in gray. */
+    fills: ReadonlyMap<string, string>;
+};
+type DrillEngine<TDatum> = {
+    /** `false` without the `drill` prop: the hook behaves as always. */
+    active: boolean;
+    controller: DrillController<TDatum> | null;
+    levels: readonly DrillLevel<TDatum>[];
+    /** The route of what is being shown (not the requested one, if the new one is still loading or the flight has not ended). */
+    shownPath: readonly string[];
+    /** Changes only when what is shown changes: serves as a key for effects. */
+    shownKey: string;
+    depth: number;
+    level: DrillLevel<TDatum> | null;
+    /** The geometry of the shown level, already resolved. */
+    geography: GeographyData | undefined;
+    status: GeographyStatus;
+    objectName: string | undefined;
+    /** Features of the shown level, already filtered. */
+    features: FeatureCollection | undefined;
+    /** Features of EACH depth `0..depth` of what is shown (the context layers). */
+    levelFeatures: readonly (FeatureCollection | undefined)[];
+    getFeatureId: ((feature: Feature) => string | undefined) | undefined;
+    /** What is drawn at each depth `0..depth`: for the projection chain. */
+    chain: readonly ChainLevel[];
+    /** Changes only if the content of `chain` changes (use it as a dependency instead of `chain`). */
+    chainSig: string;
+    /** The composite filter of the shown level: the borders (`createBorders`) need it. */
+    filterFeatures: ((feature: Feature) => boolean) | undefined;
+    /** The root geometry (for the `"auto"` aspect ratio, which must not change when going down). */
+    rootFeatures: FeatureCollection | undefined;
+    /** The shown level's data (`undefined` = loading). */
+    data: readonly TDatum[] | undefined;
+    /** Notes which item caused the next route change (received by `onDrill`). */
+    noteItem: (item: MapItem<TDatum>) => void;
+    /** The state machine (phase, layers, pending flight…). */
+    machine: DrillMachineState;
+    dispatch: Dispatch<DrillMachineEvent>;
+    /** What was shown before the last change (to draw the exiting layer). */
+    previous: DrillPrevious | null;
+    /** Records the colors of what is being shown; they are read on a level change (`previous.fills`). */
+    rememberFills: (fills: ReadonlyMap<string, string>) => void;
+    /** The chain of levels of a route (to compute where the camera flies); `null` if any are missing. */
+    chainLevelsFor: (path: readonly string[]) => ChainLevel[] | null;
+    /** The REQUESTED route (the controller's), not the shown one. */
+    target: readonly string[];
+    /**
+     * Loads the geometry of `path` (and its ancestors) into the cache without showing it: intent prefetch
+     *. Idempotent, silent and with no effect if it is already there or already being requested.
+     */
+    prefetch: (path: readonly string[]) => void;
+    /**
+     * Navigates with `run` (which calls the controller and returns the route that ended up requested) and
+     * returns a `Promise` that resolves when it returns to rest on it (`completed: false` if it was cut
+     * short or never got applied).
+     */
+    navigate: (run: (controller: DrillController<TDatum>) => readonly string[]) => Promise<TransitionResult>;
+};
+declare const useDrillEngine: <TDatum>({ drill, data, filterFeatures, store, onDrill, onDrillEnd, onDrillError, }: DrillEngineParams<TDatum>) => DrillEngine<TDatum>;
+
+/**
+ * Duration of the reveal: 200 ms of fade + up to 250 ms of staggering by distance from
+ * the click point. With "reduce motion" it is 0: the new level appears without animating.
+ */
+declare const REVEAL_MS = 450;
+type UseDrillChoreographyParams<TDatum> = {
+    engine: DrillEngine<TDatum>;
+    store: MapStore;
+    /** The projection chain of what is shown (or `null` if there is none yet). */
+    shownChain: ProjectionChain | null;
+    /** Builds a route's chain with the current size, padding and framings. */
+    chainFor: (levels: ChainLevel[], path: readonly string[]) => ProjectionChain;
+};
+/**
+ * The part of the choreography that needs the size and the projections: it moves the
+ * camera and marks the reveal as done. It reads from the reducer (`engine.machine`) WHAT to do and
+ * reports back WHAT happened (`FLIGHT_END`, `REVEAL_END`).
+ *
+ *  - **Down / lateral:** flies to `R`, the affine map separating the current level's projection from
+ *    the target's (`relativeTransform`). That way, when the flight ends, switching projection with an
+ *    identity camera paints the same pixels and the rebase is invisible. It does NOT go through
+ *    `constrain`: it has to end exactly at `R`.
+ *  - **Up / backing out:** flies to the camera that existed before going down (or to the fit).
+ *  - **No zoom** (`zoom={false}`) or no possible framing: there is no flight, the phase passes at once.
+ */
+declare const useDrillChoreography: <TDatum>({ engine, store, shownChain, chainFor, }: UseDrillChoreographyParams<TDatum>) => void;
+
+/**
+ * The imperative handle: what you get with `ref` on `<ChoroplethMap>` / `<Choropleth.Root>`
+ * and with `useChoroplethApi()` inside the compound. **Everything animated returns a `Promise`** that
+ * resolves when done, or when interrupted (`completed: false`); that way flights can be chained
+ * without timers: `await map.zoomTo("ES"); await map.zoomTo("FR");`.
+ *
+ * `drillDown`, `drillUp` and `drillTo` (step 34) navigate the `drill` levels; they resolve on returning
+ * to rest at the requested route. (`toSVGString` and `toPNG` are planned and arrive with export.)
+ */
+type ChoroplethMapHandle = {
+    /** Flies to a region (id), some `{ bounds }` or a center with zoom `{ center, zoom }`. */
+    zoomTo: (target: ZoomTarget, options?: CameraOptions) => Promise<TransitionResult>;
+    /** Multiplies the current zoom (2 = zoom in to double, 0.5 = zoom out to half), centered on the view. */
+    zoomBy: (factor: number, options?: Pick<CameraOptions, "duration">) => Promise<TransitionResult>;
+    /** Flight to the level's fit. */
+    resetView: (options?: Pick<CameraOptions, "duration">) => Promise<TransitionResult>;
+    /** The current view (also mid-flight). */
+    getView: () => ViewState;
+    /**
+     * Goes down to child `id` of what is being requested (not of what is shown: chaining `await` is safe).
+     * Resolves `completed: true` when the choreography ends at that route; `false` if something cut it
+     * short (a gesture, another navigation, a load error) or if the request was not valid (nonexistent id,
+     * `canDrill: false`, a map without `drill`): in those cases it also warns on the console outside production.
+     */
+    drillDown: (id: string) => Promise<TransitionResult>;
+    /** Goes up `steps` levels (1 by default; more = to the root). At the root it resolves `completed: true` and does nothing. */
+    drillUp: (steps?: number) => Promise<TransitionResult>;
+    /** Goes to any route (lateral, jump, the URL): `["ES", "ES-MD"]`; `[]` = the root. */
+    drillTo: (path: readonly string[]) => Promise<TransitionResult>;
+};
+
+/**
+ * `classNames` slots: a class of yours (Tailwind, CSS Modules) on each piece of the map,
+ * ADDED to the library's `cm-*` one (it never replaces it, so selectors like `.cm-region[data-drillable]`
+ * and the base styles keep working; to remove the base ones there is `unstyled`).
+ *
+ * Only the pieces that exist today are here. `sphere`, `graticule` and `labels` are planned and arrive with their layers.
+ */
+declare const CLASS_SLOTS: readonly ["root", "svg", "layer", "regions", "region", "borders", "bubbles", "bubble", "selection", "legend", "legendItem", "tooltip", "controls", "controlButton", "breadcrumb", "breadcrumbItem", "gestureHint"];
+type ClassSlot = (typeof CLASS_SLOTS)[number];
+type ChoroplethClassNames = Partial<Record<ClassSlot, string>>;
+
+/**
+ * The imperative handle from INSIDE the compound: a button that is a child of
+ * `<Choropleth.Root>` can call `zoomTo` without needing a `ref`.
+ */
+declare const useChoroplethApi: () => ChoroplethMapHandle;
+/**
+ * The id of an SVG definition (`<pattern>`, `<linearGradient>`, `<filter>`) of THIS map. With two maps
+ * on the page, `url(#hatch)` would always point to the first one: ids carry a per-instance prefix
+ * (`useId`). Use it to define your own inside `<Choropleth.Defs>` (`<pattern id={useDefId("stripes")}>`)
+ * and to reference them: `fill="url(#…)"`. The built-in ones are `"hatch"` and `"dots"`.
+ */
+declare const useDefId: (name: string) => string;
+
+type DefsProps = {
+    /** Your own definitions (`<pattern>`, `<linearGradient>`, `<filter>`), with `useDefId` ids. */
+    children?: ReactNode;
+};
+/**
+ * The map's `<defs>`: the built-in patterns (`hatch` and `dots`) plus yours. Ids carry a per-instance
+ * prefix (`useDefId`): with two maps on the page, each one references ITS definitions.
+ *
+ * The patterns draw with `currentColor` and the `<pattern>`'s own `color` is `--cm-pattern-color` (by
+ * default, the text color at 45 %), so they respect the theme (dark too).
+ */
+declare const Defs: ({ children }: DefsProps) => react.JSX.Element;
+
+/**
+ * Patterns, drawn ON TOP of each region's color (the datum still shows through underneath): those of
+ * `getRegionStyle().pattern` and that of regions without data (`emptyPattern` or the theme's). It goes
+ * between the regions and the borders. No events: it does not steal the mouse from what is underneath.
+ * It needs `<Choropleth.Defs>`.
+ */
+declare const Patterns: () => react.JSX.Element | null;
+
+/**
+ * Selector subscription to the CONFIRMED camera: it is re-evaluated when a gesture, a
+ * flight or a level change ends, **never per frame** (during the gesture `d3-zoom` writes to the DOM
+ * and React is unaware). Use it inside `<Choropleth.Root>`:
+ *
+ * ```tsx
+ * const zoomedIn = useCamera((view) => view.zoom > 3);
+ * ```
+ *
+ * The component only re-renders if the selector's result changes: primitives by `Object.is`, and
+ * objects or arrays (`(v) => v.center`) by shallow equality, so there is no need to memoize the
+ * selector or return a stable reference.
+ */
+declare const useCamera: <T>(selector: (view: ViewState) => T) => T;
+
+type UseZoomParams = {
+    svgRef: RefObject<SVGSVGElement | null>;
+    viewportRef: RefObject<SVGGElement | null>;
+    /** The `.cm-root` container: `--cm-k` and the `data-*` attributes are written here. */
+    rootRef: RefObject<HTMLElement | null>;
+    store: MapStore;
+    /** Canvas size (px). If it changes, the behavior is reinstalled and the camera restored. */
+    width: number;
+    height: number;
+    /** `null` = zoom disabled. */
+    options: ResolvedZoom | null;
+    /** To turn the camera into a geographic `ViewState`. */
+    invert: (point: Point) => Point | null;
+    /** [lon, lat] → CURRENT canvas pixels; with the previous canvas's `invert`, it preserves the view on resize. */
+    project: (coordinates: Point) => Point | null;
+    /** Called at the END of a gesture; never per frame. */
+    onViewChange: ((view: ViewState) => void) | undefined;
+    /** `ZoomTarget` → camera (already limited by `constrain`), or `null` if it cannot be resolved. */
+    resolveCamera: (target: ZoomTarget, options?: {
+        padding?: number | Padding;
+    }) => CameraTransform | null;
+    /** Flies to this region when it changes; `null` = back to the fit; the first value is placed without flying. */
+    focusId: string | null | undefined;
+    /** When it goes from "loading" to "ready" the `<svg>` appears: it has to hook up again. */
+    ready: boolean;
+};
+/**
+ * Hooks `d3-zoom` to the `<svg>`. It is the ONLY piece that uses `d3-selection`.
+ *
+ * Rules that make this smooth and keep it from fighting React:
+ *  - **React never writes the viewport's `transform`.** `d3-zoom` writes it every frame with
+ *    `setAttribute`. If React wrote it, any render (new data mid-pan) would overwrite it and the map
+ *    would jump.
+ *  - **Nothing per frame in React**: no `setState` in `zoom`. Per frame only the `transform`
+ *    attribute, `--cm-k` and `data-zoomed` are written to the DOM. The store is touched only at the
+ *    START and END of the gesture.
+ *  - **Primitive dependencies**: an inline `zoom={{ max: 20 }}` creates a new object on every render;
+ *    if the effect depended on it, `d3-zoom` would be reinstalled on every render.
+ */
+declare const useZoom: ({ svgRef, viewportRef, rootRef, store, width, height, options, invert, project, onViewChange, resolveCamera, focusId, ready, }: UseZoomParams) => void;
+
+type ContainerSize = {
+    width: number;
+    height: number;
+};
+type UseContainerSizeOptions = {
+    /** Size while there is no measurement (first render, SSR, jsdom). 960 wide by default. */
+    initial?: ContainerSize;
+    /** width / height. 960 / 500 by default, the world's proportion in Equal Earth. */
+    aspectRatio?: number;
+    /**
+     * Use the container's REAL height (which must have its own height, e.g. `height: 400px`).
+     * By default the height is derived from the width: if the `<svg>` set the height of a container with no
+     * height of its own, narrowing it would never lower the height and the map would lose its proportion.
+     */
+    useContainerHeight?: boolean;
+};
+/**
+ * Measures an element with `ResizeObserver`. Observing the DOM is a real side effect, so `useEffect`
+ * is the right tool here; whatever can be derived is derived while rendering.
+ *
+ * Only what was MEASURED is stored (real width and height); the height that comes from the ratio is
+ * computed while rendering. That way, if `aspectRatio` changes (e.g. `"auto"` when the geometry
+ * finishes loading) the height is corrected without waiting for another measurement.
+ *
+ * It never returns 0: a hidden or not-yet-measured container would give `width = 0` and
+ * `createProjection` throws on non-positive sizes. Until there is a valid measurement the previous one is kept.
+ */
+declare const useContainerSize: <T extends HTMLElement = HTMLDivElement>({ initial, aspectRatio, useContainerHeight, }?: UseContainerSizeOptions) => ContainerSize & {
+    ref: RefObject<T | null>;
+};
+
+/** Level 2 (compound): `<Choropleth.Root>` + the pieces you want, in the order you want. */
+declare const Choropleth: {
+    Root: <TDatum>(props: RootProps<TDatum> & {
+        ref?: react.Ref<ChoroplethMapHandle>;
+    }) => react.ReactElement | null;
+    Svg: ({ children, className, ariaLabel }: SvgProps) => react.JSX.Element;
+    Regions: () => react.JSX.Element;
+    Borders: () => react.JSX.Element | null;
+    Defs: ({ children }: DefsProps) => react.JSX.Element;
+    Patterns: () => react.JSX.Element | null;
+    Breadcrumb: ({ position, className, children }: BreadcrumbProps) => react.JSX.Element | null;
+    Bubbles: () => react.JSX.Element | null;
+    DrillLayers: ({ role }: {
+        role: "context" | "exiting";
+    }) => react.JSX.Element | null;
+    FallbackPoints: () => react.JSX.Element | null;
+    Selection: () => react.JSX.Element;
+    Viewport: ({ children }: {
+        children?: react.ReactNode;
+    }) => react.JSX.Element;
+    ZoomControls: ({ position, reset, className, }: ZoomControlsProps) => react.JSX.Element | null;
+    GestureHint: ({ className }: {
+        className?: string;
+    }) => react.JSX.Element;
+    Legend: ({ title, showCount, className, variant, interactive, children, }: LegendProps) => react.JSX.Element;
+    Tooltip: <TDatum>({ className, children }: TooltipProps<TDatum>) => react.JSX.Element | null;
+};
+
+/** Interior borders (a single path). Not drawn with GeoJSON: there each region carries its own stroke. */
+declare const Borders: () => react.JSX.Element | null;
+
+type BreadcrumbRenderContext = DrillNav;
+type BreadcrumbProps = {
+    /** Corner of the map. Without it, it is not positioned: you place it yourself (useful outside the map). */
+    position?: Corner;
+    className?: string;
+    /** Draws the breadcrumbs with your design system: `({ items, drillTo, drillUp }) => …`. */
+    children?: (context: BreadcrumbRenderContext) => ReactNode;
+};
+/**
+ * Breadcrumbs for the drill route: `<nav>` + `<ol>`, root with the first level's label
+ * (or `labels.breadcrumbRoot`), the last step with `aria-current="page"` and a "←" button if you can go
+ * up. They are real `<button>`s: focus and keyboard for free. Each earlier crumb goes up to that level.
+ *
+ * It reflects the REQUESTED route, not the shown one: as soon as you click, the new crumb is there
+ * (while the camera flies). Without `drill` it draws nothing. With `children` (a render prop) the look is yours.
+ */
+declare const Breadcrumb: ({ position, className, children }: BreadcrumbProps) => react.JSX.Element | null;
+
+/**
+ * Bubbles (`bubble` variant). They already come sorted from largest to smallest, so the small ones end
+ * up on top.
+ *
+ * Two kinds, with different interaction:
+ *  - **At a region's centroid** (`coordinates: null`): they do not capture the mouse; hover and click
+ *    are handled by the region underneath (a `region` item).
+ *  - **With their own coordinates** (stores): they are `point` items, with their own hover, click and tooltip.
+ */
+declare const Bubbles: () => react.JSX.Element | null;
+
+/**
+ * The drill layers that are NOT the active one, inside the camera:
+ *  - `context`: the levels above, in gray and with no datum color. Cartographic reason: the parent's
+ *    scale and the child's differ; seeing both in color invites comparing what is not comparable. Their
+ *    drillable regions can be clicked (lateral navigation).
+ *  - `exiting`: the level that was just left, fading out.
+ *
+ * The paths are each level's CACHED ones, in the pixels of its projection; the `<g>`'s `transform` (the
+ * affine map `R`, which is NOT the camera's) carries them to those of the active level: zero recomputation.
+ *
+ * `role="context"` goes BELOW the active regions and `role="exiting"` ABOVE (it fades over them).
+ */
+declare const DrillLayers: ({ role }: {
+    role: "context" | "exiting";
+}) => react.JSX.Element | null;
+
+/**
+ * Microstates the geometry does not draw (Andorra, Monaco, Singapore at 1:110m), painted as a dot with
+ * their datum's color (`fallbackPoints`). They are `point` items: they have their own
+ * hover, click and tooltip. Not used in `bubble`: there they are bubbles.
+ */
+declare const FallbackPoints: () => react.JSX.Element | null;
+
+type LegendRenderContext = {
+    items: LegendItem[];
+    /** Size reference circles (`bubble` only). */
+    sizeItems: SizeLegendItem[];
+    /** `null` in `categorical` and in `bubble` without `getColorValue`. */
+    scale: UseChoroplethResult<unknown>["scale"];
+    formatValue: (value: number) => string;
+};
+type LegendProps = {
+    title?: string;
+    /** Show the number of regions in each class. */
+    showCount?: boolean;
+    className?: string;
+    /**
+     * `"swatches"` (default): one row per class. `"bar"`: a bar with one segment per class and the breaks
+     * underneath (newspaper style; more compact). `"bar"` only works with numeric classes: with categories
+     * or a continuous scale it is drawn as usual.
+     */
+    variant?: "swatches" | "bar";
+    /**
+     * Hovering a class highlights its regions and dims the rest (default `true`). Without re-rendering
+     * regions: the legend writes `data-highlight-class` on the root and the CSS does the rest.
+     */
+    interactive?: boolean;
+    /** Headless legend: you receive the items and draw it yourself with your design system. */
+    children?: (context: LegendRenderContext) => ReactNode;
+};
+/** HTML legend. By default: swatches with ranges (classes) or a gradient bar (`linear`). */
+declare const Legend: ({ title, showCount, className, variant, interactive, children, }: LegendProps) => react.JSX.Element;
+
+/**
+ * The colored regions. ONE listener per event type on the `<g>` (delegation) instead of one
+ * per `<path>`: with hundreds of regions it is less work and no closures are recreated.
+ * Pointer Events: the same code for mouse, pen and touch.
+ */
+declare const Regions: () => react.JSX.Element;
+
+type RootProps<TDatum> = UseChoroplethOptions<TDatum> & {
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Does not apply the base styles of `styles.css` (the `--cm-*` variables you set still work). */
+    unstyled?: boolean;
+    /**
+     * Theme: a name (`"light"`, `"dark"`, `"minimal"`, `"contrast"`) or an object (`defineTheme`, `extendTheme`).
+     * It is translated into inline `--cm-*` variables on `.cm-root` (`themeToCssVars`), so they beat those you
+     * put in the CSS; to override one by hand, use `style`.
+     */
+    theme?: ThemeName | ChoroplethTheme;
+    /** Pattern over regions without data. It beats the theme's (`empty.pattern`); `"none"` removes it. */
+    emptyPattern?: "none" | "hatch" | "dots";
+    /** One class of yours per piece, ADDED to the `cm-*` one (Tailwind, CSS Modules). */
+    classNames?: ChoroplethClassNames;
+};
+/**
+ * Level 2: calls `useChoropleth` ONCE and distributes the result by Context to its children.
+ * It is the measured container (`containerRef`) and the tooltip's position reference.
+ *
+ * `ref` gives the imperative handle (`zoomTo`, `zoomBy`, `resetView`, `getView`). `forwardRef` is used
+ * (and not `ref` as a prop, which only exists in React 19) so that it also works in React 18.
+ */
+declare const Root: <TDatum>(props: RootProps<TDatum> & {
+    ref?: Ref<ChoroplethMapHandle>;
+}) => ReactElement | null;
+
+/**
+ * Highlights the hovered item and the selected region, ON TOP of the borders: if their outline were
+ * painted in `Regions`, the neighbors (painted later) would half-cover it. `pointerEvents: none` so
+ * this layer does not steal the mouse from what is underneath.
+ *
+ * A region is highlighted with a copy of its outline; a point, with a ring around its bubble.
+ */
+declare const Selection: () => react.JSX.Element;
+
+type SvgProps = {
+    /**
+     * Map layers, bottom to top. By default, inside a `Viewport` (the camera): `Regions`, `Borders`,
+     * `Bubbles`, `FallbackPoints` and `Selection`. If you pass your own layers, wrap them in
+     * `<Choropleth.Viewport>` so they move with the zoom.
+     */
+    children?: ReactNode;
+    className?: string;
+    ariaLabel?: string;
+};
+/**
+ * The `<svg>`. It exists as its own piece because `Root` mixes SVG (regions, borders) and HTML
+ * (legend, tooltip), and an HTML element cannot live inside an `<svg>`.
+ * (It is the only difference from the documented example.)
+ *
+ * While the asynchronous geometry has not arrived, it draws a skeleton with the same proportion the
+ * map will have: the page does not jump when it appears.
+ */
+declare const Svg: ({ children, className, ariaLabel }: SvgProps) => react.JSX.Element;
+
+/**
+ * The "Use Ctrl + scroll to zoom" hint (⌘ on macOS) or "Use two fingers to move the map"
+ *. It only appears with `wheel: "cooperative"`, when a gesture does NOT zoom but can
+ * be taught how: with `"always"` there is nothing to teach. It lasts 1.5 s.
+ *
+ * It is `aria-hidden`: a visual aid, not a message for screen readers (keyboard zoom and the buttons
+ * are already accessible). It is always in the DOM and shown with an attribute + CSS: that way it
+ * fades in and out, and the text does not disappear before it finishes fading.
+ */
+declare const GestureHint: ({ className }: {
+    className?: string;
+}) => react.JSX.Element;
+
+/**
+ * The camera: the `<g>` to which `d3-zoom` applies the zoom and pan `transform`.
+ * Everything that must move with the map (regions, borders, bubbles, selection) goes inside.
+ *
+ * ⚠️ **React never writes this `<g>`'s `transform` attribute**; that is why no prop touches it. It is
+ * written by `d3-zoom` every frame. If React wrote it, any render would overwrite d3's
+ * internal state and the map would jump.
+ */
+declare const Viewport: ({ children }: {
+    children?: ReactNode;
+}) => react.JSX.Element;
+
+type ZoomControlsProps = {
+    /** Corner of the map. Defaults to `"bottom-right"`. */
+    position?: Corner;
+    /** Show "reset view". Defaults to `true`. */
+    reset?: boolean;
+    className?: string;
+};
+/**
+ * `+` / `−` / `⟲` buttons. They are real `<button>`s (focus, keyboard and screen
+ * reader for free), with `aria-label` from `labels`.
+ *
+ * They are disabled according to the confirmed camera: `−` at minimum zoom, `+` at maximum and `⟲` if
+ * you are already at the fit (it does not promise what it cannot do). They subscribe to the camera
+ * through the store: a gesture does not re-render the map, only these buttons and only when the gesture ends.
+ *
+ * Opt-in: in the preset, `zoom={{ controls: true }}`; in the compound, put it wherever you like.
+ */
+declare const ZoomControls: ({ position, reset, className, }: ZoomControlsProps) => react.JSX.Element | null;
+
+/** What the tooltip receives: the `MapItem` (region or point) + value, color and name. */
+type TooltipContext<TDatum> = ItemContext<TDatum>;
+type TooltipProps<TDatum> = {
+    className?: string;
+    /** Tooltip content. By default: the region's name and formatted value. */
+    children?: (context: TooltipContext<TDatum>) => ReactNode;
+};
+/**
+ * HTML tooltip next to the cursor. The library decides WHAT (typed context) and WHERE; you, the look.
+ *
+ * It subscribes by itself to the hover and the cursor (`useMapStore`): moving it re-renders neither
+ * `Root` nor the regions. Without measuring its size, it flips to the other side of the cursor in the
+ * right / bottom half of the map so as not to overflow the container.
+ */
+declare const Tooltip: <TDatum>({ className, children }: TooltipProps<TDatum>) => react.JSX.Element | null;
+
+type LegendPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+type LegendOptions = {
+    title?: string;
+    /** Corner of the map where it is overlaid. Defaults to `bottom-left`. */
+    position?: LegendPosition;
+    showCount?: boolean;
+    /** `"swatches"` (default) or `"bar"`: a bar with one segment per class and the breaks underneath. */
+    variant?: "swatches" | "bar";
+    /** Hovering a class highlights its regions (default `true`). */
+    interactive?: boolean;
+};
+type ChoroplethMapProps<TDatum> = UseChoroplethOptions<TDatum> & {
+    /** `false` hides the legend. */
+    legend?: LegendOptions | false;
+    /** Drill breadcrumbs (only with `drill`). `false` hides them; top-left by default. */
+    breadcrumb?: {
+        position?: LegendPosition;
+    } | false;
+    /** Tooltip content. Without this: the region's name and formatted value. */
+    renderTooltip?: (context: TooltipContext<TDatum>) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    unstyled?: boolean;
+    /** `"light"` · `"dark"` · `"minimal"` · `"contrast"` or an object (`defineTheme`, `extendTheme`). */
+    theme?: ThemeName | ChoroplethTheme;
+    /** Pattern over regions without data (`"hatch"`, `"dots"`); it beats the theme's. */
+    emptyPattern?: "none" | "hatch" | "dots";
+    /** One class of yours per piece, ADDED to the `cm-*` one (Tailwind, CSS Modules). */
+    classNames?: ChoroplethClassNames;
+    ariaLabel?: string;
+};
+/**
+ * Level 1 (preset). `ref` gives the imperative handle: `ref.current.zoomTo("ES")`.
+ */
+declare const ChoroplethMap: <TDatum>(props: ChoroplethMapProps<TDatum> & {
+    ref?: Ref<ChoroplethMapHandle>;
+}) => ReactElement | null;
+
+export { Borders, Breadcrumb, type BreadcrumbProps, type BreadcrumbRenderContext, Bubbles, CameraOptions, Choropleth, type ChoroplethClassNames, ChoroplethMap, type ChoroplethMapHandle, type ChoroplethMapProps, ChoroplethTheme, type ClassSlot, type ContainerSize, DRILL_BRIDGE, Defs, type DefsProps, type DimOthers, type DrillBreadcrumb, type DrillBridge, DrillContext, type DrillController, type DrillEngine, type DrillEngineParams, type DrillEvent, type DrillLayerView, DrillLayers, type DrillLevel, type DrillLevelInfo, type DrillNav, type DrillNavItem, type DrillStatus, FALLBACK_POINT_RADIUS, type FallbackPoint, FallbackPoints, type GeographyStatus, GestureHint, type ItemContext, type ItemRef, type JoinReport, Legend, type LegendOptions, type LegendPosition, type LegendProps, type LegendRenderContext, type MapItem, type MapState, type MapStore, Patterns, type PointItem, type PointProps, type PointerPosition, REVEAL_MS, ROOT_LEVEL, type Region, type RegionItem, type RegionProps, type RegionStyle, Regions, Root, type RootProps, Selection, Svg, type SvgProps, ThemeName, Tooltip, type TooltipContext, type TooltipProps, TransitionResult, type UseChoroplethOptions, type UseChoroplethResult, type UseContainerSizeOptions, type UseDrillDownOptions, type UseGeographyResult, type UseZoomParams, ViewState, Viewport, type ZoomApi, ZoomControls, type ZoomControlsProps, ZoomOptions, ZoomTarget, buildDrillEvent, clearGeographyCache, createDrillBridge, createMapStore, defineDrillLevels, isDrillController, isDrillable, sourceDepth, useCamera, useChoropleth, useChoroplethApi, useContainerSize, useDefId, useDrillChoreography, useDrillDown, useDrillEngine, useGeography, useMapStore, useZoom };