@bicharts/chart-host 0.6.4 → 0.6.6

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-AQMNNUBY.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.4",
+  "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",