@bicharts/chart-host 0.6.102 → 0.6.105

package/dist/react.mjs

@@ -13,23 +13,25 @@ import {
   payloadRowReader,
   viewFromToken,
   viewToken
-} from "./chunk-WSNDXS3Z.mjs";
+} from "./chunk-TLIBO5PT.mjs";
 import {
   assembleD3,
   createChartGroup,
   createChartHost,
-  geoFromCache,
-  loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-ALX4D2I2.mjs";
-import "./chunk-B6BLSIID.mjs";
-import "./chunk-ASLRGGLV.mjs";
-import "./chunk-5OCL4EFM.mjs";
-import "./chunk-3JBJ2SIF.mjs";
-import "./chunk-CNT3QA3R.mjs";
+} from "./chunk-K6UXTDMR.mjs";
+import "./chunk-IE426WU6.mjs";
+import "./chunk-CPLWAW3Z.mjs";
+import "./chunk-P2DLK7WZ.mjs";
+import "./chunk-IE7TM6DX.mjs";
+import {
+  geoFromCache,
+  loadGeo
+} from "./chunk-5WTQN5DL.mjs";
+import "./chunk-SYUJ4TPX.mjs";
 import "./chunk-A2GMXZP7.mjs";
-import "./chunk-M7MBTLDP.mjs";
+import "./chunk-7XRQUFVH.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/react.tsx

package/dist/testing.mjs

@@ -4,7 +4,7 @@ import {
   MARK_CLASS,
   MARK_SELECTED_CLASS,
   ROW_IDX_ATTR
-} from "./chunk-M7MBTLDP.mjs";
+} from "./chunk-7XRQUFVH.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/testing/interact.ts

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

@@ -1,4 +1,5 @@
-export declare const HOST_CONTRACT_VERSION = "1.17.0";
+import type { ExportFormat, ExportTableService, SaveFileService } from "./exportTable";
+export declare const HOST_CONTRACT_VERSION = "1.20.0";
 export type GeoPointPrecision = "latlon" | "city" | "zip3" | "state" | "country";
 /** Every valid tier, ordered most precise → coarsest. Runtime form of GeoPointPrecision. */
 export declare const GEO_POINT_PRECISIONS: readonly GeoPointPrecision[];
@@ -13,6 +14,7 @@ export declare const AXIS_FILTER_CLASS = "d3-axis-filter";
 export declare const LIFT_SELECTED_CLASS = "d3-lift-selected";
 export declare const CONTROL_CLASS = "lch-control";
 export declare const ROW_IDX_ATTR = "data-row-idx";
+export declare const NOTE_STYLE_ATTR = "data-bic-note-style";
 export declare const SELECTION_RULE_ATTR = "data-lch-sel-rule";
 export declare const SELECTION_RULE_CLICKED_MARKS = "clicked-marks";
 export declare const MARK_KEY_ATTR = "data-mark-key";
