@bicharts/chart-host 0.6.112 → 0.6.115

package/README.md

@@ -1,6 +1,6 @@
 # @bicharts/chart-host
 
-> **Make Generative AI for Charts and Maps *Better*.**
+> **Make Generative AI for Data Apps and Maps *Better*.**
 
 **AI Data Components, running in your page:** a bivariate map with its two-way key, a what-if projection with its
 controls inside the chart, a flow map, and about 90 everyday chart types, with selection, cross-filtering and the legend
@@ -113,6 +113,50 @@ of the affordance, they are re-applied on every render (so a manual `classList`
 the next data change), and getting row indices right across a filtered payload is the hazard
 above.
 
+### A panel whose query takes the page filter
+
+A chart whose DAX query is filtered by a page filter (`filterQuery(dax, treatAs(filter, "Table[Column]"))` from
+`@bicharts/chart-host/dax`) gets rows that are already narrowed, so it can't see the filter. `scopedBy` tells it,
+and its titles say so ("North America · United States only"):
+
+```tsx
+<BicChart id="kpis" code={kpiCode} d3={d3} data={kpiRows} scopedBy={country} />
+```
+
+`treatAs` maps the key columns it's given, in the filter's order, so a query can take only part of a compound key.
+`treatAs(cell, "Accounts[Region]")` on a Region × Stage pick filters by the region alone, and a stage-label pick
+(any region) doesn't filter that query at all. Name the key columns the query takes, so the scope line names only
+those:
+
+```tsx
+<BicChart id="cases" code={casesCode} d3={d3} data={caseRows} scopedBy={{ filter: cell, takes: ["Region"] }} />
+```
+
+A cell pick then reads "Europe", not "Europe → 3-Propose", and a pick whose taken parts are all "any" adds
+nothing to the line, since that query keeps every row. A bare filter, `{ filter }` or a `takes` that names every
+key column says the whole key. `label` sets what the line calls the filter. Outside React, `filterScopeOf` from
+`@bicharts/chart-host/page` takes the same list and returns `options.filterScope`.
+
+### Several panels that pick the same key
+
+A map, a table and a scatter that each pick a country are ONE pick. Give their filters one `group`, and keep each
+panel's query taking every member but its own:
+
+```tsx
+const fromMap   = useBicFilter("Country", { label: "Country (map)",   group: "country" });
+const fromTable = useBicFilter("Country", { label: "Country (table)", group: "country" });
+const mapQuery   = filterQuery(MAP_DAX,   treatAs(fromTable, "Geo[Country]"));
+const tableQuery = filterQuery(TABLE_DAX, treatAs(fromMap,   "Geo[Country]"));
+// <MapChart selects={fromMap} scopedBy={[fromTable]} />  <TableChart selects={fromTable} scopedBy={[fromMap]} />
+```
+
+A pick in one member clears the others, so the most recent pick is the page's one pick, and only the member holding
+it is active: one chip, one scope line. Every member's chart shows the pick, so clicking the picked mark again in
+whichever panel shows it clears it, and the panel the reader picked in keeps all its marks. A list beside them (the
+open items for the picked countries) reads the members' keys, which are that one pick. Without `group` the filters
+are separate picks, ANDed: a country picked on the map and then in the table is held twice, and clicking it again on
+the map leaves the page filtered by the table's. Outside React, `scope.filter(column, { group })` does the same.
+
 ## Vanilla
 
 ```js
@@ -287,8 +331,34 @@ the host's own write cannot be told apart from it.
 createChartHost(el, { code, data, options: { dimOpacity: 0.15 } });
 ```
 
