choropleth-kit 0.1.0 → 0.2.0

package/dist/core.js

@@ -53,6 +53,7 @@ import {
   defineTheme,
   drillDirectionBetween,
   drillReducer,
+  dropOverseas,
   en,
   es,
   extendTheme,
@@ -78,11 +79,13 @@ import {
   projectBounds,
   projectionFactory,
   rebaseProjection,
+  regionRotation,
   relativeTransform,
   releaseVelocity,
   resolveControls,
   resolveDrillData,
   resolveLabels,
+  resolveRegion,
   resolveTheme,
   resolveVariant,
   resolveZoomOptions,
@@ -95,7 +98,7 @@ import {
   unwrapGeography,
   validateLevels,
   zoomKeyAction
-} from "./chunk-R3XS6XPP.js";
+} from "./chunk-ZN6SLXL3.js";
 export {
   CATEGORICAL_PALETTES,
   DEFAULT_ASPECT_RATIO,
@@ -151,6 +154,7 @@ export {
   defineTheme,
   drillDirectionBetween,
   drillReducer,
+  dropOverseas,
   en,
   es,
   extendTheme,
@@ -176,11 +180,13 @@ export {
   projectBounds,
   projectionFactory,
   rebaseProjection,
+  regionRotation,
   relativeTransform,
   releaseVelocity,
   resolveControls,
   resolveDrillData,
   resolveLabels,
+  resolveRegion,
   resolveTheme,
   resolveVariant,
   resolveZoomOptions,

package/dist/{drill-chain-DCiuiZKK.d.ts → drill-chain-C8hhHBnd.d.ts}

@@ -807,6 +807,11 @@ type CreateProjectionOptions = {
     height: number;
     /** Geometry that must fit entirely in `width × height`. */
     featureCollection: FeatureCollection;
+    /**
+     * `[λ, φ]` rotation applied BEFORE the fit (d3's `projection.rotate`). It moves the antimeridian cut away
+     * from the geometry (`regionRotation`): the Pacific or Russia would otherwise be torn across both edges.
+     */
+    rotate?: readonly [number, number];
 };
 /**
  * Creates an already-fitted d3 projection (`fitSize`) so the geometry fits the container snugly.
@@ -815,7 +820,7 @@ type CreateProjectionOptions = {
  * 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;
+declare const createProjection: ({ name, width, height, featureCollection, rotate, }: CreateProjectionOptions) => GeoProjection;
 /** Aspect ratio used if the geometry cannot be measured (the world in Equal Earth). */
 declare const DEFAULT_ASPECT_RATIO: number;
 /**
@@ -826,9 +831,10 @@ declare const DEFAULT_ASPECT_RATIO: number;
  * 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, }: {
+declare const computeAspectRatio: ({ name, featureCollection, rotate, }: {
     name?: ProjectionName;
     featureCollection: FeatureCollection;
+    rotate?: readonly [number, number];
 }) => number;
 /**
  * The affine map `R` such that `to(p) === R(from(p))` for every `p`, where `R(q) = k·q + (x, y)`.
@@ -1226,6 +1232,8 @@ type BuildProjectionChainParams = {
     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>>;
+    /** Rotation of the ROOT projection (`regionRotation`); the levels below inherit it. */
+    rotate?: readonly [number, number];
 };
 type ProjectionChain = {
     /** `projections[d]` frames region `path[d − 1]` within `projections[d − 1]` (0 being the world). */
@@ -1242,6 +1250,7 @@ type ProjectionChain = {
  * (`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;
+declare const buildProjectionChain: ({ levels, path, name, width, height, padding, focusBounds, rotate, }: 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 };
+export { DEFAULT_LEVEL_CACHE_SIZE as A, 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, FIT_TRANSFORM as W, createLruCache as a$, INERTIA_MIN_VELOCITY as a0, INERTIA_TAU_MS as a1, INERTIA_WINDOW_MS as a2, MAX_FLIGHT_MS as a9, 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_, MIN_FLIGHT_MS as aa, SEQUENTIAL_PALETTES as an, THEMES as ar, 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, DEFAULT_BUBBLE_FILL as v, DEFAULT_CLASSES as w, DEFAULT_EMPTY_FILL as x, DEFAULT_FLIGHT_CURVATURE as y, DEFAULT_FOCUS_BOUNDS as z };
+export type { GetFocusGeometryParams as $, BoundsToTransformParams as B, DivergingPaletteName as K, LonLatBounds as L, DrillContext as M, DrillCrumb as N, DrillDirection as O, Point as P, DrillLayer as Q, DrillLayerRole as R, DrillMachineEvent as S, DrillMachineState as T, DrillPhase as U, Extent as V, FlightDurationParams as X, GeographyData as Y, GeographyInput as Z, GetFocusExtentParams as _, Bubble as a, InertiaOffsetParams as a3, JoinDataOptions as a4, JoinResult as a5, LegendItem as a6, LevelShape as a7, LruCache as a8, ViewLevel as aA, ViewState as aB, ZoomControlsOptions as aC, ZoomEventLike as aD, ZoomFilterParams as aE, ZoomKeyAction as aF, ZoomOptions as aG, ZoomTarget as aH, Padding as ab, PreserveViewParams as ac, ProjectionChain as ad, ProjectionName as ae, RadiusScale as af, RebaseParams as ag, RebaseResult as ah, ReleaseVelocityParams as ai, ResolveVariantOptions as aj, ResolveZoomTargetParams as ak, ResolvedCategory as al, ResolvedZoom as am, SequentialPaletteName as ao, Size as ap, SizeLegendItem as aq, ThemeName as as, ToFeatureCollectionOptions as at, ToViewStateParams as au, TransitionResult as av, VariantConfig as aw, VariantEntry as ax, VariantName as ay, VariantResult as az, BubbleScaling as b, BuildLegendOptions as c, BuildProjectionChainParams as d, CameraOptions as e, CameraSample as f, CameraTransform as g, CategoricalPaletteName as h, CategoricalScale as i, CategorySpec as j, ChainLevel as k, ChoroplethLabels as l, ChoroplethTheme as m, Classification as n, ColorScale as o, ColorScaleOptions as p, ConstrainAxisParams as q, ConstrainTransformParams as r, Corner as s, CreateCategoricalScaleOptions as t, CreateProjectionOptions as u };

package/dist/geo.d.ts

@@ -9,6 +9,9 @@ declare const isoNumericToAlpha2: Readonly<Record<string, string>>;
 /** Point [x, y] in pixels or [lon, lat] in degrees, depending on context. */
 type Point = readonly [number, number];
 
+/** Geographic bounds [[lonW, latS], [lonE, latN]]. If `lonE < lonW`, they cross the antimeridian. */
+type LonLatBounds = readonly [Point, Point];
+
 /**
  * [lon, lat] of the countries and territories that `world-110m` does NOT draw (at 1:110m the
  * microstates and most islands disappear). Pass it as `fallbackPoints` so a datum for Andorra or
@@ -19,6 +22,56 @@ type Point = readonly [number, number];
  */
 declare const worldFallbackPoints: Readonly<Record<string, Point>>;
 
+declare const REGION_PRESETS: {
+    africa: string[];
+    asia: string[];
+    europe: string[];
+    northAmerica: string[];
+    southAmerica: readonly string[];
+    oceania: string[];
+    northernAfrica: readonly string[];
+    easternAfrica: readonly string[];
+    middleAfrica: readonly string[];
+    southernAfrica: readonly string[];
+    westernAfrica: readonly string[];
+    centralAsia: readonly string[];
+    easternAsia: readonly string[];
+    southeasternAsia: readonly string[];
+    southernAsia: readonly string[];
+    westernAsia: readonly string[];
+    northernEurope: readonly string[];
+    westernEurope: readonly string[];
+    southernEurope: readonly string[];
+    easternEurope: readonly string[];
+    usAndCanada: readonly string[];
+    centralAmerica: readonly string[];
+    caribbean: readonly string[];
+    australiaAndNewZealand: readonly string[];
+    melanesia: readonly string[];
+    micronesia: readonly string[];
+    polynesia: readonly string[];
+    eu27: readonly string[];
+    nordics: readonly string[];
+    iberia: readonly string[];
+    latam: readonly string[];
+    mena: readonly string[];
+};
+type RegionPresetName = keyof typeof REGION_PRESETS;
+
+/**
+ * Overseas territories that `region` drops, by country: lon/lat boxes `[[west, south], [east, north]]`. A
+ * polygon of the country whose middle (of its bounding box) falls inside a box is not drawn (nor framed).
+ *
+ * It is CURATED, not computed: no distance rule separates Svalbard (overseas) from Peninsular Malaysia
+ * (not). It only lists what `world110m` actually draws, and each entry is covered by a test. At 1:110m
+ * Spain, Portugal and the Netherlands have no overseas polygons (the Canary Islands, the Azores and the
+ * Caribbean are not in the data); when a 1:50m geometry is added, its territories are added here.
+ *
+ * Alaska stays on purpose: it is part of the North American mass and a `northAmerica` map without it
+ * would be wrong. Showing or hiding territories per country is FEAT-023.
+ */
+declare const OVERSEAS_TERRITORIES: Readonly<Record<string, readonly LonLatBounds[]>>;
+
 /**
  * World at 1:110m (Natural Earth, public domain) as TopoJSON, with **ISO 3166-1 alpha-2 in `id`**
  * (`"ES"`) and the English name in `properties.name`. Use the `countries` object.
@@ -32,4 +85,5 @@ declare const worldFallbackPoints: Readonly<Record<string, Point>>;
  */
 declare const world110m: Topology;
 
-export { isoNumericToAlpha2, world110m, worldFallbackPoints };
+export { OVERSEAS_TERRITORIES, REGION_PRESETS, isoNumericToAlpha2, world110m, worldFallbackPoints };
+export type { RegionPresetName };

package/dist/geo.js

@@ -351,9 +351,105 @@ var worldFallbackPoints = {
   // Samoa
 };
 
+// src/geo/region-presets.ts
+var ids = (list) => list.split(" ");
+var northernEurope = ids("AX DK EE FI FO GB GG IE IM IS JE LT LV NO SE");
+var westernEurope = ids("AT BE CH DE FR LI LU MC NL");
+var southernEurope = ids("AD AL BA ES GI GR HR IT ME MK MT PT RS SI SM VA XK");
+var easternEurope = ids("BG BY CZ HU MD PL RO SK UA");
+var northernAfrica = ids("DZ EG EH LY MA SD TN");
+var easternAfrica = ids("BI DJ ER ET KE KM MG MU MW MZ RW SC SO SS TZ UG ZM ZW");
+var middleAfrica = ids("AO CD CF CG CM GA GQ ST TD");
+var southernAfrica = ids("BW LS NA SZ ZA");
+var westernAfrica = ids("BF BJ CI CV GH GM GN GW LR ML MR NE NG SL SN TG");
+var centralAsia = ids("KG KZ TJ TM UZ");
+var easternAsia = ids("CN HK JP KP KR MN MO TW");
+var southeasternAsia = ids("BN ID KH LA MM MY PH SG TH TL VN");
+var southernAsia = ids("AF BD BT IN IR LK MV NP PK");
+var westernAsia = ids("AE AM AZ BH CY GE IL IQ JO KW LB OM PS QA SA SY TR YE");
+var usAndCanada = ids("BM CA GL US");
+var centralAmerica = ids("BZ CR GT HN MX NI PA SV");
+var caribbean = ids("AG AW BB BS CU CW DM DO GD HT JM KN KY LC PR TT VC");
+var southAmerica = ids("AR BO BR CL CO EC FK GY PE PY SR UY VE");
+var australiaAndNewZealand = ids("AU NZ");
+var melanesia = ids("FJ NC PG SB VU");
+var micronesia = ids("FM GU KI MH NR PW");
+var polynesia = ids("PF TO TV WS");
+var REGION_PRESETS = {
+  // Continents: disjoint, each one is the union of its subregions.
+  africa: [
+    ...northernAfrica,
+    ...easternAfrica,
+    ...middleAfrica,
+    ...southernAfrica,
+    ...westernAfrica
+  ],
+  asia: [...centralAsia, ...easternAsia, ...southeasternAsia, ...southernAsia, ...westernAsia],
+  europe: [...northernEurope, ...westernEurope, ...southernEurope, ...easternEurope],
+  northAmerica: [...usAndCanada, ...centralAmerica, ...caribbean],
+  southAmerica,
+  oceania: [...australiaAndNewZealand, ...melanesia, ...micronesia, ...polynesia],
+  // Subregions (UN geoscheme).
+  northernAfrica,
+  easternAfrica,
+  middleAfrica,
+  southernAfrica,
+  westernAfrica,
+  centralAsia,
+  easternAsia,
+  southeasternAsia,
+  southernAsia,
+  westernAsia,
+  northernEurope,
+  westernEurope,
+  southernEurope,
+  easternEurope,
+  usAndCanada,
+  centralAmerica,
+  caribbean,
+  australiaAndNewZealand,
+  melanesia,
+  micronesia,
+  polynesia,
+  // Political / commercial groupings: they may overlap with everything else. FIRST CUT, to be confirmed with
+  // the tools that will use them (see FEAT-022); each one is a maintenance cost.
+  eu27: ids("AT BE BG CY CZ DE DK EE ES FI FR GR HR HU IE IT LT LU LV MT NL PL PT RO SE SI SK"),
+  nordics: ids("DK FI IS NO SE"),
+  iberia: ids("ES PT"),
+  latam: ids("AR BO BR CL CO CR CU DO EC GT HN HT MX NI PA PE PR PY SV UY VE"),
+  mena: ids("AE BH DZ EG EH IL IQ IR JO KW LB LY MA OM PS QA SA SY TN YE")
+};
+
+// src/geo/overseas.ts
+var OVERSEAS_TERRITORIES = {
+  // French Guiana.
+  FR: [
+    [
+      [-56, 1],
+      [-51, 7]
+    ]
+  ],
+  // Svalbard.
+  NO: [
+    [
+      [0, 73],
+      [40, 82]
+    ]
+  ],
+  // Hawaii.
+  US: [
+    [
+      [-162, 18],
+      [-154, 23]
+    ]
+  ]
+};
+
 // src/geo/index.ts
 var world110m = world_110m_default;
 export {
+  OVERSEAS_TERRITORIES,
+  REGION_PRESETS,
   isoNumericToAlpha2,
   world110m,
   worldFallbackPoints

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 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 { M as DrillContext, aH as ZoomTarget, e as CameraOptions, av as TransitionResult, aB as ViewState, aG as ZoomOptions, as as ThemeName, m as ChoroplethTheme } from './drill-chain-C8hhHBnd.js';
+import { Point, GeographyInput, VariantConfig, ProjectionName, DrillDirection, CameraTransform, DrillCrumb, GeographyData, ChoroplethLabels, JoinResult, LonLatBounds, ResolvedZoom, Padding, LegendItem, SizeLegendItem, Bubble, ColorScale, ChainLevel, DrillMachineState, DrillMachineEvent, ProjectionChain, Corner } from './core.js';
+export { ar as THEMES, b5 as defineTheme, ba as extendTheme, bC as themeToCssVars } from './drill-chain-C8hhHBnd.js';
 import { GeoProjection } from 'd3-geo';
 import 'topojson-specification';
 import 'd3-interpolate';
@@ -316,6 +317,54 @@ declare const useGeography: (input: GeographyInput, key: string | undefined, onE
 /** For tests only: empties the cache between tests. */
 declare const clearGeographyCache: () => void;
 
+declare const REGION_PRESETS: {
+    africa: string[];
+    asia: string[];
+    europe: string[];
+    northAmerica: string[];
+    southAmerica: readonly string[];
+    oceania: string[];
+    northernAfrica: readonly string[];
+    easternAfrica: readonly string[];
+    middleAfrica: readonly string[];
+    southernAfrica: readonly string[];
+    westernAfrica: readonly string[];
+    centralAsia: readonly string[];
+    easternAsia: readonly string[];
+    southeasternAsia: readonly string[];
+    southernAsia: readonly string[];
+    westernAsia: readonly string[];
+    northernEurope: readonly string[];
+    westernEurope: readonly string[];
+    southernEurope: readonly string[];
+    easternEurope: readonly string[];
+    usAndCanada: readonly string[];
+    centralAmerica: readonly string[];
+    caribbean: readonly string[];
+    australiaAndNewZealand: readonly string[];
+    melanesia: readonly string[];
+    micronesia: readonly string[];
+    polynesia: readonly string[];
+    eu27: readonly string[];
+    nordics: readonly string[];
+    iberia: readonly string[];
+    latam: readonly string[];
+    mena: readonly string[];
+};
+type RegionPresetName = keyof typeof REGION_PRESETS;
+
+/**
+ * What the `region` prop accepts: a preset (`"europe"`, `"westernEurope"`, `"eu27"`…), an ISO 3166-1 alpha-2
+ * code (`"ES"`), or a list mixing both. The `(string & {})` keeps autocompletion for the presets while
+ * still allowing any code.
+ */
+type RegionProp = RegionPresetName | (string & {}) | readonly (RegionPresetName | (string & {}))[];
+/** A `region` already resolved: the ids that stay, and a key that changes only when the CONTENT changes. */
+type ResolvedRegion = {
+    key: string;
+    ids: ReadonlySet<string>;
+};
+
 /** A region ready to paint. */
 type Region<TDatum> = {
     id: string;
@@ -396,7 +445,14 @@ type DrillNav = {
     drillTo: (depth: number) => void;
     drillUp: (steps?: number) => void;
 };
-type JoinReport = Omit<JoinResult<unknown>, "joined">;
+type JoinReport = Omit<JoinResult<unknown>, "joined"> & {
+    /**
+     * Ids of data that belong to the world but not to the map's `region` (e.g. a worldwide dataset on a map of
+     * Europe). They are expected, not an error: they are neither in `unmatchedData` nor warned about. `[]`
+     * without `region`.
+     */
+    outOfRegion: string[];
+};
 /** What is dimmed when there is a selection or hover. */
 type DimOthers = "never" | "selection" | "hover-and-selection";
 type BaseOptions<TDatum> = {
@@ -408,6 +464,15 @@ type BaseOptions<TDatum> = {
     /** Cache key for an async geometry (otherwise the function's identity is used). */
     geographyKey?: string;
     objectName?: string;
+    /**
+     * Restricts the map to a continent, a subregion or some countries, from the first frame (no flight, no
+     * world around it): `"europe"`, `"westernEurope"`, `"eu27"`, `"ES"`, `["ES", "PT"]`, `["europe", "MA"]`.
+     * It matches `feature.id` (or `getFeatureId`) against ISO 3166-1 alpha-2 codes. Overseas territories
+     * (Guiana, Svalbard, Hawaii…) are left out so they do not shrink the framing. Russia is in no preset:
+     * ask for it with `"RU"`. With `drill` it restricts the root level; the levels below bring their own
+     * geometry. Data outside the region is ignored without warnings (`joinReport.outOfRegion`).
+     */
+    region?: RegionProp;
     /** Discards regions before anything else (e.g. Antarctica: `(f) => f.id !== "010"`). */
     filterFeatures?: (feature: Feature) => boolean;
     /**
@@ -645,6 +710,8 @@ type DrillEngineParams<TDatum> = {
     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;
+    /** The map's `region`: like the filter, applied only to the root geometry (and whatever inherits it). */
+    region: ResolvedRegion | 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;
@@ -689,6 +756,8 @@ type DrillEngine<TDatum> = {
     filterFeatures: ((feature: Feature) => boolean) | undefined;
     /** The root geometry (for the `"auto"` aspect ratio, which must not change when going down). */
     rootFeatures: FeatureCollection | undefined;
+    /** The root geometry BEFORE the map's filter and `region`: what a datum "outside the region" belongs to. */
+    rootAll: FeatureCollection | undefined;
     /** The shown level's data (`undefined` = loading). */
     data: readonly TDatum[] | undefined;
     /** Notes which item caused the next route change (received by `onDrill`). */
@@ -716,7 +785,7 @@ type DrillEngine<TDatum> = {
      */
     navigate: (run: (controller: DrillController<TDatum>) => readonly string[]) => Promise<TransitionResult>;
 };
-declare const useDrillEngine: <TDatum>({ drill, data, filterFeatures, store, onDrill, onDrillEnd, onDrillError, }: DrillEngineParams<TDatum>) => DrillEngine<TDatum>;
+declare const useDrillEngine: <TDatum>({ drill, data, filterFeatures, region, 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
@@ -1183,4 +1252,5 @@ 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 };
+export { Borders, Breadcrumb, Bubbles, CameraOptions, Choropleth, ChoroplethMap, ChoroplethTheme, DRILL_BRIDGE, Defs, DrillContext, DrillLayers, FALLBACK_POINT_RADIUS, FallbackPoints, GestureHint, Legend, Patterns, REVEAL_MS, ROOT_LEVEL, Regions, Root, Selection, Svg, ThemeName, Tooltip, TransitionResult, ViewState, Viewport, ZoomControls, ZoomOptions, ZoomTarget, buildDrillEvent, clearGeographyCache, createDrillBridge, createMapStore, defineDrillLevels, isDrillController, isDrillable, sourceDepth, useCamera, useChoropleth, useChoroplethApi, useContainerSize, useDefId, useDrillChoreography, useDrillDown, useDrillEngine, useGeography, useMapStore, useZoom };
+export type { BreadcrumbProps, BreadcrumbRenderContext, ChoroplethClassNames, ChoroplethMapHandle, ChoroplethMapProps, ClassSlot, ContainerSize, DefsProps, DimOthers, DrillBreadcrumb, DrillBridge, DrillController, DrillEngine, DrillEngineParams, DrillEvent, DrillLayerView, DrillLevel, DrillLevelInfo, DrillNav, DrillNavItem, DrillStatus, FallbackPoint, GeographyStatus, ItemContext, ItemRef, JoinReport, LegendOptions, LegendPosition, LegendProps, LegendRenderContext, MapItem, MapState, MapStore, PointItem, PointProps, PointerPosition, Region, RegionItem, RegionProp, RegionProps, RegionStyle, RootProps, SvgProps, TooltipContext, TooltipProps, UseChoroplethOptions, UseChoroplethResult, UseContainerSizeOptions, UseDrillDownOptions, UseGeographyResult, UseZoomParams, ZoomApi, ZoomControlsProps };