@bicharts/chart-host 0.6.58 → 0.6.60

package/dist/{chunk-ZEZXNAFL.mjs → chunk-XIAL6EEC.mjs}

@@ -1,6 +1,26 @@
 /*! @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. */
 
 // src/filterScope.ts
+function viewToken(view) {
+  const bytes = new TextEncoder().encode(JSON.stringify(view));
+  let bin = "";
+  bytes.forEach((b) => {
+    bin += String.fromCharCode(b);
+  });
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function viewFromToken(token) {
+  if (!token) return null;
+  try {
+    const b64 = token.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((token.length + 3) % 4);
+    const bin = atob(b64);
+    const bytes = Uint8Array.from(bin, (ch) => ch.charCodeAt(0));
+    const v = JSON.parse(new TextDecoder().decode(bytes));
+    return v && v.v === 1 ? v : null;
+  } catch {
+    return null;
+  }
+}
 function keyString(values) {
   return JSON.stringify(values.map((v) => v instanceof Date ? `__date:${v.getTime()}` : v === void 0 ? null : v));
 }
@@ -28,6 +48,8 @@ function createFilter(columns, opts = {}) {
   let reason = null;
   let version = 0;
   const subs = /* @__PURE__ */ new Set();
+  let hovered = null;
+  const hoverSubs = /* @__PURE__ */ new Set();
   const kept = /* @__PURE__ */ new WeakMap();
   const commit = (nextKeys, nextRows, why) => {
     const nextSet = new Set(nextKeys.map(keyString));
@@ -65,6 +87,23 @@ function createFilter(columns, opts = {}) {
   let warnedKeep = false;
   const filter = {
     id: opts.id ?? `f${++nextId}`,
+    key: opts.key ?? cols.join("+"),
+    hoverEnabled: !!opts.hover,
+    get hovered() {
+      return hovered;
+    },
+    setHover(k) {
+      const next = k && k.length ? k.slice(0, cols.length) : null;
+      if ((next ? keyString(next) : null) === (hovered ? keyString(hovered) : null)) return;
+      hovered = next;
+      for (const cb of Array.from(hoverSubs)) cb(hovered);
+    },
+    onHover(cb) {
+      hoverSubs.add(cb);
+      return () => {
+        hoverSubs.delete(cb);
+      };
+    },
     columns: cols,
     label: opts.label ?? cols.join(" / "),
     get active() {
@@ -148,6 +187,8 @@ function createFilter(columns, opts = {}) {
 function createFilterScope() {
   const list = [];
   const offs = /* @__PURE__ */ new Map();
+  const ctl = /* @__PURE__ */ new Map();
+  const ctlOffs = /* @__PURE__ */ new Map();
   const subs = /* @__PURE__ */ new Set();
   const notify = () => {
     for (const cb of Array.from(subs)) cb(scope);
@@ -188,10 +229,60 @@ function createFilterScope() {
       return () => {
         subs.delete(cb);
       };
+    },
+    get controls() {
+      return ctl;
+    },
+    addControls(key, c) {
+      let k = key, n = 1;
+      while (ctl.has(k) && ctl.get(k) !== c) k = `${key}-${++n}`;
+      if (!ctl.has(k)) {
+        ctl.set(k, c);
+        ctlOffs.set(k, c.onChange(() => notify()));
+        notify();
+      }
+      return () => {
+        if (ctl.get(k) !== c) return;
+        ctlOffs.get(k)?.();
+        ctlOffs.delete(k);
+        ctl.delete(k);
+        notify();
+      };
+    },
+    save() {
+      const view = { v: 1 };
+      for (const f of list) if (f.active) (view.filters ??= {})[f.key] = f.keys.map((k) => k.slice());
+      for (const [k, c] of ctl) {
+        const values = c.values;
+        if (Object.keys(values).length) (view.controls ??= {})[k] = { ...values };
+      }
+      return view;
+    },
+    restore(view) {
+      if (!view || view.v !== 1) return;
+      for (const f of list) {
+        const keys = view.filters?.[f.key];
+        if (keys && keys.length) f.set(keys, "page");
+        else f.clear("page");
+      }
+      for (const [k, c] of ctl) {
+        const values = view.controls?.[k];
+        if (values) c.set(values);
+      }
     }
   };
   return scope;
 }
+var LINKED_HOVER_CLASS = "bic-linked-hover";
+var hoverStyled = false;
+function ensureHoverStyle(doc) {
+  if (hoverStyled || !doc?.head) return;
+  hoverStyled = true;
+  const s = doc.createElement("style");
+  s.setAttribute("data-bic", "linked-hover");
+  s.textContent = `.${LINKED_HOVER_CLASS}{filter:drop-shadow(0 0 2px var(--bic-linked-hover,rgba(0,0,0,.65))) drop-shadow(0 0 1px var(--bic-linked-hover,rgba(0,0,0,.65)))}`;
+  doc.head.appendChild(s);
+}
 function payloadRowReader(getPayload) {
   return {
     rowAt(i) {
@@ -258,6 +349,41 @@ function bindFilter(host, filter, opts) {
     if (o && o.keys !== ownerKeys()) owners.delete(filter);
     paint();
   });
+  const el = opts.container ?? null;
+  let offHoverDom = () => {
+  };
+  let offHover = () => {
+  };
+  if (filter.hoverEnabled && el) {
+    ensureHoverStyle(el.ownerDocument);
+    const markRow = (t) => {
+      const m = t?.closest?.(".d3-mark[data-row-idx]");
+      const v = m ? parseInt((m.getAttribute("data-row-idx") ?? "").split(",")[0], 10) : NaN;
+      return Number.isFinite(v) ? v : null;
+    };
+    const over = (e) => {
+      const i = markRow(e.target);
+      const r = i === null ? null : opts.rowAt(i);
+      if (r) filter.setHover(keyOfRow(r, filter.columns));
+    };
+    const leave = () => filter.setHover(null);
+    el.addEventListener("mouseover", over);
+    el.addEventListener("mouseleave", leave);
+    offHoverDom = () => {
+      el.removeEventListener("mouseover", over);
+      el.removeEventListener("mouseleave", leave);
+    };
+    const paintHover = (k) => {
+      const want = k ? keyString(k) : null;
+      el.querySelectorAll(".d3-mark[data-row-idx]").forEach((m) => {
+        const idx = parseInt((m.getAttribute("data-row-idx") ?? "").split(",")[0], 10);
+        const r = Number.isFinite(idx) ? opts.rowAt(idx) : null;
+        const on = !!want && !!r && keyString(keyOfRow(r, filter.columns)) === want;
+        m.classList.toggle(LINKED_HOVER_CLASS, on);
+      });
+    };
+    offHover = filter.onHover(paintHover);
+  }
   return {
     reconcile() {
       if (filter.active && opts.rowCount() > 0 && isMine()) {
@@ -279,6 +405,8 @@ function bindFilter(host, filter, opts) {
     detach() {
       offHost();
       offFilter();
+      offHoverDom();
+      offHover();
       const o = owners.get(filter);
       if (o && o.token === token) owners.set(filter, { ...o, orphan: true });
     }
@@ -453,8 +581,11 @@ function notesFor(notes, key, opts) {
 }
 
 export {
+  viewToken,
+  viewFromToken,
   createFilter,
   createFilterScope,
+  LINKED_HOVER_CLASS,
   payloadRowReader,
   bindFilter,
   fromVegaInteraction,

package/dist/page.mjs

@@ -1,5 +1,6 @@
 /*! @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 {
+  LINKED_HOVER_CLASS,
   attachControls,
   badgeKey,
   bindFilter,
@@ -10,10 +11,13 @@ import {
   noteBadges,
   notesFor,
   payloadRowReader,
-  readControls
-} from "./chunk-ZEZXNAFL.mjs";
+  readControls,
+  viewFromToken,
+  viewToken
+} from "./chunk-XIAL6EEC.mjs";
 import "./chunk-GHODWOAL.mjs";
 export {
+  LINKED_HOVER_CLASS,
   attachControls,
   badgeKey,
   bindFilter,
@@ -24,5 +28,7 @@ export {
   noteBadges,
   notesFor,
   payloadRowReader,
-  readControls
+  readControls,
+  viewFromToken,
+  viewToken
 };

package/dist/react.mjs

@@ -1,5 +1,6 @@
 /*! @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 {
+  LINKED_HOVER_CLASS,
   attachControls,
   badgeKey,
   bindFilter,
@@ -9,8 +10,10 @@ import {
   fromVegaInteraction,
   noteBadges,
   notesFor,
-  payloadRowReader
-} from "./chunk-ZEZXNAFL.mjs";
+  payloadRowReader,
+  viewFromToken,
+  viewToken
+} from "./chunk-XIAL6EEC.mjs";
 import {
   assembleD3,
   createChartGroup,
@@ -179,6 +182,7 @@ function BicChart(props) {
     if (!host || !selects) return;
     const payloadRows = payloadRowReader(() => dataRef.current);
     const b = bindFilter(host, selects, {
+      container: ref.current,
       rowAt(i) {
         const g = groupRef.current, map = rowMapRef.current;
         if (g && map) {
@@ -261,13 +265,94 @@ function useBicFilter(columns, opts) {
   useSyncExternalStore((cb) => f.onChange(() => cb()), () => f.version, () => f.version);
   return f;
 }
-function useBicControls(initial) {
+function useBicControls(initial, opts) {
+  const scope = useContext(PageCtx);
   const ref = useRef(null);
   if (!ref.current) ref.current = createControls(initial);
   const c = ref.current;
+  useEffect(() => scope.addControls(opts?.id ?? "controls", c), [scope, c, opts?.id]);
   useSyncExternalStore((cb) => c.onChange(() => cb()), () => c.version, () => c.version);
   return c;
 }
+function useBicView() {
+  const scope = useContext(PageCtx);
+  return useMemo(() => ({
+    save: () => scope.save(),
+    restore: (v) => scope.restore(v),
+    token: () => viewToken(scope.save()),
+    restoreToken: (t) => scope.restore(viewFromToken(t))
+  }), [scope]);
+}
+function useBicUrlState(param = "view") {
+  const scope = useContext(PageCtx);
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const url = new URL(window.location.href);
+    scope.restore(viewFromToken(url.searchParams.get(param)));
+    return scope.onChange(() => {
+      const u = new URL(window.location.href);
+      const view = scope.save();
+      const empty = !view.filters && !view.controls;
+      if (empty) u.searchParams.delete(param);
+      else u.searchParams.set(param, viewToken(view));
+      if (u.href !== window.location.href) window.history.replaceState(window.history.state, "", u.href);
+    });
+  }, [scope, param]);
+}
+function BicDevtools({ max = 20 }) {
+  const scope = useContext(PageCtx);
+  const [, tick] = useState(0);
+  const log = useRef([]);
+  useEffect(() => scope.onChange(() => {
+    const at = (/* @__PURE__ */ new Date()).toLocaleTimeString();
+    const changed = scope.filters.map((f) => `${f.label}: ${f.active ? f.text : "(none)"}${f.reason ? ` [${f.reason}]` : ""}`);
+    log.current = [`${at}  ${changed.join(" | ")}`, ...log.current].slice(0, max);
+    tick((t) => t + 1);
+  }), [scope, max]);
+  const box = {
+    position: "fixed",
+    right: 8,
+    bottom: 8,
+    zIndex: 2147483e3,
+    maxWidth: 420,
+    maxHeight: "50vh",
+    overflow: "auto",
+    font: "12px/1.4 ui-monospace, monospace",
+    background: "Canvas",
+    color: "CanvasText",
+    border: "1px solid GrayText",
+    borderRadius: 6,
+    padding: 6,
+    opacity: 0.95
+  };
+  return /* @__PURE__ */ jsxs("details", { className: "bic-devtools", style: box, children: [
+    /* @__PURE__ */ jsxs("summary", { style: { cursor: "pointer" }, children: [
+      "chart-host: ",
+      scope.active.length,
+      " filter(s) active"
+    ] }),
+    scope.filters.map((f) => /* @__PURE__ */ jsxs("div", { children: [
+      /* @__PURE__ */ jsx("b", { children: f.label }),
+      " [",
+      f.key,
+      "] ",
+      f.active ? JSON.stringify(f.keys) : "(none)",
+      " ",
+      f.text && `"${f.text}"`,
+      f.reason ? ` - last: ${f.reason}` : "",
+      " v",
+      f.version
+    ] }, f.id)),
+    [...scope.controls].map(([k, c]) => /* @__PURE__ */ jsxs("div", { children: [
+      /* @__PURE__ */ jsx("b", { children: "controls" }),
+      " [",
+      k,
+      "] ",
+      c.summary || JSON.stringify(c.values)
+    ] }, k)),
+    /* @__PURE__ */ jsx("div", { style: { marginTop: 4, opacity: 0.8 }, children: log.current.map((l, i) => /* @__PURE__ */ jsx("div", { children: l }, i)) })
+  ] });
+}
 function useBicFilters() {
   const scope = useContext(PageCtx);
   const [, tick] = useState(0);
@@ -372,8 +457,10 @@ function useMeasuredSize(ref) {
 export {
   BicChart,
   BicChartGroup,
+  BicDevtools,
   BicFilterChips,
   BicPage,
+  LINKED_HOVER_CLASS,
   assembleD3,
   badgeKey,
   createControls,
@@ -386,5 +473,9 @@ export {
   useBicFilter,
   useBicFilters,
   useBicSelection,
-  useMeasuredSize
+  useBicUrlState,
+  useBicView,
+  useMeasuredSize,
+  viewFromToken,
+  viewToken
 };

package/dist/types/filterScope.d.ts

@@ -1,4 +1,5 @@
 import type { ChartHost } from "./host";
+import type { Controls } from "./controls";
 /** Why a filter changed. */
 export type FilterChangeReason = "click" | "clear" | "page" | "data";
 /** One selected key: a value per key column, in the filter's column order. */
@@ -14,9 +15,26 @@ export interface FilterOptions {
     display?: string | readonly string[];
     /** A stable id for this filter within its scope. Generated when absent. */
     id?: string;
+    /** Its name in a saved view (scope.save / a link). Defaults to the key columns joined with "+". */
+    key?: string;
+    /**
+     * LINKED HOVER: hovering a mark on a chart bound to this filter lights the marks with the same key on every other
+     * chart bound to it (a glow, never a filter). Off by default.
+     */
+    hover?: boolean;
 }
 export interface Filter {
     readonly id: string;
+    /** Its name in a saved view. */
+    readonly key: string;
+    /** Whether linked hover is on (FilterOptions.hover). */
+    readonly hoverEnabled: boolean;
+    /** The key being hovered on a bound chart now, or null. */
+    readonly hovered: FilterKey | null;
+    /** Set or clear the hovered key (bound charts do this; a page may too). */
+    setHover(key: FilterKey | null): void;
+    /** Subscribe to hover changes. Returns the unsubscribe. */
+    onHover(cb: (key: FilterKey | null) => void): () => void;
     /** The key column(s). */
     readonly columns: readonly string[];
     readonly label: string;
@@ -74,9 +92,27 @@ export interface FilterScope {
     add(filter: Filter): () => void;
     /** Clear every filter. */
     clearAll(reason?: FilterChangeReason): void;
-    /** Subscribe to any change of any filter, and to filters being added or removed. */
+    /** Subscribe to any change of any filter or controls, and to either being added or removed. */
     onChange(cb: (scope: FilterScope) => void): () => void;
+    /** A chart's controls, to be saved and restored with the page's view. Returns the remove. */
+    addControls(key: string, controls: Controls): () => void;
+    /** The registered controls, by key. */
+    readonly controls: ReadonlyMap<string, Controls>;
+    /** The page's view now: every filter's keys and every registered controls' values - JSON-safe. */
+    save(): PageView;
+    /** Put a saved view back: each filter set (or cleared when the view doesn't name it), each controls set. */
+    restore(view: PageView | null | undefined): void;
+}
+/** A saved page view: what save() returns and restore() takes. */
+export interface PageView {
+    v: 1;
+    filters?: Record<string, unknown[][]>;
+    controls?: Record<string, Record<string, unknown>>;
 }
+/** A view as a URL-safe token (base64url of its JSON), for a link or a bookmark. */
+export declare function viewToken(view: PageView): string;
+/** A token from viewToken back to a view; null when it isn't one. */
+export declare function viewFromToken(token: string | null | undefined): PageView | null;
 /** Make a filter keyed by `columns` (one name, or several for a compound key such as a route). */
 export declare function createFilter(columns: string | readonly string[], opts?: FilterOptions): Filter;
 /** Make a page's filter scope. */
@@ -98,7 +134,11 @@ export interface BindFilterOptions {
     rowAt(i: number): Record<string, unknown> | null;
     /** How many rows the chart is drawing now. */
     rowCount(): number;
+    /** The chart's container, for linked hover (FilterOptions.hover). Without it the chart takes no part in hover. */
+    container?: HTMLElement | null;
 }
+/** The class a mark wears while its key is hovered on another chart bound to the same filter. */
+export declare const LINKED_HOVER_CLASS = "bic-linked-hover";
 /** The source row behind each payload row, from a payload of { columns, rows: unknown[][] }. */
 export declare function payloadRowReader(getPayload: () => {
     columns: readonly {

package/dist/types/index.d.ts

@@ -12,7 +12,7 @@ export { ANNOTATION_CLASS, ANNOTATION_LAYER_CLASS, type MarkAnnotation, type Ann
 export type { MarkNoteLike, NoteBadgeOptions } from "./markNotes";
 export type { Controls, ControlInfo, ControlsAttachment } from "./controls";
 export { createChartGroup, toSourceRows, syncMemberSelection, type ChartGroup, type ChartGroupMember, type ChartGroupSelection, type ChartGroupChange, type ChartGroupMemberOptions, type ChartGroupSourceOptions, type ChartGroupPayload } from "./group";
-export type { Filter, FilterScope, FilterOptions, FilterKey, FilterChangeReason, FilterBinding, BindFilterOptions, VegaInteractionEvent } from "./filterScope";
+export type { Filter, FilterScope, FilterOptions, FilterKey, FilterChangeReason, FilterBinding, BindFilterOptions, VegaInteractionEvent, PageView } from "./filterScope";
 export { createMarkResolver, isInsideControl, rowIdxsFromMark, nextSelection, collectD3GlyphCenters, clearSelectionGlyphs, paintSelectionGlyphs, SELECTION_GLYPH_CLASS, type MarkResolver, type MarkResolverEnv, type GlyphCenter, type SelectionGlyphStyle, type SelectionModifiers, } from "./selection";
 export { planTrivialChart, compileTrivialSource, type TrivialPlan, type TrivialShapeKind } from "./trivial";
 export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngDataUrl, tableHostOf, chartSvgOf, htmlToSvgDataUrl, htmlNaturalSize, type SnapshotOptions } from "./snapshot";

package/dist/types/page.d.ts

@@ -1,3 +1,4 @@
+export { viewToken, viewFromToken, LINKED_HOVER_CLASS, type PageView } from "./filterScope";
 export { createFilter, createFilterScope, bindFilter, payloadRowReader, fromVegaInteraction, type Filter, type FilterScope, type FilterOptions, type FilterKey, type FilterChangeReason, type FilterBinding, type BindFilterOptions, type VegaInteractionEvent } from "./filterScope";
 export { createControls, attachControls, readControls, type Controls, type ControlInfo, type ControlsAttachment } from "./controls";
 export { noteBadges, badgeKey, notesFor, type MarkNoteLike, type NoteBadgeOptions } from "./markNotes";

package/dist/types/react.d.ts

@@ -2,11 +2,12 @@ import type { ReactNode, RefObject } from "react";
 import { type ChartHostConfig } from "./host";
 import type { ResolveOptionsInput } from "./defaults";
 import type { GeoPointBinding } from "./payload";
-import { type Filter, type FilterOptions } from "./filterScope";
+import { type PageView, type Filter, type FilterOptions } from "./filterScope";
 export { assembleD3 } from "./host";
 import { type Controls } from "./controls";
 export { createControls, type Controls, type ControlInfo } from "./controls";
 export { noteBadges, badgeKey, notesFor, type MarkNoteLike, type NoteBadgeOptions } from "./markNotes";
+export { viewToken, viewFromToken, LINKED_HOVER_CLASS, type PageView } from "./filterScope";
 export { createFilter, createFilterScope, fromVegaInteraction, type Filter, type FilterOptions, type FilterScope, type FilterChangeReason } from "./filterScope";
 export interface BicChartProps {
     /** Generated render() source (an ES module's `code` export, or the raw string). */
@@ -150,7 +151,33 @@ export declare function useBicFilter(columns: string | readonly string[], opts?:
  * and `summary`, `set(saved)` to apply a saved scenario, `reset()` for the defaults. Re-renders the
  * component on every change. `initial` seeds the values the chart first draws with.
  */
-export declare function useBicControls(initial?: Readonly<Record<string, unknown>>): Controls;
+export declare function useBicControls(initial?: Readonly<Record<string, unknown>>, opts?: {
+    id?: string;
+}): Controls;
+/**
+ * THE PAGE'S VIEW, SAVED AND PUT BACK: every page filter's keys and every chart's controls (useBicControls). `save()`
+ * returns a JSON-safe view to store (a saved view, a user preference); `restore(view)` puts one back; `token()` /
+ * `restoreToken(t)` do the same as a URL-safe string for a link.
+ */
+export declare function useBicView(): {
+    save: () => PageView;
+    restore: (v: PageView | null | undefined) => void;
+    token: () => string;
+    restoreToken: (t: string | null | undefined) => void;
+};
+/**
+ * THE VIEW IN THE ADDRESS BAR (opt-in): restores the page's filters and controls from `?<param>=` on mount, then keeps
+ * the parameter current as they change (history.replaceState - no navigation, no new history entries). A copied link
+ * opens the page as it was. Call once, in the page component, after its useBicFilter / useBicControls calls.
+ */
+export declare function useBicUrlState(param?: string): void;
+/**
+ * A DEVELOPER'S VIEW OF THE PAGE'S STATE: every filter (its keys, its text, the last change and why), every chart's
+ * controls, and the last changes in order. Collapsed in a corner; render it only in development.
+ */
+export declare function BicDevtools({ max }: {
+    max?: number;
+}): import("react").JSX.Element;
 /** Every filter on the page (or the enclosing <BicPage>), and its clear-all - for a page's own chip bar or count. */
 export declare function useBicFilters(): {
     filters: readonly Filter[];

package/package.json

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