-**A glyph on each selected mark.** `options.selectionGlyph` (`"dot"` or `"check"`; absent or
-`"none"` draws nothing, the default) puts a small glyph on every selected mark, in a layer the host
+**The selection marker: an outline or a glyph on each selected mark.** The dim alone fails where a
+selected mark's colour sits close to the canvas: a diverging ramp's centre is a neutral just off the
+canvas, and the dim pulls every other mark toward it too, so a selected region near the centre reads
+the same as the dimmed ones. Two options choose what marks the selection beyond the dim:
+
+- `options.selectionGlyph`, the *selection marker* on every chart that isn't a region map (the key
+  keeps its first name): `"auto"` (the default), `"none"`, `"dot"`, `"check"` or `"outline"`.
+  `"auto"` is an outline on a chart that declares a neutral-centre ramp (the shared value ramp's
+  diverging legend, `.llm-value-ramp[data-kind="diverging"]`) and nothing on any other chart, which
+  draws exactly as it did before.
+- `options.mapSelectionGlyph`, the marker on a *region map* (a chart whose rows carry the host's
+  `__geoIso__` join column: a choropleth, a cartogram, a province map): `"outline"` (the default),
+  `"none"`, `"dot"` or `"check"`. A point map places its rows by coordinates and has no join column,
+  so it takes `selectionGlyph`.
+
+An outline (`.lch-sel-outline`, in the same host layer as the glyphs) is each selected AREA mark's own
+shape (a filled path, rect or polygon) stroked 2px in the chart's text colour (`themeFg`, else the
+colour the container's text inherits) over a halo of its canvas (`themeBg`). It's drawn over the chart,
+so a border shared with a neighbour isn't painted over, and the marks themselves are neither restyled
+nor moved: the keyboard's order, a chart's transitions and what a click hits are unchanged. The chart's own
+controls (every element it declares `lch-control`, such as a map's zoom pad) are holes in the outline (`controlBoxesIn`, a mask): a
+region that runs under the pad is outlined up to it, never across the buttons. A line or a
+point keeps its geometry and gets no outline. `resolveOptions` gives the whole choice as
+`selectionMarker` and `mapSelectionMarker`; `selectionMarkerFor` and the traits behind it
+(`isRegionMapData`, `hasNeutralCentreRamp`) and the painter (`collectOutlineMarks`,
+`paintSelectionOutlines`) are exported for a host that draws its own layer.
+
+A glyph (`"dot"` or `"check"`) is a small mark on every selected mark, in a layer the host
 owns inside the container (`.bic-selection-glyphs`, each glyph `.lch-sel-glyph`, never hit-tested).
 It is painted after every selection change and, on a redraw, after the layout pass and the fit, so
 nothing measures it as part of the chart. Only a mark the reader can see gets one: a mark hidden by
@@ -311,13 +381,14 @@ every point. The generate answer says so (`suppressSelectionGlyph`, read by shap
 `parseGenerateResponse`); pass it as `options.suppressSelectionGlyph`, or leave it in the payload's
 `meta` (`data.meta.suppressSelectionGlyph`) and the host promotes it, the way it promotes
 `geoPoint`. Keep it with the chart's code, so a redraw from a cache honors it too.
-`onSelectionGlyphs` reports what each paint did (`{ mode, drawn, total, suppressed }`), and is
-called only when a glyph mode is set:
+The same fact keeps an outline off such a chart. `onSelectionGlyphs` reports what each paint did
+(`{ mode, drawn, total, suppressed }`, `mode` one of `"dot"`, `"check"` or `"outline"`), and is called
+only when the chart's marker is one of those:
 
 ```js
 createChartHost(el, {
   code, data,
-  options: { selectionGlyph: "dot", suppressSelectionGlyph: answer.suppressSelectionGlyph },
+  options: { selectionGlyph: "dot", mapSelectionGlyph: "outline", suppressSelectionGlyph: answer.suppressSelectionGlyph },
   onSelectionGlyphs: r => console.debug("glyphs", r),
 });
 ```

package/dist/adapters.mjs

@@ -3,7 +3,7 @@ import {
   censusHitBands,
   ensureCrossfilterHitTargets,
   hitBandFlag
-} from "./chunk-AEO5SFEQ.mjs";
+} from "./chunk-YOCYWON4.mjs";
 import {
   clickWasDrag,
   collectD3GlyphCenters,
@@ -12,13 +12,13 @@ import {
   markKeyOf,
   rowIdxsFromMark,
   selectionRuleOf
-} from "./chunk-KGVNZR23.mjs";
+} from "./chunk-PQKLWYKK.mjs";
 import {
   AXIS_FILTER_CLASS,
   LEGEND_MARK_CLASS,
   MARK_CLASS,
   ROW_IDX_ATTR
-} from "./chunk-KY4FI2HA.mjs";
+} from "./chunk-GXR7T6G5.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/adapters/types.ts

