@bicharts/chart-host 0.1.14 → 0.3.0

package/README.md

@@ -120,6 +120,19 @@ The integration contract returned by `generate_chart` names exactly which ones *
 needs. If one is missing, the host throws a message naming the package instead of a bare
 `d3.sankey is not a function`.
 
+You can also ask the code itself, *before* rendering it — which is what you want when the chart
+arrives at run time and a blank frame is not an acceptable answer:
+
+```js
+import { requiredD3Plugins } from "@bicharts/chart-host";
+
+requiredD3Plugins(code);            // -> ["d3-sankey"]  (sorted, deduped, [] for core-only d3)
+```
+
+It is a static scan, not a trial render: synchronous, side-effect free, and safe to run on
+generated code you have not executed yet. It errs toward naming a plugin the chart may not
+reach — a needless install is cheaper than a blank chart.
+
 ## Selection styling
 
 Generated code emits marks and `data-row-idx`; it never styles "selected", because only the host
@@ -131,6 +144,43 @@ visual — override them if you want a different look:
 .bic-chart-host.lch-has-selection .d3-mark:not(.lch-mark-selected) { opacity: var(--lch-dim-opacity); }
 ```
 
+## Architecture — three layers, and why it matters if you contribute
+
+Read this before adding code. The package has **three** concerns, and they are independent.
+Most well-meaning changes that damage it do so by collapsing two of them.
+
+| layer | knows about | must **not** know about |
+| --- | --- | --- |
+| **1 · Core** | rows, marks as a *concept*, selection state, the cross-filter protocol, option resolution | any charting library, any host |
+| **2 · Renderer adapter** | how *one* library expresses a binding, and where its marks live | the host it is running in |
+| **3 · Host glue** | one host's lifecycle, identity model and settings | a library's internals |
+
+Layer 3 is **not in this package** — it is the integrator's. `createChartHost` is the glue for a
+plain web page; the BIC Power BI visual has its own, because a report host's lifecycle is
+genuinely different. That separation is deliberate: merging them would drag host concepts into a
+package whose entire value is not having them.
+
+**Layer 2 is the one that is easy to get wrong**, because today only one adapter exists (D3) and
+its assumptions are easy to mistake for universal truths. They are not. Two examples from charts
+BIC already generates:
+
+- **Marks are not always DOM elements.** D3 tags them in the DOM (`.d3-mark` + `data-row-idx`).
+  Other libraries carry the row binding in their *data model* instead, on the trace or point.
+  An abstraction phrased as `querySelectorAll(markClass)` is D3's implementation wearing the
+  costume of an interface.
+- **A renderer may support no interaction at all.** Some chart types render to a raster image —
+  no DOM, no marks, nothing to hit-test. A null adapter has to be legal.
+
+So: if you are adding support for another charting library, you should be implementing layer 2
+and touching nothing else. If your change needs edits in the core to make one library work, the
+seam is in the wrong place — please open an issue rather than widening the core.
+
+**Known wart, and it is ours, not yours.** `contract.ts` currently mixes layers 1 and 2:
+`MARK_CLASS` (`"d3-mark"`) and `ROW_IDX_ATTR` are D3's binding mechanism, while
+`XFILTER_REFRESH_EVENT`, the `lch-*` selection classes and `DIM_OPACITY_VAR` are genuinely
+renderer-neutral. The names are historical. Do not take the file's current shape as licence to
+add more renderer-specific constants to it.
+
 ## Versioning
 
 `HOST_CONTRACT_VERSION` is the grammar version (mark classes, container slots, the cross-filter

package/dist/{chunk-RTPHW4YT.mjs → chunk-4DULDBNH.mjs}

@@ -85,11 +85,11 @@ var byAsset = /* @__PURE__ */ new Map();
 var _na;
 function geoAssetFor(geoKind) {
   if (!geoKind) return null;
-  const k3 = geoKind.toLowerCase();
-  if (/^country/.test(k3)) return "world";
-  if (k3 === "north-america") return "world";
-  if (k3 === "us-state-code" || k3 === "us-state-name") return "us-states";
-  if (k3 === "us-zip5") return "us-zip3";
+  const k2 = geoKind.toLowerCase();
+  if (/^country/.test(k2)) return "world";
+  if (k2 === "north-america") return "world";
+  if (k2 === "us-state-code" || k2 === "us-state-name") return "us-states";
+  if (k2 === "us-zip5") return "us-zip3";
   return null;
 }
 function northAmerica(world) {
@@ -246,8 +246,8 @@ var T = { latlon: 0, city: 1, zip3: 2, state: 3 };
 function F(a) {
   let e = new Array(a.length), n = new Array(a.length), o = /* @__PURE__ */ new Set(), l2 = [], t = 0, r = 0, i = null;
   for (let s = 0; s < a.length; ++s) {
-    let M2 = a[s], A = k(M2);
-    if (A) e[s] = A.lat, n[s] = A.lon, t++, A.ambiguous && r++, (i === null || T[A.precision] > T[i]) && (i = A.precision);
+    let M2 = a[s], A2 = k(M2);
+    if (A2) e[s] = A2.lat, n[s] = A2.lon, t++, A2.ambiguous && r++, (i === null || T[A2.precision] > T[i]) && (i = A2.precision);
     else {
       e[s] = null, n[s] = null;
       let d = [M2.city, M2.state, M2.zip].filter((u) => u != null && String(u).trim() !== "").map((u) => String(u).trim()).join(", ");
@@ -374,10 +374,10 @@ function Rn(n, o) {
     else {
       let I3 = n[c2];
       if (I3 != null) {
-        let T2 = String(I3).trim();
-        if (T2.length > 0) {
-          let R2 = T2.toLowerCase();
-          e.has(R2) || (e.add(R2), u.push(T2));
+        let T3 = String(I3).trim();
+        if (T3.length > 0) {
+          let R = T3.toLowerCase();
+          e.has(R) || (e.add(R), u.push(T3));
         }
       }
     }
@@ -387,11 +387,11 @@ function Rn(n, o) {
 
 // ../shape-core/dist/index.mjs
 /*! @bicharts/shape-core — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; US Census/TIGER (public domain). Full text: NOTICE in this package. */
-var R = 85;
+var b2 = 85;
 var S2 = 2;
-var ot = 100;
+var st = 100;
 var L3 = 400;
-var w = /* @__PURE__ */ new Set(["us", "usa", "u s", "u s a", "united states", "united states of america", "america", "ca", "can", "canada", "mx", "mex", "mexico", "estados unidos mexicanos"]);
+var T2 = /* @__PURE__ */ new Set(["us", "usa", "u s", "u s a", "united states", "united states of america", "america", "ca", "can", "canada", "mx", "mex", "mexico", "estados unidos mexicanos"]);
 function m2(i) {
   let n = /* @__PURE__ */ new Set();
   for (let e of i) {
@@ -403,10 +403,10 @@ function m2(i) {
 }
 function P2(i) {
   let n = m2(i);
-  return n.length === 0 || !n.every((e) => w.has(e)) ? false : n.some((e) => !O(e));
+  return n.length === 0 || !n.every((e) => T2.has(e)) ? false : n.some((e) => !O(e));
 }
-function M(i) {
-  return w.has(i) && !!O(i);
+function A(i) {
+  return T2.has(i) && !!O(i);
 }
 function x2(i) {
   let n = m2(i);
@@ -415,7 +415,7 @@ function x2(i) {
   for (let o of n) O(o) && e++;
   return Math.round(e / n.length * 1e3) / 10;
 }
-function z(i) {
+function I2(i) {
   let n = /* @__PURE__ */ new Set();
   for (let e of i) {
     if (e == null) continue;
@@ -424,40 +424,40 @@ function z(i) {
   }
   return Array.from(n);
 }
-function I2(i) {
-  let n = z(i);
+function w(i) {
+  let n = I2(i);
   if (n.length === 0) return 0;
   let e = 0;
   for (let o of n) p(o).length > 0 && e++;
   return Math.round(e / n.length * 1e3) / 10;
 }
-function it(i) {
+function rt(i) {
   let n = m2(i);
   if (n.length === 0) return 0;
   let e = 0;
   for (let o of n) W(o) && e++;
   return Math.round(e / n.length * 1e3) / 10;
 }
-function k2(i, n) {
+function M(i, n) {
   let e = 0;
   for (let o of m2(i)) n(o) && e++;
   return e;
 }
-function st(i, n) {
+function at(i, n) {
   let e = 0;
-  for (let o of z(i)) n(o) && e++;
+  for (let o of I2(i)) n(o) && e++;
   return e;
 }
-function rt(i, n, e) {
-  let o = [], p2 = [], s = {}, A = new Set(i), d = (t) => n.map((r) => r[t]);
+function ct(i, n, e) {
+  let o = [], p2 = [], s = {}, k2 = new Set(i), d = (t) => n.map((r) => r[t]);
   for (let t of ["city", "zip", "lat", "lon", "country"]) {
     let r = e?.[t];
-    r && A.has(r) && (s[t] = r);
+    r && k2.has(r) && (s[t] = r);
   }
   let u = e?.state;
-  if (u && A.has(u)) {
+  if (u && k2.has(u)) {
     let t = d(u), r = m2(t);
-    r.length > 0 && r.every(M) ? p2.push(`state=${u} (every value is "CA", which is both Canada and California)`) : P2(t) ? (p2.push(`state=${u} (every value is a country, not a state)`), s.country || (s.country = u)) : x2(t) < R ? p2.push(`state=${u} (only ${x2(t)}% of values are states/provinces)`) : s.state = u;
+    r.length > 0 && r.every(A) ? p2.push(`state=${u} (every value is "CA", which is both Canada and California)`) : P2(t) ? (p2.push(`state=${u} (every value is a country, not a state)`), s.country || (s.country = u)) : x2(t) < b2 ? p2.push(`state=${u} (only ${x2(t)}% of values are states/provinces)`) : s.state = u;
   }
   let l2 = new Set(Object.values(s).filter(Boolean)), y2 = i.filter((t) => !l2.has(t) && !t.startsWith("__"));
   if (!s.state) {
@@ -466,16 +466,16 @@ function rt(i, n, e) {
       let a = d(r);
       if (P2(a)) continue;
       let c2 = x2(a);
-      if (c2 < R) continue;
-      let v3 = k2(a, (h2) => !!O(h2)), T2 = k2(a, (h2) => !!O(h2) && !M(h2));
-      v3 < S2 && T2 < 1 || (!t || c2 > t.pct) && (t = { name: r, pct: c2 });
+      if (c2 < b2) continue;
+      let C2 = M(a, (g2) => !!O(g2)), z = M(a, (g2) => !!O(g2) && !A(g2));
+      C2 < S2 && z < 1 || (!t || c2 > t.pct) && (t = { name: r, pct: c2 });
     }
     t && (s.state = t.name, l2.add(t.name), o.push(`state=${t.name} (${t.pct}% states/provinces)`));
   }
   if (!s.zip) for (let t of y2) {
     if (l2.has(t)) continue;
-    let r = d(t), a = I2(r);
-    if (!(a < ot) && !(st(r, (c2) => p(c2).length > 0) < S2)) {
+    let r = d(t), a = w(r);
+    if (!(a < st) && !(at(r, (c2) => p(c2).length > 0) < S2)) {
       s.zip = t, l2.add(t), o.push(`zip=${t} (${a}% ZIP codes)`);
       break;
     }
@@ -490,8 +490,8 @@ function rt(i, n, e) {
     let t = null;
     for (let r of y2) {
       if (l2.has(r)) continue;
-      let a = d(r), c2 = it(a);
-      c2 < R || k2(a, (v3) => W(v3)) < S2 || (!t || c2 > t.pct) && (t = { name: r, pct: c2 });
+      let a = d(r), c2 = rt(a);
+      c2 < b2 || M(a, (C2) => W(C2)) < S2 || (!t || c2 > t.pct) && (t = { name: r, pct: c2 });
     }
     t && (s.city = t.name, o.push(`city=${t.name} (${t.pct}% known cities)`));
   }
@@ -509,7 +509,7 @@ function buildRenderPayload(cols, rowObjs, geo, point) {
   let rolesRefused = [];
   if (bind) {
     const dims = cols.filter((c2) => !c2.isMeasure).map((c2) => c2.name);
-    const res = rt(dims, rowObjs, bind);
+    const res = ct(dims, rowObjs, bind);
     bind = res.bind;
     rolesBackfilled = res.backfilled;
     rolesRefused = res.refused;
@@ -561,12 +561,12 @@ function buildRenderPayload(cols, rowObjs, geo, point) {
         a[c2] = v3 ?? null;
       }
     }
-    let k3 = cols.length;
-    a[k3++] = r;
-    if (geoIso) a[k3++] = geoIso[r];
+    let k2 = cols.length;
+    a[k2++] = r;
+    if (geoIso) a[k2++] = geoIso[r];
     if (pLat && pLon) {
-      a[k3++] = pLat[r];
-      a[k3++] = pLon[r];
+      a[k2++] = pLat[r];
+      a[k2++] = pLon[r];
     }
     out[r] = a;
   }
@@ -742,6 +742,14 @@ var D3_PLUGIN_PACKAGES = {
   voronoiMap: "d3-voronoi-map",
   weightedVoronoi: "d3-weighted-voronoi"
 };
+function requiredD3Plugins(code) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m3 of String(code || "").matchAll(/\bd3\s*\.\s*(\w+)\s*\(/g)) {
+    const pkg = D3_PLUGIN_PACKAGES[m3[1]];
+    if (pkg) out.add(pkg);
+  }
+  return [...out].sort();
+}
 function explainRenderFailure(err, d3) {
   const msg = String(err?.message ?? err ?? "");
   if (!d3) {
@@ -1013,6 +1021,8 @@ export {
   clearGeoCache,
   buildRenderPayload,
   createMarkResolver,
+  requiredD3Plugins,
+  explainRenderFailure,
   compileRenderFn,
   createChartHost
 };

package/dist/index.mjs

@@ -29,13 +29,15 @@ import {
   compileRenderFn,
   createChartHost,
   createMarkResolver,
+  explainRenderFailure,
   geoAssetFor,
   geoFromCache,
   loadGeo,
   registerGeo,
   registerGeoAsset,
+  requiredD3Plugins,
   resolveOptions
-} from "./chunk-RTPHW4YT.mjs";
+} from "./chunk-4DULDBNH.mjs";
 import "./chunk-A2GMXZP7.mjs";
 export {
   ANIM_MAX_IDEAL_FRAMES_DEFAULT,
@@ -67,10 +69,12 @@ export {
   compileRenderFn,
   createChartHost,
   createMarkResolver,
+  explainRenderFailure,
   geoAssetFor,
   geoFromCache,
   loadGeo,
   registerGeo,
   registerGeoAsset,
+  requiredD3Plugins,
   resolveOptions
 };

package/dist/react.mjs

@@ -2,7 +2,7 @@
 import {
   buildRenderPayload,
   createChartHost
-} from "./chunk-RTPHW4YT.mjs";
+} from "./chunk-4DULDBNH.mjs";
 import "./chunk-A2GMXZP7.mjs";
 
 // src/react.tsx

package/dist/types/host.d.ts

@@ -56,6 +56,7 @@ export interface ChartHost {
     initialMark(): Element | null;
     destroy(): void;
 }
+export declare function requiredD3Plugins(code: string): string[];
 export declare function explainRenderFailure(err: unknown, d3: any): unknown;
 export declare function compileRenderFn(code: string, win: any, doc: any, d3: any): RenderFn;
 export declare function createChartHost(container: HTMLElement, config: ChartHostConfig): ChartHost;

package/dist/types/index.d.ts

@@ -2,5 +2,5 @@ export * from "./contract";
 export { resolveOptions, type ResolveOptionsInput } from "./defaults";
 export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clearGeoCache, type GeoAssetName, } from "./geoLazy";
 export { buildRenderPayload, type RenderPayload, type GeoPointBinding } from "./payload";
-export { createChartHost, compileRenderFn, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
+export { createChartHost, compileRenderFn, requiredD3Plugins, explainRenderFailure, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
 export { createMarkResolver, type MarkResolver, type MarkResolverEnv } from "./selection";

package/package.json

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