@bicharts/chart-host 0.5.76 → 0.5.77

package/dist/{chunk-N6XJDJRN.mjs → chunk-WI2R6E6U.mjs}

@@ -1813,6 +1813,64 @@ function planFrameGrow(inkBottomPx, elHeightPx, viewBoxH, ctmScale, slackPx = SC
   if (!(ctmScale > 0) || !isFinite(ctmScale)) return none("no-scale");
   return { grow: true, heightPx, viewBoxH: viewBoxH + delta / ctmScale, reason: "grow" };
 }
+var AXIS_PIN_MIN_LABELS = 2;
+var AXIS_PIN_BAND_PAD_PX = 2;
+var AXIS_PIN_MAX_BAND_FRACTION = 0.4;
+var AXIS_PIN_TRACK_REACH_PX = 12;
+function isHorizontalLabelRow(boxes) {
+  if (!boxes || boxes.length < 2) return false;
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+  for (const b2 of boxes) {
+    const cx = (b2.left + b2.right) / 2, cy = (b2.top + b2.bottom) / 2;
+    if (!isFinite(cx) || !isFinite(cy)) return false;
+    if (cx < minX) minX = cx;
+    if (cx > maxX) maxX = cx;
+    if (cy < minY) minY = cy;
+    if (cy > maxY) maxY = cy;
+  }
+  return maxX - minX > maxY - minY;
+}
+function labelBand(boxes, tracks = [], pad = AXIS_PIN_BAND_PAD_PX, trackReach = AXIS_PIN_TRACK_REACH_PX) {
+  if (!boxes || boxes.length === 0) return null;
+  let top = Infinity, bottom = -Infinity;
+  for (const b2 of boxes) {
+    if (!isFinite(b2.top) || !isFinite(b2.bottom)) continue;
+    if (b2.top < top) top = b2.top;
+    if (b2.bottom > bottom) bottom = b2.bottom;
+  }
+  if (!isFinite(top) || !isFinite(bottom) || bottom <= top) return null;
+  for (const t of tracks || []) {
+    if (!isFinite(t.top) || !isFinite(t.bottom)) continue;
+    const gap = t.bottom < top ? top - t.bottom : t.top > bottom ? t.top - bottom : 0;
+    if (gap > trackReach) continue;
+    if (t.top < top) top = t.top;
+    if (t.bottom > bottom) bottom = t.bottom;
+  }
+  return { top: top - pad, bottom: bottom + pad };
+}
+function planAxisPin(candidates, viewportH, minLabels = AXIS_PIN_MIN_LABELS, maxFraction = AXIS_PIN_MAX_BAND_FRACTION) {
+  const none = (reason) => ({ pin: false, index: -1, band: null, reason });
+  if (!isFinite(viewportH) || viewportH <= 0) return none("unmeasurable");
+  let sawAxis = false, best = null;
+  for (const c of candidates || []) {
+    if (!c || !c.labels || c.labels.length < minLabels) continue;
+    sawAxis = true;
+    if (!isHorizontalLabelRow(c.labels)) continue;
+    if (!best || c.labels.length > best.labels.length) best = c;
+  }
+  if (!best) return none(sawAxis ? "vertical-only" : "no-axis");
+  const band = labelBand(best.labels, best.tracks || []);
+  if (!band) return none("unmeasurable");
+  if (band.bottom - band.top > viewportH * maxFraction) return none("band-too-tall");
+  return { pin: true, index: best.index, band, reason: "pinned" };
+}
+function axisPinPlacement(band, scrollTop, viewportH) {
+  if (!band || !isFinite(band.top) || !isFinite(band.bottom)) return null;
+  if (!isFinite(scrollTop) || !isFinite(viewportH) || viewportH <= 0) return null;
+  if (band.top < scrollTop) return "top";
+  if (band.bottom > scrollTop + viewportH) return "bottom";
+  return null;
+}
 
 // src/fitDom.ts
 var FIT_WALK_CAP = 8e3;
