@bicharts/chart-host 0.6.84 → 0.6.86

package/dist/react.mjs

@@ -22,11 +22,12 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-2HKO6GEK.mjs";
+} from "./chunk-MXL5SK7X.mjs";
 import "./chunk-QIRLWJBI.mjs";
 import "./chunk-2ZUUIZWL.mjs";
 import "./chunk-7HKVV5T5.mjs";
 import "./chunk-IURROJT7.mjs";
+import "./chunk-BQFG5HWZ.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-MR6TL7QZ.mjs";
 import "./chunk-GHODWOAL.mjs";
@@ -68,6 +69,7 @@ function BicChart(props) {
     viewState,
     labelContrast,
     onLabelContrast,
+    layoutPass,
     onInvalidSentinel,
     id,
     filteredBy,
@@ -149,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
@@ -180,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;
@@ -206,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/frameFit.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Frame fit — pure geometry.
+ *
+ * The third measured sibling of the label-contrast and legend-reconcile passes.
+ * Generated code routinely parks a footer/source caption against the
+ * RAW svg edge — `svg.append('text').attr('y', height - 2)` — instead of reserving
+ * a band for it inside `margin.bottom`. That looks right in the code and is wrong
+ * on screen: a baseline is not an ink box. A glyph descends roughly 0.27 * fontSize
+ * BELOW its baseline, so a 2px gap at font-size 7.5 puts the tails of "g", "p", "y"
+ * exactly on (or past) the frame, and `.lch-d3ctr` is `overflow:hidden` — the host
+ * silently slices them. Measured live on a Marimekko (690x340): the
+ * caption's ink box ran 331->340 in a 340-tall frame, i.e. flush, tails gone.
+ *
+ * Corpus: 41 D3 generations across ~20 chart types park text within 5 user units of
+ * the frame, so this is a RENDERER-level habit, not one chart's bug.
+ *
+ * WHY EXTEND THE VIEWBOX RATHER THAN MOVE THE TEXT: nudging a glyph back inside
+ * can shove it into whatever sits above it — in that Marimekko the axis title's ink
+ * ends 12 units above the caption, so a blind 6-unit lift would collide the two
+ * and trade a clipped line for an overlapping one. Growing the viewBox instead
+ * makes the SVG scale to fit its container: nothing moves relative to anything
+ * else, nothing is clipped, and a 2-unit grow on a 340-unit frame is a 0.6%
+ * rescale nobody can see. This is exactly the remedy the legend-reconcile pass already
+ * uses for a legend that runs off the right edge.
+ *
+ * Coordinates: EVERYTHING here is in the SVG's USER space (== viewBox units). The
+ * caller maps measured client-px boxes through `svg.getScreenCTM().inverse()`
+ * first, which captures viewBox, preserveAspectRatio, container scaling AND host
+ * page zoom in one matrix — so this module needs no px<->unit factor. Same
+ * contract as legendReconcile; the box and viewBox types are shared with it.
+ *
+ * DOM-free so it can be unit-tested on plain numbers; the DOM I/O lives in
+ * frameFitDom.fitTextToFrame.
+ */
+import type { Rect, ViewBox } from "./legendReconcile";
+export type { Rect, ViewBox };
+export interface FrameFitPlan {
+    action: "none" | "extend" | "defer";
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    newViewBox: ViewBox;
+    considered: number;
+    rescued: number;
+    deferred: number;
+    deferredIdx: number[];
+    reason: string;
+}
+export declare const FRAME_PAD = 1;
+export declare const MAX_EXTEND_FRACTION = 0.08;
+/**
+ * Work out how much the viewBox must grow so every measured ink box sits inside
+ * the frame with FRAME_PAD to spare.
+ *
+ * @param boxes  ink boxes in USER space (see module note on the CTM mapping)
+ * @param vb     the SVG's current viewBox in user units
+ * @param maxFraction  per-axis extension ceiling, as a fraction of the frame
+ */
+export declare function planFrameFit(boxes: Rect[], vb: ViewBox, maxFraction?: number): FrameFitPlan;
+/** Serialize a viewBox the way the SVG attribute wants it. */
+export declare function viewBoxAttr(vb: ViewBox): string;
+export type TextAnchor = "start" | "middle" | "end";
+/** The minimum readable type, px. */
+export declare const FIT_TYPE_FLOOR = 10;
+/** A shrink never goes below this fraction of the chart's own size: past it, cut instead. */
+export declare const FIT_SHRINK_FLOOR = 0.8;
+/**
+ * The width, in user units, a label may keep so that its box sits inside `frame` (with
+ * FRAME_PAD), given the edge its anchor holds - or null when no shortening can fit it
+ * (it overflows vertically, or its held edge is itself outside the frame).
+ */
+export declare function labelRoom(box: Rect, frame: ViewBox, anchor: TextAnchor): number | null;
+export interface LabelFitDecision {
+    action: "none" | "shrink" | "cut";
+    fontSize: number;
+}
+/**
+ * Shrink or cut: a label `width` units wide at `fontSize` px that must fit `room` units.
+ * Width scales with the font size, so the first guess is exact to within hinting; the caller
+ * re-measures after a shrink and falls through to the cut if hinting disagreed.
+ */
+export declare function labelFitDecision(width: number, room: number, fontSize: number): LabelFitDecision;
+/**
+ * The widest prefix of `full` (plus the ellipsis) that `fits`, never cut inside a number:
+ * a cut between two digits moves back to before the number ("largest 12..." of
+ * "largest 128 of 400" states a different count). Empty when nothing fits.
+ */
+export declare function cutToFit(full: string, fits: (s: string) => boolean, ell?: string): string;

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

@@ -0,0 +1,70 @@
+/**
+ * Frame fit - the labels the viewBox could not rescue.
+ *
+ * fitTextToFrame grows the viewBox for text that pokes a few units past the frame and
+ * DEFERS text that is further out, because swallowing it would shrink the whole chart. A
+ * deferred label used to stay exactly where the chart put it, sliced by the frame, and
+ * a log line only counted it: a Bullet of 21 KPIs at 1230x626 reported
+ * `{"rescued":8,"deferred":6,"grew":"left+68.06"}` while six KPI names still read
+ * "...f Service Effort - Reduce effort".
+ *
+ * A label that overflows on the side its anchor does NOT hold is fitted in place: the type
+ * shrinks first (see labelFitDecision - never below the 10px floor or 80% of the chart's size),
+ * then the string is cut to the widest prefix that fits, never inside a number, and the full
+ * text rides a <title>. A label that overflows vertically, or on the side its anchor holds, is
+ * counted as unfixable and left alone. The geometry is in frameFit.ts; this is the DOM I/O,
+ * with the measurement handed in so the caller's CTM mapping (viewBox, zoom) is the only one.
+ */
+import { Rect, ViewBox, FrameFitPlan } from "./frameFit";
+export interface DeferredLabelFitReport {
+    /** Deferred text elements looked at. */
+    deferred: number;
+    /** Fitted by a smaller font size alone. */
+    shrunk: number;
+    /** Fitted by cutting the string (after any shrink). */
+    cut: number;
+    /** Could not be fitted by shortening: vertical overflow, the held edge outside, rotated, tspans. */
+    unfixable: number;
+    /** The first few full labels that were fitted, for the log line. */
+    labels: string[];
+}
+/**
+ * Fit ONE label, `width` wide, into `room` (both in whatever units `widthNow` measures): shrink the
+ * type first (labelFitDecision - never below the 10px floor or 80% of the label's size), then cut
+ * the string to the widest prefix that fits, never inside a number, with the full text riding a
+ * <title>. `minChars` keeps at least that many characters before the ellipsis even when they do not
+ * fit - a caller that must never REMOVE a label (the nominal axis) passes 1. Shared by the
+ * frame fit and the nominal-axis cut.
+ */
+export declare function fitLabelToRoom(el: Element, width: number, room: number, widthNow: () => number, minChars?: number): "none" | "shrunk" | "cut";
+/**
+ * Fit each deferred label to `frame`. `measure` returns the element's box in the SAME user
+ * space as `frame` (null when it cannot). Never throws; a label it cannot judge is unfixable.
+ */
+export declare function fitDeferredLabels(els: Element[], frame: ViewBox, measure: (el: Element) => Rect | null): DeferredLabelFitReport;
+/** Perf ceiling: every text costs a getBoundingClientRect, and a Tabular can paint thousands of
+ *  cells; above this the sweep costs more than the defect it fixes (and such charts scroll their
+ *  own body anyway, so their overflow is intentional). */
+export declare const FRAME_FIT_TEXT_CAP = 600;
+export interface FrameFitOutcome {
+    /** Set when the pass declined: too many texts to measure. */
+    skipped?: {
+        texts: number;
+        cap: number;
+    };
+    /** The viewBox plan (planFrameFit). */
+    plan?: FrameFitPlan;
+    /** What happened to the labels the plan deferred, when there were any. */
+    labels?: DeferredLabelFitReport;
+}
+/**
+ * THE WHOLE PASS, host-free: grow the viewBox for text a few units past the frame (planFrameFit),
+ * then fit the labels it deferred (fitDeferredLabels). Null when there is nothing to measure (no
+ * svg, no text, no CTM, an unreadable viewBox). A host adds its own logging around this call; it
+ * is kept DOM-only so a headless replay can run exactly what a host runs.
+ */
+export declare function fitTextToFrame(host: HTMLElement): FrameFitOutcome | null;
+/** True when the element sits under a clip-path/mask, inside <defs>, or inside a scrollable
+ *  subtree - all cases where being outside the frame is the chart's intent rather than a
+ *  text-metric miss. */
+export declare function isClippedOrScrolled(el: Element, stopAt: Element): boolean;

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

@@ -0,0 +1,5 @@
+export { MIN_OVERLAP, MAX_GUTTER_FRACTION, COLORBAR_ON_PLOT_COVER, MAX_FIT_FRACTION, FIT_PAD, LEGIBILITY_GRACE_PX, MIN_LEGIBLE_PX, BOTTOM_TEXT_MIN_TICK_HITS, SWATCH_MAX_PX, SWATCH_LABEL_GAP_PX, SIGNATURE_MIN_PAIRS, AXIS_THIN_MIN_TICKS, AXIS_THIN_GAP, LABEL_ROW_MIN_TEXTS, LABEL_ROW_Y_TOLERANCE, LABEL_ROW_TRACK_COVER, LABEL_ROW_TRACK_REACH, rightmostOverlappingPlotEdge, bottommostOverlappingPlotEdge, planLegendReconcile, colorbarProbePoints, colorbarOnPlot, colorbarSitsOnMarks, colorbarReconcileSide, planContentFit, planBottomTextPush, swatchPairs, isLegendSignature, planAxisTickThin, isNumericLabelText, isDateLikeLabelText, isOrderedAxisLabelText, axisLabelsAreNominal, nominalLabelRooms, groupLabelRows, labelRowHasTrack, type Rect, type ViewBox, type ReconcileSide, type ReconcilePlan, type ReconcileOptions, type ContentFitPlan, type ContentFitOptions, type SwatchPairs, type AxisThinPlan, } from "./legendReconcile";
+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/legendReconcile.d.ts

@@ -0,0 +1,295 @@
+/**
+ * D3 legend / plot reconciliation — pure geometry.
+ *
+ * The measured sibling of the label-contrast pass. A generated D3 chart
+ * can draw its legend ON TOP of plot content, or with its text running off the
+ * right edge, because legend WIDTH is data-dependent — the generator can't reserve
+ * the right gutter at author time without measuring rendered text, which only
+ * exists after render. So we measure post-render and fix it.
+ *
+ * Coordinates: EVERYTHING here is in the SVG's USER space (== viewBox units).
+ * The caller maps the measured client-px bounding boxes into user space via
+ * svg.getScreenCTM().inverse() before calling — that one matrix captures the
+ * viewBox, preserveAspectRatio and any container scaling/letterboxing exactly,
+ * so this module needs no px↔unit scale factor.
+ *
+ * The fix is TWO independent quantities (the bug in v1 was conflating them):
+ *   - SLIDE (legendDx): move the legend right just enough that its LEFT edge
+ *     clears the rightmost plot content it overlaps, + pad.
+ *   - EXTEND (ext): widen the viewBox just enough that the slid legend's RIGHT
+ *     edge sits inside it, + pad. Widening the viewBox makes the SVG scale to
+ *     fit its container, so nothing is clipped and the plot isn't reflowed.
+ * The first version set EXTEND = SLIDE, which left the legend's right edge exactly
+ * as clipped as before and made the gutter overlap-sized rather than need-sized
+ * (a Sankey's legend text stayed cut off at the viewport edge, with more gutter
+ * than necessary).
+ *
+ * DOM-free: the caller gathers user-space boxes + the viewBox and applies the
+ * plan (set newViewBox, translate the legend group by legendDx). Tests feed
+ * plain numbers and assert the plan.
+ */
+export interface Rect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export interface ViewBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type ReconcileSide = "right" | "bottom";
+export interface ReconcilePlan {
+    action: "none" | "reserve";
+    legendDx: number;
+    legendDy: number;
+    ext: number;
+    newViewBox: ViewBox;
+    reason: string;
+}
+export declare const MIN_OVERLAP = 2;
+export declare const MAX_GUTTER_FRACTION = 0.6;
+export interface ReconcileOptions {
+    /** Ignore overlaps at or below this many user units (default MIN_OVERLAP). */
+    minOverlap?: number;
+    /** Defer if the viewBox extension would exceed this fraction of its width
+     *  (default MAX_GUTTER_FRACTION). */
+    maxGutterFraction?: number;
+    /** Gap (user units) left between the legend's LEFT and the plot (default 8). */
+    pad?: number;
+    /** Gap (user units) left between the legend's RIGHT and the viewBox edge
+     *  (default 4). Smaller than `pad` so the legend hugs the right edge — this
+     *  is the lever for "too much gutter to the right of the legend". */
+    edgePad?: number;
+}
+/**
+ * The rightmost right-edge among plot elements that vertically overlap the
+ * legend and do NOT horizontally span it. Per-element (not a union) so a title
+ * or axis label that isn't actually beside the legend doesn't count, and a
+ * full-width plot background (which spans the legend) is ignored — that's not a
+ * collision a right gutter fixes. Returns -Infinity when nothing sits beside it.
+ */
+export declare function rightmostOverlappingPlotEdge(legendBox: Rect, plotRects: Rect[]): number;
+/**
+ * The bottom-most bottom-edge among plot elements whose box INTERSECTS the legend
+ * (horizontal AND vertical overlap) without fully spanning it. The 90°-rotated
+ * analogue of rightmostOverlappingPlotEdge — for a horizontal bottom
+ * legend/colorbar overprinted by the x-axis ticks/title. Box-intersection (not a
+ * "starts above" test) so a colorbar whose own TITLE sits above its gradient —
+ * making the union box taller than the colliders — still detects the x-axis
+ * labels that overlap the gradient. Content that clears the legend entirely
+ * (a cell row above, a footer below) doesn't intersect and is ignored. Returns
+ * -Infinity when nothing intersects.
+ */
+export declare function bottommostOverlappingPlotEdge(legendBox: Rect, plotRects: Rect[]): number;
+/**
+ * Decide whether/how to reconcile an overlapping/clipped D3 legend.
+ *
+ * @param legendBox  legend group bbox in USER space
+ * @param plotRects  per-element plot-content bboxes (marks + non-legend text) in USER space
+ * @param viewBox    the SVG's current viewBox
+ * @param opts       strictness thresholds (mode-dependent)
+ */
+export declare function planLegendReconcile(legendBox: Rect | null, plotRects: Rect[] | null, viewBox: ViewBox | null, opts?: ReconcileOptions, side?: ReconcileSide): ReconcilePlan;
+/**
+ * WHICH MARGIN A STRUCTURALLY-FOUND COLORBAR BELONGS IN.
+ *
+ * The colorbar pass was first written for ONE case — a horizontal bar in the bottom margin
+ * overprinting the x-axis — so it asked `planLegendReconcile` for side "bottom" and nothing
+ * else. A VERTICAL colorbar inset into the plot was therefore detected, measured, refused
+ * ("not-horizontal-legend") and shipped covering the marks. A treemap with `margin.right = 4`,
+ * a colorbar at `plotW - barW - 52` and a `rgba(255,255,255,0.88)` plate under it is that case
+ * exactly — the generated code's own comment reads *"Background plate so legend is readable
+ * over treemap tiles"*, so the occlusion was deliberate, and two cells and their labels went
+ * behind it.
+ *
+ * The right-side remedy already existed for a legend that carries `.d3-legend-mark`; a colorbar
+ * carries no contract class, which is the only reason it was out of reach. So this picks the
+ * side from the bar's own geometry and the rest of the machinery is unchanged.
+ *
+ * THE TESTS HERE MIRROR THE PLANNER'S OWN GATES, deliberately — a strip wider than 2× its
+ * height can only go down, anything else can only go right, and each must already be anchored
+ * in the margin it is being pushed into. Returning null where the planner would refuse keeps
+ * the two from disagreeing: a caller that guesses gets a "not-…" reason instead of a move, and
+ * a decorative gradient panel in the middle of the canvas is nobody's furniture.
+ */
+/**
+ * IS THE COLORBAR DRAWN ON TOP OF THE CHART? Measured against the GRADIENT BAR itself,
+ * not the group box - and by plain intersection, not by the edge test the right slide uses.
+ *
+ * BOTH of those choices were forced by a corpus of rendered charts, and each was wrong the
+ * first time:
+ *
+ *  - THE GROUP BOX IS AMBIGUOUS. It also holds the ticks, the title and a backing plate, so
+ *    "marks reach past the group's left edge" reads the same for a colorbar sitting on the
+ *    plot and for one parked correctly in the gutter with a label hanging left of its bar.
+ *    Over 401 rendered charts that ambiguity was the whole problem: gating on the group box
+ *    moved 89 charts, only 37 of which had a mark near the bar at all. The BAR's own box has
+ *    no such ambiguity - a mark under it means the colorbar was drawn over the chart, full
+ *    stop. That reading finds 15.
+ *  - `rightmostOverlappingPlotEdge` SKIPS A MARK THAT SPANS THE BOX, which is right for a
+ *    full-width backdrop and exactly wrong here: a treemap tile drawn behind the colorbar
+ *    spans it, and that is the case where the occlusion is TOTAL. It answered "nothing
+ *    overlaps" on a bar sitting entirely on a tile.
+ *
+ * A MAJORITY, because a colorbar beside the marks still gets its edge touched. The measured
+ * spread of `cover` over the 15 is
+ * 1.00 1.00 1.00 0.97 | 0.57 0.49 0.41 | 0.25 0.25 0.13 0.06 0.05 0.03 0.01 0.01
+ * - the top four are bars drawn wholly on a mark, and the tail from 0.25 down is the last
+ * bar of a chart grazing a bar parked in the gutter, which is the content-fit pass's business
+ * and not a reason to re-lay-out a cached chart. 0.5 is the default, not a discovery: it is
+ * the one number here that a reader should feel free to move.
+ */
+export declare const COLORBAR_ON_PLOT_COVER = 0.5;
+/**
+ * WHERE TO ASK "IS ANYTHING PAINTED HERE?" - an evenly spaced grid strictly inside the
+ * bar, inset half a cell so no probe lands on its own edge.
+ *
+ * A BOX IS NOT INK, and this pass learned it the expensive way. Gating on box
+ * intersection alone fired on a density-contour plot whose OUTERMOST contour
+ * is a thin diagonal band from the top-left to the bottom-right: its bounding box is
+ * 705x664 of a 776x779 canvas and therefore covers the colorbar completely, while its
+ * ink comes nowhere near it. A box-only test shipped at 50% precision on the corpus.
+ * The remedy is the browser's own answer - isPointInFill / isPointInStroke at these
+ * points.
+ */
+export declare function colorbarProbePoints(bar: Rect | null, cols?: number, rows?: number): {
+    x: number;
+    y: number;
+}[];
+/** A majority of the bar's own area has a mark painted under it. */
+export declare function colorbarOnPlot(inkHits: number, probes: number, minCover?: number): boolean;
+export declare function colorbarSitsOnMarks(bar: Rect | null, marks: Rect[] | null, minCover?: number): boolean;
+export declare function colorbarReconcileSide(bar: Rect | null, viewBox: ViewBox | null): ReconcileSide | null;
+/**
+ * CONTENT FIT — the universal "nothing gets cut off" pass (a Sankey used
+ * margin.left=20 with text-anchor:end node labels at x0-6, so left labels hung ~80
+ * units into NEGATIVE x and were clipped — while the legend mechanism, which only
+ * ever measures the legend column and extends the RIGHT edge, applied cleanly.
+ * Whack-a-mole by design: every targeted fix watches one edge).
+ *
+ * This is edge- and chart-agnostic: take the union bbox of ALL rendered
+ * content and EXTEND the viewBox on whichever sides content hangs past, + pad.
+ * Extend-only — never shrink (intentional margins/whitespace are not ours to
+ * reclaim). Runs after any legend slide (it re-measures, so it covers the slid
+ * legend's final position too) and also when there is NO legend at all.
+ *
+ * Outlier defense: a generation may park junk far off-canvas (work elements at
+ * x=-9999). A rect is considered only if it intersects the viewBox expanded by
+ * maxFitFraction per side; the final extension is also clamped to that
+ * fraction. A real hanging label sits just past the edge and is unaffected;
+ * parked junk is ignored rather than blowing the canvas up.
+ */
+export interface ContentFitPlan {
+    action: "none" | "fit";
+    newViewBox: ViewBox;
+    reason: string;
+    /** user units added per side (0 when that side didn't move) */
+    cut: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+}
+export declare const MAX_FIT_FRACTION = 0.35;
+export declare const FIT_PAD = 4;
+export declare const LEGIBILITY_GRACE_PX = 1;
+export interface ContentFitOptions {
+    /** Ignore per-side overhangs at or below this many user units (default MIN_OVERLAP). */
+    minOverhang?: number;
+    /** Per-side extension cap as a fraction of the viewBox dimension (default MAX_FIT_FRACTION). */
+    maxFitFraction?: number;
+    /** Padding (user units) between content and the new viewBox edge (default FIT_PAD). */
+    pad?: number;
+    /**
+     * The smallest text the chart currently paints, in SCREEN px — declared user units
+     * already multiplied by the live CTM scale, because that is the number a reader's eye
+     * meets. Omitted (or non-finite) disables the legibility test entirely, which is the
+     * honest degrade: a chart whose text could not be measured must keep today's behaviour
+     * rather than be refused on a guess.
+     */
+    smallestTextPx?: number;
+    /** The readable floor in px (default MIN_LEGIBLE_PX). */
+    minLegiblePx?: number;
+    /** How much of the smallest text the fit may spend (default LEGIBILITY_GRACE_PX). */
+    legibilityGracePx?: number;
+}
+export declare const MIN_LEGIBLE_PX = 10;
+export declare function planContentFit(contentRects: Rect[] | null, viewBox: ViewBox | null, opts?: ContentFitOptions): ContentFitPlan;
+export declare const BOTTOM_TEXT_MIN_TICK_HITS = 2;
+export declare function planBottomTextPush(candidate: Rect, tickBoxes: Rect[], gap?: number, transform?: string): {
+    move: boolean;
+    dy: number;
+};
+export declare const SWATCH_MAX_PX = 28;
+export declare const SWATCH_LABEL_GAP_PX = 30;
+export declare const SIGNATURE_MIN_PAIRS = 2;
+export interface SwatchPairs {
+    pairs: number;
+    sameSize: boolean;
+}
+export declare function swatchPairs(shapes: Rect[], texts: Rect[]): SwatchPairs;
+export declare function isLegendSignature(p: SwatchPairs): boolean;
+export declare const AXIS_THIN_MIN_TICKS = 4;
+export declare const AXIS_THIN_GAP = 2;
+export interface AxisThinPlan {
+    stride: number;
+    hide: number[];
+    reason: string;
+}
+/**
+ * Boxes are the tick labels of ONE axis, in any order (they are sorted here by
+ * left edge, and `hide` comes back indexed against the INPUT). Returns the
+ * smallest stride that clears every adjacent collision.
+ *
+ * Fail-open in both directions: too few ticks to be worth thinning, and an axis
+ * still colliding when only its two ends survive, both hide NOTHING. An ugly
+ * axis is recoverable by resizing the tile; an axis stripped to one label is not.
+ */
+export declare function planAxisTickThin(boxes: Rect[], gap?: number, minTicks?: number): AxisThinPlan;
+export declare const LABEL_ROW_MIN_TEXTS = 3;
+export declare const LABEL_ROW_Y_TOLERANCE = 2;
+/**
+ * A tick-like label: at least one digit, and nothing but digits and the furniture a number
+ * format adds - separators, sign, decimal point, currency, percent, a K/M/B suffix, a
+ * time colon. "Jan 2026" and "1 region unmatched" are not numeric; "$1.2M" and "-3.5%" are.
+ */
+export declare function isNumericLabelText(s: string): boolean;
+/**
+ * A date-like axis caption: a year (2026, FY2026, "Jan 2026"), a month or weekday name, a quarter,
+ * half or week ("Q3", "H1", "W12"), a slashed date ("1/15", "15.01.2026") or a clock time ("6 PM").
+ * Deliberately generous: a label read as ordered is thinned as before, so the cost of a wrong
+ * "date" is today's behaviour, never worse.
+ */
+export declare function isDateLikeLabelText(s: string): boolean;
+/** Ordered = a number (isNumericLabelText) or a date-like caption (isDateLikeLabelText). */
+export declare function isOrderedAxisLabelText(s: string): boolean;
+/** A NOMINAL axis: at least one non-empty label that is neither a number nor date-like. One name
+ *  among dates counts - that name has no neighbour to imply it. Empty labels say nothing. */
+export declare function axisLabelsAreNominal(labels: string[]): boolean;
+/**
+ * The room each label of a nominal axis may take, in input order: the step to its NARROWER
+ * neighbour less `gap`. `anchors` are the labels' anchor x positions (centre for middle, left
+ * edge for start, right edge for end - one anchor kind per axis), so the step is the band pitch
+ * whatever the labels' widths. Two labels each within that room cannot collide, whichever anchor
+ * they share. A lone anchor has no band and no limit.
+ */
+export declare function nominalLabelRooms(anchors: number[], gap?: number): number[];
+/**
+ * Group label boxes into horizontal ROWS - same vertical centre within `tol` px. Returns
+ * index lists into the input, each sorted by left edge; rows of one are dropped because a
+ * lone label has nothing to collide with.
+ */
+export declare function groupLabelRows(boxes: Rect[], tol?: number): number[][];
+export declare const LABEL_ROW_TRACK_COVER = 0.8;
+export declare const LABEL_ROW_TRACK_REACH = 3;
+/**
+ * Does a horizontal track run under (or over) this row of labels? `row` is the row's label
+ * boxes; `candidates` are the non-mark rect / line / path boxes of the row's own group. The
+ * candidates within reach are unioned - a five-swatch bar is five rects - and the union has
+ * to cover `cover` of the row's span. Pure, so the geometry is testable without a DOM.
+ */
+export declare function labelRowHasTrack(row: Rect[], candidates: Rect[], cover?: number, reach?: number): boolean;

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

@@ -0,0 +1,109 @@
+/**
+ * D3 legend reconcile — DOM adapter.
+ *
+ * The PURE geometry lives in legendReconcile.ts (unit-tested). This is the
+ * browser-side glue that the geometry can't be: find the legend group in a
+ * rendered SVG, measure it + the plot content in the SVG's USER space (via
+ * getScreenCTM, which captures viewBox + scaling exactly), run the plan, and
+ * apply it (widen the viewBox, slide the legend). It needs browser layout
+ * (getScreenCTM / DOMPoint), so its tests run on a jsdom layout stand-in — same
+ * split as the label-contrast pass's applier and its pure decision. Idempotent within
+ * a render via a data attribute; the caller wraps it in try/catch and owns logging.
+ */
+import { ReconcileOptions } from "./legendReconcile";
+export interface LegendReconcileResult {
+    applied: boolean;
+    reason: string;
+    dx?: number;
+    ext?: number;
+    newW?: number;
+    furniture?: number;
+    fit?: string;
+    cb?: string;
+    bt?: string;
+    fitDeclined?: string;
+    smallestTextPx?: number;
+    at?: string;
+    axisThin?: AxisThinReport;
+    lt?: string;
+    labelThin?: {
+        rows: number;
+        hidden: number;
+        stride: number;
+    };
+    dy?: number;
+    source?: "class" | "signature";
+}
+export declare function smallestRenderedTextPx(svg: SVGSVGElement, ctmScale: number): number | null;
+/**
+ * SELF-MANAGED SCROLL LAYOUT. A chart that renders its
+ * content as HTML inside a <foreignObject> with its OWN inner scroll body — a
+ * table-with-embedded scorecard (30 users × 32px rows scrolling inside a ~525px body) —
+ * manages its own frame. Its below-the-fold rows are SCROLLED, not clipped. The
+ * content-fit pass, which exists to rescue clipped SVG content, reads those off-canvas
+ * row <text>/marks as clipped and grows the viewBox (+239 on the bottom in that case);
+ * preserveAspectRatio then draws the taller viewBox to fit, letterboxing the chart into
+ * huge left/right gutters with everything shrunk (~72%) and the text illegibly small.
+ * NONE of the reconcile passes (legend slide / colorbar push / bottom-text / content-fit)
+ * apply to a self-scrolling HTML table, so skip the whole thing. Detected STRUCTURALLY (a
+ * <foreignObject> containing an element that scrolls its own content), never by chart-type
+ * name — any future self-managed layout is covered automatically.
+ */
+export declare function styleDeclaresScroll(inlineStyle: string | null | undefined, overflow?: string, overflowY?: string): boolean;
+/**
+ * AXIS TICK THINNING. A horizontal axis whose own tick labels overlap each
+ * other - eleven "Jan 2026" into a 312px plot, or "50K | 60K | 70K" along a
+ * numeric axis. The decision (which stride clears it) is planAxisTickThin; this
+ * is the DOM half: find each axis, establish it IS horizontal, measure the real
+ * text, and hide the labels the plan drops.
+ *
+ * MEASURED, NOT ESTIMATED, and that is the whole reason this lives client-side.
+ * The server exec-gate breadcrumb has to approximate text width as
+ * chars * fontSize * 0.6 because jsdom has no getComputedTextLength - good
+ * enough to triage on and not good enough to spend a regeneration on. Here the
+ * box is the browser's own.
+ *
+ * Hides the text only. The tick LINE and the gridline stay, so the reader keeps
+ * every position they align against and loses only a redundant caption.
+ * Conservative and fail-open throughout: fewer than four ticks, any rotated
+ * label (rotation is the generation's own answer to density and pairs badly
+ * with thinning), a vertical axis, or an axis still colliding when only its two
+ * ends survive all leave the axis exactly as it was drawn.
+ */
+/** What the axis pass did, for the caller's log line. cut / shrunk / nominal appear only when a
+ *  NOMINAL axis was fitted instead of thinned; colliding counts labels still touching a
+ *  neighbour after the cut kept their first character (a band too narrow for even that). */
+export interface AxisThinReport {
+    axes: number;
+    hidden: number;
+    stride: number;
+    cut?: number;
+    shrunk?: number;
+    nominal?: boolean;
+    colliding?: number;
+}
+export declare function reconcileLegendInSvg(svg: SVGSVGElement, opts?: ReconcileOptions): LegendReconcileResult;
+/**
+ * LEGENDS THAT NEVER ANNOUNCED THEMSELVES. The
+ * maximal mark-free <g> subtrees of the chart, judged by the legend signature in
+ * legendReconcile.ts. Walk top-down and stop descending once a group qualifies as
+ * mark-free, so an axis is one block and a legend nested inside the plot group is
+ * found on the way down. Axes are skipped STRUCTURALLY - d3's axis generator always
+ * emits g.tick / path.domain - which is the one exclusion a signature is allowed.
+ */
+export declare function findSignatureLegendGroups(svg: SVGSVGElement): Element[];
+/**
+ * THE COLORBAR'S OWN FURNITURE, FOUND STRUCTURALLY. The class-based legend finder
+ * above can't see a colorbar — the generator leaves the gradient rect UNCLASSED (and
+ * reuses .d3-legend-mark for the clickable AXIS labels, which are COLLIDERS here,
+ * not furniture). So: a <rect> filled url(#<gradient>) that isn't a plot mark; its
+ * parent <g> is the colorbar group, which is what carries the tick labels, the
+ * title and — the case that made this matter — a backing plate.
+ *
+ * Exported so the corpus replay measures with the SHIPPED detector instead of a
+ * copy of it; a replay that re-implements the predicate tests the translation.
+ */
+export declare function findColorbarFurniture(svg: SVGSVGElement): {
+    groups: Element[];
+    bars: SVGGraphicsElement[];
+};