@bicharts/chart-host 0.5.48 → 0.5.50

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
@@ -580,6 +582,34 @@ function qualifyGroupHeadingFor(row, state) {
   }
   return null;
 }
+function newQualifyRefusalGroupState() {
+  return { poorFit: false, cannotDraw: false };
+}
+function refusalIsSelectable(row) {
+  return !!row && row.isVeto !== true;
+}
+function orderRefusalsForDisplay(rows) {
+  if (!Array.isArray(rows)) return [];
+  const named = rows.filter((r) => !!r && typeof r.name === "string" && r.name.trim() !== "");
+  return [...named.filter(refusalIsSelectable), ...named.filter((r) => !refusalIsSelectable(r))];
+}
+function qualifyRefusalHeadingFor(row, state) {
+  if (refusalIsSelectable(row)) {
+    if (!state.poorFit) {
+      state.poorFit = true;
+      return "poorFit";
+    }
+    return null;
+  }
+  if (!state.cannotDraw) {
+    state.cannotDraw = true;
+    return "cannotDraw";
+  }
+  return null;
+}
+function hasRefusalsToShow(rows) {
+  return orderRefusalsForDisplay(rows).length > 0;
+}
 
 // src/qualifyLaunch.ts
 var qualifyPick = (chartType) => ({ kind: "pick", chartType });
@@ -888,12 +918,16 @@ export {
   explainRenderFailure,
   geoAssetFor,
   geoFromCache,
+  hasRefusalsToShow,
   isBlankRender,
   launchFavorStyle,
   launchGenerates,
   loadGeo,
   newQualifyGroupState,
+  newQualifyRefusalGroupState,
+  noopViewStateProvider,
   normaliseAggregation,
+  orderRefusalsForDisplay,
   periodTickSuppressesFeedback,
   planTrivialChart,
   qualifyAuto,
@@ -901,12 +935,15 @@ export {
   qualifyFailureFallsOpen,
   qualifyGroupHeadingFor,
   qualifyPick,
+  qualifyRefusalHeadingFor,
   rasterizeSvgToPngDataUrl,
+  refusalIsSelectable,
   registerCityTable,
   registerGeo,
   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

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,17 +1,17 @@
-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";
 export { shouldReview, buildReviewWire, bareBase64, actionFor, type ReviewGate, type ReviewWire, type ReviewVerdict, type ReviewAction } from "./review";
 export { askApplyImprovements, type ReviewDialogOptions, type ReviewDialogText } from "./reviewDialog";
-export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, } from "./qualifyGroups";
+export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, orderRefusalsForDisplay, refusalIsSelectable, hasRefusalsToShow, qualifyRefusalHeadingFor, newQualifyRefusalGroupState, type QualifyRefusalRow, type QualifyRefusalGroupState, type QualifyRefusalHeading, } from "./qualifyGroups";
 export { qualifyPick, qualifyAuto, qualifyCancel, launchGenerates, launchFavorStyle, chooserFitsViewport, shouldOpenChooserOnGenerate, shouldOpenInlineChooserOnGenerate, canConfirmLaunch, confirmLaunch, qualifyFailureFallsOpen, CHOOSER_MIN_WIDTH_PX, CHOOSER_MIN_HEIGHT_PX, type QualifyLaunchOutcome, type ChooserGateInput, } from "./qualifyLaunch";
 export { computeSelectionCard, normaliseAggregation, type SelectionCardModel, type SelectionCardLine, type SelectionCardOptions, } from "./selectionCard";
 export { ensureCrossfilterHitTargets, type HitTargetReport } from "./hitTargets";

package/dist/types/qualifyGroups.d.ts

@@ -29,3 +29,54 @@ export declare function newQualifyGroupState(): QualifyGroupState;
  *  3. "projected" and 4. "notRecommended" are unchanged from the single-host original.
  */
 export declare function qualifyGroupHeadingFor(row: QualifyGroupRow, state: QualifyGroupState): QualifyGroupHeading | null;
+/** One row of a qualify result's `refused` array, in the only shape this logic cares about. */
+export interface QualifyRefusalRow {
+    name?: string | null;
+    /** The gate's sentence. Absent is a real answer — the blocker rested on a runtime signal. */
+    reason?: string | null;
+    /** True = a required channel is ABSENT. Absent/false = a threshold we are willing to waive. */
+    isVeto?: boolean | null;
+}
+/** Which heading to write BEFORE a refused row, if any. */
+export type QualifyRefusalHeading = "poorFit" | "cannotDraw";
+/** Carried across the refusal loop. One per render. */
+export interface QualifyRefusalGroupState {
+    poorFit: boolean;
+    cannotDraw: boolean;
+}
+export declare function newQualifyRefusalGroupState(): QualifyRefusalGroupState;
+/**
+ * MAY THE READER PICK THIS ONE? The single place that answers it, in either host.
+ *
+ * DEFAULTS TO YES, and the asymmetry is deliberate. An older server sends no `isVeto` at all, so
+ * every row reads selectable and the reader is offered something that may be refused — one wasted
+ * click, and the refusal that follows names its own reason. The opposite default would hide charts
+ * from readers on exactly the servers that cannot tell us it is wrong to.
+ */
+export declare function refusalIsSelectable(row: QualifyRefusalRow | null | undefined): boolean;
+/**
+ * The refused rows in RENDER ORDER: everything pickable first, then the vetoes.
+ *
+ * A STABLE PARTITION, not a sort — within each block the server's alphabetical order survives, so
+ * two answers over the same shape stay diffable. Rows without a name are dropped: a control
+ * labelled with nothing cannot be chosen and a reason with no subject cannot be read.
+ *
+ * The two blocks are ordered pickable-first because the reader opened this section to DO something.
+ * Putting the inert half above the actionable half makes them scroll past every chart they cannot
+ * have to reach the ones they can.
+ */
+export declare function orderRefusalsForDisplay<T extends QualifyRefusalRow>(rows: readonly T[] | null | undefined): T[];
+/**
+ * The heading (if any) belonging immediately before `row`, MUTATING `state` — same shape as
+ * `qualifyGroupHeadingFor` so the two loops read alike.
+ *
+ * Assumes `rows` came through `orderRefusalsForDisplay`; fed an unpartitioned list it would write
+ * a heading at every alternation, which is why the ordering and the headings are one export pair
+ * rather than two independent helpers a host can half-adopt.
+ */
+export declare function qualifyRefusalHeadingFor(row: QualifyRefusalRow, state: QualifyRefusalGroupState): QualifyRefusalHeading | null;
+/**
+ * Is there anything behind "Show all chart types"? A checkbox that reveals nothing is worse than
+ * no checkbox: it reads as a broken control rather than an empty category.
+ */
+export declare function hasRefusalsToShow(rows: readonly QualifyRefusalRow[] | null | undefined): boolean;

package/package.json

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