@bicharts/chart-host 0.6.89 → 0.6.90

package/README.md

@@ -420,6 +420,20 @@ only while `rememberAcrossSessions()` is true. It is keyed by the chart's code a
 somewhere arbitrary. A chart with several zoomable panels is left alone. In React, pass the hook as
 the `zoomMemory` prop of `<BicChart>`.
 
+**A scrolled chart** keeps its place with no setup. A chart taller than its frame scrolls, and every
+redraw empties the container, which used to send the reader back to the top. The host now parks the
+scroll offset on the container before it clears it, and the fit puts it back once the new layout has
+decided whether it still scrolls. The offset is clamped to what the new layout can scroll, and only
+restored on an axis that still scrolls. That covers a resize, a filter, a restyle, and a new host
+created on the same element. The memory is keyed by the chart (its `code`, or the `renderFn`'s
+source text), so a different chart opens at the top, while a `renderFn` closure rebuilt on every draw
+is still the same chart. It lives on the element for the session
+only, and nothing is persisted. A page that manages the container's scrolling itself passes
+`restoreScroll: false` (the `restoreScroll` prop of `<BicChart>`), and then nothing is remembered or
+restored. A host that clears and fits its container on its own can use the same pieces:
+`rememberScroll` before the clear, `takeScroll` after the render, and `fitRenderedChart`'s
+`restoreScroll` option (or the pure `planScrollRestore`).
+
 ## Keeping a drawn chart readable inside its frame
 
 A generated chart cannot know how wide its own legend text will come out, where its tick labels will

package/dist/adapters.mjs

@@ -3,7 +3,7 @@ import {
   censusHitBands,
   ensureCrossfilterHitTargets,
   hitBandFlag
-} from "./chunk-XNS34AMM.mjs";
+} from "./chunk-PDVEIW42.mjs";
 import {
   clickWasDrag,
   collectD3GlyphCenters,
@@ -12,13 +12,13 @@ import {
   markKeyOf,
   rowIdxsFromMark,
   selectionRuleOf
-} from "./chunk-DJ5IJV57.mjs";
+} from "./chunk-VEVBXK44.mjs";
 import {
   AXIS_FILTER_CLASS,
   LEGEND_MARK_CLASS,
   MARK_CLASS,
   ROW_IDX_ATTR
-} from "./chunk-YDHXOIAI.mjs";
+} from "./chunk-45VILLJT.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/adapters/types.ts

package/dist/{chunk-YDHXOIAI.mjs → chunk-45VILLJT.mjs}

@@ -19,6 +19,7 @@ var CONTAINER_SLOT_ANIM_STOP = "__llmAnimStop";
 var CONTAINER_SLOT_XF_CLEAR = "__llmXfClear";
 var CONTAINER_SLOT_INITIAL_XF_MARK = "__llmInitialXfMark";
 var CONTAINER_SLOT_UI_STATE = "__lchUiState";
