@bicharts/chart-host 0.5.44 → 0.5.45

package/dist/{chunk-BMYEYUEN.mjs → chunk-DZ5FNFID.mjs}

@@ -1086,6 +1086,42 @@ function ensureCrossfilterHitTargets(container, doc) {
   return report;
 }
 
+// src/blankRender.ts
+var EMPTY = { markCount: 0, legendMarkCount: 0, containerKind: "empty" };
+function censusMarks(container) {
+  if (!container || typeof container.querySelectorAll !== "function") return EMPTY;
+  try {
+    const marks = /* @__PURE__ */ new Set();
+    for (const el of Array.from(container.querySelectorAll(`.${MARK_CLASS}`))) marks.add(el);
+    for (const el of Array.from(container.querySelectorAll(`[${ROW_IDX_ATTR}]`))) marks.add(el);
+    const legend = /* @__PURE__ */ new Set();
+    for (const el of Array.from(container.querySelectorAll(`.${LEGEND_MARK_CLASS}`))) {
+      legend.add(el);
+      marks.delete(el);
+    }
+    const hasSvg = !!container.querySelector("svg");
+    const hasAnything = hasSvg || (container.childElementCount ?? 0) > 0;
+    return {
+      markCount: marks.size,
+      legendMarkCount: legend.size,
+      containerKind: hasSvg ? "svg" : hasAnything ? "html" : "empty"
+    };
+  } catch {
+    return EMPTY;
+  }
+}
+function isBlankRender(i) {
+  if (i.contractUntagged) return false;
+  if (i.animated) return false;
+  if (i.authoredNoDataText) return false;
+  if (!(i.rows > 0)) return false;
+  return i.markCount === 0;
+}
+function blankRenderFlag(lang, cause) {
+  const clean = (s) => String(s || "unknown").toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+  return `blankrender:${clean(lang)}:${clean(cause)}`;
+}
+
 // src/host.ts
 var parseRowIdxs = (s) => (s || "").split(",").map((x2) => parseInt(x2, 10)).filter((n) => Number.isFinite(n));
 var D3_PLUGIN_PACKAGES = {
@@ -1186,6 +1222,7 @@ function createChartHost(container, config) {
   let renderFn = config.renderFn ?? null;
   let destroyed = false;
   let warnedGeo = false;
+  let warnedBlank = false;
   let current = null;
   let activeTickEl = null;
   let selectionIsPeriod = false;
@@ -1353,6 +1390,27 @@ function createChartHost(container, config) {
       }
       ensureCrossfilterHitTargets(container, doc);
       paintSelection();
+      try {
+        const census = censusMarks(container);
+        if (isBlankRender({
+          markCount: census.markCount,
+          rows: data.rows ? data.rows.length : 0,
+          animated: config.animated,
+          contractUntagged: config.contractUntagged
+        })) {
+          if (!warnedBlank) {
+            warnedBlank = true;
+            try {
+              (win?.console ?? console)?.warn(
+                `[@bicharts/chart-host] this chart rendered without error but painted no data marks, against ${data.rows.length} row(s) \u2014 so the container is empty. The usual cause is that the generated code binds a column BY NAME that is no longer in the data, sending it down its own "no data" branch. Check that the columns in your table still match the ones the chart was generated for.`
+              );
+            } catch {
+            }
+          }
+          config.onBlankRender?.({ census, rows: data.rows ? data.rows.length : 0 });
+        }
+      } catch {
+      }
     },
     setOptions(partial) {
       raw = { ...raw, ...partial };
@@ -1448,6 +1506,9 @@ export {
   buildRenderPayload,
   createMarkResolver,
   ensureCrossfilterHitTargets,
+  censusMarks,
+  isBlankRender,
+  blankRenderFlag,
   requiredD3Plugins,
   explainRenderFailure,
   stripEsmExports,

package/dist/index.mjs

@@ -30,7 +30,9 @@ import {
   ROW_IDX_ATTR,
   SELECTION_ACTIVE_CLASS,
   XFILTER_REFRESH_EVENT,
+  blankRenderFlag,
   buildRenderPayload,
+  censusMarks,
   chartOwnsTimeline,
   clearGeoCache,
   compileRenderFn,
@@ -40,6 +42,7 @@ import {
   explainRenderFailure,
   geoAssetFor,
   geoFromCache,
+  isBlankRender,
   loadGeo,
   periodTickSuppressesFeedback,
   registerGeo,
@@ -47,7 +50,7 @@ import {
   requiredD3Plugins,
   resolveOptions,
   stripEsmExports
-} from "./chunk-BMYEYUEN.mjs";
+} from "./chunk-DZ5FNFID.mjs";
 import "./chunk-A2GMXZP7.mjs";
 
 // src/trivial.ts
@@ -811,10 +814,12 @@ export {
   actionFor,
   askApplyImprovements,
   bareBase64,
+  blankRenderFlag,
   buildRenderPayload,
   buildReviewWire,
   canConfirmLaunch,
   captureSvgSnapshot,
+  censusMarks,
   chartOwnsTimeline,
   chooserFitsViewport,
   clearGeoCache,
@@ -828,6 +833,7 @@ export {
   explainRenderFailure,
   geoAssetFor,
   geoFromCache,
+  isBlankRender,
   launchFavorStyle,
   launchGenerates,
   loadGeo,

package/dist/react.mjs

@@ -4,7 +4,7 @@ import {
   createChartHost,
   geoFromCache,
   loadGeo
-} from "./chunk-BMYEYUEN.mjs";
+} from "./chunk-DZ5FNFID.mjs";
 import "./chunk-A2GMXZP7.mjs";
 
 // src/react.tsx

package/dist/types/blankRender.d.ts

@@ -0,0 +1,60 @@
+export interface MarkCensus {
+    /** Data marks found anywhere in the container. */
+    markCount: number;
+    /** Legend swatches / axis furniture — clickable, but NOT evidence the data drew. */
+    legendMarkCount: number;
+    /** What the chart built. `html` is a first-class answer, not a failure — see below. */
+    containerKind: "svg" | "html" | "empty";
+}
+/**
+ * Count what the render actually left behind.
+ *
+ * NOT SCOPED TO `<svg>`, and that is what makes this work at all. Plenty of chart types are pure
+ * HTML - a table with embedded bars, a KPI card - and never create an SVG, so a census that
+ * starts from `container.querySelector("svg")` finds nothing for exactly the charts it most needs
+ * to measure. Those charts still honour the contract: their working path tags each row
+ * `class="d3-mark"` + `data-row-idx`, and their no-data branch appends a bare element with
+ * neither. The class and the attribute ARE the signal, in both DOM worlds; the element name never
+ * was.
+ *
+ * Counts by contract, never by tag: a chart marking `<rect>`, `<text>`, `<path>`, `<circle>` or
+ * `<div>` is equally visible here. Never throws — telemetry must not be why a delivered render
+ * fails.
+ */
+export declare function censusMarks(container: Element | null | undefined): MarkCensus;
+export interface BlankVerdictInput {
+    /** From censusMarks. */
+    markCount: number;
+    /** Rows the chart was HANDED. Zero rows is a different, already-handled story. */
+    rows: number;
+    /**
+     * This chart declares time keyframes. Its first frame is legitimately allowed to be empty
+     * (an animated map before any country enters the series), so a verdict on frame one would be
+     * a lie about the commonest animated opening.
+     */
+    animated?: boolean;
+    /**
+     * The author configured their own "No Data Text". They asked for this rectangle to say
+     * something when there is nothing to draw, and overruling them would be telling someone their
+     * deliberate empty state is a defect.
+     */
+    authoredNoDataText?: boolean;
+    /**
+     * The chart's marks are not tagged by our contract at all — a Vega lane, whose marks the
+     * generated spec names itself. Absence of `.d3-mark` there proves nothing, so the census is
+     * evidence-free and must not return a verdict.
+     */
+    contractUntagged?: boolean;
+}
+/**
+ * Did this render paint nothing, against data that had something to paint?
+ *
+ * EVERY CLAUSE IS A FALSE POSITIVE WE WOULD OTHERWISE SHIP. The value of this verdict is that a
+ * human believes it; one wrong accusation on a chart that is fine costs more than the case it
+ * catches, which is the same argument `columnsGoneFromDiff` makes about type narrowings.
+ */
+export declare function isBlankRender(i: BlankVerdictInput): boolean;
+/** A short, stable token a host can attach to its own per-render telemetry. Deliberately
+ *  formatted for an always-on channel rather than a debug log: a blank render is most
+ *  interesting in aggregate, and the charts worth counting are the ones nobody is watching. */
+export declare function blankRenderFlag(lang: string, cause: string): string;

package/dist/types/host.d.ts

@@ -1,5 +1,6 @@
 import { type RenderOptions } from "./contract";
 import { type ResolveOptionsInput } from "./defaults";
+import { type MarkCensus } from "./blankRender";
 export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
 export interface ChartHostConfig {
     data: {
@@ -36,6 +37,26 @@ export interface ChartHostConfig {
      *  already holds its assets (e.g. `geoForKind` from "@bicharts/chart-host/geo", or the
      *  data.geo.json the MCP wrote next to the chart). */
     geoProvider?: (geoKind: string) => any | undefined;
+    /**
+     * Called when a render completes cleanly having painted NO data marks against a non-empty
+     * table (2026-09-01). The chart did not throw, so nothing else will tell you — this is
+     * the only notification that the rectangle your reader is looking at is empty.
+     *
+     * The commonest cause by far is schema drift: generated code binds columns BY NAME, so a
+     * renamed or removed field sends its own `findIndex(...) === -1` guard down the no-data
+     * branch. A host that knows the binding can say WHICH column; one that does not should still
+     * surface it, because "empty and silent" is the state this exists to abolish.
+     */
+    onBlankRender?: (info: {
+        census: MarkCensus;
+        rows: number;
+    }) => void;
+    /** This chart declares time keyframes: frame one is allowed to be empty, so no blank verdict
+     *  is issued for it. */
+    animated?: boolean;
+    /** The chart's marks are not tagged with the shared contract (a Vega lane names its own
+     *  marks), so a mark count proves nothing and the blank verdict is suppressed. */
+    contractUntagged?: boolean;
 }
 export interface ChartHost {
     render(): void;

package/dist/types/index.d.ts

@@ -15,3 +15,4 @@ export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, typ
 export { qualifyPick, qualifyAuto, qualifyCancel, launchGenerates, launchFavorStyle, chooserFitsViewport, shouldOpenChooserOnGenerate, shouldOpenInlineChooserOnGenerate, canConfirmLaunch, confirmLaunch, qualifyFailureFallsOpen, CHOOSER_MIN_WIDTH_PX, CHOOSER_MIN_HEIGHT_PX, type QualifyLaunchOutcome, type ChooserGateInput, } from "./qualifyLaunch";
 export { computeSelectionCard, normaliseAggregation, type SelectionCardModel, type SelectionCardLine, type SelectionCardOptions, } from "./selectionCard";
 export { ensureCrossfilterHitTargets, type HitTargetReport } from "./hitTargets";
+export { censusMarks, isBlankRender, blankRenderFlag, type MarkCensus, type BlankVerdictInput } from "./blankRender";

package/package.json

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