@bicharts/chart-host 0.6.85 → 0.6.86

package/README.md

@@ -394,6 +394,27 @@ a throw must never fail a chart that already drew. The geometry behind each phas
 `planAxisTickThin`, `planFrameFit`, ...) is exported as plain functions over boxes, for a host that
 measures on its own terms.
 
+**Running them after every render.** `createLegendFitPass()` is both passes in the order that works
+(the legend first, then the frame fit, which measures what the legend pass left), with nothing to log
+and no policy. Hand it to the host as `layoutPass`, and the host runs it after every render, re-render
+and async settle, after the label colors are fixed and before anything measures the marks or the
+frame:
+
+```ts
+import { createChartHost } from "@bicharts/chart-host";
+import { createLegendFitPass } from "@bicharts/chart-host/legend-fit";
+
+const layoutPass = createLegendFitPass({
+    legend: true,            // or "narrow" to act only on large overlaps, or false
+    frameFit: true,
+    onReport: r => console.debug(r.legend, r.frame),   // what each run did; log what you like
+});
+const host = createChartHost(el, { code, data, d3, layoutPass });
+```
+
+In React it is the `layoutPass` prop of `<BicChart>`. Build the pass once, at module scope or in a
+`useMemo`: a new function on every render is a new host config, and the chart is rebuilt.
+
 ## Architecture — three layers, and why it matters if you contribute
 
 Read this before adding code. The package has **three** concerns, and they are independent.

package/dist/{chunk-CDWNZHIN.mjs → chunk-MXL5SK7X.mjs}

@@ -2312,6 +2312,12 @@ function createChartHost(container, config) {
       } catch {
       }
     }