+var CONTAINER_SLOT_SCROLL = "__lchScroll";
 var CONTAINER_SLOT_CLICKED_MARKS = "__lchClickedMarks";
 var VIEW_ONLY_UI_STATE_KEYS = Object.freeze(["camera", "llmZoom"]);
 function withoutViewOnlyKeys(bag) {
@@ -89,6 +90,7 @@ export {
   CONTAINER_SLOT_XF_CLEAR,
   CONTAINER_SLOT_INITIAL_XF_MARK,
   CONTAINER_SLOT_UI_STATE,
+  CONTAINER_SLOT_SCROLL,
   CONTAINER_SLOT_CLICKED_MARKS,
   VIEW_ONLY_UI_STATE_KEYS,
   withoutViewOnlyKeys,

package/dist/{chunk-GOIG756B.mjs → chunk-CR7DSJVG.mjs}

@@ -1,7 +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 {
   LASSO_KNOB_KEY
-} from "./chunk-OG6RR2AJ.mjs";
+} from "./chunk-QHMLMF4L.mjs";
 
 // src/filterScope.ts
 function viewToken(view) {

package/dist/{chunk-562LF7XM.mjs → chunk-FHHT7DBM.mjs}

@@ -2,11 +2,11 @@
 import {
   LASSO_OUTLINE_CLASS,
   installLasso
-} from "./chunk-OG6RR2AJ.mjs";
+} from "./chunk-QHMLMF4L.mjs";
 import {
   censusHitBands,
   ensureCrossfilterHitTargets
-} from "./chunk-XNS34AMM.mjs";
+} from "./chunk-PDVEIW42.mjs";
 import {
   clearPress,
   clearSelectionGlyphs,
@@ -23,12 +23,14 @@ import {
   selectionRuleOf,
   trackPress,
   validRowSet
-} from "./chunk-DJ5IJV57.mjs";
+} from "./chunk-VEVBXK44.mjs";
 import {
   clipWindowOf,
   fitRenderedChart,
+  rememberScroll,
+  takeScroll,
   unpinScrolledAxis
-} from "./chunk-QHIPRAZK.mjs";
+} from "./chunk-NNLBFIWU.mjs";
 import {
   Fn,
   J3,
@@ -82,7 +84,7 @@ import {
   XFILTER_REFRESH_EVENT,
   chartOwnsTimeline,
   periodTickSuppressesFeedback
-} from "./chunk-YDHXOIAI.mjs";
+} from "./chunk-45VILLJT.mjs";
 
 // src/labelContrast.ts
 function parseRGBA(c) {
@@ -2521,6 +2523,20 @@ function createChartHost(container, config) {
       }
     }
   };
