@bicharts/chart-host 0.6.103 → 0.6.106

package/dist/index.mjs

@@ -5,7 +5,7 @@ import {
   formatSourceDateFor,
   isExcelDateFormat,
   normaliseAggregation
-} from "./chunk-D6A37G2G.mjs";
+} from "./chunk-MU4BWWO6.mjs";
 import {
   captureSvgSnapshot,
   chartSvgOf,
@@ -63,7 +63,6 @@ import {
   censusColourSpread,
   censusMarks,
   censusValuePlacement,
-  clearGeoCache,
   clippedTextFlag,
   colourSpreadFlag,
   compileRenderFn,
@@ -79,21 +78,16 @@ import {
   exportFileName,
   exportFormatsFor,
   exportTableService,
-  geoAssetFor,
-  geoFromCache,
   glyphSampleGrid,
   invalidSentinelReason,
   isBlankRender,
   isInvalidSentinelError,
   isPillBackdropAlpha,
-  loadGeo,
   minContrastOver,
   newIdScope,
   noopViewStateProvider,
   pickColorOver,
   pillBacksGlyph,
-  registerGeo,
-  registerGeoAsset,
   relativeLuminance,
   requiredD3Plugins,
   resolveAutoColorScale,
@@ -111,7 +105,7 @@ import {
   toRGBA,
   toSourceRows,
   valuePlacementFlag
-} from "./chunk-4BR6VJQX.mjs";
+} from "./chunk-K6UXTDMR.mjs";
 import {
   LASSO_AXES_SLOT,
   LASSO_COUNT_CLASS,
@@ -200,10 +194,18 @@ import {
   unpinScrolledAxis
 } from "./chunk-IE7TM6DX.mjs";
 import {
-  _3,
+  clearGeoCache,
+  geoAssetFor,
+  geoFromCache,
+  loadGeo,
+  registerGeo,
+  registerGeoAsset
+} from "./chunk-5WTQN5DL.mjs";
+import {
+  Kt,
   l,
   o
-} from "./chunk-CNT3QA3R.mjs";
+} from "./chunk-SYUJ4TPX.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import {
   ACTIVE_TICK_CLASS,
@@ -334,7 +336,12 @@ var OPTIONS_VOCABULARY = Object.freeze({
    * that made the chart asked for them. "on" / "off" is a reader's choice and wins either way.
    */
   hoverDropLines: entry({ timing: "live", default: "", values: ["", "on", "off"] }),
+  /** A province map draws the national borders over its provinces unless this is false (a reader's "Country borders"). */
+  geoBorders: entry({ timing: "live", default: true }),
   // ---- the next generated chart ----
+  /** A reader's "Derive provinces": false measures no city or coordinate rollup, so only a real province column offers
+   *  a province map. It changes what the profile measures, so it travels in the shape rather than as a field. */
+  deriveProvinces: entry({ timing: "next-generate", default: true }),
   levelOfDetail: entry({ timing: "next-generate", default: "", values: ["", "High", "Medium", "Low"], wire: "clientHints" }),
   favorLimitTo: entry({ timing: "next-generate", default: "", values: ["", "latest", "top / greatest", "bottom / smallest", "most common", "outliers"], wire: "clientHints" }),
   /** 0 asks for no limit, and travels as absent (`wireLimitCount`): any value the server receives is a limit. */
@@ -821,10 +828,10 @@ function buildProductFeedbackPayload(input) {
   };
 }
 var DEFAULT_TEXT2 = {
-  label: "Ideas to improve this product",
-  placeholder: "A feature you'd like, or something that got in your way",
-  hint: "This sends a note to our team. It won't draw a chart.",
-  open: "Suggest an improvement",
+  label: "Suggestions for the team that makes this product",
+  placeholder: "Message to the makers of this product: a feature you'd like, or something that got in your way. This is not a chart request.",
+  hint: "This goes to the people who build this product, not to the chart. It won't draw a chart.",
+  open: "Send a suggestion to the product team",
   send: "Send",
   sending: "Sending...",
   sent: "Thank you - your suggestion was sent.",
@@ -2290,7 +2297,7 @@ function fingerprintComponentDigest(components) {
 
 // src/index.ts
 function registerCityTable(packed) {
-  _3(packed);
+  Kt(packed);
 }
 export {
   ACTIVE_TICK_CLASS,

package/dist/provinces.mjs

@@ -0,0 +1,229 @@
+/*! @bicharts/chart-host — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; Natural Earth and US Census/TIGER (public domain). Full text: NOTICE in this package. */
+import {
+  geoFromCache,
+  registerGeo
+} from "./chunk-5WTQN5DL.mjs";
+import {
+  Si,
+  W,
+  bt
+} from "./chunk-SYUJ4TPX.mjs";
+import "./chunk-A2GMXZP7.mjs";
+import "./chunk-GHODWOAL.mjs";
+
+// src/provinceGeo.ts
+var PROVINCE_REGIONS = ["europe", "asia", "africa", "south-america", "north-america", "oceania"];
+function provinceGeoPath(region) {
+  return `/geo/admin1-${String(region).toLowerCase()}.v1.json`;
+}
+function provinceGeoKey(region) {
+  return `admin1:${String(region).toLowerCase()}`;
+}
+function geoKeyFor(res) {
+  if (res.geoGrain && res.geoGrain.toLowerCase() === "admin1" && res.geoRegion) return provinceGeoKey(res.geoRegion);
+  return res.geoKind ?? null;
+}
+var inflight = /* @__PURE__ */ new Map();
+async function loadProvinceGeo(region, opts = {}) {
+  const key = provinceGeoKey(region);
+  const cached = geoFromCache(key);
+  if (cached) return cached;
+  if (!PROVINCE_REGIONS.includes(String(region).toLowerCase())) return void 0;
+  const url = opts.url ?? (opts.origin ? opts.origin.replace(/\/+$/, "") : "") + provinceGeoPath(region);
+  let p = inflight.get(key);
+  if (!p) {
+    const started = Date.now();
+    p = (async () => {
+      try {
+        const doc = opts.fetchJson ? await opts.fetchJson(url) : await (await fetch(url, { credentials: "omit" })).json();
+        if (!doc || doc.type !== "FeatureCollection" || !Array.isArray(doc.features) || doc.features.length === 0)
+          throw new Error("not a FeatureCollection");
+        registerGeo(key, doc);
+        opts.log?.("province-geo-loaded", { region, ms: Date.now() - started, features: doc.features.length });
+        return doc;
+      } catch (e) {
+        opts.log?.("province-geo-failed", { region, url, error: String(e).slice(0, 200) });
+        return void 0;
+      } finally {
+        inflight.delete(key);
+      }
+    })();
+    inflight.set(key, p);
+  }
+  return p;
+}
+var PROVINCE_SNAP_DEG = 0.05;
+function shapesOf(geo) {
+  const out = [];
+  for (const f of geo?.features ?? []) {
+    const g = f?.geometry;
+    if (!g || f?.properties?.kind === "border" || f.id === null || f.id === void 0) continue;
+    const polys = g.type === "Polygon" ? [g.coordinates] : g.type === "MultiPolygon" ? g.coordinates : [];
+    if (!polys.length) continue;
+    let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+    for (const poly of polys) for (const [x, y] of poly[0] ?? []) {
+      if (x < x0) x0 = x;
+      if (x > x1) x1 = x;
+      if (y < y0) y0 = y;
+      if (y > y1) y1 = y;
+    }
+    out.push({ id: String(f.id), polys, box: [x0, y0, x1, y1] });
+  }
+  return out;
+}
+function inRing(x, y, ring) {
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const [xi, yi] = ring[i], [xj, yj] = ring[j];
+    if (yi > y !== yj > y && x < (xj - xi) * (y - yi) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+function inShape(x, y, s) {
+  if (x < s.box[0] || x > s.box[2] || y < s.box[1] || y > s.box[3]) return false;
+  return s.polys.some((poly) => poly.length > 0 && inRing(x, y, poly[0]) && !poly.slice(1).some((h) => inRing(x, y, h)));
+}
+function segDist2(px, py, ax, ay, bx, by) {
+  const dx = bx - ax, dy = by - ay;
+  const t = dx === 0 && dy === 0 ? 0 : Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / (dx * dx + dy * dy)));
+  const ex = ax + t * dx - px, ey = ay + t * dy - py;
+  return ex * ex + ey * ey;
+}
+var locators = /* @__PURE__ */ new WeakMap();
+function provinceLocator(geo, snapDeg = PROVINCE_SNAP_DEG) {
+  if (geo && typeof geo === "object" && snapDeg === PROVINCE_SNAP_DEG) {
+    const hit = locators.get(geo);
+    if (hit) return hit;
+  }
+  const shapes = shapesOf(geo);
+  const locate = (lat, lon) => {
+    if (!isFinite(lat) || !isFinite(lon)) return null;
+    for (const x of [lon, lon + 360, lon - 360]) {
+      for (const s of shapes) if (inShape(x, lat, s)) return s.id;
+    }
+    const k = Math.cos(lat * Math.PI / 180) || 1e-6;
+    let best = null, bestD = snapDeg * snapDeg;
+    for (const s of shapes) {
+      if (lon < s.box[0] - snapDeg / k || lon > s.box[2] + snapDeg / k || lat < s.box[1] - snapDeg || lat > s.box[3] + snapDeg) continue;
+      for (const poly of s.polys) for (const ring of poly) for (let i = 1; i < ring.length; i++) {
+        const d = segDist2(lon * k, lat, ring[i - 1][0] * k, ring[i - 1][1], ring[i][0] * k, ring[i][1]);
+        if (d <= bestD) {
+          bestD = d;
+          best = s.id;
+        }
+      }
+    }
+    return best;
+  };
+  if (geo && typeof geo === "object" && snapDeg === PROVINCE_SNAP_DEG) locators.set(geo, locate);
+  return locate;
+}
+
+// src/admin1LookupLoader.ts
+var ADMIN1_LOOKUP_PATH = "/geo/admin1-lookup.v1.json";
+var inflight2 = null;
+async function loadAdmin1Lookup(url, opts = {}) {
+  if (W()) return true;
+  const log = opts.log;
+  if (!inflight2) {
+    const started = Date.now();
+    inflight2 = (async () => {
+      try {
+        const doc = opts.fetchJson ? await opts.fetchJson(url) : await (await fetch(url, { credentials: "omit" })).json();
+        const counts = bt(doc);
+        log?.("admin1-lookup-loaded", { url, ms: Date.now() - started, ...counts });
+        return true;
+      } catch (e) {
+        log?.("admin1-lookup-failed", { url, ms: Date.now() - started, error: String(e).slice(0, 200) });
+        inflight2 = null;
+        return false;
+      }
+    })();
+  }
+  const timeoutMs = opts.timeoutMs ?? 3e3;
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      log?.("admin1-lookup-timeout", { url, timeoutMs });
+      resolve(false);
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([inflight2, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+var PLACE_TOKENS = /(^|[^a-z])(city|cities|town|ville|stadt|ciudad|citta|cidade|state|province|provincia|provinz|county|department|departement|departamento|prefecture|oblast|canton|kanton|bundesland|municipality)([^a-z]|$)/i;
+function needsAdmin1Lookup(columns) {
+  if (!columns) return false;
+  const geographic = columns.some((c) => {
+    const kind = (c?.geoKind ?? "").toLowerCase();
+    return kind.startsWith("country") || kind.startsWith("city");
+  });
+  if (geographic) return true;
+  return columns.some((c) => !!c && !c.isMeasure && !!c.name && PLACE_TOKENS.test(c.name.replace(/[_-]+/g, " ")));
+}
+
+// src/provinceHost.ts
+async function prepareProvinceProfile(profile, opts) {
+  if (!profile || typeof profile.getColumnsWithStats !== "function") return;
+  let invalidate = false;
+  if (profile.deriveProvinces !== opts.deriveProvinces) {
+    profile.deriveProvinces = opts.deriveProvinces;
+    invalidate = true;
+  }
+  const origin = typeof opts.origin === "string" ? opts.origin.trim() : "";
+  if (!W() && origin) {
+    let cols = [];
+    try {
+      cols = profile.getColumnsWithStats(opts.privacyLevel, opts.locale);
+    } catch {
+    }
+    if (needsAdmin1Lookup(cols)) {
+      const ok = await loadAdmin1Lookup(
+        origin.replace(/\/+$/, "") + ADMIN1_LOOKUP_PATH,
+        { timeoutMs: opts.timeoutMs ?? 3e3, fetchJson: opts.fetchJson, log: opts.log }
+      );
+      invalidate = invalidate || ok;
+    }
+  }
+  if (invalidate) profile.invalidateStats?.();
+}
+function provinceBinding(res, cols, opts) {
+  if (!res.geoColumn || !res.geoKind) return null;
+  if (String(res.geoGrain ?? "").toLowerCase() !== "admin1") return { column: res.geoColumn, kind: res.geoKind };
+  const dims = cols.filter((c) => !c.isMeasure && c.name !== res.geoColumn);
+  const kindOf = (c) => String(c.geoKind ?? "");
+  const words = (n) => n.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z]+/);
+  const named = (re) => cols.find((c) => words(c.name).some((w) => re.test(w)))?.name ?? null;
+  return {
+    column: res.geoColumn,
+    kind: res.geoKind,
+    grain: "admin1",
+    region: res.geoRegion || null,
+    fallback: {
+      city: dims.find((c) => kindOf(c).startsWith("city"))?.name ?? null,
+      country: dims.find((c) => kindOf(c).startsWith("country"))?.name ?? null,
+      lat: named(/^(lat|latitude)$/),
+      lon: named(/^(lon|lng|long|longitude)$/)
+    },
+    deriveProvinces: opts.deriveProvinces,
+    join: Si,
+    locate: opts.geo ? provinceLocator(opts.geo) : null
+  };
+}
+function geoKeyOfFields(res) {
+  return geoKeyFor({ geoKind: res.geoKind, geoRegion: res.geoRegion, geoGrain: res.geoGrain });
+}
+export {
+  ADMIN1_LOOKUP_PATH,
+  geoKeyFor,
+  geoKeyOfFields,
+  loadAdmin1Lookup,
+  loadProvinceGeo,
+  needsAdmin1Lookup,
+  prepareProvinceProfile,
+  provinceBinding,
+  provinceLocator
+};

package/dist/react.mjs

@@ -18,16 +18,18 @@ import {
   assembleD3,
   createChartGroup,
   createChartHost,
-  geoFromCache,
-  loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-4BR6VJQX.mjs";
+} from "./chunk-K6UXTDMR.mjs";
 import "./chunk-IE426WU6.mjs";
 import "./chunk-CPLWAW3Z.mjs";
 import "./chunk-P2DLK7WZ.mjs";
 import "./chunk-IE7TM6DX.mjs";
-import "./chunk-CNT3QA3R.mjs";
+import {
+  geoFromCache,
+  loadGeo
+} from "./chunk-5WTQN5DL.mjs";
+import "./chunk-SYUJ4TPX.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-7XRQUFVH.mjs";
 import "./chunk-GHODWOAL.mjs";

package/dist/types/admin1LookupLoader.d.ts

@@ -0,0 +1,26 @@
+/** Where the lookup is served, relative to the site origin. Versioned in the file name, so a rebuilt lookup is a new
+ *  URL rather than a stale cache entry. */
+export declare const ADMIN1_LOOKUP_PATH = "/geo/admin1-lookup.v1.json";
+/**
+ * Fetch and register the lookup. Resolves true once it is registered (immediately when it already is), false on a
+ * timeout, a failed fetch or a body that is not a lookup - and never throws. One fetch is in flight at a time, so N
+ * charts on a page cause one request. `timeoutMs` bounds how long a host waits before profiling without it (default
+ * 3000); a late arrival still registers, for the next profile.
+ */
+export declare function loadAdmin1Lookup(url: string, opts?: {
+    timeoutMs?: number;
+    fetchJson?: (url: string) => Promise<any>;
+    log?: (tag: string, data?: any) => void;
+}): Promise<boolean>;
+/**
+ * Is the lookup worth loading for a table, judged from its profile? True when a column was profiled as a country or a
+ * city, or when a dimension's name reads as a city or a first-level division. Takes plain column records, so a host
+ * passes its profile as is.
+ */
+export declare function needsAdmin1Lookup(columns: ReadonlyArray<{
+    name?: string | null;
+    geoKind?: string | null;
+    isMeasure?: boolean | null;
+}> | null | undefined): boolean;
+/** Forget an in-flight load. Tests only. */
+export declare function resetAdmin1LookupLoaderForTests(): void;

package/dist/types/contract.d.ts

@@ -157,6 +157,7 @@ export interface RenderOptions {
     colorScaleSelfClampPct?: number;
     geoLandColor?: string;
     geoNoDataColor?: string;
+    geoBorders?: boolean;
     aggregation?: string;
     uiState?: unknown;
     setUiState?: (s: unknown) => void;

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@ export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clea
 /** REPLACE the bundled city gazetteer with another packed table. Rarely needed — see the
  *  note above registerCityTable in shape-core's geoPoint.ts before using it. */
 export declare function registerCityTable(packed: string): void;
-export { buildRenderPayload, type RenderPayload, type GeoPointBinding } from "./payload";
+export { buildRenderPayload, type RenderPayload, type GeoPointBinding, type GeoBinding, type GeoProvinceReport, type ProvinceJoin } from "./payload";
 export { codeReadsDatesInLocalTime, vegaSpecReadsDatesInLocalTime } from "./dateCells";
 export { createChartHost, compileRenderFn, stripEsmExports, requiredD3Plugins, explainRenderFailure, sessionViewStateProvider, noopViewStateProvider, assembleD3, D3_PLUGIN_PACKAGES, type ChartHost, type ChartHostConfig, type RenderFn, type SelectionPaintReport } from "./host";
 export { ANNOTATION_CLASS, ANNOTATION_LAYER_CLASS, type MarkAnnotation, type AnnotationReport } from "./annotations";

package/dist/types/optionsVocabulary.d.ts

@@ -71,6 +71,11 @@ export declare const OPTIONS_VOCABULARY: Readonly<{
      * that made the chart asked for them. "on" / "off" is a reader's choice and wins either way.
      */
     hoverDropLines: OptionVocabularyEntry;
+    /** A province map draws the national borders over its provinces unless this is false (a reader's "Country borders"). */
+    geoBorders: OptionVocabularyEntry;
+    /** A reader's "Derive provinces": false measures no city or coordinate rollup, so only a real province column offers
+     *  a province map. It changes what the profile measures, so it travels in the shape rather than as a field. */
+    deriveProvinces: OptionVocabularyEntry;
     levelOfDetail: OptionVocabularyEntry;
     favorLimitTo: OptionVocabularyEntry;
     /** 0 asks for no limit, and travels as absent (`wireLimitCount`): any value the server receives is a limit. */

package/dist/types/payload.d.ts

@@ -9,6 +9,7 @@ export interface GeoPointBinding {
     lon?: string;
     country?: string;
     mapKind?: GeoMapKind;
+    region?: string | null;
 }
 /** What a point binding's resolution ACHIEVED, so the chart can annotate honestly rather
  *  than implying a precision it does not have. Named (rather than inlined on RenderPayload)
@@ -25,9 +26,70 @@ export interface GeoPointReport {
     rolesBackfilled?: string[];
     rolesRefused?: string[];
 }
+/** How a province map's rows were placed (geo binding with grain "admin1"), so the chart can say what its provinces
+ *  rest on: the reader's province values, their coordinates, or their cities rolled up. */
+export interface GeoProvinceReport {
+    /** Rows placed by each source. */
+    sources: {
+        province: number;
+        coordinates: number;
+        city: number;
+    };
+    /** Rows whose city matched more than one province: not placed, never guessed. */
+    ambiguousRows: number;
+    ambiguousExamples: string[];
+    /** Rows whose coordinates landed in no province. */
+    unplacedPoints: number;
+}
+/** The province join a host hands a province-map binding: shape-core's buildProvinceIsoColumn. Typed here, not imported,
+ *  because the province code lives off this package's main entry (its eager budget): a host already loads shape-core to
+ *  profile, so it passes the function it has rather than this bundle carrying a second copy. */
+export type ProvinceJoin = (rows: Array<{
+    province?: unknown;
+    city?: unknown;
+    country?: unknown;
+    lat?: unknown;
+    lon?: unknown;
+}>, opts: {
+    provinceKind?: string | null;
+    deriveProvinces?: boolean;
+    locate?: (lat: number, lon: number) => string | null;
+}) => {
+    iso: (string | null)[];
+    source: ("province" | "coordinates" | "city" | null)[];
+    unmatched: string[];
+    matchedRows: number;
+    totalRows: number;
+    ambiguousRows: number;
+    ambiguousExamples: string[];
+    unplacedPoints: number;
+};
+/** A geo binding. A province map adds `grain: "admin1"`, its continent and `join`; the province value, a blank province's
+ *  coordinates (through `locate`, from "@bicharts/chart-host/provinces" provinceLocator) and its city are then read in that
+ *  order (the city and coordinate columns may be named in `fallback` beside the bound column), unless the reader turned
+ *  deriving provinces off. A province binding without `join` builds no join column. */
+export interface GeoBinding {
+    column: string;
+    kind: string;
+    grain?: string | null;
+    region?: string | null;
+    fallback?: {
+        city?: string | null;
+        country?: string | null;
+        lat?: string | null;
+        lon?: string | null;
+    } | null;
+    deriveProvinces?: boolean;
+    /** Places a coordinate in its province (provinceLocator over the continent's geometry). Absent: coordinates do not place. */
+    locate?: ((lat: number, lon: number) => string | null) | null;
+    /** Builds the province join (shape-core buildProvinceIsoColumn). Required for grain "admin1". */
+    join?: ProvinceJoin | null;
+}
 export interface RenderPayload {
     columns: any[];
     rows: any[][];
+    /** Present only for a province map: what placed its rows. */
+    geoProvince?: GeoProvinceReport;
     geoUnmatched?: {
         count: number;
         examples: string[];
@@ -77,10 +139,7 @@ export interface RenderPayload {
 }
 export declare function buildRenderPayload(cols: Array<{
     name: string;
-} & Record<string, any>>, rowObjs: Array<Record<string, any>>, geo?: {
-    column: string;
-    kind: string;
-} | null, point?: GeoPointBinding | null, destination?: GeoPointBinding | null, opts?: {
+} & Record<string, any>>, rowObjs: Array<Record<string, any>>, geo?: GeoBinding | null, point?: GeoPointBinding | null, destination?: GeoPointBinding | null, opts?: {
     utcDays?: boolean;
     localWallClock?: boolean;
     aliases?: ReadonlyArray<{

package/dist/types/provinceGeo.d.ts

@@ -0,0 +1,38 @@
+/** The continents a province map is drawn for. */
+export declare const PROVINCE_REGIONS: readonly ["europe", "asia", "africa", "south-america", "north-america", "oceania"];
+export type ProvinceRegion = typeof PROVINCE_REGIONS[number];
+/** Where a continent's provinces are served, relative to the site origin. Versioned in the name, like the lookup. */
+export declare function provinceGeoPath(region: string): string;
+/** The geometry key a province map renders against: pass it as the host's geoKind. */
+export declare function provinceGeoKey(region: string): string;
+/**
+ * The geometry key for a generation's geo fields: a province map (grain "admin1") renders against its continent's
+ * provinces, every other geo chart against its geoKind as before.
+ */
+export declare function geoKeyFor(res: {
+    geoKind?: string | null;
+    geoRegion?: string | null;
+    geoGrain?: string | null;
+}): string | null;
+/**
+ * Fetch and register a continent's provinces. Resolves the FeatureCollection once registered (immediately when it
+ * already is), undefined on a failed fetch or a body that is not one - and never throws. One fetch per continent is in
+ * flight at a time. The file is fetched from `origin` (default: the page's own) at its served path, or from `url`.
+ */
+export declare function loadProvinceGeo(region: string, opts?: {
+    origin?: string;
+    url?: string;
+    fetchJson?: (url: string) => Promise<any>;
+    log?: (tag: string, data?: any) => void;
+}): Promise<any | undefined>;
+/** How far outside every province a point may sit and still be placed in the nearest one, in degrees (about 5 km at
+ *  the equator, less toward the poles): simplification moves coastlines, and a harbour city must not fall in the sea. */
+export declare const PROVINCE_SNAP_DEG = 0.05;
+/**
+ * A function placing a coordinate in its province: the province that contains it, else the nearest one within
+ * PROVINCE_SNAP_DEG (east-west distance scaled to the latitude), else null. Border lines are never a province. Built once
+ * per geometry object and reused.
+ */
+export declare function provinceLocator(geo: any, snapDeg?: number): (lat: number, lon: number) => string | null;
+/** Forget in-flight loads. Tests only. */
+export declare function resetProvinceGeoForTests(): void;

package/dist/types/provinceHost.d.ts

@@ -0,0 +1,47 @@
+import type { GeoBinding } from "./payload";
+/** The profile a host measures with: shape-core's IndexedText, by the members this needs. */
+export interface ProvinceProfile {
+    deriveProvinces?: boolean;
+    getColumnsWithStats(privacyLevel: string, locale?: string): ReadonlyArray<{
+        name?: string | null;
+        geoKind?: string | null;
+        isMeasure?: boolean | null;
+    }>;
+    invalidateStats?(): void;
+}
+/**
+ * Before a request is profiled: hand the profile the reader's Derive Provinces setting, and when the table could carry
+ * provinces, wait (up to `timeoutMs`, default 3000) for the hosted admin-1 lookup served at `origin`. Either change
+ * re-measures the profile, which keeps its rows. Never throws; a late or failed load costs a province map, never a chart.
+ */
+export declare function prepareProvinceProfile(profile: ProvinceProfile | null | undefined, opts: {
+    origin: string;
+    deriveProvinces: boolean;
+    privacyLevel: string;
+    locale?: string;
+    timeoutMs?: number;
+    fetchJson?: (url: string) => Promise<any>;
+    log?: (tag: string, data?: any) => void;
+}): Promise<void>;
+/** The geo fields a generation names, as every host keeps them. */
+export interface GeoFields {
+    geoColumn?: string | null;
+    geoKind?: string | null;
+    geoRegion?: string | null;
+    geoGrain?: string | null;
+}
+/**
+ * The geo binding for a render. A province map (grain "admin1") gets the province join, a locator over `geo` (the
+ * continent's province geometry, when the host has it), the reader's Derive Provinces setting and the columns a blank
+ * province falls back to, named from the profile; every other geo chart its column + kind. Null when nothing is bound.
+ */
+export declare function provinceBinding(res: GeoFields, cols: ReadonlyArray<{
+    name: string;
+    geoKind?: string | null;
+    isMeasure?: boolean | null;
+}>, opts: {
+    deriveProvinces: boolean;
+    geo?: any;
+}): GeoBinding | null;
+/** The geometry key a generation renders against (geoKeyFor over a host's kept fields). */
+export declare function geoKeyOfFields(res: GeoFields): string | null;

package/dist/types/provinces.d.ts

@@ -0,0 +1,3 @@
+export { loadProvinceGeo, geoKeyFor, provinceLocator } from "./provinceGeo";
+export { loadAdmin1Lookup, needsAdmin1Lookup, ADMIN1_LOOKUP_PATH } from "./admin1LookupLoader";
+export { prepareProvinceProfile, provinceBinding, geoKeyOfFields, type ProvinceProfile, type GeoFields } from "./provinceHost";

package/dist/zoom-memory.mjs

@@ -1,7 +1,7 @@
 /*! @bicharts/chart-host — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; Natural Earth and US Census/TIGER (public domain). Full text: NOTICE in this package. */
 import {
   K
-} from "./chunk-CNT3QA3R.mjs";
+} from "./chunk-SYUJ4TPX.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/zoomMemory/zoomMemory.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.6.103",
+  "version": "0.6.106",
   "description": "Run a BIC-generated D3 chart in any web host: compiles the generated render() function, applies the shared option defaults, resolves mark clicks (through tooltip overlays), owns the selection affordance, and translates row indices between cross-filtered charts. The same contract the BIC Power BI visual implements, minus Power BI. React bindings at @bicharts/chart-host/react.",
   "license": "Apache-2.0",
   "type": "module",
@@ -64,6 +64,11 @@
       "import": "./dist/legend-fit.mjs",
       "default": "./dist/legend-fit.mjs"
     },
+    "./provinces": {
+      "types": "./dist/types/provinces.d.ts",
+      "import": "./dist/provinces.mjs",
+      "default": "./dist/provinces.mjs"
+    },
     "./zoom-memory": {
       "types": "./dist/types/zoomMemory/index.d.ts",
       "import": "./dist/zoom-memory.mjs",