@bicharts/chart-host 0.6.5 → 0.6.6

package/README.md

@@ -114,6 +114,31 @@ host.setOptions({ colorScaleLow: "#eee" });   // live restyle — never a regene
 host.destroy();                               // call on unmount
 ```
 
+### Several charts, one selection, without React
+
+`createChartGroup` is the group `<BicChartGroup>` wraps: it owns the source table, derives each
+member's payload, and translates every click to **source** row indices, so the row-index hazard
+above is handled the same way in any framework (or none).
+
+```js
+import { createChartGroup, createChartHost, assembleD3 } from "@bicharts/chart-host";
+
+const group = createChartGroup(columns, rows, { point: { city: "City" } });
+const d3all = assembleD3(d3, d3Sankey);                     // one extensible d3 for every chart
+
+function mount(id, el, code, opts = {}) {                   // opts: { filteredBy, respondsWith }
+  const host = createChartHost(el, { code, d3: d3all, data: group.memberPayload(id, opts).payload,
+                                     options: { width: 800, height: 500 } });
+  host.render();
+  return group.attach(id, host, opts);                      // .detach() on teardown
+}
+mount("map", mapEl, mapCode, { respondsWith: "highlight" });
+mount("table", tableEl, tableCode);
+
+group.onChange(sel => console.log(sel.sourceId, sel.rows));  // SOURCE row indices
+group.clear();
+```
+
 ## Sizing is yours
 
 `width`/`height` have **no defaults**. A chart draws once at whatever it is handed and does not
@@ -125,6 +150,9 @@ a background or headless tab, where frames are barely produced.
 useLayoutEffect(() => setW(ref.current.getBoundingClientRect().width), []);
 ```
 
+In React, `useMeasuredSize(ref)` from `@bicharts/chart-host/react` does exactly that and follows
+later resizes: give the element its size in CSS and pass what it measures.
+
 ## Maps
 
 Geometry is **not** bundled into the entry — the three assets are ~1.3 MB raw, and a bar chart

package/dist/{chunk-CZRYIPEL.mjs → chunk-ZPWRXCS5.mjs}

@@ -3331,6 +3331,9 @@ function noopViewStateProvider() {
   } };
 }
 var parseRowIdxs = (s) => (s || "").split(",").map((x3) => parseInt(x3, 10)).filter((n) => Number.isFinite(n));