+    if (config.layoutPass) {
+      try {
+        config.layoutPass(container);
+      } catch {
+      }
+    }
     ensureCrossfilterHitTargets(container, doc);
     paintSelection();
     try {

package/dist/index.mjs

@@ -97,7 +97,7 @@ import {
   toRGBA,
   toSourceRows,
   valuePlacementFlag
-} from "./chunk-CDWNZHIN.mjs";
+} from "./chunk-MXL5SK7X.mjs";
 import {
   LASSO_AXES_SLOT,
   LASSO_COUNT_CLASS,

package/dist/legend-fit.mjs

@@ -1,6 +1,7 @@
 /*! @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 {
-  chartSvgOf
+  chartSvgOf,
+  tableHostOf
 } from "./chunk-ZGQURBRJ.mjs";
 import {
   FIT_CONTENT_SELECTOR,
@@ -1554,6 +1555,36 @@ function reconcileBottomTextPhase(svg) {
   }
   return { applied: true, bt: `moved${moved} dy${Math.round(maxDy)}` };
 }
+
+// src/legendFit/pass.ts
+var NARROW = { minOverlap: 16, maxGutterFraction: 0.2 };
+var errorText = (e) => String(e?.message ?? e).slice(0, 120);
+function createLegendFitPass(opts = {}) {
+  const legendOn = opts.legend ?? true;
+  const frameOn = opts.frameFit ?? true;
+  return (container) => {
+    const report = { legend: { skipped: "off" }, frame: { skipped: "off" } };
+    if (legendOn !== false) {
+      try {
+        const svg = chartSvgOf(container);
+        report.legend = svg ? reconcileLegendInSvg(svg, legendOn === "narrow" ? NARROW : {}) : { skipped: "no-svg" };
+      } catch (e) {
+        report.legend = { error: errorText(e) };
+      }
+    }
+    if (frameOn) {
+      try {
+        report.frame = tableHostOf(container) ? { skipped: "table-lane" } : fitTextToFrame(container) ?? { skipped: "nothing-to-measure" };
+      } catch (e) {
+        report.frame = { error: errorText(e) };
+      }
+    }
+    try {
+      opts.onReport?.(report);
+    } catch {
+    }
+  };
+}
 export {
   AXIS_THIN_GAP,
   AXIS_THIN_MIN_TICKS,
@@ -1583,6 +1614,7 @@ export {
   colorbarProbePoints,
   colorbarReconcileSide,
   colorbarSitsOnMarks,
+  createLegendFitPass,
   cutToFit,
   findColorbarFurniture,
   findSignatureLegendGroups,

package/dist/react.mjs

@@ -22,7 +22,7 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-CDWNZHIN.mjs";
+} from "./chunk-MXL5SK7X.mjs";
 import "./chunk-QIRLWJBI.mjs";
 import "./chunk-2ZUUIZWL.mjs";
 import "./chunk-7HKVV5T5.mjs";
@@ -69,6 +69,7 @@ function BicChart(props) {
     viewState,
     labelContrast,
     onLabelContrast,
+    layoutPass,
     onInvalidSentinel,
     id,
     filteredBy,
@@ -150,6 +151,7 @@ function BicChart(props) {
       geoKind,
       viewState,
       labelContrast,
+      layoutPass,
       onLabelContrast: (r) => onLabelContrastRef.current?.(r),
       // A GETTER, not a wrapper: the host decides whether to
       // swallow the sentinel throw by whether this is SET, so
@@ -181,7 +183,7 @@ function BicChart(props) {
       host.destroy();
       hostRef.current = null;
     };
-  }, [code, renderFn, d3, geoKind, labelContrast, controls]);
+  }, [code, renderFn, d3, geoKind, labelContrast, layoutPass, controls]);
   useLayoutEffect(() => {
     const host = hostRef.current;
     if (!host || !selects) return;
@@ -207,7 +209,7 @@ function BicChart(props) {
       b.detach();
       if (bindingRef.current === b) bindingRef.current = null;
     };
-  }, [selects, code, renderFn, d3, geoKind, labelContrast]);
+  }, [selects, code, renderFn, d3, geoKind, labelContrast, layoutPass]);
   useEffect(() => {
     if (!hostRef.current || !options) return;
     if (builtWithRef.current?.optKey === optKey) return;

package/dist/types/host.d.ts

@@ -190,6 +190,15 @@ export interface ChartHostConfig {
     labelContrast?: boolean | LabelContrastOptions;
     /** What the label-contrast pass did after each render - counts, so a host can log them. */
     onLabelContrast?: (report: LabelContrastReport) => void;
+    /**
+     * A LAYOUT PASS the host brings, run after every render (both the synchronous and the promise lane, and every
+     * setOptions / setData re-render) AFTER the label-contrast pass and BEFORE the hit-target heal, the selection
+     * repaint, the censuses and the fit - the order a pass that moves the legend or grows the viewBox needs, because
+     * the fit must measure the final layout. Absent by default: the main entry carries no such pass. Build one with
+     * createLegendFitPass() from "@bicharts/chart-host/legend-fit". It must not throw (a throw is swallowed and the
+     * render stands); it reports through its own callback, never through this host.
+     */
+    layoutPass?: (container: HTMLElement) => void;
     /**
      * What the id-scoping pass did after each render: how many of the chart's ids got this host's suffix, and which
      * of them also existed elsewhere in the page (a clash it prevented - two same-size charts naming one clip path).

package/dist/types/legendFit/index.d.ts

@@ -2,3 +2,4 @@ export { MIN_OVERLAP, MAX_GUTTER_FRACTION, COLORBAR_ON_PLOT_COVER, MAX_FIT_FRACT
 export { FRAME_PAD, MAX_EXTEND_FRACTION, FIT_TYPE_FLOOR, FIT_SHRINK_FLOOR, planFrameFit, viewBoxAttr, labelRoom, labelFitDecision, cutToFit, type FrameFitPlan, type TextAnchor, type LabelFitDecision, } from "./frameFit";
 export { reconcileLegendInSvg, findSignatureLegendGroups, findColorbarFurniture, smallestRenderedTextPx, styleDeclaresScroll, type LegendReconcileResult, type AxisThinReport, } from "./legendReconcileDom";
 export { FRAME_FIT_TEXT_CAP, fitTextToFrame, fitDeferredLabels, fitLabelToRoom, isClippedOrScrolled, type FrameFitOutcome, type DeferredLabelFitReport, } from "./frameFitDom";
+export { createLegendFitPass, type LegendFitPassOptions, type LegendFitReport, type LegendFitStrictness } from "./pass";

package/dist/types/legendFit/pass.d.ts

@@ -0,0 +1,29 @@
+import { type LegendReconcileResult } from "./legendReconcileDom";
+import { type FrameFitOutcome } from "./frameFitDom";
+/** "smart" acts on smaller overlaps with larger moves; "narrow" only on large, unambiguous ones. */
+export type LegendFitStrictness = "smart" | "narrow";
+export interface LegendFitPassOptions {
+    /** Run the legend reconcile (legend slide, colorbar, axis and label-row thinning, bottom-text push, content fit). Default true. */
+    legend?: boolean | LegendFitStrictness;
+    /** Run the frame fit (viewBox growth for text just past the frame, then shrink-and-cut of the labels it deferred). Default true. */
+    frameFit?: boolean;
+    /** What each run did. Counts and reasons only; the host decides what to log. */
+    onReport?: (report: LegendFitReport) => void;
+}
+export interface LegendFitReport {
+    legend: LegendReconcileResult | {
+        skipped: "off" | "no-svg";
+    } | {
+        error: string;
+    };
+    frame: FrameFitOutcome | {
+        skipped: "off" | "table-lane" | "nothing-to-measure";
+    } | {
+        error: string;
+    };
+}
+/**
+ * Build the pass once (module scope, or a memo) and hand it to createChartHost as `layoutPass`: a new function
+ * on every render is a new host config. Each run never throws; a pass that fails reports `{ error }`.
+ */
+export declare function createLegendFitPass(opts?: LegendFitPassOptions): (container: HTMLElement) => void;

package/dist/types/react.d.ts

@@ -41,6 +41,13 @@ export interface BicChartProps {
     labelContrast?: ChartHostConfig["labelContrast"];
     /** What the label-contrast pass did after each render - counts, for a page that logs. */
     onLabelContrast?: ChartHostConfig["onLabelContrast"];
+    /**
+     * A LAYOUT PASS run after every render, after label contrast and before the fit - e.g.
+     * `createLegendFitPass()` from "@bicharts/chart-host/legend-fit", which slides a legend clear of
+     * the plot and fits text to the frame. Absent by default. Build it ONCE (module scope or useMemo):
+     * a new function each render rebuilds the host. See createChartHost's `layoutPass`.
+     */
+    layoutPass?: ChartHostConfig["layoutPass"];
     /**
      * THE CHART STOPPED BECAUSE THE DATA LACKS A COLUMN IT IS BUILT ON. Supplied: the chart's
      * container is left empty and this is called with the chart's reason, instead of the throw

package/package.json

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