@adminiumjs/widgets 0.1.0-rc.1

package/dist/families/geo/geo-config.d.ts

@@ -0,0 +1,375 @@
+import { z } from 'zod';
+export declare const mapBubbleConfigSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    href: z.ZodOptional<z.ZodString>;
+    binding: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodDefault<z.ZodLiteral<"table-query">>;
+        connectionId: z.ZodString;
+        source: z.ZodObject<{
+            schema: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            type: z.ZodDefault<z.ZodEnum<{
+                table: "table";
+                view: "view";
+            }>>;
+        }, z.core.$strip>;
+        shape: z.ZodEnum<{
+            "single-metric": "single-metric";
+            "metric+delta": "metric+delta";
+            timeseries: "timeseries";
+            "multi-timeseries": "multi-timeseries";
+            categorical: "categorical";
+            "record-list": "record-list";
+            record: "record";
+            matrix: "matrix";
+            "hierarchy/tree": "hierarchy/tree";
+            "calendar-events": "calendar-events";
+            "geo-points": "geo-points";
+            flows: "flows";
+            ohlc: "ohlc";
+            distribution: "distribution";
+            "boolean-map": "boolean-map";
+            stream: "stream";
+            "form-state": "form-state";
+            static: "static";
+        }>;
+        select: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        aggregations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            fn: z.ZodEnum<{
+                count: "count";
+                sum: "sum";
+                avg: "avg";
+                min: "min";
+                max: "max";
+                count_distinct: "count_distinct";
+                percentile: "percentile";
+            }>;
+            column: z.ZodOptional<z.ZodString>;
+            p: z.ZodOptional<z.ZodNumber>;
+            alias: z.ZodString;
+        }, z.core.$strip>>>;
+        groupBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bucket: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            unit: z.ZodEnum<{
+                hour: "hour";
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>;
+        }, z.core.$strip>>;
+        filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            op: z.ZodEnum<{
+                eq: "eq";
+                neq: "neq";
+                gt: "gt";
+                gte: "gte";
+                lt: "lt";
+                lte: "lte";
+                in: "in";
+                like: "like";
+                ilike: "ilike";
+                is_null: "is_null";
+                not_null: "not_null";
+                between: "between";
+            }>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            param: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        window: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            last: z.ZodNumber;
+            unit: z.ZodEnum<{
+                hour: "hour";
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>;
+            compareToPrior: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            dir: z.ZodEnum<{
+                asc: "asc";
+                desc: "desc";
+            }>;
+        }, z.core.$strip>>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    refreshInterval: z.ZodOptional<z.ZodNumber>;
+    emptyState: z.ZodOptional<z.ZodObject<{
+        icon: z.ZodOptional<z.ZodString>;
+        titleKey: z.ZodOptional<z.ZodString>;
+        bodyKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        accent: "accent";
+        pos: "pos";
+        warn: "warn";
+        danger: "danger";
+        info: "info";
+        muted: "muted";
+    }>>;
+    format: z.ZodOptional<z.ZodObject<{
+        locale: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+        number: z.ZodOptional<z.ZodEnum<{
+            percent: "percent";
+            plain: "plain";
+            compact: "compact";
+        }>>;
+        date: z.ZodOptional<z.ZodEnum<{
+            relative: "relative";
+            short: "short";
+            long: "long";
+        }>>;
+        referenceTime: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    testId: z.ZodOptional<z.ZodString>;
+    latColumn: z.ZodDefault<z.ZodString>;
+    lngColumn: z.ZodDefault<z.ZodString>;
+    nameField: z.ZodDefault<z.ZodString>;
+    codeField: z.ZodDefault<z.ZodString>;
+    metrics: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    metricLabels: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    valueFormat: z.ZodDefault<z.ZodEnum<{
+        percent: "percent";
+        plain: "plain";
+        currency: "currency";
+        compact: "compact";
+    }>>;
+    initialCenter: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    initialZoom: z.ZodDefault<z.ZodNumber>;
+    flyToOnClick: z.ZodDefault<z.ZodBoolean>;
+    linkedList: z.ZodOptional<z.ZodString>;
+    topN: z.ZodDefault<z.ZodNumber>;
+    emptyTitle: z.ZodOptional<z.ZodString>;
+    emptyBody: z.ZodOptional<z.ZodString>;
+    mapUnavailableLabel: z.ZodOptional<z.ZodString>;
+    regionsLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MapBubbleConfig = z.infer<typeof mapBubbleConfigSchema>;
+/**
+ * Deterministic `geo-points` payload (04 §7.7) in the canonical §3 `{ points }`
+ * envelope. Two metrics so the annex's metric switcher has something to switch.
+ */
+export declare function mapBubbleDemoData(seed: number): {
+    points: {
+        name: string;
+        lat: number;
+        lng: number;
+        values: {
+            users: number;
+            revenue: number;
+        };
+    }[];
+};
+/**
+ * annex §7: "See `chart-choropleth-grid` (registered in Charts; cross-listed
+ * here). Region-coded tiles when only region codes exist, no coordinates."
+ *
+ * CROSS-LISTED, SO IT SHARES THE GEOMETRY, NOT A COPY OF IT: the component
+ * renders @adminium/charts' `ChoroplethGridChart` — the same primitive
+ * `chart-choropleth-grid` renders, over the same `choroplethLayout` tilegram. The
+ * two registry ids differ only in FAMILY and in the entry point the generator
+ * reaches them by: the charts id is the analytics-dashboard tile, this one is
+ * what the annex §7 auto-instantiation rule ("country/state/region code column +
+ * numeric → `map-choropleth-grid`") emits when a table has region codes but no
+ * coordinates, i.e. when `map-bubble` cannot be built.
+ *
+ * The schema mirrors `chartChoroplethGridConfigSchema` field-for-field for the
+ * shared knobs. It is declared here rather than imported from the charts family
+ * because that schema lives in a `.tsx` (`MatrixGeoWidgets.tsx`) — importing it
+ * would pull a component module into this family's metadata graph and defeat the
+ * split the chunk-budget gate protects. The `*Field` names below are this
+ * family's own reader config and have no counterpart there.
+ */
+export declare const mapChoroplethGridConfigSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    href: z.ZodOptional<z.ZodString>;
+    binding: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodDefault<z.ZodLiteral<"table-query">>;
+        connectionId: z.ZodString;
+        source: z.ZodObject<{
+            schema: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            type: z.ZodDefault<z.ZodEnum<{
+                table: "table";
+                view: "view";
+            }>>;
+        }, z.core.$strip>;
+        shape: z.ZodEnum<{
+            "single-metric": "single-metric";
+            "metric+delta": "metric+delta";
+            timeseries: "timeseries";
+            "multi-timeseries": "multi-timeseries";
+            categorical: "categorical";
+            "record-list": "record-list";
+            record: "record";
+            matrix: "matrix";
+            "hierarchy/tree": "hierarchy/tree";
+            "calendar-events": "calendar-events";
+            "geo-points": "geo-points";
+            flows: "flows";
+            ohlc: "ohlc";
+            distribution: "distribution";
+            "boolean-map": "boolean-map";
+            stream: "stream";
+            "form-state": "form-state";
+            static: "static";
+        }>;
+        select: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        aggregations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            fn: z.ZodEnum<{
+                count: "count";
+                sum: "sum";
+                avg: "avg";
+                min: "min";
+                max: "max";
+                count_distinct: "count_distinct";
+                percentile: "percentile";
+            }>;
+            column: z.ZodOptional<z.ZodString>;
+            p: z.ZodOptional<z.ZodNumber>;
+            alias: z.ZodString;
+        }, z.core.$strip>>>;
+        groupBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bucket: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            unit: z.ZodEnum<{
+                hour: "hour";
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>;
+        }, z.core.$strip>>;
+        filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            op: z.ZodEnum<{
+                eq: "eq";
+                neq: "neq";
+                gt: "gt";
+                gte: "gte";
+                lt: "lt";
+                lte: "lte";
+                in: "in";
+                like: "like";
+                ilike: "ilike";
+                is_null: "is_null";
+                not_null: "not_null";
+                between: "between";
+            }>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            param: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        window: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            last: z.ZodNumber;
+            unit: z.ZodEnum<{
+                hour: "hour";
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>;
+            compareToPrior: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            dir: z.ZodEnum<{
+                asc: "asc";
+                desc: "desc";
+            }>;
+        }, z.core.$strip>>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    refreshInterval: z.ZodOptional<z.ZodNumber>;
+    emptyState: z.ZodOptional<z.ZodObject<{
+        icon: z.ZodOptional<z.ZodString>;
+        titleKey: z.ZodOptional<z.ZodString>;
+        bodyKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        accent: "accent";
+        pos: "pos";
+        warn: "warn";
+        danger: "danger";
+        info: "info";
+        muted: "muted";
+    }>>;
+    format: z.ZodOptional<z.ZodObject<{
+        locale: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+        number: z.ZodOptional<z.ZodEnum<{
+            percent: "percent";
+            plain: "plain";
+            compact: "compact";
+        }>>;
+        date: z.ZodOptional<z.ZodEnum<{
+            relative: "relative";
+            short: "short";
+            long: "long";
+        }>>;
+        referenceTime: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    testId: z.ZodOptional<z.ZodString>;
+    layout: z.ZodDefault<z.ZodEnum<{
+        grid: "grid";
+        "us-tilegram": "us-tilegram";
+    }>>;
+    metric: z.ZodOptional<z.ZodString>;
+    nameField: z.ZodDefault<z.ZodString>;
+    codeField: z.ZodDefault<z.ZodString>;
+    columns: z.ZodDefault<z.ZodNumber>;
+    levels: z.ZodDefault<z.ZodNumber>;
+    topN: z.ZodDefault<z.ZodNumber>;
+    valueFormat: z.ZodDefault<z.ZodEnum<{
+        percent: "percent";
+        plain: "plain";
+        currency: "currency";
+        compact: "compact";
+    }>>;
+    legendLowLabel: z.ZodOptional<z.ZodString>;
+    legendHighLabel: z.ZodOptional<z.ZodString>;
+    emptyTitle: z.ZodOptional<z.ZodString>;
+    emptyBody: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MapChoroplethGridConfig = z.infer<typeof mapChoroplethGridConfigSchema>;
+/**
+ * Deterministic `geo-points` payload keyed by region code (04 §7.7) — the same
+ * `{ points: [{code, name, values}] }` envelope `chart-choropleth-grid`'s
+ * generator emits, since the two ids share a data contract by the annex's
+ * cross-listing.
+ */
+export declare function mapChoroplethGridDemoData(seed: number): {
+    points: {
+        code: string;
+        name: string;
+        values: {
+            sales: number;
+            orders: number;
+        };
+    }[];
+};
+/** The map's opening view: config's center/zoom, else the whole world. */
+export declare function initialView(config: Pick<MapBubbleConfig, 'initialCenter' | 'initialZoom'>): {
+    center: readonly [number, number];
+    zoom: number;
+};
+//# sourceMappingURL=geo-config.d.ts.map

package/dist/families/geo/geo-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo-config.d.ts","sourceRoot":"","sources":["../../../src/families/geo/geo-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuChC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAsBpE;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;IAC/C,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,EAAE,CAAC;CAClG,CAkBA;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAUpF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG;IACvD,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,EAAE,CAAC;CACrF,CAWA;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,eAAe,GAAG,aAAa,CAAC,GAAG;IAC3F,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd,CAEA"}

package/dist/families/geo/geo-config.js

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import { DEFAULT_CENTER, DEFAULT_ZOOM, mulberry32 } from './geo-lib.js';
+import { widgetSharedConfigSchema } from '../../registry/shared-config.js';
+/**
+ * `geo` family config schemas + deterministic demo generators — PURE module
+ * (zod + geo-lib + shared-config only; no React component code, **no Leaflet**).
+ *
+ * WHY THIS EXISTS: the registry metadata graph reaches this family through
+ * `geo-track.definitions.ts`, which imports these schemas and `demoData`
+ * generators. If they lived in the component files, the definitions module would
+ * statically import a `.tsx` — and `registry/index.ts` statically imports every
+ * definitions module, so Leaflet, @adminium/ui and the map markup would all land
+ * in the EAGER registry chunk, on every page, whether or not a map is placed.
+ * That is exactly what acceptance #3 forbids ("Leaflet code is absent unless
+ * map-bubble is placed"). The components load only through
+ * `lazy(() => import('./geo-track-components.js'))`; the component files
+ * re-export these symbols so barrel/story/test import points stay one-per-widget.
+ *
+ * FIELD-NAMING CONFIG (04 §5, annex §7): the auto-instantiation rule
+ * (`geo.lat-lng-pair`, registry/candidates.ts) binds a real table and passes
+ * `latColumn`/`lngColumn` for the classifier's `geo-point` pair, so those two
+ * names are FIXED BY THAT RULE — renaming them here silently breaks every
+ * generated map. The rest follow the family's `*Field` convention.
+ */
+// ── map-bubble (annex §7) ───────────────────────────────────────────────────
+/** A `[lat, lng]` pair, validated to the real coordinate domain. */
+const latLngSchema = z.tuple([z.number().min(-90).max(90), z.number().min(-180).max(180)]);
+export const mapBubbleConfigSchema = widgetSharedConfigSchema.extend({
+    /**
+     * The classifier's lat/lng pair. NAMED `latColumn`/`lngColumn` (not the
+     * family's `*Field` convention) because `registry/candidates.ts`'s
+     * `geo.lat-lng-pair` rule emits exactly these keys — see the module header.
+     */
+    latColumn: z.string().default('lat'),
+    lngColumn: z.string().default('lng'),
+    nameField: z.string().default('name'),
+    codeField: z.string().default('code'),
+    /**
+     * Switchable metrics (annex §7 config `metrics`) — the tabs above the map, and
+     * what sizes the circle markers. Empty → every numeric column is inferred as a
+     * metric, so an unconfigured instance still plots something sensible.
+     */
+    metrics: z.array(z.string()).default([]),
+    /** Already-translated tab labels, keyed by metric name (host resolves i18n). */
+    metricLabels: z.record(z.string(), z.string()).default({}),
+    valueFormat: z.enum(['plain', 'compact', 'currency', 'percent']).default('compact'),
+    /** annex §7 config `initialZoom/center`. */
+    initialCenter: latLngSchema.optional(),
+    initialZoom: z.number().int().min(1).max(18).default(DEFAULT_ZOOM),
+    /** Clicking a marker flies the map to it (annex §7 "flyTo on click"). */
+    flyToOnClick: z.boolean().default(true),
+    /**
+     * annex §7 config `linkedList` — the INSTANCE id of a sibling
+     * `ranked-entity-list` this map pairs with. The widget doesn't reach for it
+     * (widgets never talk to each other); it rides along on the `record-open`
+     * event as `linkedInstanceId` so the PAGE HOST can focus the paired list.
+     * Absent → the event is still emitted, just with no pairing on it.
+     */
+    linkedList: z.string().optional(),
+    /** The built-in top-N companion list (0 = off) — the map's a11y fallback too. */
+    topN: z.number().int().min(0).max(10).default(5),
+    emptyTitle: z.string().optional(),
+    emptyBody: z.string().optional(),
+    /** Already-translated copy for the "map couldn't load" notice. */
+    mapUnavailableLabel: z.string().optional(),
+    regionsLabel: z.string().optional(),
+});
+/**
+ * Real cities with real coordinates — a demo map whose markers land on land.
+ * `[name, lat, lng, weight]`; `weight` biases the seeded metrics so the picture
+ * reads like plausible traffic (Tokyo outweighs Auckland) instead of noise.
+ */
+const DEMO_CITIES = [
+    ['Tokyo', 35.6762, 139.6503, 1],
+    ['New York', 40.7128, -74.006, 0.92],
+    ['London', 51.5072, -0.1276, 0.86],
+    ['São Paulo', -23.5505, -46.6333, 0.7],
+    ['Berlin', 52.52, 13.405, 0.58],
+    ['Cairo', 30.0444, 31.2357, 0.52],
+    ['Mumbai', 19.076, 72.8777, 0.66],
+    ['Sydney', -33.8688, 151.2093, 0.44],
+    ['Lagos', 6.5244, 3.3792, 0.4],
+    ['Toronto', 43.6532, -79.3832, 0.48],
+    ['Singapore', 1.3521, 103.8198, 0.5],
+    ['Auckland', -36.8485, 174.7633, 0.22],
+];
+/**
+ * Deterministic `geo-points` payload (04 §7.7) in the canonical §3 `{ points }`
+ * envelope. Two metrics so the annex's metric switcher has something to switch.
+ */
+export function mapBubbleDemoData(seed) {
+    const random = mulberry32(seed || 1);
+    const points = DEMO_CITIES.map(([name, lat, lng, weight]) => {
+        // Draw both jitters unconditionally and in a fixed order, so a point's
+        // values depend only on the seed + its index — never on a branch above it.
+        const usersJitter = 0.6 + random() * 0.8;
+        const revenueJitter = 0.6 + random() * 0.8;
+        return {
+            name,
+            lat,
+            lng,
+            values: {
+                users: Math.round(400 + weight * 24_000 * usersJitter),
+                revenue: Math.round(2_000 + weight * 180_000 * revenueJitter),
+            },
+        };
+    });
+    return { points };
+}
+// ── map-choropleth-grid (annex §7) ──────────────────────────────────────────
+/**
+ * annex §7: "See `chart-choropleth-grid` (registered in Charts; cross-listed
+ * here). Region-coded tiles when only region codes exist, no coordinates."
+ *
+ * CROSS-LISTED, SO IT SHARES THE GEOMETRY, NOT A COPY OF IT: the component
+ * renders @adminium/charts' `ChoroplethGridChart` — the same primitive
+ * `chart-choropleth-grid` renders, over the same `choroplethLayout` tilegram. The
+ * two registry ids differ only in FAMILY and in the entry point the generator
+ * reaches them by: the charts id is the analytics-dashboard tile, this one is
+ * what the annex §7 auto-instantiation rule ("country/state/region code column +
+ * numeric → `map-choropleth-grid`") emits when a table has region codes but no
+ * coordinates, i.e. when `map-bubble` cannot be built.
+ *
+ * The schema mirrors `chartChoroplethGridConfigSchema` field-for-field for the
+ * shared knobs. It is declared here rather than imported from the charts family
+ * because that schema lives in a `.tsx` (`MatrixGeoWidgets.tsx`) — importing it
+ * would pull a component module into this family's metadata graph and defeat the
+ * split the chunk-budget gate protects. The `*Field` names below are this
+ * family's own reader config and have no counterpart there.
+ */
+export const mapChoroplethGridConfigSchema = widgetSharedConfigSchema.extend({
+    layout: z.enum(['us-tilegram', 'grid']).default('us-tilegram'),
+    /** Metric key read from each region's `values` map; defaults to the first. */
+    metric: z.string().optional(),
+    nameField: z.string().default('name'),
+    codeField: z.string().default('code'),
+    columns: z.number().int().min(2).max(12).default(6),
+    levels: z.number().int().min(4).max(6).default(5),
+    /** Top-N ranked companion list (0 = off). */
+    topN: z.number().int().min(0).max(10).default(5),
+    valueFormat: z.enum(['plain', 'compact', 'currency', 'percent']).default('compact'),
+    /** Already-translated low/high legend copy. */
+    legendLowLabel: z.string().optional(),
+    legendHighLabel: z.string().optional(),
+    emptyTitle: z.string().optional(),
+    emptyBody: z.string().optional(),
+});
+/** USPS code + name for the tilegram demo (a spread of real states). */
+const DEMO_STATES = [
+    ['CA', 'California'], ['TX', 'Texas'], ['NY', 'New York'], ['FL', 'Florida'],
+    ['IL', 'Illinois'], ['PA', 'Pennsylvania'], ['OH', 'Ohio'], ['GA', 'Georgia'],
+    ['NC', 'North Carolina'], ['MI', 'Michigan'], ['WA', 'Washington'], ['AZ', 'Arizona'],
+    ['MA', 'Massachusetts'], ['CO', 'Colorado'], ['OR', 'Oregon'], ['MN', 'Minnesota'],
+];
+/**
+ * Deterministic `geo-points` payload keyed by region code (04 §7.7) — the same
+ * `{ points: [{code, name, values}] }` envelope `chart-choropleth-grid`'s
+ * generator emits, since the two ids share a data contract by the annex's
+ * cross-listing.
+ */
+export function mapChoroplethGridDemoData(seed) {
+    const random = mulberry32(seed || 1);
+    const points = DEMO_STATES.map(([code, name]) => ({
+        code,
+        name,
+        values: {
+            sales: Math.round(20_000 + random() * 480_000),
+            orders: Math.round(120 + random() * 4200),
+        },
+    }));
+    return { points };
+}
+/** The map's opening view: config's center/zoom, else the whole world. */
+export function initialView(config) {
+    return { center: config.initialCenter ?? DEFAULT_CENTER, zoom: config.initialZoom };
+}
+//# sourceMappingURL=geo-config.js.map

package/dist/families/geo/geo-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo-config.js","sourceRoot":"","sources":["../../../src/families/geo/geo-config.ts"],"names":[],"mappings":"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"}

package/dist/families/geo/geo-lib.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared helpers for the `geo` family (annex §7) — the seeded PRNG the demo
+ * generators use, the `geo-points` envelope reader, the bubble radius scale, the
+ * theme-following Carto tile URLs, and the binding → event-source read.
+ *
+ * PURE AND FRAMEWORK-LIGHT: no React, no DOM, and — load-bearing — **no
+ * Leaflet**. `geo-config.ts` imports this module and `geo-track.definitions.ts`
+ * imports that, so anything reachable from here lands in the registry's EAGER
+ * metadata graph. Leaflet is reachable from exactly one module in this package
+ * (`MapBubble.tsx`, through a dynamic `import()` inside an effect); see the map
+ * dependency tests in `qa/chunk-budget.test.ts`, which walk the transitive
+ * static-import graph from every definitions module to prove it.
+ */
+/** Mulberry32 — the repo's deterministic seeded PRNG (see feeds/feed-lib.tsx). */
+export declare function mulberry32(seed: number): () => number;
+/**
+ * Fixed demo epoch so `demoData(seed)` is byte-identical across runs and
+ * platforms (04 §7.7). Matches the communication family's `CHAT_DEMO_EPOCH`.
+ * No `Date.now()` / `Math.random()` may appear anywhere in this family.
+ */
+export declare const GEO_DEMO_EPOCH: number;
+/**
+ * One plotted place. `lat`/`lng` are present for `map-bubble` (the annex's
+ * "lat/lng columns"); `code` is present for `map-choropleth-grid` (the annex's
+ * "region codes, no coordinates"). Both carry a `values` metric map, which is
+ * what the metric switcher tabs through.
+ */
+export interface GeoPoint {
+    name: string;
+    code?: string | undefined;
+    lat?: number | undefined;
+    lng?: number | undefined;
+    values: Record<string, number>;
+}
+/** Column names the reader maps a raw `record-list` row through (04 §5). */
+export interface GeoFieldConfig {
+    nameField: string;
+    codeField: string;
+    latField: string;
+    lngField: string;
+    /** Metric columns to lift into `values`; empty → every other finite number. */
+    metricFields: readonly string[];
+}
+/**
+ * Read a `geo-points` payload.
+ *
+ * TWO ENVELOPES, DELIBERATELY. The canonical §3 shape is `{ points: [...] }`
+ * with a per-point `values` map — the same shape `chart-choropleth-grid`
+ * consumes, and the one `isEmptyByShape['geo-points']` tests. But the annex §7
+ * auto-instantiation rule (`geo.lat-lng-pair` in registry/candidates.ts) binds
+ * `map-bubble` to a plain `select` over the source table, so a LIVE instance
+ * receives raw `{ rows: [...] }` whose lat/lng/metric columns are named by
+ * config. Reading only `points` would render "no locations" against a perfectly
+ * good payload — the exact bug `chatRowsOf` was fixed for in the communication
+ * family. So both are read, `points` first (it is the declared contract).
+ */
+export declare function geoPointsOf(data: unknown, fields: GeoFieldConfig): GeoPoint[];
+/** Points that can actually be plotted on a coordinate map. */
+export declare function plottablePoints(points: readonly GeoPoint[]): GeoPoint[];
+/** Every metric key present across the payload, in first-seen order. */
+export declare function metricKeysOf(points: readonly GeoPoint[]): string[];
+/** A point's value for the active metric (0 when absent). */
+export declare function metricValue(point: GeoPoint, metric: string): number;
+export declare const BUBBLE_MIN_RADIUS = 6;
+export declare const BUBBLE_MAX_RADIUS = 28;
+/**
+ * Marker radius for a value, on a SQRT scale between the min/max radii.
+ *
+ * Sqrt, not linear: a circle's visual weight is its AREA, so scaling the radius
+ * linearly makes a 4× value look 16× bigger and misreads the data. This is the
+ * same perceptual rule the `chart-scatter-bubble` primitive follows.
+ *
+ * Degenerate inputs collapse to the min radius rather than dividing by zero: a
+ * single-point payload, an all-zero metric, and an all-equal metric all have
+ * `max === min`, and there is no honest "relative size" to draw.
+ */
+export declare function bubbleRadius(value: number, max: number): number;
+/** The largest value of the active metric across the payload (0 when empty). */
+export declare function maxMetric(points: readonly GeoPoint[], metric: string): number;
+/**
+ * Carto Positron / Dark Matter raster tiles — the annex's "theme-following Carto
+ * light/dark tiles". Swapped live through @adminium/ui's `subscribeTheme`, whose
+ * own docblock names this exact case ("for Leaflet tile swaps").
+ */
+export declare const CARTO_TILES: Readonly<Record<'light' | 'dark', string>>;
+/** Carto's required attribution (their tiles, OSM's data). Rendered in the map. */
+export declare const CARTO_ATTRIBUTION = "\u00A9 OpenStreetMap contributors \u00A9 CARTO";
+/** Default view when config names no center: the whole world, roughly framed. */
+export declare const DEFAULT_CENTER: readonly [number, number];
+export declare const DEFAULT_ZOOM = 2;
+/**
+ * The `{connectionId, table}` pair a `record-open` / `drill-through` event
+ * carries, read off the widget's query descriptor (04 §5.1: `binding.source.name`
+ * is the table/view — NOT `binding.table`). Tolerant of a `table`-spelled source
+ * and of an absent binding, so a demoData-backed instance still emits sensibly.
+ */
+export declare function sourceOf(binding: unknown): {
+    connectionId?: string | undefined;
+    table: string;
+};
+/**
+ * Coerce an untrusted locale tag to one `Intl` accepts. `format.locale` is an
+ * optional free-string in the shared widget config, so `''` is SCHEMA-VALID and
+ * reaches us — and every `Intl` constructor throws `RangeError` on an empty tag.
+ * Mirrors `chat-lib.localeOf`.
+ */
+export declare function localeOf(tag: string | undefined): string;
+//# sourceMappingURL=geo-lib.d.ts.map