+  const keepScroll = config.restoreScroll !== false;
+  let chartSource;
+  const scrollKey = () => {
+    if (config.code) return config.code;
+    if (chartSource === void 0 && typeof config.renderFn === "function") {
+      try {
+        chartSource = Function.prototype.toString.call(config.renderFn);
+      } catch {
+        return config.renderFn;
+      }
+    }
+    return chartSource;
+  };
+  let hasRendered = false;
   const runPostRenderPasses = () => {
     if (zoomMemory && zoomCap) {
       try {
@@ -2608,9 +2624,11 @@ function createChartHost(container, config) {
       } catch {
       }
     }
+    const scrollMem = takeScroll(container);
     if (fitOpts !== false) {
       try {
-        const r = fitRenderedChart(container, fitOpts === true ? {} : fitOpts);
+        const base = fitOpts === true ? {} : fitOpts;
+        const r = fitRenderedChart(container, keepScroll ? { ...base, restoreScroll: { memory: scrollMem, key: scrollKey() } } : base);
         config.onFit?.(r);
       } catch {
       }
@@ -2649,7 +2667,9 @@ function createChartHost(container, config) {
       followGlyphs(false);
       disposeLasso();
       flushZoom();
+      if (hasRendered && keepScroll) rememberScroll(container, scrollKey());
       container.innerHTML = "";
+      hasRendered = true;
       if (!renderFn) {
         if (!config.code) throw new Error("createChartHost: provide code or renderFn");
         renderFn = compileRenderFn(config.code, win, doc, chartD3);
@@ -2816,6 +2836,7 @@ function createChartHost(container, config) {
         dimVarSet = false;
       }
       annotationLayer.destroy();
+      if (hasRendered && keepScroll) rememberScroll(container, scrollKey());
       unpinScrolledAxis(container);
       flushZoom();
       followGlyphs(false);

package/dist/{chunk-QHIPRAZK.mjs → chunk-NNLBFIWU.mjs}

@@ -1,7 +1,8 @@
 /*! @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 {
+  CONTAINER_SLOT_SCROLL,
   SNAPSHOT_SVG_ATTR
-} from "./chunk-YDHXOIAI.mjs";
+} from "./chunk-45VILLJT.mjs";
 
 // src/fit.ts
 var SCROLL_SLACK_PX = 8;
@@ -104,6 +105,15 @@ function axisPinPlacement(band, scrollTop, viewportH) {
   if (band.bottom > scrollTop + viewportH) return "bottom";
   return null;
 }
+var nonNegative = (n) => typeof n === "number" && isFinite(n) && n > 0 ? n : 0;
+function planScrollRestore(saved, key, m) {
+  if (!saved || key === void 0 || key === null || saved.key !== key) return { x: 0, y: 0 };
+  const room = (content, view) => Math.max(0, nonNegative(content) - nonNegative(view));
+  return {
+    x: m.overflowX === "auto" ? Math.min(nonNegative(saved.x), room(m.scrollWidth, m.clientWidth)) : 0,
+    y: m.overflowY === "auto" ? Math.min(nonNegative(saved.y), room(m.scrollHeight, m.clientHeight)) : 0
+  };
+}
 
 // src/fitDom.ts
 var FIT_WALK_CAP = 8e3;
@@ -256,6 +266,28 @@ function unpinScrolledAxis(container) {
   } catch {
   }
 }
+function rememberScroll(container, key) {
+  if (!container) return;
+  try {
+    const slot = container;
+    if (slot[CONTAINER_SLOT_SCROLL]) return;
+    if (container.querySelector(".llm-mm-scroll")) return;
+    const x = container.scrollLeft, y = container.scrollTop;
+    if (x > 0 || y > 0) slot[CONTAINER_SLOT_SCROLL] = { key, x, y };
+  } catch {
+  }
+}
+function takeScroll(container) {
+  if (!container) return null;
+  try {
+    const slot = container;
+    const m = slot[CONTAINER_SLOT_SCROLL] ?? null;
+    delete slot[CONTAINER_SLOT_SCROLL];
+    return m;
+  } catch {
+    return null;
+  }
+}
 function textHidden(t, view) {
   if (t.getAttribute("display") === "none" || t.getAttribute("visibility") === "hidden") return true;
   try {
@@ -476,7 +508,8 @@ function fitRenderedChart(container, opts = {}) {
     overflowX: "hidden",
     overflowY: "hidden",
     reading: null,
-    axisPin: noPin("no-container")
+    axisPin: noPin("no-container"),
+    scrolledTo: null
   };
   if (!container) return result;
   try {
@@ -537,6 +570,19 @@ function fitRenderedChart(container, opts = {}) {
     if (opts.applyOverflow !== false) {
       container.style.overflowX = fit.overflowX;
       container.style.overflowY = fit.overflowY;
+      if (opts.restoreScroll) {
+        const to = planScrollRestore(opts.restoreScroll.memory, opts.restoreScroll.key, {
+          scrollWidth: container.scrollWidth,
+          scrollHeight: container.scrollHeight,
+          clientWidth: container.clientWidth,
+          clientHeight: container.clientHeight,
+          overflowX: fit.overflowX,
+          overflowY: fit.overflowY
+        });
+        if (container.scrollLeft !== to.x) container.scrollLeft = to.x;
+        if (container.scrollTop !== to.y) container.scrollTop = to.y;
+        result.scrolledTo = to;
+      }
       if (fit.overflowY !== "auto") {
         unpinScrolledAxis(container);
         result.axisPin = noPin("not-scrolling");
@@ -571,12 +617,15 @@ export {
   labelBand,
   planAxisPin,
   axisPinPlacement,
+  planScrollRestore,
   ctmScaleOf,
   svgInkReach,
   clipWindowOf,
   measureContainerBoxes,
   fitReadingFor,
   unpinScrolledAxis,
+  rememberScroll,
+  takeScroll,
   pinScrolledAxis,
   fitRenderedChart
 };

package/dist/{chunk-XNS34AMM.mjs → chunk-PDVEIW42.mjs}

@@ -4,7 +4,7 @@ import {
   LEGEND_MARK_CLASS,
   MARK_CLASS,
   ROW_IDX_ATTR
-} from "./chunk-YDHXOIAI.mjs";
+} from "./chunk-45VILLJT.mjs";
 
 // src/hitTargets.ts
 var SVG_NS = "http://www.w3.org/2000/svg";

package/dist/{chunk-OG6RR2AJ.mjs → chunk-QHMLMF4L.mjs}

@@ -4,7 +4,7 @@ import {
   gestureWasDrag,
   isInsideControl,
   rowIdxsFromMark
-} from "./chunk-DJ5IJV57.mjs";
+} from "./chunk-VEVBXK44.mjs";
 import {
   AXIS_FILTER_CLASS,
   CONTROL_CLASS,
@@ -12,7 +12,7 @@ import {
   MARK_CLASS,
   ROW_IDX_ATTR,
   SNAPSHOT_SVG_ATTR
-} from "./chunk-YDHXOIAI.mjs";
+} from "./chunk-45VILLJT.mjs";
 
 // src/lasso.ts
 var LASSO_ROW_CAP = 5e3;

package/dist/{chunk-UBB5LNH4.mjs → chunk-VC3Z5CH7.mjs}

@@ -1,7 +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 {
   SNAPSHOT_SVG_ATTR
-} from "./chunk-YDHXOIAI.mjs";
+} from "./chunk-45VILLJT.mjs";
 
 // src/snapshot.ts
 var DEFAULT_TIMEOUT_MS = 2e3;

package/dist/{chunk-DJ5IJV57.mjs → chunk-VEVBXK44.mjs}

@@ -8,7 +8,7 @@ import {
   SELECTION_RULE_ATTR,
   SELECTION_RULE_CLICKED_MARKS,
   XFILTER_REFRESH_EVENT
-} from "./chunk-YDHXOIAI.mjs";
+} from "./chunk-45VILLJT.mjs";
 
 // src/selection.ts
 function rowIdxsFromMark(el) {

package/dist/index.mjs

@@ -15,7 +15,7 @@ import {
   svgNaturalSize,
   svgToDataUrl,
   tableHostOf
-} from "./chunk-UBB5LNH4.mjs";
+} from "./chunk-VC3Z5CH7.mjs";
 import {
   ANNOTATION_CLASS,
   ANNOTATION_LAYER_CLASS,
@@ -97,7 +97,7 @@ import {
   toRGBA,
   toSourceRows,
   valuePlacementFlag
-} from "./chunk-562LF7XM.mjs";
+} from "./chunk-FHHT7DBM.mjs";
 import {
   LASSO_AXES_SLOT,
   LASSO_COUNT_CLASS,
@@ -122,13 +122,13 @@ import {
   lassoVerdict,
   pointInShape,
   registerLassoAction
-} from "./chunk-OG6RR2AJ.mjs";
+} from "./chunk-QHMLMF4L.mjs";
 import {
   MIN_HIT_BAND_PX,
   censusHitBands,
   ensureCrossfilterHitTargets,
   hitBandFlag
-} from "./chunk-XNS34AMM.mjs";
+} from "./chunk-PDVEIW42.mjs";
 import {
   CONTAINER_SLOT_PRESS_AT,
   DRAG_NOT_CLICK_PX,
@@ -153,7 +153,7 @@ import {
   selectionRuleOf,
   trackPress,
   validRowSet
-} from "./chunk-DJ5IJV57.mjs";
+} from "./chunk-VEVBXK44.mjs";
 import {
   AXIS_PIN_BAND_PAD_PX,
   AXIS_PIN_MAX_BAND_FRACTION,
@@ -176,10 +176,13 @@ import {
   pinScrolledAxis,
   planAxisPin,
   planFrameGrow,
+  planScrollRestore,
+  rememberScroll,
   scrollFitFor,
   svgInkReach,
+  takeScroll,
   unpinScrolledAxis
-} from "./chunk-QHIPRAZK.mjs";
+} from "./chunk-NNLBFIWU.mjs";
 import {
   _3,
   l,
@@ -205,6 +208,7 @@ import {
   CONTAINER_SLOT_ANIM_STOP,
   CONTAINER_SLOT_CLICKED_MARKS,
   CONTAINER_SLOT_INITIAL_XF_MARK,
+  CONTAINER_SLOT_SCROLL,
   CONTAINER_SLOT_UI_STATE,
   CONTAINER_SLOT_XF_CLEAR,
   CONTROL_CLASS,
@@ -237,7 +241,7 @@ import {
   chartOwnsTimeline,
   periodTickSuppressesFeedback,
   withoutViewOnlyKeys
-} from "./chunk-YDHXOIAI.mjs";
+} from "./chunk-45VILLJT.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/optionsVocabulary.ts
@@ -2154,6 +2158,7 @@ export {
   CONTAINER_SLOT_CLICKED_MARKS,
   CONTAINER_SLOT_INITIAL_XF_MARK,
   CONTAINER_SLOT_PRESS_AT,
+  CONTAINER_SLOT_SCROLL,
   CONTAINER_SLOT_UI_STATE,
   CONTAINER_SLOT_XF_CLEAR,
   CONTROL_CLASS,
@@ -2393,6 +2398,7 @@ export {
   pinScrolledAxis,
   planAxisPin,
   planFrameGrow,
+  planScrollRestore,
   planSelectionPaint,
   planTrivialChart,
   pointInShape,
@@ -2429,6 +2435,7 @@ export {
   registerGeoAsset,
   registerLassoAction,
   relativeLuminance,
+  rememberScroll,
   requiredD3Plugins,
   resolveAutoColorScale,
   resolveOptions,
@@ -2455,6 +2462,7 @@ export {
   svgToDataUrl,
   syncMemberSelection,
   tableHostOf,
+  takeScroll,
   toRGBA,
   toSourceRows,
   trackPress,

package/dist/legend-fit.mjs

@@ -2,13 +2,13 @@
 import {
   chartSvgOf,
   tableHostOf
-} from "./chunk-UBB5LNH4.mjs";
+} from "./chunk-VC3Z5CH7.mjs";
 import {
   FIT_CONTENT_SELECTOR,
   ctmScaleOf,
   isPhantomBox
-} from "./chunk-QHIPRAZK.mjs";
-import "./chunk-YDHXOIAI.mjs";
+} from "./chunk-NNLBFIWU.mjs";
+import "./chunk-45VILLJT.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/legendFit/legendReconcile.ts

package/dist/page.mjs

@@ -14,10 +14,10 @@ import {
   readControls,
   viewFromToken,
   viewToken
-} from "./chunk-GOIG756B.mjs";
-import "./chunk-OG6RR2AJ.mjs";
-import "./chunk-DJ5IJV57.mjs";
-import "./chunk-YDHXOIAI.mjs";
+} from "./chunk-CR7DSJVG.mjs";
+import "./chunk-QHMLMF4L.mjs";
+import "./chunk-VEVBXK44.mjs";
+import "./chunk-45VILLJT.mjs";
 import "./chunk-GHODWOAL.mjs";
 export {
   LINKED_HOVER_CLASS,

package/dist/react.mjs

@@ -13,7 +13,7 @@ import {
   payloadRowReader,
   viewFromToken,
   viewToken
-} from "./chunk-GOIG756B.mjs";
+} from "./chunk-CR7DSJVG.mjs";
 import {
   assembleD3,
   createChartGroup,
@@ -22,14 +22,14 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-562LF7XM.mjs";
-import "./chunk-OG6RR2AJ.mjs";
-import "./chunk-XNS34AMM.mjs";
-import "./chunk-DJ5IJV57.mjs";
-import "./chunk-QHIPRAZK.mjs";
+} from "./chunk-FHHT7DBM.mjs";
+import "./chunk-QHMLMF4L.mjs";
+import "./chunk-PDVEIW42.mjs";
+import "./chunk-VEVBXK44.mjs";
+import "./chunk-NNLBFIWU.mjs";
 import "./chunk-KQN5C7SZ.mjs";
 import "./chunk-A2GMXZP7.mjs";
-import "./chunk-YDHXOIAI.mjs";
+import "./chunk-45VILLJT.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/react.tsx
@@ -69,6 +69,7 @@ function BicChart(props) {
     viewState,
     zoomMemory,
     labelContrast,
+    restoreScroll,
     onLabelContrast,
     onSelectionGlyphs,
     layoutPass,
@@ -157,6 +158,7 @@ function BicChart(props) {
       zoomMemory,
       labelContrast,
       layoutPass,
+      restoreScroll,
       onLabelContrast: (r) => onLabelContrastRef.current?.(r),
       onSelectionGlyphs: (r) => onSelectionGlyphsRef.current?.(r),
       // A GETTER, not a wrapper: the host decides whether to
@@ -189,7 +191,7 @@ function BicChart(props) {
       host.destroy();
       hostRef.current = null;
     };
-  }, [code, renderFn, d3, geoKind, labelContrast, layoutPass, controls]);
+  }, [code, renderFn, d3, geoKind, labelContrast, layoutPass, restoreScroll, controls]);
   useLayoutEffect(() => {
     const host = hostRef.current;
     if (!host || !selects) return;
@@ -215,7 +217,7 @@ function BicChart(props) {
       b.detach();
       if (bindingRef.current === b) bindingRef.current = null;
     };
-  }, [selects, code, renderFn, d3, geoKind, labelContrast, layoutPass]);
+  }, [selects, code, renderFn, d3, geoKind, labelContrast, layoutPass, restoreScroll]);
   useEffect(() => {
     if (!hostRef.current || !options) return;
     if (builtWithRef.current?.optKey === optKey) return;

package/dist/testing.mjs

@@ -4,7 +4,7 @@ import {
   MARK_CLASS,
   MARK_SELECTED_CLASS,
   ROW_IDX_ATTR
-} from "./chunk-YDHXOIAI.mjs";
+} from "./chunk-45VILLJT.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/testing/interact.ts

package/dist/types/contract.d.ts

@@ -35,6 +35,7 @@ export declare const CONTAINER_SLOT_ANIM_STOP = "__llmAnimStop";
 export declare const CONTAINER_SLOT_XF_CLEAR = "__llmXfClear";
 export declare const CONTAINER_SLOT_INITIAL_XF_MARK = "__llmInitialXfMark";
 export declare const CONTAINER_SLOT_UI_STATE = "__lchUiState";
+export declare const CONTAINER_SLOT_SCROLL = "__lchScroll";
 export declare const CONTAINER_SLOT_CLICKED_MARKS = "__lchClickedMarks";
 export declare const VIEW_ONLY_UI_STATE_KEYS: readonly string[];
 /** The bag with every view-only key removed: what a host persists when the reader has not asked

package/dist/types/fit.d.ts

@@ -90,3 +90,26 @@ export type AxisPinEdge = "top" | "bottom";
  * one drawn over it.
  */
 export declare function axisPinPlacement(band: AxisBand, scrollTop: number, viewportH: number): AxisPinEdge | null;
+/** A reader's scroll offsets and the identity of the chart they were made on. */
+export interface ScrollMemory {
+    key: unknown;
+    x: number;
+    y: number;
+}
+/** What the container reports once the overflow is decided. */
+export interface ScrollMetrics {
+    scrollWidth: number;
+    scrollHeight: number;
+    clientWidth: number;
+    clientHeight: number;
+    overflowX: string;
+    overflowY: string;
+}
+/**
+ * Where the scroll goes after a redraw. The saved offsets when the SAME chart is back, clamped to what the new layout can scroll and
+ * applied per axis only where the container scrolls; otherwise the origin. A new chart opens at the top.
+ */
+export declare function planScrollRestore(saved: ScrollMemory | null | undefined, key: unknown, m: ScrollMetrics): {
+    x: number;
+    y: number;
+};

package/dist/types/fitDom.d.ts

@@ -1,4 +1,4 @@
-import type { ContentExtent, MeasuredBox, AxisPinEdge } from "./fit";
+import type { ContentExtent, MeasuredBox, AxisPinEdge, ScrollMemory } from "./fit";
 export declare function ctmScaleOf(m: {
     a: number;
     b: number;
@@ -59,6 +59,16 @@ export interface FitRenderedChartOptions {
      * Set false for a host that draws its own sticky header.
      */
     pinAxis?: boolean;
+    /**
+     * Put the reader's scroll back once the overflow is decided: `memory` (what `takeScroll` handed
+     * back) is restored only when its key is `key`, the chart now drawn, clamped to what the new
+     * layout can scroll and only on an axis that scrolls. Applied before the axis pin, which places
+     * its copy from the scroll it finds. Absent, the container is left where the render put it.
+     */
+    restoreScroll?: {
+        memory: ScrollMemory | null;
+        key: unknown;
+    };
 }
 export interface FitRenderedChartResult {
     /** The frame was grown, so content that was being clipped is now painted. */
@@ -73,6 +83,11 @@ export interface FitRenderedChartResult {
     reading: FitReading | null;
     /** The axis pin: what was pinned when the container scrolls, or why nothing was. */
     axisPin: AxisPinReport;
+    /** Where `restoreScroll` put the container ({0,0} for a different chart), or null when it was not asked or the overflow was not applied. */
+    scrolledTo: {
+        x: number;
+        y: number;
+    } | null;
 }
 export interface AxisPinReport {
     pinned: boolean;
@@ -94,5 +109,13 @@ export interface AxisPinReport {
  *  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;
+/**
+ * Remember where the container is scrolled, BEFORE the container is cleared. A memory already waiting is kept: a second render that
+ * starts before the first one restored sees an emptied (unscrolled) container, and must not overwrite what the reader really did.
+ * A diagram that scrolls inside itself remembers its own position, so it is left alone.
+ */
+export declare function rememberScroll(container: HTMLElement | null | undefined, key: unknown): void;
+/** The waiting memory, removed. The one place it is consumed, so a stale memory can never outlive a render. */
+export declare function takeScroll(container: HTMLElement | null | undefined): ScrollMemory | null;
 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/host.d.ts

@@ -181,6 +181,15 @@ export interface ChartHostConfig {
      * reading without touching the chart (`grow: false`, `applyOverflow: false`).
      */
     fit?: boolean | FitRenderedChartOptions;
+    /**
+     * KEEP THE READER'S SCROLL when the SAME chart is drawn again - a resize, a filter, a theme
+     * switch, or a new host on the same element. Default true: the offset is parked on the
+     * container before each clear and put back by the fit, clamped to what the new layout can
+     * scroll; a different chart (other code, or a renderFn with other source) opens at the top. Pass `false`
+     * for a page that manages the container's scrolling itself: nothing is remembered or restored,
+     * and a memory an earlier host left on the element is discarded at the next render.
+     */
+    restoreScroll?: boolean;
     /** The fit result after each render - what was grown, and how the chart measured. */
     onFit?: (result: FitRenderedChartResult) => void;
     /**

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, DIM_OPACITY_MIN, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, type XfilterRefreshDetail, } from "./contract";
+export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, CONTAINER_SLOT_SCROLL, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, DIM_OPACITY_MIN, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, type XfilterRefreshDetail, } from "./contract";
 export { resolveOptions, type ResolveOptionsInput } from "./defaults";
 export { OPTIONS_VOCABULARY, LIVE_OPTION_KEYS, MAX_MAP_POINTS_MIN, MAX_MAP_POINTS_MAX, LIMIT_COUNT_MAX, wireLimitCount, codeReadsOption, type OptionVocabularyEntry, type OptionTiming, type OptionWire, type OptionKey, } from "./optionsVocabulary";
 export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clearGeoCache, type GeoAssetName, } from "./geoLazy";
@@ -42,6 +42,8 @@ export { SCROLL_SLACK_PX, MAX_FRAME_GROW_FACTOR, PHANTOM_FRACTION, FIT_CONTENT_S
 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";
+export { planScrollRestore, type ScrollMemory, type ScrollMetrics } from "./fit";
+export { rememberScroll, takeScroll } from "./fitDom";
 export { MIN_DELTA_E, pickDistinctColorFromSeed, buildPalette, buildPaletteFromSeed, orderMostDistinct, LEGIBLE_LIGHTNESS, type PaletteResult, type SeedForSlot, type PaletteOptions, } from "./palette";
 export { deltaEHex } from "./deltaE";
 export { resolveAutoColorScale, autoRampMinStep, autoRampCanvas, AUTO_RAMP_CLASSES, AUTO_RAMP_DRAWN_OPACITY, AUTO_RAMP_MIN_STEP_DELTA_E, type AutoColorScale, type AutoColorScaleInput } from "./autoRamp";

package/dist/types/react.d.ts

@@ -46,6 +46,12 @@ export interface BicChartProps {
      * themed page is not white, and readability is measured against it. See createChartHost.
      */
     labelContrast?: ChartHostConfig["labelContrast"];
+    /**
+     * KEEP THE READER'S SCROLL when the same chart repaints (new data, new options, a rebuild).
+     * Default on; a different chart opens at the top. Pass `false` for a page that manages the
+     * chart's scrolling itself. Host config: changing it rebuilds the host. See createChartHost.
+     */
+    restoreScroll?: ChartHostConfig["restoreScroll"];
     /** What the label-contrast pass did after each render - counts, for a page that logs. */
     onLabelContrast?: ChartHostConfig["onLabelContrast"];
     /** What the selection-glyph pass did after each paint, when `options.selectionGlyph` is set - counts, for a page

package/package.json

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