@@ -126,6 +128,11 @@ export interface RenderOptions {
     dataComplete?: boolean;
     rowsWithheld?: number;
     rowsFilteredOut?: number;
+    openUrl?: (url: string) => void;
+    copyText?: (text: string) => boolean | void | Promise<boolean | void>;
+    saveFile?: SaveFileService;
+    exportFormats?: readonly ExportFormat[];
+    exportTable?: ExportTableService;
     geoPointDest?: {
         precision: GeoPointPrecision | null;
         precisionCounts: Record<GeoPointPrecision, number>;
@@ -150,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/exportTable.d.ts

@@ -0,0 +1,100 @@
+/** The kind of value one exported column holds. Anything that is not a number, a date or a yes/no is text. */
+export type ExportColumnType = "text" | "number" | "date" | "boolean";
+/** One exported column, in the order the reader sees it. */
+export interface ExportColumn {
+    /** The header, as the reader sees it. */
+    name: string;
+    type: ExportColumnType;
+    /** The d3-format specifier the chart prints this number with (a number column only). Wins over modelFormat. */
+    d3Format?: string | null;
+    /** The data model's own number format (an Excel / Power BI format string), used when there is no d3Format. */
+    modelFormat?: string | null;
+}
+/** One cell's value. A blank (null, undefined, "" or a value its column's type cannot read) is an empty cell. */
+export type ExportCell = string | number | boolean | Date | null | undefined;
+/** What a chart hands out: the visible columns in display order, and the rows in display order. */
+export interface ExportTable {
+    /** Names the file and the worksheet. Absent: "table". */
+    title?: string | null;
+    columns: ExportColumn[];
+    rows: ExportCell[][];
+}
+export type ExportFormat = "csv" | "xlsx";
+/** The formats a chart may offer, best first. */
+export declare const EXPORT_FORMATS: readonly ExportFormat[];
+/** A finished file, as a host's file service receives it. */
+export interface ExportFile {
+    /** A file name with its extension, safe on every file system. */
+    name: string;
+    format: ExportFormat;
+    mime: string;
+    bytes: Uint8Array;
+    /** The same content as text, for a text format (the CSV); absent for a binary one. */
+    text?: string;
+    /**
+     * The table the file was written from, for a host that keeps it its own way (a spreadsheet add-in that must give
+     * the new sheet a name the open workbook does not already use, and so writes the workbook again under that name).
+     */
+    table: ExportTable;
+}
+export declare const XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+export declare const CSV_MIME = "text/csv";
+/**
+ * Excel's day number for a UTC time: days since 1899-12-30, the fraction being the time of day. Excel counts a
+ * 29 February 1900 that never was (day 60), so a day before 1 March 1900 is one lower to read back as itself.
+ */
+export declare function excelSerial(t: number): number;
+/**
+ * The Excel number format for an exported number column, or null for General. `values` are the column's numbers, so a
+ * format that shows "up to" some decimals shows as many as the data has.
+ */
+export declare function excelNumberFormat(col: Pick<ExportColumn, "d3Format" | "modelFormat">, values?: readonly number[]): string | null;
+/**
+ * The table as CSV text: a header row, then one line per row, CRLF between lines, RFC 4180 quoting. A number is its
+ * plain value (a point for the decimal, no grouping), a date its ISO day (and time, when the column has one), a yes/no
+ * TRUE or FALSE. The text starts with a byte-order mark so a spreadsheet reads it as UTF-8.
+ */
+export declare function tableToCsv(table: ExportTable): string;
+/** A1-style column letters for a 0-based column index. */
+export declare function columnLetters(ci: number): string;
+/** A worksheet name Excel accepts: at most 31 characters, none of []:*?/\, not blank, not starting or ending with '. */
+export declare function sheetName(title: string | null | undefined): string;
+/** A file name safe on every file system, from a title: no reserved characters, at most 80 characters. */
+export declare function exportFileName(title: string | null | undefined, format: ExportFormat): string;
+/**
+ * The table as an .xlsx workbook's bytes. One worksheet named after the title: a bold header row, frozen, with filter
+ * buttons; typed cells (numbers with their format where Excel can carry it, dates as dates, TRUE/FALSE); each column as
+ * wide as its widest value, within limits. Rows past Excel's limit are left out (a sheet holds 1,048,576 rows).
+ */
+export declare function tableToXlsx(table: ExportTable): Uint8Array;
+/**
+ * A ZIP archive of the given files, stored without compression (method 0) - every reader of a workbook accepts it. The
+ * entries carry a fixed timestamp, so the same table always gives the same bytes.
+ */
+export declare function zipStored(files: Array<[string, string | Uint8Array]>): Uint8Array;
+/** Builds the finished file for a table in one of the export formats. */
+export declare function buildExportFile(table: ExportTable, format: ExportFormat): ExportFile;
+/** Base64 of a file's bytes, for a host whose file service takes binary content as base64 text. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** A host's file service: saves a finished file the host's own way. False, a throw or a rejection means it did not. */
+export type SaveFileService = (file: ExportFile) => boolean | void | Promise<boolean | void>;
+/** The chart-facing export: what options.exportTable is. Resolves true when the host saved the file. */
+export type ExportTableService = (table: ExportTable, format: ExportFormat) => Promise<boolean>;
+/**
+ * The formats a host's file service takes, best first: the host's own list (when it names one) kept to the formats
+ * this module writes, in EXPORT_FORMATS order, without repeats. Absent or not a list: every format. An empty result
+ * means the host can save none of them, so it gets no export.
+ */
+export declare function exportFormatsFor(hostFormats?: readonly unknown[] | null): ExportFormat[];
+/**
+ * Builds the chart-facing exportTable from a host's file service. Never throws and never rejects: a table that cannot
+ * be written, a format the host does not take, or a host that refuses, resolves false, and the chart says the export
+ * did not happen.
+ */
+export declare function exportTableService(save: SaveFileService, formats?: readonly ExportFormat[]): ExportTableService;
+/**
+ * A file service for a page in a browser: the file downloads through a link the page never shows. For a React or
+ * Blazor page, a Fabric App, or any page whose browser allows downloads; a sandboxed frame without the
+ * "allow-downloads" permission silently drops it, so a host in one passes its own service (or none) instead.
+ */
+export declare function browserSaveFile(doc?: Document): SaveFileService;

package/dist/types/host.d.ts

@@ -257,8 +257,9 @@ export interface ChartHostConfig {
     /**
      * NOTES ON MARKS. Each annotation names a key - a value in a column of this chart's data, such as a
      * country code - and the host draws a badge on that key's mark after every render, wherever a filter,
-     * a re-query or a zoom has put it. Keyed by value, never by row position. Change them with
-     * setAnnotations; none (the default) draws nothing.
+     * a re-query, a zoom or a scroll has put it. A chart that declares NOTE_STYLE_ATTR="dot" gets a small
+     * dot at a fixed spot instead, the label in its tooltip. Keyed by value, never by row position. Change
+     * them with setAnnotations; none (the default) draws nothing.
      */
     annotations?: MarkAnnotation[];
     /** A badge was clicked. The mark beneath is not selected. */

package/dist/types/hostLinks.d.ts

@@ -0,0 +1,11 @@
+/** The clipboard half a host can supply: navigator.clipboard, or anything with the same writeText. */
+export interface ClipboardLike {
+    writeText?: (text: string) => Promise<void>;
+}
+/** The two services, ready to spread into a host's render options: each is absent when the host supplied nothing for it. */
+export interface HostLinkServices {
+    openUrl?: (url: string) => void;
+    copyText?: (text: string) => boolean | Promise<boolean>;
+}
+/** Builds openUrl and copyText from a host's own opener and clipboard. */
+export declare function hostLinkServices(open: ((url: string) => void) | undefined | null, clipboard: ClipboardLike | undefined | null): HostLinkServices;

package/dist/types/index.d.ts

@@ -1,11 +1,13 @@
-export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, CONTAINER_SLOT_SCROLL, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, DIM_OPACITY_MIN, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, type XfilterRefreshDetail, } from "./contract";
+export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, NOTE_STYLE_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, CONTAINER_SLOT_SCROLL, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, DIM_OPACITY_MIN, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, type XfilterRefreshDetail, } from "./contract";
 export { resolveOptions, type ResolveOptionsInput } from "./defaults";
+export { hostLinkServices, type HostLinkServices, type ClipboardLike } from "./hostLinks";
+export { tableToCsv, tableToXlsx, buildExportFile, exportFileName, sheetName as exportSheetName, excelNumberFormat, excelSerial, bytesToBase64, exportFormatsFor, exportTableService, browserSaveFile, EXPORT_FORMATS, XLSX_MIME, CSV_MIME, type ExportTable, type ExportColumn, type ExportColumnType, type ExportCell, type ExportFormat, type ExportFile, type SaveFileService, type ExportTableService, } from "./exportTable";
 export { OPTIONS_VOCABULARY, LIVE_OPTION_KEYS, MAX_MAP_POINTS_MIN, MAX_MAP_POINTS_MAX, LIMIT_COUNT_MAX, wireLimitCount, codeReadsOption, type OptionVocabularyEntry, type OptionTiming, type OptionWire, type OptionKey, } from "./optionsVocabulary";
 export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clearGeoCache, type GeoAssetName, } from "./geoLazy";
 /** 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";
@@ -21,6 +23,7 @@ export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngData
 export { shouldReview, buildReviewWire, bareBase64, actionFor, type ReviewGate, type ReviewWire, type ReviewVerdict, type ReviewAction } from "./review";
 export { askApplyImprovements, type ReviewDialogOptions, type ReviewDialogText } from "./reviewDialog";
 export { mountProductFeedbackBox, normaliseProductFeedbackText, productFeedbackSendable, buildProductFeedbackPayload, PRODUCT_FEEDBACK_MAX_CHARS, PRODUCT_FEEDBACK_MIN_CHARS, type ProductFeedbackBox, type ProductFeedbackBoxOptions, type ProductFeedbackText, type ProductFeedbackSendResult, type ProductFeedbackPayload, type ProductFeedbackIdentity, type ProductFeedbackHost, } from "./productFeedback";
+export { mountShareRateLine, shareRateLineModel, type ShareRateLine, type ShareRateLineOptions, type ShareRateText, type ShareRateModel, type ShareLink, type ShareAskWire, type ShareTargetWire, } from "./shareRate";
 export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, orderRefusalsForDisplay, refusalIsSelectable, hasRefusalsToShow, qualifyRefusalHeadingFor, newQualifyRefusalGroupState, qualifyRefusalReason, QUALIFY_REFUSAL_UNSPECIFIED, refusalIsTileBound, QUALIFY_TILE_REFUSAL_CODES, QUALIFY_TOO_SMALL_HEADING, type QualifyRefusalRow, type QualifyRefusalGroupState, type QualifyRefusalHeading, } from "./qualifyGroups";
 export { qualifyPick, qualifyAuto, qualifyCancel, launchGenerates, launchFavorStyle, chooserFitsViewport, shouldOpenChooserOnGenerate, shouldOpenInlineChooserOnGenerate, canConfirmLaunch, confirmLaunch, qualifyFailureFallsOpen, CHOOSER_MIN_WIDTH_PX, CHOOSER_MIN_HEIGHT_PX, type QualifyLaunchOutcome, type ChooserGateInput, } from "./qualifyLaunch";
 export { normalizeFilterTerm, filterQualifyRows, readQualifyChartRow, readQualifyRefusalRow, DEFAULT_FILTER_MATCH_STYLE, filterMatchStyleOf, type FilterMatchStyle, filterFitsChooser, listNeedsFilter, qualifyFilterGate, inlineFilterGate, FILTER_MIN_TERM_CHARS, FILTER_ROW_PX, FILTER_MIN_WIDTH_PX, FILTER_MIN_HEIGHT_PX, INLINE_FILTER_MIN_ROWS, computeQualifyFilterView, qualifyFilterCountText, type QualifyFilterTier, type QualifyFilterResult, type QualifyFilterRead, type QualifyFilterGateReason, type QualifyFilterGateInput, type QualifyFilterRow, type QualifyFilterGroup, type QualifyFilterView, type QualifyFilterNoteKind, } from "./qualifyFilter";

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/types/shareRate.d.ts

@@ -0,0 +1,90 @@
+/** The block as the service sends it. Either casing is accepted, because the hosts' status calls serialise differently.
+ *  shape-core types the same block on the status answer (GetLicenseStatusResult.shareAsk); it is restated here because
+ *  this package's published declarations import nothing they do not ship, and a typecheck test holds the two equal. */
+export interface ShareAskWire {
+    productUrl?: string;
+    ProductUrl?: string;
+    rateUrl?: string;
+    RateUrl?: string;
+    targets?: ShareTargetWire[];
+    Targets?: ShareTargetWire[];
+}
+export interface ShareTargetWire {
+    id?: string;
+    Id?: string;
+    label?: string;
+    Label?: string;
+    url?: string;
+    Url?: string;
+}
+export interface ShareLink {
+    /** Short network id ("li", "fb", "x"); a host's click counter names it. */
+    id: string;
+    label: string;
+    url: string;
+}
+export interface ShareRateModel {
+    share: ShareLink[];
+    /** The listing to rate; null when the block had none worth drawing. */
+    rateUrl: string | null;
+}
+/**
+ * The links to draw for a service block, or null to draw nothing. Absent block, nothing https, or nothing usable: null.
+ * A target whose URL is not https, whose id is malformed or repeated, or which has no label is dropped; the order the
+ * service sent is kept.
+ */
+export declare function shareRateLineModel(ask: ShareAskWire | null | undefined): ShareRateModel | null;
+/** The words a reader sees. Hosts localize; every field has an English default. Network names come from the service. */
+export interface ShareRateText {
+    /** Before the network links: "Like it? Share it on". */
+    lead?: string;
+    /** Between the network links. */
+    separator?: string;
+    /** Between the share links and the rate link: ", or". */
+    or?: string;
+    /** The rate link after share links: "rate it on AppSource". */
+    rate?: string;
+    /** The rate link when there is nothing to share: "Like it? Rate it on AppSource". */
+    rateAlone?: string;
+    /** After the links: "Your ratings and feedback encourage us to do more." */
+    note?: string;
+    /** Menu layout, first: "Thanks for rating it." */
+    thanks?: string;
+    /** Menu layout, the rate link: "Rate it on AppSource too". */
+    rateToo?: string;
+    /** Menu layout, the toggle that reveals the networks: "Share it". */
+    shareMenu?: string;
+}
+export interface ShareRateLineOptions {
+    /** The service's block, as it arrived. Nothing is drawn when it yields no links. */
+    ask: ShareAskWire | null | undefined;
+    /** Opens a URL through the host's own door. The line never navigates by itself. */
+    open: (url: string) => void;
+    text?: ShareRateText;
+    /** Added to the wrapper so the host can skin it. */
+    className?: string;
+    /** "inline" (the landing line: the networks named in the sentence) or "menu" (after a vote: a short thank-you, the
+     *  rate link, and a "Share it" toggle that reveals the networks). The links, their order and the click contract are
+     *  the same either way. */
+    layout?: "inline" | "menu";
+    /** Menu layout: the "Share it" toggle opened the networks. */
+    onMenu?: () => void;
+    /** Called once, when the line is mounted - the host's "shown" counter. A host that folds the line away counts it
+     *  itself instead and passes nothing here. */
+    onShown?: () => void;
+    /** A network link was clicked. */
+    onShare?: (id: string) => void;
+    /** The rate link was clicked. */
+    onRate?: () => void;
+}
+export interface ShareRateLine {
+    element: HTMLElement;
+    destroy(): void;
+}
+/**
+ * Draw the line inside `container`, or return null (and draw nothing) when the block yields no links. The wrapper carries
+ * `bic-share-rate`; network links `bic-share-rate-share` with `data-target`; the rate link `bic-share-rate-rate`; the
+ * note `bic-share-rate-note`. Every link carries its real href (so it reads as a link, and a reader can copy it), but a
+ * click is cancelled and handed to `open`.
+ */
+export declare function mountShareRateLine(container: HTMLElement, opts: ShareRateLineOptions): ShareRateLine | null;

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.102",
+  "version": "0.6.105",
   "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",