package/dist/card.mjs

@@ -1,8 +1,8 @@
 /*! @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 {
   computeSelectionCard
-} from "./chunk-OLCUKXKL.mjs";
-import "./chunk-FIG5DIW7.mjs";
+} from "./chunk-YSRMSDRP.mjs";
+import "./chunk-VPFP35XI.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/selectionCardChrome.ts

package/dist/{chunk-2KLFIGTQ.mjs → chunk-2GW3S5VD.mjs}

@@ -43,6 +43,11 @@ function toKeys(input, width) {
   return input.length === width ? [input.slice()] : [];
 }
 var nextId = 0;
+var peersOf = /* @__PURE__ */ new WeakMap();
+var pickSubsOf = /* @__PURE__ */ new WeakMap();
+var firePick = (f) => {
+  for (const m of Array.from(peersOf.get(f) ?? [f])) for (const cb of Array.from(pickSubsOf.get(m) ?? [])) cb();
+};
 function createFilter(columns, opts = {}) {
   const cols = Array.isArray(columns) ? columns.slice() : [columns];
   if (!cols.length || cols.some((c) => typeof c !== "string" || !c)) {
@@ -71,7 +76,11 @@ function createFilter(columns, opts = {}) {
     rows = nextRows;
     reason = why;
     version++;
+    if (nextKeys.length) {
+      for (const p of Array.from(peersOf.get(filter) ?? [])) if (p !== filter && p.active) p.clear(why);
+    }
     for (const cb of Array.from(subs)) cb(filter, why);
+    firePick(filter);
   };
   const dedupe = (ks) => {
     const seen2 = /* @__PURE__ */ new Set();
@@ -94,6 +103,15 @@ function createFilter(columns, opts = {}) {
     const text = parts.filter(shown).map(String).join(" \u2192 ");
     return text || k.filter(shown).map(String).join(" \u2192 ");
   };
+  const partsOf = (k, more, names) => {
+    const s = keyString(k);
+    const pos = cols.map((c, i) => names.includes(c) && !isAnyValue(k[i]) ? i : -1).filter((i) => i >= 0);
+    const row = (more ?? []).find((r) => keyString(keyOfRow(r, cols)) === s) ?? seen.get(s);
+    const speaksFor = (d, j) => cols.includes(d) ? cols.indexOf(d) : display.length === cols.length ? j : -1;
+    const shown = (p) => p != null && p !== "" && !isAnyValue(p);
+    const text = row ? display.filter((d, j) => pos.includes(speaksFor(d, j))).map((d) => row[d]).filter(shown).map(String).join(" \u2192 ") : "";
+    return text || pos.map((i) => k[i]).filter(shown).map(String).join(" \u2192 ");
+  };
   let warnedKeep = false;
   const filter = {
     id: opts.id ?? `f${++nextId}`,
@@ -137,9 +155,9 @@ function createFilter(columns, opts = {}) {
     get text() {
       return keys.map((k) => displayOf(k)).join(", ");
     },
-    textOf(key, more) {
-      const k = Array.isArray(key) ? key : [key];
-      return displayOf(k.slice(0, cols.length), more);
+    textOf(key, more, parts) {
+      const k = (Array.isArray(key) ? key : [key]).slice(0, cols.length);
+      return parts && cols.some((c) => !parts.includes(c)) ? partsOf(k, more, parts) : displayOf(k, more);
     },
     get reason() {
       return reason;
@@ -198,8 +216,23 @@ function createFilter(columns, opts = {}) {
       return () => {
         subs.delete(cb);
       };
+    },
+    group: opts.group || null,
+    get pick() {
+      const peers = peersOf.get(filter);
+      if (!peers) return keys.length ? filter : null;
+      for (const p of peers) if (p.active) return p;
+      return null;
+    },
+    onPick(cb) {
+      pickSubs.add(cb);
+      return () => {
+        pickSubs.delete(cb);
+      };
     }
   };
+  const pickSubs = /* @__PURE__ */ new Set();
+  pickSubsOf.set(filter, pickSubs);
   return filter;
 }
 function createFilterScope() {
@@ -211,6 +244,35 @@ function createFilterScope() {
   const notify = () => {
     for (const cb of Array.from(subs)) cb(scope);
   };
+  const groups = /* @__PURE__ */ new Map();
+  const join = (f) => {
+    const name = f.group;
+    if (!name) return;
+    const members = groups.get(name) ?? /* @__PURE__ */ new Set();
+    const first = members.values().next().value;
+    if (first && first.columns.join("
") !== f.columns.join("
")) {
+      try {
+        console.warn(`[chart-host] filter "${f.label}" is keyed by ${f.columns.join(", ")} but its group "${name}" by ${first.columns.join(", ")}, so it stays out of the group: give one pick's filters the same key columns.`);
+      } catch {
+      }
+      return;
+    }
+    if (f.active && [...members].some((m) => m.active)) f.clear("page");
+    members.add(f);
+    groups.set(name, members);
+    peersOf.set(f, members);
+    firePick(f);
+  };
+  const leave = (f) => {
+    const members = f.group ? groups.get(f.group) : void 0;
+    if (!members?.has(f)) return;
+    members.delete(f);
+    peersOf.delete(f);
+    if (!members.size) groups.delete(f.group);
+    firePick(f);
+    const rest = members.values().next().value;
+    if (rest) firePick(rest);
+  };
   const scope = {
     get filters() {
       return list.slice();
@@ -227,6 +289,7 @@ function createFilterScope() {
       if (!offs.has(f)) {
         list.push(f);
         offs.set(f, f.onChange(() => notify()));
+        join(f);
         notify();
       }
       return () => {
@@ -236,6 +299,7 @@ function createFilterScope() {
         offs.delete(f);
         const i = list.indexOf(f);
         if (i >= 0) list.splice(i, 1);
+        leave(f);
         notify();
       };
     },
@@ -278,10 +342,15 @@ function createFilterScope() {
     },
     restore(view) {
       if (!view || view.v !== 1) return;
+      const restored = /* @__PURE__ */ new Set();
       for (const f of list) {
         const keys = view.filters?.[f.key];
-        if (keys && keys.length) f.set(keys, "page");
-        else f.clear("page");
+        const g = f.group && peersOf.get(f) ? f.group : null;
+        if (g && restored.has(g)) continue;
+        if (keys && keys.length) {
+          f.set(keys, "page");
+          if (g) restored.add(g);
+        } else f.clear("page");
       }
       for (const [k, c] of ctl) {
         const values = view.controls?.[k];
@@ -291,19 +360,47 @@ function createFilterScope() {
   };
   return scope;
 }
+function scopeFilterOf(src) {
+  if (!src || typeof src !== "object") return null;
+  if (Array.isArray(src.keys)) return src;
+  const f = src.filter;
+  return f && typeof f === "object" ? f : null;
+}
+var warnedTakes = /* @__PURE__ */ new Set();
 function filterScopeOf(filters) {
   const list = Array.isArray(filters) ? filters : filters ? [filters] : [];
-  const active = list.filter((f) => f && f.active);
   const values = [];
-  for (const f of active) {
+  const fields = [];
+  for (const src of list) {
+    const f = scopeFilterOf(src);
+    if (!f || !f.active) continue;
+    const entry = src === f ? null : src;
+    const takes = entry?.takes;
+    for (const c of takes ?? []) {
+      if (f.columns.includes(c) || warnedTakes.has(`${f.id}
${c}`)) continue;
+      warnedTakes.add(`${f.id}
${c}`);
+      try {
+        console.warn(`[chart-host] scopedBy: filter "${f.label}" isn't keyed by ${c} (its key: ${f.columns.join(", ")}), so its scope line can't take it - name the filter's own key columns in takes.`);
+      } catch {
+      }
+    }
+    const part = takes ? f.columns.filter((c) => takes.includes(c)) : f.columns;
+    const whole = part.length === f.columns.length;
+    if (!whole) {
+      const at = part.map((c) => f.columns.indexOf(c));
+      if (!at.length || f.keys.some((k) => at.every((i) => isAnyValue(k[i])))) continue;
+    }
+    let said = false;
     for (const k of f.keys) {
-      const t = f.textOf(k).trim();
+      const t = (whole ? f.textOf(k) : f.textOf(k, void 0, part)).trim();
+      if (t) said = true;
       if (t && !values.includes(t)) values.push(t);
     }
+    if (!whole && !said) continue;
+    const label = entry?.label || (whole || f.label !== f.columns.join(" / ") ? f.label : part.join(" / "));
+    if (label && !fields.includes(label)) fields.push(label);
   }
   if (!values.length) return void 0;
-  const fields = [];
-  for (const f of active) if (f.label && !fields.includes(f.label)) fields.push(f.label);
   return { field: fields.join(", "), values };
 }
 var LINKED_HOVER_CLASS = "bic-linked-hover";
@@ -339,18 +436,21 @@ var sortedEq = (a, b) => {
   return x.every((v, i) => v === y[i]);
 };
 function bindFilter(host, filter, opts) {
+  const pickOf = () => filter.pick ?? filter;
   const wanted = () => {
-    if (!filter.active) return [];
+    const src = pickOf();
+    if (!src.active) return [];
     const out = [];
     const n = opts.rowCount();
     for (let i = 0; i < n; i++) {
       const r = opts.rowAt(i);
-      if (r && filter.has(r)) out.push(i);
+      if (r && src.has(r)) out.push(i);
     }
     return out;
   };
   const hiddenKeys = () => {
-    if (!filter.active) return [];
+    const src = pickOf();
+    if (!src.active) return [];
     const carried = /* @__PURE__ */ new Set();
     const n = opts.rowCount();
     for (let i = 0; i < n; i++) {
@@ -364,7 +464,7 @@ function bindFilter(host, filter, opts) {
       }
       return false;
     };
-    return filter.keys.filter((k) => k.some(isAnyValue) ? !anyRowMatches(k) : !carried.has(keyString(k)));
+    return src.keys.filter((k) => k.some(isAnyValue) ? !anyRowMatches(k) : !carried.has(keyString(k)));
   };
   const paint = () => {
     const want = wanted();
@@ -379,7 +479,8 @@ function bindFilter(host, filter, opts) {
     if (source === "host") return;
     const keep = meta?.keepHidden ? hiddenKeys() : [];
     if (!idxs.length && !keep.length) {
-      if (filter.active) filter.clear("clear");
+      const src = pickOf();
+      if (src.active) src.clear("clear");
       return;
     }
     const rows = idxs.map((i) => opts.rowAt(i)).filter((r) => !!r);
@@ -389,8 +490,20 @@ function bindFilter(host, filter, opts) {
       filter.set([label], "click");
       return;
     }
+    const group = meta?.fromMark && !keep.length ? sharedKey(rows) : null;
+    if (group) {
+      filter.set([group], "click");
+      return;
+    }
     filter.selectRows(rows, "click", keep);
   });
+  const sharedKey = (rows) => {
+    const key = filter.columns.map((c) => {
+      const v = rows[0][c];
+      return rows.every((r) => keyString([r[c]]) === keyString([v])) ? v : ANY_VALUE;
+    });
+    return key.some(isAnyValue) && !key.every(isAnyValue) ? key : null;
+  };
   const labelKey = (rows) => {
     const n = opts.rowCount();
     const key = filter.columns.map((c) => {
@@ -404,7 +517,7 @@ function bindFilter(host, filter, opts) {
     });
     return key.some(isAnyValue) && !key.every(isAnyValue) ? key : null;
   };
-  const offFilter = filter.onChange(() => paint());
+  const offFilter = filter.onPick ? filter.onPick(() => paint()) : filter.onChange(() => paint());
   const el = opts.container ?? null;
   let offHoverDom = () => {
   };
@@ -486,6 +599,7 @@ export {
   isAnyValue,
   createFilter,
   createFilterScope,
+  scopeFilterOf,
   filterScopeOf,
   LINKED_HOVER_CLASS,
   payloadRowReader,