@bicharts/chart-host 0.6.50 → 0.6.52

package/dist/{chunk-P4FOCNAX.mjs → chunk-TOKJTZNS.mjs}

@@ -3518,10 +3518,10 @@ function paintRoot(el, container) {
   }
   return root;
 }
-function drawnBeneath(shape, text, textRoot) {
+function drawnBeneath(shape, text2, textRoot) {
   if (!shape.root || shape.root !== textRoot) return true;
   if (typeof shape.el.compareDocumentPosition !== "function") return true;
-  return (shape.el.compareDocumentPosition(text) & DOC_POSITION_FOLLOWING) !== 0;
+  return (shape.el.compareDocumentPosition(text2) & DOC_POSITION_FOLLOWING) !== 0;
 }
 function sampleBackgrounds(shapes, pts, pageRGB, effAlpha) {
   if (pts.length === 0 || shapes.length === 0) return null;
@@ -3797,13 +3797,13 @@ function applyLabelContrast(container, opts = {}) {
 }
 
 // src/invalidSentinel.ts
-function isInvalidSentinelError(text) {
-  if (!text) return false;
-  return /\bINVALID\s*:/.test(text);
+function isInvalidSentinelError(text2) {
+  if (!text2) return false;
+  return /\bINVALID\s*:/.test(text2);
 }
-function invalidSentinelReason(text, max = 240) {
-  if (!text) return "";
-  const m4 = /\bINVALID\s*:\s*([^\r\n]*)/.exec(text);
+function invalidSentinelReason(text2, max = 240) {
+  if (!text2) return "";
+  const m4 = /\bINVALID\s*:\s*([^\r\n]*)/.exec(text2);
   if (!m4) return "";
   const reason = m4[1].trim();
   const cap = Math.max(0, Math.floor(max));
@@ -3811,6 +3811,138 @@ function invalidSentinelReason(text, max = 240) {
   return cap <= 3 ? reason.slice(0, cap) : reason.slice(0, cap - 3).trimEnd() + "...";
 }
 
+// src/annotations.ts
+var ANNOTATION_LAYER_CLASS = "bic-annotations";
+var ANNOTATION_CLASS = "bic-annotation";
+var text = (v) => v == null ? "" : String(v).trim();
+var parseIdxs = (s2) => (s2 || "").split(",").map((x3) => parseInt(x3, 10)).filter((n) => Number.isFinite(n));
+function createAnnotationLayer(container, onClick) {
+  let list = [];
+  let report = { shown: 0, notShown: 0 };
+  let last = null;
+  const doc = container.ownerDocument;
+  const win = doc.defaultView;
+  let observer = null;
+  let queued = false;
+  const redrawSoon = () => {
+    if (queued || !last) return;
+    queued = true;
+    const run = () => {
+      queued = false;
+      if (last) paint(last.data, last.theme);
+    };
+    if (win?.requestAnimationFrame) win.requestAnimationFrame(run);
+    else setTimeout(run, 16);
+  };
+  const watch = (on) => {
+    const MO = win?.MutationObserver;
+    if (on && !observer && MO) {
+      observer = new MO((records) => {
+        if (records.some((r2) => !r2.target.closest?.(`.${ANNOTATION_LAYER_CLASS}`))) redrawSoon();
+      });
+      observer.observe(container, { subtree: true, attributes: true, attributeFilter: ["transform", "d", "cx", "cy", "x", "y", "points"] });
+    } else if (!on && observer) {
+      observer.disconnect();
+      observer = null;
+    }
+  };
+  function paint(data, theme) {
+    let layer = container.querySelector(`:scope > .${ANNOTATION_LAYER_CLASS}`);
+    if (!list.length) {
+      layer?.remove();
+      report = { shown: 0, notShown: 0 };
+      return;
+    }
+    if (!layer) {
+      layer = doc.createElement("div");
+      layer.className = ANNOTATION_LAYER_CLASS;
+      layer.setAttribute("aria-hidden", "false");
+      Object.assign(layer.style, { position: "absolute", left: "0", top: "0", width: "0", height: "0", overflow: "visible", zIndex: "2" });
+      if (win?.getComputedStyle(container).position === "static") container.style.position = "relative";
+      container.appendChild(layer);
+    }
+    layer.textContent = "";
+    const names = (data.columns || []).map((c2) => typeof c2 === "string" ? c2 : c2?.name);
+    const marks = Array.from(container.querySelectorAll(`.${MARK_CLASS}[${ROW_IDX_ATTR}]`)).filter((m4) => !m4.closest(`.${ANNOTATION_LAYER_CLASS}`));
+    const marksByRow = /* @__PURE__ */ new Map();
+    for (const m4 of marks) for (const r2 of parseIdxs(m4.getAttribute(ROW_IDX_ATTR))) {
+      const at = marksByRow.get(r2);
+      if (at) at.push(m4);
+      else marksByRow.set(r2, [m4]);
+    }
+    const origin = container.getBoundingClientRect();
+    let shown = 0;
+    for (const a3 of list) {
+      const pairs = (a3.where ? Object.entries(a3.where) : a3.column != null ? [[a3.column, a3.value]] : []).map(([c2, v]) => [names.indexOf(c2), text(v)]);
+      const want = pairs.map((p4) => p4[1]).join(" / ");
+      const hits = /* @__PURE__ */ new Set();
+      if (pairs.length && pairs.every((p4) => p4[0] >= 0)) (data.rows || []).forEach((row, r2) => {
+        if (pairs.every(([ci, v]) => text(row?.[ci]) === v)) for (const m4 of marksByRow.get(r2) ?? []) hits.add(m4);
+      });
+      if (!hits.size) continue;
+      shown++;
+      let best = null;
+      for (const m4 of hits) {
+        const b4 = m4.getBoundingClientRect();
+        if (!best || b4.width * b4.height > best.width * best.height) best = b4;
+      }
+      const badge = doc.createElement("div");
+      badge.className = ANNOTATION_CLASS;
+      badge.textContent = a3.label ?? "\u2022";
+      if (a3.title) badge.setAttribute("title", a3.title);
+      badge.setAttribute("role", "button");
+      badge.setAttribute("aria-label", a3.title ? `Note: ${a3.title}` : `Note on ${want}`);
+      const laidOut = !!best && best.width > 0 && best.height > 0;
+      Object.assign(badge.style, {
+        position: "absolute",
+        left: `${Math.round(laidOut ? best.left - origin.left + best.width / 2 : 0)}px`,
+        top: `${Math.round(laidOut ? best.top - origin.top + best.height / 2 : 0)}px`,
+        transform: "translate(-50%, -50%)",
+        minWidth: "16px",
+        height: "16px",
+        padding: "0 4px",
+        boxSizing: "border-box",
+        borderRadius: "8px",
+        font: "600 10px/16px system-ui, sans-serif",
+        textAlign: "center",
+        color: theme.bg || "#ffffff",
+        background: theme.accent || theme.fg || "#0f6cbd",
+        boxShadow: `0 0 0 1.5px ${theme.bg || "#ffffff"}`,
+        cursor: onClick ? "pointer" : "default",
+        // Never pointer-events (a host failsafe turns it back on); visibility hides a badge whose mark
+        // has no box yet.
+        visibility: laidOut ? "visible" : "hidden"
+      });
+      badge.addEventListener("click", (e) => {
+        e.stopPropagation();
+        onClick?.(a3);
+      });
+      layer.appendChild(badge);
+    }
+    report = { shown, notShown: list.length - shown };
+  }
+  return {
+    set(next) {
+      list = Array.isArray(next) ? next.slice() : [];
+      watch(list.length > 0);
+      if (last) paint(last.data, last.theme);
+    },
+    draw(data, theme) {
+      last = { data, theme };
+      paint(data, theme);
+    },
+    get report() {
+      return report;
+    },
+    destroy() {
+      watch(false);
+      list = [];
+      last = null;
+      container.querySelector(`:scope > .${ANNOTATION_LAYER_CLASS}`)?.remove();
+    }
+  };
+}
+
 // src/host.ts
 function sessionViewStateProvider(container) {
   const holder = container;
@@ -3971,6 +4103,16 @@ function createChartHost(container, config) {
   let warnedGeo = false;
   let warnedBlank = false;
   let renderSeq = 0;
+  const annotationLayer = createAnnotationLayer(container, (a3) => config.onAnnotationClick?.(a3));
+  const drawAnnotations = () => annotationLayer.draw(
+    { columns: data.columns, rows: data.rows },
+    {
+      fg: resolved.themeFg,
+      accent: resolved.themeAccent,
+      bg: resolved.backgroundColor ?? resolved.themeBg
+    }
+  );
+  annotationLayer.set(config.annotations ?? []);
   let renderedPromise = Promise.resolve();
   const settle = (p4) => {
     renderedPromise = p4;
@@ -4192,6 +4334,10 @@ function createChartHost(container, config) {
       } catch {
       }
     }
+    try {
+      drawAnnotations();
+    } catch {
+    }
   };
   const renderFailure = (err) => {
     const message = String(err?.message ?? err ?? "");
@@ -4290,6 +4436,16 @@ function createChartHost(container, config) {
     get options() {
       return resolved;
     },
+    setAnnotations(list) {
+      annotationLayer.set(list);
+      if (!destroyed) try {
+        drawAnnotations();
+      } catch {
+      }
+    },
+    get annotationReport() {
+      return annotationLayer.report;
+    },
     // A GETTER, not a captured value: `rendered` names the LATEST render, so a host that
     // read it once would otherwise hold the promise of a draw long since replaced.
     get rendered() {
@@ -4328,6 +4484,7 @@ function createChartHost(container, config) {
       container.removeEventListener(XFILTER_REFRESH_EVENT, onXf);
       container.removeEventListener("click", onClick);
       subs.clear();
+      annotationLayer.destroy();
       unpinScrolledAxis(container);
       container.innerHTML = "";
     }
@@ -4629,6 +4786,8 @@ export {
   applyLabelContrast,
   isInvalidSentinelError,
   invalidSentinelReason,
+  ANNOTATION_LAYER_CLASS,
+  ANNOTATION_CLASS,
   sessionViewStateProvider,
   noopViewStateProvider,
   assembleD3,

package/dist/index.mjs

@@ -10,6 +10,8 @@ import {
   ANIM_PLAY_SPEED_DEFAULT,
   ANIM_PLAY_SPEED_MAX,
   ANIM_PLAY_SPEED_MIN,
+  ANNOTATION_CLASS,
+  ANNOTATION_LAYER_CLASS,
   APPROXIMATE_POSITIONS_DEFAULT,
   AUTO_RAMP_CLASSES,
   AUTO_RAMP_DRAWN_OPACITY,
@@ -163,7 +165,7 @@ import {
   unpinScrolledAxis,
   valuePlacementFlag,
   withoutViewOnlyKeys
-} from "./chunk-P4FOCNAX.mjs";
+} from "./chunk-TOKJTZNS.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -2789,6 +2791,8 @@ export {
   ANIM_PLAY_SPEED_DEFAULT,
   ANIM_PLAY_SPEED_MAX,
   ANIM_PLAY_SPEED_MIN,
+  ANNOTATION_CLASS,
+  ANNOTATION_LAYER_CLASS,
   APPROXIMATE_POSITIONS_DEFAULT,
   AUTO_RAMP_CLASSES,
   AUTO_RAMP_DRAWN_OPACITY,

package/dist/react.mjs

@@ -7,7 +7,7 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-P4FOCNAX.mjs";
+} from "./chunk-TOKJTZNS.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -53,6 +53,8 @@ function BicChart(props) {
     filteredBy,
     respondsWith,
     onSelect,
+    annotations,
+    onAnnotationClick,
     className,
     style
   } = props;
@@ -78,6 +80,11 @@ function BicChart(props) {
   onLabelContrastRef.current = onLabelContrast;
   const onInvalidSentinelRef = useRef(onInvalidSentinel);
   onInvalidSentinelRef.current = onInvalidSentinel;
+  const onAnnotationClickRef = useRef(onAnnotationClick);
+  onAnnotationClickRef.current = onAnnotationClick;
+  const annKey = useMemo(() => JSON.stringify(annotations ?? []), [annotations]);
+  const annotationsRef = useRef(annotations);
+  annotationsRef.current = annotations;
   const [geoTick, setGeoTick] = useState(0);
   useEffect(() => {
     if (!geoKind || geoFromCache(geoKind)) return;
@@ -112,9 +119,12 @@ function BicChart(props) {
       // newest prop wins without a rebuild.
       get onInvalidSentinel() {
         return onInvalidSentinelRef.current ? (info) => onInvalidSentinelRef.current?.(info) : void 0;
-      }
+      },
+      annotations: annotationsRef.current ?? [],
+      onAnnotationClick: (a) => onAnnotationClickRef.current?.(a)
     });
     hostRef.current = host;
+    builtAnnKeyRef.current = annKey;
     const off = host.selection.onChange((payloadIdxs, source) => {
       if (source === "host") return;
       const sourceIdxs = toSourceRows(rowMapRef.current, payloadIdxs);
@@ -135,6 +145,12 @@ function BicChart(props) {
     builtWithRef.current = { ...builtWithRef.current, optKey };
     hostRef.current.setOptions(options);
   }, [optKey]);
+  const builtAnnKeyRef = useRef(null);
+  useEffect(() => {
+    if (!hostRef.current || builtAnnKeyRef.current === annKey) return;
+    builtAnnKeyRef.current = annKey;
+    hostRef.current.setAnnotations(annotationsRef.current ?? []);
+  }, [annKey]);
   useEffect(() => {
     if (!hostRef.current || !data) return;
     if (builtWithRef.current?.data === data) return;

package/dist/types/annotations.d.ts

@@ -0,0 +1,40 @@
+export interface MarkAnnotation {
+    /** The column holding the key (with `value`). */
+    column?: string;
+    /** The key's value; matched as text, trimmed, so a number column and a string key agree. */
+    value?: string | number;
+    /**
+     * A key over several columns - a route by both of its ends, `{ Origin: "BRA", Dest: "CHL" }` - so no key
+     * column has to be added to the query or the chart. Every named column must match. Used instead of column/value.
+     */
+    where?: Record<string, string | number>;
+    /** Badge text (a count, a letter). Default: a dot. */
+    label?: string;
+    /** Tooltip text - the note, or a summary of several. */
+    title?: string;
+    /** Anything the host wants back on click. */
+    id?: string;
+}
+export interface AnnotationReport {
+    /** Annotations drawn on a mark. */
+    shown: number;
+    /** Annotations with no mark in this render (filtered out, off the map, no such key). */
+    notShown: number;
+}
+export declare const ANNOTATION_LAYER_CLASS = "bic-annotations";
+export declare const ANNOTATION_CLASS = "bic-annotation";
+export interface AnnotationLayer {
+    set(list: MarkAnnotation[]): void;
+    /** Redraw against the container's current marks and the given data. */
+    draw(data: {
+        columns: any[];
+        rows: any[][];
+    }, theme: {
+        fg?: string;
+        accent?: string;
+        bg?: string;
+    }): void;
+    readonly report: AnnotationReport;
+    destroy(): void;
+}
+export declare function createAnnotationLayer(container: HTMLElement, onClick?: (a: MarkAnnotation) => void): AnnotationLayer;

package/dist/types/host.d.ts

@@ -6,6 +6,7 @@ import { type ColourSpreadCensus } from "./colourSpread";
 import { type ValuePlacementCensus } from "./valuePlacement";
 import { type FitRenderedChartOptions, type FitRenderedChartResult } from "./fitDom";
 import { type LabelContrastOptions, type LabelContrastReport } from "./labelContrastDom";
+import { type MarkAnnotation, type AnnotationReport } from "./annotations";
 export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
 /**
  * THE SESSION PROVIDER — what every host got hard-coded before contract 1.6.0, now named.
@@ -181,8 +182,21 @@ export interface ChartHostConfig {
         reason: string;
         message: string;
     }) => void;
+    /**
+     * NOTES ON MARKS. Each annotation names a key - a value in a column of this chart's data, such as a
+     * country code - and the host draws a badge on that key's mark after every render, wherever a filter,
+     * a re-query or a zoom has put it. Keyed by value, never by row position. Change them with
+     * setAnnotations; none (the default) draws nothing.
+     */
+    annotations?: MarkAnnotation[];
+    /** A badge was clicked. The mark beneath is not selected. */
+    onAnnotationClick?: (annotation: MarkAnnotation) => void;
 }
 export interface ChartHost {
+    /** Replace the notes drawn on marks (see ChartHostConfig.annotations); redraws them at once. */
+    setAnnotations(list: MarkAnnotation[]): void;
+    /** How many annotations the last draw placed on a mark, and how many had none in this render. */
+    readonly annotationReport: AnnotationReport;
     render(): void;
     /**
      * THE LAST RENDER, SETTLED. render() stays synchronous — it returns nothing, exactly as it

package/dist/types/index.d.ts

@@ -8,6 +8,7 @@ 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, assembleD3, D3_PLUGIN_PACKAGES, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
+export { ANNOTATION_CLASS, ANNOTATION_LAYER_CLASS, type MarkAnnotation, type AnnotationReport } from "./annotations";
 export { createChartGroup, toSourceRows, syncMemberSelection, type ChartGroup, type ChartGroupMember, type ChartGroupSelection, type ChartGroupChange, type ChartGroupMemberOptions, type ChartGroupSourceOptions, type ChartGroupPayload } from "./group";
 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";

package/dist/types/react.d.ts

@@ -61,6 +61,14 @@ export interface BicChartProps {
     respondsWith?: "filter" | "highlight";
     /** Selection callback in SOURCE row indices (group) or payload indices (standalone). */
     onSelect?: (rowIdxs: number[]) => void;
+    /**
+     * Notes on marks: a badge on each key's mark, redrawn after every render - e.g.
+     * `[{ column: "CountryCode", value: "USA", label: "2", title: "..." }]`. Keyed by a value in a column,
+     * never a row position, so a filter or a re-query never moves one.
+     */
+    annotations?: ChartHostConfig["annotations"];
+    /** A badge was clicked (the mark beneath is not selected). */
+    onAnnotationClick?: ChartHostConfig["onAnnotationClick"];
     className?: string;
     style?: React.CSSProperties;
 }

package/package.json

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