@@ -1898,6 +1956,237 @@ function fitReadingFor(lane, c, slackPx = SCROLL_SLACK_PX, inkOf) {
     scrollH: c.scrollHeight
   };
 }
+var noPin = (reason) => ({ pinned: false, reason, bandPx: 0, axisAt: "", labels: 0, carried: 0, edge: null });
+var CONTAINER_SLOT_AXIS_PIN = "__bicAxisPin";
+var SVG_NS2 = "http://www.w3.org/2000/svg";
+var AXIS_PIN_MAX_CARRIED = 12;
+function unpinScrolledAxis(container) {
+  if (!container) return;
+  const st = container[CONTAINER_SLOT_AXIS_PIN];
+  if (!st) return;
+  try {
+    container.removeEventListener("scroll", st.onScroll);
+  } catch {
+  }
+  try {
+    if (st.overlay.parentNode) st.overlay.parentNode.removeChild(st.overlay);
+  } catch {
+  }
+  try {
+    delete container[CONTAINER_SLOT_AXIS_PIN];
+  } catch {
+  }
+}
+function textHidden(t, view) {
+  if (t.getAttribute("display") === "none" || t.getAttribute("visibility") === "hidden") return true;
+  try {
+    const cs = view.getComputedStyle(t);
+    if (cs && (cs.display === "none" || cs.visibility === "hidden")) return true;
+  } catch {
+  }
+  return false;
+}
+function backdropFill(svg, container, view, svgBox) {
+  try {
+    const rects = svg.querySelectorAll("rect");
+    for (let i2 = 0; i2 < rects.length && i2 < 6; i2++) {
+      const r = rects[i2];
+      if (r.closest(".d3-mark")) continue;
+      const b2 = r.getBoundingClientRect();
+      if (b2.width >= svgBox.width * 0.9 && b2.height >= svgBox.height * 0.9) {
+        let fill = "";
+        try {
+          fill = view.getComputedStyle(r).fill || "";
+        } catch {
+        }
+        if (!fill || fill === "none") fill = r.getAttribute("fill") || "";
+        if (fill && fill !== "none" && fill !== "transparent") return fill;
+        break;
+      }
+    }
+  } catch {
+  }
+  try {
+    let el = container;
+    for (let hops = 0; el && hops < 12; hops++, el = el.parentElement) {
+      const bg = view.getComputedStyle(el).backgroundColor;
+      if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") return bg;
+    }
+  } catch {
+  }
+  return "#ffffff";
+}
+function cloneWithChain(el, svg, root) {
+  const chain = [];
+  let n = el.parentElement;
+  while (n && n !== svg) {
+    chain.unshift(n);
+    n = n.parentElement;
+  }
+  let parent = root;
+  for (const anc of chain) {
+    const c = anc.cloneNode(false);
+    parent.appendChild(c);
+    parent = c;
+  }
+  parent.appendChild(el.cloneNode(true));
+  const ids = root.querySelectorAll("[id]");
+  for (let i2 = 0; i2 < ids.length; i2++) ids[i2].removeAttribute("id");
+}
+function pinScrolledAxis(container, svg) {
+  unpinScrolledAxis(container);
+  if (!container) return noPin("no-container");
+  if (!svg) return noPin("no-svg");
+  try {
+    const doc = svg.ownerDocument;
+    const view = doc && doc.defaultView || globalThis;
+    const svgBox = svg.getBoundingClientRect();
+    if (!(svgBox.width > 0) || !(svgBox.height > 0)) return noPin("unmeasurable");
+    const m2 = typeof svg.getScreenCTM === "function" ? svg.getScreenCTM() : null;
+    if (!m2 || !(m2.a > 0) || !(m2.d > 0) || !isFinite(m2.e) || !isFinite(m2.f)) return noPin("no-ctm");
+    const viewportH = container.clientHeight;
+    if (!(viewportH > 0)) return noPin("unmeasurable");
+    const rel = (r) => ({ left: r.left - svgBox.left, top: r.top - svgBox.top, right: r.right - svgBox.left, bottom: r.bottom - svgBox.top });
+    const ticks = svg.querySelectorAll(".tick");
+    const byAxis = /* @__PURE__ */ new Map();
+    for (let i2 = 0; i2 < ticks.length; i2++) {
+      const t = ticks[i2];
+      if (t.closest("svg") !== svg) continue;
+      const p2 = t.parentElement;
+      if (!p2) continue;
+      const list = byAxis.get(p2);
+      if (list) list.push(t);
+      else byAxis.set(p2, [t]);
+    }
+    const axes = [];
+    const cands = [];
+    byAxis.forEach((group, axis2) => {
+      const labels = [];
+      for (const tick of group) {
+        const txt = tick.querySelector("text");
+        if (!txt || textHidden(txt, view)) continue;
+        const r = txt.getBoundingClientRect();
+        if (!(r.width > 0) || !(r.height > 0)) continue;
+        labels.push(rel(r));
+      }
+      const tracks = [];
+      for (let i2 = 0; i2 < axis2.children.length; i2++) {
+        const ch = axis2.children[i2];
+        if (ch.tagName.toLowerCase() !== "path" || !(ch.getAttribute("class") || "").split(/\s+/).includes("domain")) continue;
+        const r = ch.getBoundingClientRect();
+        if (r.width > 0 && r.height <= 4) tracks.push(rel(r));
+      }
+      cands.push({ index: axes.length, labels, tracks });
+      axes.push(axis2);
+    });
+    const plan = planAxisPin(cands, viewportH);
+    if (!plan.pin || !plan.band) return noPin(plan.reason);
+    const axis = axes[plan.index];
+    const band = { top: Math.max(0, plan.band.top), bottom: Math.min(svgBox.height, plan.band.bottom) };
+    const bandPx = band.bottom - band.top;
+    if (!(bandPx > 0)) return noPin("unmeasurable");
+    const carried = [];
+    const texts = svg.querySelectorAll("text");
+    for (let i2 = 0; i2 < texts.length && carried.length < AXIS_PIN_MAX_CARRIED; i2++) {
+      const t = texts[i2];
+      if (t.closest("svg") !== svg) continue;
+      if (t.closest(".tick") || t.closest(".d3-mark") || t.closest(".d3-legend-mark")) continue;
+      if (axis.contains(t) || textHidden(t, view)) continue;
+      const r = rel(t.getBoundingClientRect());
+      if (!(r.right > r.left) || !(r.bottom > r.top)) continue;
+      if (r.top >= band.top && r.bottom <= band.bottom) carried.push(t);
+    }
+    const pinSvg = doc.createElementNS(SVG_NS2, "svg");
+    for (const a2 of ["font-family", "font-size", "font-weight", "font", "fill", "color", "text-rendering"]) {
+      const v2 = svg.getAttribute(a2);
+      if (v2) pinSvg.setAttribute(a2, v2);
+    }
+    const styles = svg.querySelectorAll("style");
+    for (let i2 = 0; i2 < styles.length; i2++) pinSvg.appendChild(styles[i2].cloneNode(true));
+    const vbX = (svgBox.left - m2.e) / m2.a, vbY = (svgBox.top + band.top - m2.f) / m2.d;
+    const vbW = svgBox.width / m2.a, vbH = bandPx / m2.d;
+    pinSvg.setAttribute("viewBox", `${vbX} ${vbY} ${vbW} ${vbH}`);
+    pinSvg.setAttribute("preserveAspectRatio", "none");
+    pinSvg.setAttribute("width", String(svgBox.width));
+    pinSvg.setAttribute("height", String(bandPx));
+    pinSvg.setAttribute("aria-hidden", "true");
+    pinSvg.style.display = "block";
+    pinSvg.style.pointerEvents = "none";
+    const back = doc.createElementNS(SVG_NS2, "rect");
+    back.setAttribute("x", String(vbX));
+    back.setAttribute("y", String(vbY));
+    back.setAttribute("width", String(vbW));
+    back.setAttribute("height", String(vbH));
+    back.setAttribute("fill", backdropFill(svg, container, view, svgBox));
+    pinSvg.appendChild(back);
+    cloneWithChain(axis, svg, pinSvg);
+    for (const t of carried) cloneWithChain(t, svg, pinSvg);
+    const overlay = doc.createElement("div");
+    overlay.setAttribute("data-bic-axis-pin", "1");
+    const o2 = overlay.style;
+    o2.position = "absolute";
+    o2.margin = "0";
+    o2.padding = "0";
+    o2.border = "0";
+    o2.width = `${svgBox.width}px`;
+    o2.height = `${bandPx}px`;
+    o2.overflow = "hidden";
+    o2.pointerEvents = "none";
+    o2.zIndex = "3";
+    o2.display = "none";
+    overlay.appendChild(pinSvg);
+    try {
+      const cs = view.getComputedStyle(container);
+      const pos = cs && cs.position || container.style.position;
+      if (!pos || pos === "static") container.style.position = "relative";
+    } catch {
+      container.style.position = container.style.position || "relative";
+    }
+    const cRect = container.getBoundingClientRect();
+    const svgLeft = svgBox.left - cRect.left - container.clientLeft + container.scrollLeft;
+    const svgTop = svgBox.top - cRect.top - container.clientTop + container.scrollTop;
+    const contentBand = { top: svgTop + band.top, bottom: svgTop + band.bottom };
+    const place = () => {
+      const st = container.scrollTop, vh = container.clientHeight;
+      const edge2 = axisPinPlacement(contentBand, st, vh);
+      if (!edge2) {
+        o2.display = "none";
+        return null;
+      }
+      o2.display = "block";
+      o2.left = `${svgLeft}px`;
+      o2.top = `${edge2 === "top" ? st : st + vh - bandPx}px`;
+      return edge2;
+    };
+    const onScroll = () => {
+      try {
+        if (!overlay.isConnected) {
+          unpinScrolledAxis(container);
+          return;
+        }
+        place();
+      } catch {
+      }
+    };
+    container.appendChild(overlay);
+    container.addEventListener("scroll", onScroll, { passive: true });
+    container[CONTAINER_SLOT_AXIS_PIN] = { overlay, onScroll };
+    const edge = place();
+    const mid = (band.top + band.bottom) / 2 / svgBox.height;
+    return {
+      pinned: true,
+      reason: "pinned",
+      bandPx: Math.round(bandPx),
+      axisAt: mid < 1 / 3 ? "top" : mid > 2 / 3 ? "bottom" : "middle",
+      labels: cands[plan.index].labels.length,
+      carried: carried.length,
+      edge
+    };
+  } catch {
+    unpinScrolledAxis(container);
+    return noPin("threw");
+  }
+}
 function fitRenderedChart(container, opts = {}) {
   const slackPx = opts.slackPx ?? SCROLL_SLACK_PX;
   const result = {
@@ -1907,7 +2196,8 @@ function fitRenderedChart(container, opts = {}) {
     growReason: "no-container",
     overflowX: "hidden",
     overflowY: "hidden",
-    reading: null
+    reading: null,
+    axisPin: noPin("no-container")
   };
   if (!container) return result;
   try {
@@ -1968,6 +2258,16 @@ function fitRenderedChart(container, opts = {}) {
     if (opts.applyOverflow !== false) {
       container.style.overflowX = fit.overflowX;
       container.style.overflowY = fit.overflowY;
+      if (fit.overflowY !== "auto") {
+        unpinScrolledAxis(container);
+        result.axisPin = noPin("not-scrolling");
+      } else if (opts.pinAxis === false) {
+        unpinScrolledAxis(container);
+        result.axisPin = noPin("disabled");
+      } else result.axisPin = pinScrolledAxis(container, svg);
+    } else {
+      unpinScrolledAxis(container);
+      result.axisPin = noPin("overflow-not-applied");
     }
   } catch {
   }
@@ -2631,6 +2931,7 @@ function createChartHost(container, config) {
       container.removeEventListener(XFILTER_REFRESH_EVENT, onXf);
       container.removeEventListener("click", onClick);
       subs.clear();
+      unpinScrolledAxis(container);
       container.innerHTML = "";
     }
   };
@@ -2703,10 +3004,20 @@ export {
   isPhantomBox,
   MAX_FRAME_GROW_FACTOR,
   planFrameGrow,
+  AXIS_PIN_MIN_LABELS,
+  AXIS_PIN_BAND_PAD_PX,
+  AXIS_PIN_MAX_BAND_FRACTION,
+  AXIS_PIN_TRACK_REACH_PX,
+  isHorizontalLabelRow,
+  labelBand,
+  planAxisPin,
+  axisPinPlacement,
   ctmScaleOf,
   svgInkReach,
   measureContainerBoxes,
   fitReadingFor,
+  unpinScrolledAxis,
+  pinScrolledAxis,
   fitRenderedChart,
   DARK_TEXT,
   LIGHT_TEXT,

package/dist/index.mjs

@@ -11,6 +11,10 @@ import {
   ANIM_PLAY_SPEED_MIN,
   APPROXIMATE_POSITIONS_DEFAULT,
   AXIS_FILTER_CLASS,
+  AXIS_PIN_BAND_PAD_PX,
+  AXIS_PIN_MAX_BAND_FRACTION,
+  AXIS_PIN_MIN_LABELS,
+  AXIS_PIN_TRACK_REACH_PX,
   BACKING_MAJORITY,
   COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
   COLOR_SCALE_SELF_CLAMP_PCT_MAX,
@@ -56,6 +60,7 @@ import {
   XFILTER_REFRESH_EVENT,
   _e,
   applyLabelContrast,
+  axisPinPlacement,
   backingHoldsGlyph,
   blankRenderFlag,
   buildRenderPayload,
@@ -81,14 +86,18 @@ import {
   glyphSampleGrid,
   hitBandFlag,
   isBlankRender,
+  isHorizontalLabelRow,
   isPhantomBox,
   isPillBackdropAlpha,
+  labelBand,
   loadGeo,
   measureContainerBoxes,
   needsScroll,
   noopViewStateProvider,
   periodTickSuppressesFeedback,
   pillBacksGlyph,
+  pinScrolledAxis,
+  planAxisPin,
   planFrameGrow,
   registerGeo,
   registerGeoAsset,
@@ -99,8 +108,9 @@ import {
   sessionViewStateProvider,
   stripEsmExports,
   svgInkReach,
-  toRGBA
-} from "./chunk-N6XJDJRN.mjs";
+  toRGBA,
+  unpinScrolledAxis
+} from "./chunk-WI2R6E6U.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -1033,6 +1043,10 @@ export {
   ANIM_PLAY_SPEED_MIN,
   APPROXIMATE_POSITIONS_DEFAULT,
   AXIS_FILTER_CLASS,
+  AXIS_PIN_BAND_PAD_PX,
+  AXIS_PIN_MAX_BAND_FRACTION,
+  AXIS_PIN_MIN_LABELS,
+  AXIS_PIN_TRACK_REACH_PX,
   BACKING_MAJORITY,
   CHOOSER_MIN_HEIGHT_PX,
   CHOOSER_MIN_WIDTH_PX,
@@ -1082,6 +1096,7 @@ export {
   actionFor,
   applyLabelContrast,
   askApplyImprovements,
+  axisPinPlacement,
   backingHoldsGlyph,
   bareBase64,
   blankRenderFlag,
@@ -1120,8 +1135,10 @@ export {
   hitBandFlag,
   inlineFilterGate,
   isBlankRender,
+  isHorizontalLabelRow,
   isPhantomBox,
   isPillBackdropAlpha,
+  labelBand,
   launchFavorStyle,
   launchGenerates,
   listNeedsFilter,
@@ -1136,6 +1153,8 @@ export {
   orderRefusalsForDisplay,
   periodTickSuppressesFeedback,
   pillBacksGlyph,
+  pinScrolledAxis,
+  planAxisPin,
   planFrameGrow,
   planTrivialChart,
   qualifyAuto,
@@ -1165,5 +1184,6 @@ export {
   svgInkReach,
   svgNaturalSize,
   svgToDataUrl,
-  toRGBA
+  toRGBA,
+  unpinScrolledAxis
 };

package/dist/react.mjs

@@ -4,7 +4,7 @@ import {
   createChartHost,
   geoFromCache,
   loadGeo
-} from "./chunk-N6XJDJRN.mjs";
+} from "./chunk-WI2R6E6U.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 

package/dist/types/fit.d.ts

@@ -34,3 +34,59 @@ export interface FrameGrowPlan {
  * @param ctmScale     px per user unit, from the live screen CTM
  */
 export declare function planFrameGrow(inkBottomPx: number, elHeightPx: number, viewBoxH: number, ctmScale: number, slackPx?: number, maxFactor?: number): FrameGrowPlan;
+export declare const AXIS_PIN_MIN_LABELS = 2;
+export declare const AXIS_PIN_BAND_PAD_PX = 2;
+export declare const AXIS_PIN_MAX_BAND_FRACTION = 0.4;
+export declare const AXIS_PIN_TRACK_REACH_PX = 12;
+export interface LabelRowBox {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Does a row of label boxes run ACROSS the chart rather than DOWN it? A horizontal axis spreads
+ * its label centres over x; a y-axis spreads them over y, and pinning a y-axis would pin the
+ * ROWS - the exact thing the scroll exists to reveal. Ties are vertical: a single label has no
+ * direction and is not an axis.
+ */
+export declare function isHorizontalLabelRow(boxes: LabelRowBox[]): boolean;
+export interface AxisBand {
+    top: number;
+    bottom: number;
+}
+/**
+ * The vertical band a label row occupies, padded, widened to take in a thin track (the domain
+ * line) that sits within reach of the labels. Tracks further away are ignored on purpose: a
+ * gridline drawn as a full-height tick line is part of the plot, not of the header.
+ */
+export declare function labelBand(boxes: LabelRowBox[], tracks?: LabelRowBox[], pad?: number, trackReach?: number): AxisBand | null;
+export interface AxisPinCandidate {
+    /** The caller's handle for this axis - returned in the plan. */
+    index: number;
+    /** One box per VISIBLE tick label, in any one consistent coordinate space. */
+    labels: LabelRowBox[];
+    /** Thin tracks that may belong to the band (a horizontal domain line). Optional. */
+    tracks?: LabelRowBox[];
+}
+export interface AxisPinPlan {
+    pin: boolean;
+    index: number;
+    band: AxisBand | null;
+    reason: string;
+}
+/**
+ * Which axis to pin, and the band it occupies. Coordinates are whatever the caller measured in;
+ * the plan only compares them, and `viewportH` (same units) bounds the band. With two horizontal
+ * axes the one with more labels wins - it is the one carrying the scale.
+ */
+export declare function planAxisPin(candidates: AxisPinCandidate[], viewportH: number, minLabels?: number, maxFraction?: number): AxisPinPlan;
+export type AxisPinEdge = "top" | "bottom";
+/**
+ * Where the pinned copy sits for this scroll position, or null when the original axis is in view
+ * and the copy must get out of the way. `band` is in CONTENT coordinates (the scroll origin), the
+ * viewport is [scrollTop, scrollTop + viewportH]. The copy appears as soon as the original is CUT
+ * by an edge, not only once it has fully left: a half-visible label row reads worse than a whole
+ * one drawn over it.
+ */
+export declare function axisPinPlacement(band: AxisBand, scrollTop: number, viewportH: number): AxisPinEdge | null;

package/dist/types/fitDom.d.ts

@@ -1,4 +1,4 @@
-import type { ContentExtent, MeasuredBox } from "./fit";
+import type { ContentExtent, MeasuredBox, AxisPinEdge } from "./fit";
 export declare function ctmScaleOf(m: {
     a: number;
     b: number;
@@ -43,6 +43,13 @@ export interface FitRenderedChartOptions {
      * its own scrolling and only wants to be told.
      */
     applyOverflow?: boolean;
+    /**
+     * When the container scrolls vertically, keep the chart's horizontal axis in view by pinning
+     * a copy of it at the viewport edge while the original is scrolled out. Default true. The
+     * copy hides itself whenever the original is on screen, so there is never a second axis.
+     * Set false for a host that draws its own sticky header.
+     */
+    pinAxis?: boolean;
 }
 export interface FitRenderedChartResult {
     /** The frame was grown, so content that was being clipped is now painted. */
@@ -55,5 +62,28 @@ export interface FitRenderedChartResult {
     overflowY: "hidden" | "auto";
     /** The post-grow reading, or null when nothing could be measured. */
     reading: FitReading | null;
+    /** The axis pin: what was pinned when the container scrolls, or why nothing was. */
+    axisPin: AxisPinReport;
+}
+export interface AxisPinReport {
+    pinned: boolean;
+    /** "pinned", or the fail-open reason: not-scrolling, disabled, no-svg, no-ctm, no-axis,
+     *  vertical-only, band-too-tall, unmeasurable, overflow-not-applied, threw. */
+    reason: string;
+    /** The pinned band's height on screen, px. */
+    bandPx: number;
+    /** Where the ORIGINAL axis sits in the chart body: top third, bottom third, or between. */
+    axisAt: "top" | "bottom" | "middle" | "";
+    /** Visible tick labels in the copy. */
+    labels: number;
+    /** Furniture texts that shared the band and came along (a "Today" caption, an axis title). */
+    carried: number;
+    /** Where the copy sat at the moment of the pass - null when the original was in view. */
+    edge: AxisPinEdge | null;
 }
+/** Remove a previous render's pinned axis - its overlay and its scroll listener. Safe to call
+ *  when there is none. Hosts that clear the container themselves still need this for the
+ *  listener, which outlives the overlay. */
+export declare function unpinScrolledAxis(container: HTMLElement | null | undefined): void;
+export declare function pinScrolledAxis(container: HTMLElement | null | undefined, svg: SVGSVGElement | null | undefined): AxisPinReport;
 export declare function fitRenderedChart(container: HTMLElement | null | undefined, opts?: FitRenderedChartOptions): FitRenderedChartResult;

package/dist/types/index.d.ts

@@ -22,3 +22,5 @@ export { censusMarks, isBlankRender, blankRenderFlag, type MarkCensus, type Blan
 export { censusHitBands, hitBandFlag, MIN_HIT_BAND_PX, type HitBandCensus } from "./hitBands";
 export { SCROLL_SLACK_PX, MAX_FRAME_GROW_FACTOR, PHANTOM_FRACTION, FIT_CONTENT_SELECTOR, needsScroll, contentExtentOf, scrollFitFor, planFrameGrow, isPhantomBox, type MeasuredBox, type ContentExtent, type ScrollFit, type FrameGrowPlan, } from "./fit";
 export { fitRenderedChart, fitReadingFor, measureContainerBoxes, svgInkReach, ctmScaleOf, type FitReading, type InkReach, type FitRenderedChartOptions, type FitRenderedChartResult, } from "./fitDom";
+export { AXIS_PIN_MIN_LABELS, AXIS_PIN_BAND_PAD_PX, AXIS_PIN_MAX_BAND_FRACTION, AXIS_PIN_TRACK_REACH_PX, isHorizontalLabelRow, labelBand, planAxisPin, axisPinPlacement, type LabelRowBox, type AxisBand, type AxisPinCandidate, type AxisPinPlan, type AxisPinEdge, } from "./fit";
+export { pinScrolledAxis, unpinScrolledAxis, type AxisPinReport } from "./fitDom";

package/package.json

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