@bicharts/chart-host 0.5.49 → 0.5.51

package/dist/{chunk-OSJNZVRA.mjs → chunk-B4RZSFAC.mjs}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-A2GMXZP7.mjs";
 
 // src/contract.ts
-var HOST_CONTRACT_VERSION = "1.5.0";
+var HOST_CONTRACT_VERSION = "1.6.0";
 var GEO_POINT_PRECISIONS = ["latlon", "city", "zip3", "state", "country"];
 var MARK_CLASS = "d3-mark";
 var LEGEND_MARK_CLASS = "d3-legend-mark";
@@ -1197,6 +1197,23 @@ function blankRenderFlag(lang, cause) {
 }
 
 // src/host.ts
+function sessionViewStateProvider(container) {
+  const holder = container;
+  const existing = holder[CONTAINER_SLOT_UI_STATE];
+  const store = existing && typeof existing === "object" ? existing : holder[CONTAINER_SLOT_UI_STATE] = {};
+  return {
+    load: () => store,
+    save: (next) => {
+      if (!next || typeof next !== "object") return;
+      for (const k2 of Object.keys(store)) delete store[k2];
+      Object.assign(store, next);
+    }
+  };
+}
+function noopViewStateProvider() {
+  return { load: () => ({}), save: () => {
+  } };
+}
 var parseRowIdxs = (s) => (s || "").split(",").map((x2) => parseInt(x2, 10)).filter((n) => Number.isFinite(n));
 var D3_PLUGIN_PACKAGES = {
   sankey: "d3-sankey",
@@ -1280,16 +1297,22 @@ function createChartHost(container, config) {
   }
   let raw = { ...config.options ?? {} };
   if (typeof raw.setUiState !== "function") {
-    const holder = container;
-    const existing = holder[CONTAINER_SLOT_UI_STATE];
-    const store = existing && typeof existing === "object" ? existing : holder[CONTAINER_SLOT_UI_STATE] = {};
-    if (raw.uiState && typeof raw.uiState === "object" && Object.keys(store).length === 0)
-      Object.assign(store, raw.uiState);
-    raw.uiState = store;
+    const provider = config.viewState ?? sessionViewStateProvider(container);
+    let bag;
+    try {
+      bag = provider.load() ?? {};
+    } catch {
+      bag = {};
+    }
+    if (raw.uiState && typeof raw.uiState === "object" && Object.keys(bag).length === 0)
+      Object.assign(bag, raw.uiState);
+    raw.uiState = bag;
     raw.setUiState = (s) => {
       if (!s || typeof s !== "object") return;
-      for (const k2 of Object.keys(store)) delete store[k2];
-      Object.assign(store, s);
+      try {
+        provider.save(s);
+      } catch {
+      }
     };
   }
   let resolved = resolveOptions(raw);
@@ -1587,6 +1610,8 @@ export {
   censusMarks,
   isBlankRender,
   blankRenderFlag,
+  sessionViewStateProvider,
+  noopViewStateProvider,
   requiredD3Plugins,
   explainRenderFailure,
   stripEsmExports,

package/dist/index.mjs

@@ -48,13 +48,15 @@ import {
   geoFromCache,
   isBlankRender,
   loadGeo,
+  noopViewStateProvider,
   periodTickSuppressesFeedback,
   registerGeo,
   registerGeoAsset,
   requiredD3Plugins,
   resolveOptions,
+  sessionViewStateProvider,
   stripEsmExports
-} from "./chunk-OSJNZVRA.mjs";
+} from "./chunk-B4RZSFAC.mjs";
 import "./chunk-A2GMXZP7.mjs";
 
 // src/trivial.ts
@@ -923,6 +925,7 @@ export {
   loadGeo,
   newQualifyGroupState,
   newQualifyRefusalGroupState,
+  noopViewStateProvider,
   normaliseAggregation,
   orderRefusalsForDisplay,
   periodTickSuppressesFeedback,
@@ -940,6 +943,7 @@ export {
   registerGeoAsset,
   requiredD3Plugins,
   resolveOptions,
+  sessionViewStateProvider,
   shouldOpenChooserOnGenerate,
   shouldOpenInlineChooserOnGenerate,
   shouldReview,

package/dist/react.mjs

@@ -4,7 +4,7 @@ import {
   createChartHost,
   geoFromCache,
   loadGeo
-} from "./chunk-OSJNZVRA.mjs";
+} from "./chunk-B4RZSFAC.mjs";
 import "./chunk-A2GMXZP7.mjs";
 
 // src/react.tsx
@@ -49,6 +49,7 @@ function BicChart(props) {
     options,
     d3,
     geoKind,
+    viewState,
     id,
     filteredBy,
     respondsWith,
@@ -89,7 +90,7 @@ function BicChart(props) {
   useLayoutEffect(() => {
     const el = ref.current;
     if (!el || !code && !renderFn || !data) return;
-    const host = createChartHost(el, { code, renderFn, data, options, d3, geoKind });
+    const host = createChartHost(el, { code, renderFn, data, options, d3, geoKind, viewState });
     hostRef.current = host;
     const off = host.selection.onChange((payloadIdxs, source) => {
       if (source === "host") return;

package/dist/types/contract.d.ts

@@ -1,4 +1,4 @@
-export declare const HOST_CONTRACT_VERSION = "1.5.0";
+export declare const HOST_CONTRACT_VERSION = "1.6.0";
 export type GeoPointPrecision = "latlon" | "city" | "zip3" | "state" | "country";
 /** Every valid tier, ordered most precise → coarsest. Runtime form of GeoPointPrecision. */
 export declare const GEO_POINT_PRECISIONS: readonly GeoPointPrecision[];
@@ -16,6 +16,32 @@ 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";
+/**
+ * WHERE A CHART'S RESTING VIEW-STATE LIVES between draws (contract 1.6.0).
+ *
+ * Generated code never sees this. It keeps reading `options.uiState` and calling
+ * `options.setUiState(bag)`; `createChartHost` is what binds that pair to a provider. The seam
+ * exists because the answer genuinely differs per host: a Power BI visual persists into the
+ * report file so every viewer lands on the author's view, an Excel add-in persists into the
+ * workbook that travels with the sheet, a React page has only the session, and a static preview
+ * has nowhere at all. Before this, the first of those was a raw function pair passed by one
+ * caller and every other host got a session store hard-coded in the host runtime.
+ *
+ * IMPLEMENTORS: `load()` must never throw and returns `{}` when nothing is stored — a chart must
+ * never be blocked from drawing by a storage failure. `save()` takes the WHOLE new bag (REPLACE
+ * semantics, matching setUiState) and MAY DEBOUNCE; a drag emits hundreds of repaints and no
+ * host's persistence layer is a frame buffer.
+ *
+ * READERS: whatever comes back is UNTRUSTED. It may have been written by a previous generation of
+ * the chart, by a different chart on the same element, or by a person editing a file. Validate and
+ * clamp every value you read; a key you do not recognise is not an error, it is someone else's.
+ */
+export interface ViewStateProvider {
+    /** The stored bag, or {} when there is none. Never throws. */
+    load(): Record<string, unknown>;
+    /** Replace the stored bag. May debounce internally. */
+    save(next: Record<string, unknown>): void;
+}
 export declare const HOST_CONTAINER_CLASS = "bic-chart-host";
 export declare const SELECTION_ACTIVE_CLASS = "lch-has-selection";
 export declare const MARK_SELECTED_CLASS = "lch-mark-selected";

package/dist/types/host.d.ts

@@ -1,7 +1,29 @@
-import { type RenderOptions } from "./contract";
+import { type RenderOptions, type ViewStateProvider } from "./contract";
 import { type ResolveOptionsInput } from "./defaults";
 import { type MarkCensus } from "./blankRender";
 export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
+/**
+ * THE SESSION PROVIDER — what every host got hard-coded before contract 1.6.0, now named.
+ *
+ * The bag is parked on the CONTAINER ELEMENT, which outlives the host object in every host that
+ * destroys and re-creates itself on the same node — the Excel add-in does exactly that on every
+ * resize and every cell edit, so a chart's resting knob used to reset whenever the pane moved.
+ * It dies with the element, which is precisely the scope "session" means here.
+ *
+ * `load()` returns the LIVE store, and `save()` mutates it in place rather than replacing the
+ * object, so a caller holding the bag from before a save still sees the current values. That is
+ * the 1.5.0 behaviour preserved exactly.
+ */
+export declare function sessionViewStateProvider(container: HTMLElement): ViewStateProvider;
+/**
+ * NOWHERE TO PUT IT, said out loud. For a host with no session to speak of — a server-side
+ * render, a static preview, a thumbnail capture — where remembering would be wrong rather than
+ * merely absent: a thumbnail must be the same picture every time it is taken.
+ *
+ * Deliberately not the same as omitting a provider. Omitting one gets the session store and a
+ * chart that remembers within the page; choosing this one says the forgetting is the point.
+ */
+export declare function noopViewStateProvider(): ViewStateProvider;
 export interface ChartHostConfig {
     data: {
         columns: any[];
@@ -28,6 +50,10 @@ export interface ChartHostConfig {
     renderFn?: RenderFn;
     /** Partial raw options; resolveOptions applies the shared defaults/clamps. */
     options?: ResolveOptionsInput;
+    /** WHERE this host keeps a chart's resting view-state (contract 1.6.0). Omit for the
+     *  session store parked on the container — the behaviour every host had before 1.6.0.
+     *  A raw `options.setUiState` still wins over this, so an existing caller is untouched. */
+    viewState?: ViewStateProvider;
     /** D3 v7 instance handed to the compiled code. Default: (globalThis as any).d3. */
     d3?: any;
     /** Attach geometry for this geoKind as options.geo (choropleths / basemaps). Resolved

package/dist/types/index.d.ts

@@ -1,11 +1,11 @@
-export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, 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, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type ColorScaleScope, type RenderOptions, } from "./contract";
+export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, 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, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type ColorScaleScope, type RenderOptions, type ViewStateProvider, } from "./contract";
 export { resolveOptions, type ResolveOptionsInput } from "./defaults";
 export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clearGeoCache, type GeoAssetName, } from "./geoLazy";
 /** REPLACE the bundled city gazetteer with another packed table. Rarely needed — see the
  *  note above registerCityTable in shape-core's geoPoint.ts before using it. */
 export declare function registerCityTable(packed: string): void;
 export { buildRenderPayload, type RenderPayload, type GeoPointBinding } from "./payload";
-export { createChartHost, compileRenderFn, stripEsmExports, requiredD3Plugins, explainRenderFailure, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
+export { createChartHost, compileRenderFn, stripEsmExports, requiredD3Plugins, explainRenderFailure, sessionViewStateProvider, noopViewStateProvider, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
 export { createMarkResolver, type MarkResolver, type MarkResolverEnv } from "./selection";
 export { planTrivialChart, compileTrivialSource, type TrivialPlan, type TrivialShapeKind } from "./trivial";
 export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngDataUrl, type SnapshotOptions } from "./snapshot";

package/dist/types/react.d.ts

@@ -15,6 +15,16 @@ export interface BicChartProps {
     d3: any;
     /** Attach the bundled geometry for this kind as options.geo (choropleth or basemap). */
     geoKind?: string;
+    /**
+     * WHERE THIS APP KEEPS THE CHART'S RESTING VIEW-STATE - a sort, an expanded row, a 3D
+     * camera. Omit for the session store parked on the container element, which is the right
+     * answer for most pages: the chart remembers while it is mounted and forgets on reload.
+     *
+     * Supply one to outlive the page. A React app is the host that most often has somewhere
+     * better to put it - localStorage, a URL query, a user profile on the server - and no
+     * default could pick between them, which is why this is a prop rather than a flag.
+     */
+    viewState?: ChartHostConfig["viewState"];
     /** Identity within a <BicChartGroup> — the key other charts filter by. */
     id?: string;
     /** Take this group member's selection as a filter on THIS chart's rows. */

package/package.json

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