+function assembleD3(base, ...plugins) {
+  return Object.assign({}, base, ...plugins);
+}
 var D3_PLUGIN_PACKAGES = {
   sankey: "d3-sankey",
   sankeyLinkHorizontal: "d3-sankey",
@@ -3839,6 +3842,116 @@ function createChartHost(container, config) {
   return host;
 }
 
+// src/group.ts
+var EMPTY6 = Object.freeze({ sourceId: null, rows: Object.freeze([]) });
+function toSourceRows(rowMap, payloadRowIdxs) {
+  if (!rowMap) return payloadRowIdxs.slice();
+  return payloadRowIdxs.map((i) => rowMap[i]).filter((i) => i !== void 0);
+}
+function syncMemberSelection(host, selection, id, highlight, incoming) {
+  const mine = selection.sourceId === id && selection.rows.length > 0;
+  if (mine) return;
+  if (highlight && incoming && incoming.length) {
+    host.selection.highlight(incoming.slice());
+    return;
+  }
+  if (host.selection.current && host.selection.current.length) host.selection.clear();
+}
+function createChartGroup(columns, rows, opts = {}) {
+  let cols = columns;
+  let table = rows;
+  let geo = opts.geo ?? null;
+  let point = opts.point ?? null;
+  let selection = EMPTY6;
+  const subs = /* @__PURE__ */ new Set();
+  const members = /* @__PURE__ */ new Set();
+  const notify = (change) => {
+    for (const cb of Array.from(subs)) cb(selection, change);
+  };
+  const incomingFor = (id, filteredBy) => {
+    const s = selection;
+    const forId = s.rows.length && s.sourceId && s.sourceId !== id ? s.rows.slice() : null;
+    if (filteredBy) return s.sourceId === filteredBy ? forId : null;
+    return forId;
+  };
+  const payloadFor = (sourceRowIdxs) => {
+    const idxs = sourceRowIdxs ? sourceRowIdxs.slice() : table.map((_2, i) => i);
+    const subset = idxs.map((i) => table[i]);
+    const payload = buildRenderPayload(cols, subset, geo ?? void 0, point ?? void 0);
+    return { payload, rowMap: idxs };
+  };
+  const memberPayload = (id, o = {}) => payloadFor(o.respondsWith === "highlight" ? null : incomingFor(id, o.filteredBy));
+  const group = {
+    get selection() {
+      return selection;
+    },
+    get columns() {
+      return cols;
+    },
+    get rows() {
+      return table;
+    },
+    incomingFor,
+    payloadFor,
+    memberPayload,
+    publish(id, sourceRowIdxs) {
+      selection = sourceRowIdxs.length ? { sourceId: id, rows: sourceRowIdxs.slice() } : { sourceId: null, rows: [] };
+      notify(sourceRowIdxs.length ? "select" : "clear");
+    },
+    clear() {
+      selection = { sourceId: null, rows: [] };
+      notify("clear");
+    },
+    setSource(nextColumns, nextRows, o = {}) {
+      cols = nextColumns;
+      table = nextRows;
+      geo = o.geo ?? null;
+      point = o.point ?? null;
+      notify("source");
+    },
+    onChange(cb) {
+      subs.add(cb);
+      return () => {
+        subs.delete(cb);
+      };
+    },
+    attach(id, host, o = {}) {
+      const highlight = o.respondsWith === "highlight";
+      let rowMap = memberPayload(id, o).rowMap;
+      const offHost = host.selection.onChange((payloadIdxs, source) => {
+        if (source === "host") return;
+        const sourceIdxs = toSourceRows(rowMap, payloadIdxs);
+        if (id) group.publish(id, sourceIdxs);
+        o.onSelect?.(sourceIdxs);
+      });
+      const offGroup = group.onChange((sel) => {
+        const incoming = incomingFor(id, o.filteredBy);
+        const next = payloadFor(highlight ? null : incoming);
+        rowMap = next.rowMap;
+        host.setData(next.payload);
+        syncMemberSelection(host, sel, id, highlight, incoming);
+      });
+      const member = {
+        get rowMap() {
+          return rowMap;
+        },
+        detach() {
+          offHost();
+          offGroup();
+          members.delete(member);
+        }
+      };
+      members.add(member);
+      return member;
+    },
+    destroy() {
+      for (const m of Array.from(members)) m.detach();
+      subs.clear();
+    }
+  };
+  return group;
+}
+
 export {
   HOST_CONTRACT_VERSION,
   GEO_POINT_PRECISIONS,
@@ -3970,9 +4083,13 @@ export {
   invalidSentinelReason,
   sessionViewStateProvider,
   noopViewStateProvider,
+  assembleD3,
   requiredD3Plugins,
   explainRenderFailure,
   stripEsmExports,
   compileRenderFn,
-  createChartHost
+  createChartHost,
+  toSourceRows,
+  syncMemberSelection,
+  createChartGroup
 };

package/dist/index.mjs

@@ -69,6 +69,7 @@ import {
   We,
   XFILTER_REFRESH_EVENT,
   applyLabelContrast,
+  assembleD3,
   autoRampCanvas,
   autoRampMinStep,
   axisPinPlacement,
@@ -87,6 +88,7 @@ import {
   compositeOver,
   contentExtentOf,
   contrastRatio,
+  createChartGroup,
   createChartHost,
   createMarkResolver,
   ctmScaleOf,
@@ -131,11 +133,13 @@ import {
   stripEsmExports,
   stripJsComments,
   svgInkReach,
+  syncMemberSelection,
   toRGBA,
+  toSourceRows,
   unpinScrolledAxis,
   valuePlacementFlag,
   withoutViewOnlyKeys
-} from "./chunk-CZRYIPEL.mjs";
+} from "./chunk-ZPWRXCS5.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -2499,6 +2503,7 @@ export {
   actionFor,
   applyLabelContrast,
   askApplyImprovements,
+  assembleD3,
   autoRampCanvas,
   autoRampMinStep,
   axisPinPlacement,
@@ -2531,6 +2536,7 @@ export {
   confirmLaunch,
   contentExtentOf,
   contrastRatio,
+  createChartGroup,
   createChartHost,
   createMarkResolver,
   ctmScaleOf,
@@ -2631,7 +2637,9 @@ export {
   svgInkReach,
   svgNaturalSize,
   svgToDataUrl,
+  syncMemberSelection,
   toRGBA,
+  toSourceRows,
   transportFailureShouldRecover,
   unpinScrolledAxis,
   valuePlacementFlag,

package/dist/react.mjs

@@ -1,10 +1,13 @@
 /*! @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 {
-  buildRenderPayload,
+  assembleD3,
+  createChartGroup,
   createChartHost,
   geoFromCache,
-  loadGeo
-} from "./chunk-CZRYIPEL.mjs";
+  loadGeo,
+  syncMemberSelection,
+  toSourceRows
+} from "./chunk-ZPWRXCS5.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -17,32 +20,28 @@ function useBicSelection() {
   return {
     rows: g?.selection.rows ?? [],
     sourceId: g?.selection.sourceId ?? null,
-    clear: () => g?.clear()
+    clear: () => g?.group.clear()
   };
 }
 function BicChartGroup({ rows, columns, geo, point, children }) {
-  const [sel, setSel] = useState({ sourceId: null, rows: [] });
-  const value = useMemo(() => ({
-    rows,
-    columns,
-    geo,
-    point,
-    selection: sel,
-    publish: (id, sourceRowIdxs) => setSel(sourceRowIdxs.length ? { sourceId: id, rows: sourceRowIdxs } : { sourceId: null, rows: [] }),
-    // A chart never filters itself — that is what keeps the gesture reversible:
-    // the origin chart still shows every mark, so there is always something left
-    // to click to change or clear the selection.
-    filterFor: (id) => sel.rows.length && sel.sourceId && sel.sourceId !== id ? sel.rows : null,
-    clear: () => setSel({ sourceId: null, rows: [] })
-  }), [rows, columns, geo, point, sel]);
+  const groupRef = useRef(null);
+  if (!groupRef.current) groupRef.current = createChartGroup(columns, rows, { geo, point });
+  const group = groupRef.current;
+  const [sel, setSel] = useState(group.selection);
+  const source = useMemo(() => {
+    group.setSource(columns, rows, { geo, point });
+    return {};
+  }, [group, rows, columns, geo, point]);
+  useEffect(() => group.onChange((s, change) => {
+    if (change !== "source") setSel(s);
+  }), [group]);
+  const value = useMemo(
+    () => ({ group, selection: sel }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [group, sel, source]
+  );
   return /* @__PURE__ */ jsx(Ctx.Provider, { value, children });
 }
-function payloadFor(g, sourceIdxs) {
-  const idxs = sourceIdxs ?? g.rows.map((_, i) => i);
-  const subset = idxs.map((i) => g.rows[i]);
-  const p = buildRenderPayload(g.columns, subset, g.geo ?? void 0, g.point ?? void 0);
-  return { payload: p, rowMap: idxs };
-}
 function BicChart(props) {
   const {
     code,
@@ -64,15 +63,15 @@ function BicChart(props) {
   const ref = useRef(null);
   const hostRef = useRef(null);
   const rowMapRef = useRef(null);
-  const group = useContext(Ctx);
-  const active = group ? group.selection : null;
-  const incoming = !group ? null : filteredBy ? active.sourceId === filteredBy ? group.filterFor(id) : null : group.filterFor(id);
+  const ctx = useContext(Ctx);
+  const group = ctx ? ctx.group : null;
+  const incoming = group ? group.incomingFor(id, filteredBy) : null;
   const highlightMode = respondsWith === "highlight";
   const filterSel = highlightMode ? null : incoming;
   const built = useMemo(() => {
     if (!group) return null;
-    return payloadFor(group, filterSel);
-  }, [group, filterSel && filterSel.join(",")]);
+    return group.payloadFor(filterSel);
+  }, [ctx, filterSel && filterSel.join(",")]);
   const data = built ? built.payload : props.data;
   rowMapRef.current = built ? built.rowMap : null;
   const onSelectRef = useRef(onSelect);
@@ -120,8 +119,7 @@ function BicChart(props) {
     hostRef.current = host;
     const off = host.selection.onChange((payloadIdxs, source) => {
       if (source === "host") return;
-      const map = rowMapRef.current;
-      const sourceIdxs = map ? payloadIdxs.map((i) => map[i]).filter((i) => i !== void 0) : payloadIdxs;
+      const sourceIdxs = toSourceRows(rowMapRef.current, payloadIdxs);
       if (group && id) group.publish(id, sourceIdxs);
       onSelectRef.current?.(sourceIdxs);
     });
@@ -141,19 +139,33 @@ function BicChart(props) {
   }, [data]);
   useEffect(() => {
     const host = hostRef.current;
-    if (!host || !group) return;
-    const mine = group.selection.sourceId === id && group.selection.rows.length > 0;
-    if (mine) return;
-    if (highlightMode && incoming && incoming.length) {
-      host.selection.highlight(incoming);
-      return;
-    }
-    if (host.selection.current && host.selection.current.length) host.selection.clear();
-  }, [group?.selection, id, group, highlightMode, incoming && incoming.join(",")]);
+    if (!host || !ctx) return;
+    syncMemberSelection(host, ctx.selection, id, highlightMode, incoming);
+  }, [ctx?.selection, id, ctx, highlightMode, incoming && incoming.join(",")]);
   return /* @__PURE__ */ jsx("div", { ref, className, style });
 }
+function useMeasuredSize(ref) {
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const read = () => {
+      const r = el.getBoundingClientRect();
+      const width = Math.round(r.width), height = Math.round(r.height);
+      setSize((s) => s.width === width && s.height === height ? s : { width, height });
+    };
+    read();
+    if (typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(read);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [ref]);
+  return size;
+}
 export {
   BicChart,
   BicChartGroup,
-  useBicSelection
+  assembleD3,
+  useBicSelection,
+  useMeasuredSize
 };

package/dist/types/group.d.ts

@@ -0,0 +1,88 @@
+import type { ChartHost } from "./host";
+import { type GeoPointBinding, type RenderPayload } from "./payload";
+/** The group's one active selection, in SOURCE row indices. `sourceId` is the member that made it. */
+export interface ChartGroupSelection {
+    readonly sourceId: string | null;
+    readonly rows: readonly number[];
+}
+/** The table every member's payload is derived from, and the geo bindings applied to each. */
+export interface ChartGroupSourceOptions {
+    /** Choropleth join binding, applied when building each member's payload. */
+    geo?: {
+        column: string;
+        kind: string;
+    } | null;
+    /** Point-map geocoding binding (city/state/zip/lat/lon column names). */
+    point?: GeoPointBinding | null;
+}
+/** How one member takes part in the group. */
+export interface ChartGroupMemberOptions {
+    /** Respond only to this member's selection (one-way wiring). Absent: respond to any sibling. */
+    filteredBy?: string;
+    /** "filter" (default) re-derives the member's payload; "highlight" keeps it and paints. */
+    respondsWith?: "filter" | "highlight";
+}
+/** A member's payload and the map from each payload row to its source row. */
+export interface ChartGroupPayload {
+    payload: RenderPayload;
+    /** `rowMap[k]` is the source row index of payload row `k`. */
+    rowMap: number[];
+}
+/** Why the group notified: a member's selection, a clear, or a new source table. */
+export type ChartGroupChange = "select" | "clear" | "source";
+/** A live chart wired into the group by `attach`. */
+export interface ChartGroupMember {
+    /** The payload-row -> source-row map of the payload the member is drawing now. */
+    readonly rowMap: readonly number[];
+    /** Unwire the member: its clicks stop publishing and the group stops redrawing it. */
+    detach(): void;
+}
+export interface ChartGroup {
+    /** The active selection. A new object on every publish and clear; kept across a new source. */
+    readonly selection: ChartGroupSelection;
+    readonly columns: readonly any[];
+    readonly rows: readonly Record<string, any>[];
+    /**
+     * The source rows member `id` should be FILTERED to now, or null for all of them. Never the
+     * member's own selection. With `filteredBy`, only that partner's selection counts.
+     */
+    incomingFor(id: string | undefined, filteredBy?: string): number[] | null;
+    /** A payload for a subset of source rows (null = every row), with its row map. */
+    payloadFor(sourceRowIdxs: readonly number[] | null): ChartGroupPayload;
+    /** The payload member `id` should draw now, under the given options. */
+    memberPayload(id: string | undefined, opts?: ChartGroupMemberOptions): ChartGroupPayload;
+    /** Publish member `id`'s selection in SOURCE rows. An empty list clears the selection. */
+    publish(id: string, sourceRowIdxs: readonly number[]): void;
+    /** Clear the group's selection. */
+    clear(): void;
+    /** Replace the source table (and bindings). The selection is kept, as source indices. */
+    setSource(columns: readonly any[], rows: readonly Record<string, any>[], opts?: ChartGroupSourceOptions): void;
+    /** Subscribe to every change. Returns the unsubscribe. */
+    onChange(cb: (selection: ChartGroupSelection, change: ChartGroupChange) => void): () => void;
+    /**
+     * Wire a live chart host into the group as member `id` (undefined: a member that responds but
+     * never publishes). Create the host with `memberPayload(id, opts).payload` as its data. From
+     * then on its clicks publish SOURCE rows (and reach `onSelect`), and every group change hands
+     * it a re-derived payload and paints or clears the selection it should show.
+     */
+    attach(id: string | undefined, host: ChartHost, opts?: ChartGroupMemberOptions & {
+        onSelect?: (sourceRowIdxs: number[]) => void;
+    }): ChartGroupMember;
+    /** Detach every member and drop every subscriber. */
+    destroy(): void;
+}
+/** Payload row indices -> source row indices, dropping any the map does not cover. */
+export declare function toSourceRows(rowMap: readonly number[] | null | undefined, payloadRowIdxs: readonly number[]): number[];
+/**
+ * Make a member's painted selection agree with the group's. A member that made the selection
+ * keeps what its host already painted. A highlight member with an incoming selection paints it.
+ * Any other member that still shows a selection clears it - a stale highlight left on the origin
+ * after the selection moved elsewhere, or after a clear. Both paths notify with source "host",
+ * so nothing done here is republished.
+ */
+export declare function syncMemberSelection(host: ChartHost, selection: ChartGroupSelection, id: string | undefined, highlight: boolean, incoming: readonly number[] | null): void;
+/**
+ * Create a cross-filter group over one source table: `rows` are objects keyed by column name,
+ * `columns` the column descriptors (`ingest()` returns both).
+ */
+export declare function createChartGroup(columns: readonly any[], rows: readonly Record<string, any>[], opts?: ChartGroupSourceOptions): ChartGroup;

package/dist/types/host.d.ts

@@ -235,6 +235,16 @@ export interface ChartHost {
     initialMark(): Element | null;
     destroy(): void;
 }
+/**
+ * ONE d3 OBJECT FROM d3 AND ITS PLUGINS - the object a chart is handed as `d3`.
+ *
+ * In a bundled app d3 and each plugin (d3-sankey, d3-hexbin, ...) are separate module
+ * namespaces, and a chart reaches all of them through one `d3`. A namespace is also FROZEN, and a
+ * generated chart installs its own helpers onto the d3 it is given, so the object must be a plain
+ * extensible copy: `assembleD3(d3, d3Sankey, d3Hexbin)`. Later arguments win on a name clash.
+ * `requiredD3Plugins(code)` names the plugin packages a given chart needs.
+ */
+export declare function assembleD3(base: object, ...plugins: object[]): Record<string, any>;
 export declare function requiredD3Plugins(code: string): string[];
 export declare function explainRenderFailure(err: unknown, d3: any): unknown;
 export declare function stripEsmExports(code: string): string;

package/dist/types/index.d.ts

@@ -6,7 +6,8 @@ export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clea
 export declare function registerCityTable(packed: string): void;
 export { buildRenderPayload, type RenderPayload, type GeoPointBinding } from "./payload";
 export { codeReadsDatesInLocalTime, vegaSpecReadsDatesInLocalTime } from "./dateCells";
-export { createChartHost, compileRenderFn, stripEsmExports, requiredD3Plugins, explainRenderFailure, sessionViewStateProvider, noopViewStateProvider, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
+export { createChartHost, compileRenderFn, stripEsmExports, requiredD3Plugins, explainRenderFailure, sessionViewStateProvider, noopViewStateProvider, assembleD3, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
+export { createChartGroup, toSourceRows, syncMemberSelection, type ChartGroup, type ChartGroupMember, type ChartGroupSelection, type ChartGroupChange, type ChartGroupMemberOptions, type ChartGroupSourceOptions, type ChartGroupPayload } from "./group";
 export { createMarkResolver, isInsideControl, type MarkResolver, type MarkResolverEnv } from "./selection";
 export { planTrivialChart, compileTrivialSource, type TrivialPlan, type TrivialShapeKind } from "./trivial";
 export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngDataUrl, type SnapshotOptions } from "./snapshot";

package/dist/types/react.d.ts

@@ -1,7 +1,8 @@
-import type { ReactNode } from "react";
+import type { ReactNode, RefObject } from "react";
 import { type ChartHostConfig } from "./host";
 import type { ResolveOptionsInput } from "./defaults";
-import { type GeoPointBinding } from "./payload";
+import type { GeoPointBinding } from "./payload";
+export { assembleD3 } from "./host";
 export interface BicChartProps {
     /** Generated render() source (an ES module's `code` export, or the raw string). */
     code?: string;
@@ -89,3 +90,15 @@ export interface BicChartGroupProps {
  */
 export declare function BicChartGroup({ rows, columns, geo, point, children }: BicChartGroupProps): import("react").JSX.Element;
 export declare function BicChart(props: BicChartProps): import("react").JSX.Element;
+/**
+ * THE SIZE A CHART SHOULD DRAW AT: the element's measured box, kept current as it resizes.
+ *
+ * A chart draws to `options.width` / `options.height`, and a page that hard-codes them draws the
+ * same size in a phone and on a wall. Give the element its size in CSS (a width of 100%, a height
+ * or an aspect ratio) and pass what this measures. `{ width: 0, height: 0 }` until the element has
+ * been measured - skip rendering until then rather than drawing at zero.
+ */
+export declare function useMeasuredSize(ref: RefObject<Element | null>): {
+    width: number;
+    height: number;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "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",