@bicharts/chart-host 0.5.118 → 0.5.120

package/dist/index.mjs

@@ -64,6 +64,7 @@ import {
   SELECTION_ACTIVE_CLASS,
   VALUE_AXIS_BASELINE_DEFAULT,
   VALUE_AXIS_MIN_FIT,
+  VIEW_ONLY_UI_STATE_KEYS,
   WHITE_TEXT_BG_LUM,
   XFILTER_REFRESH_EVENT,
   Xt,
@@ -126,11 +127,13 @@ import {
   scrollFitFor,
   sessionViewStateProvider,
   stripEsmExports,
+  stripJsComments,
   svgInkReach,
   toRGBA,
   unpinScrolledAxis,
-  valuePlacementFlag
-} from "./chunk-2UU3N4AG.mjs";
+  valuePlacementFlag,
+  withoutViewOnlyKeys
+} from "./chunk-CNFVXCOY.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -1391,6 +1394,11 @@ function aggLabel(agg) {
       return "Sum";
   }
 }
+function measureLineLabel(agg, name2) {
+  const col = String(name2 ?? "");
+  const prefix = aggLabel(agg) + " of ";
+  return col.trim().toLowerCase().startsWith(prefix.toLowerCase()) ? col.trim() : prefix + col;
+}
 function isSynthetic(name2) {
   return String(name2 ?? "").startsWith(SYNTHETIC_PREFIX);
 }
@@ -1542,7 +1550,7 @@ function computeSelectionCard(payload, selectedRowIdxs, opts = {}) {
     }
     lines.push({
       column: String(col?.name ?? ""),
-      label: `${aggLabel(colAgg)} of ${col?.name ?? ""}`,
+      label: measureLineLabel(colAgg, String(col?.name ?? "")),
       value,
       valueText: value == null ? "\u2014" : fmtNumber(value, opts.cultureCode),
       sharePct,
@@ -2343,6 +2351,30 @@ function pendingRecoveryRemainingMs(m2, nowMs) {
 function transportFailureShouldRecover(headersReceived, genNew) {
   return headersReceived && genNew;
 }
+var TRANSPORT_LOST_CHECKING_MESSAGE = "The connection dropped while your chart was being generated - checking whether it finished on the server...";
+var GENERATION_CANCELLED_MESSAGE = "The connection dropped before the chart finished - nothing was charged. Generate again.";
+function recoveryAnswerIsCancelled(r2) {
+  return !!r2 && r2.isGenerationCancelled === true;
+}
+function generationCancelledMessage(serverMessage) {
+  const s2 = String(serverMessage ?? "").trim();
+  return s2 !== "" ? s2 : GENERATION_CANCELLED_MESSAGE;
+}
+
+// src/chartPick.ts
+function reconcileChartPick(pick, offered, autoLabel) {
+  const want = String(pick ?? "").trim();
+  if (!want) return { pick: "", dropped: false, message: "" };
+  const names = (offered || []).map((n2) => String(n2 ?? "").trim()).filter((n2) => n2 !== "");
+  if (names.length === 0) return { pick: want, dropped: false, message: "" };
+  const key = want.toLowerCase();
+  if (names.some((n2) => n2.toLowerCase() === key)) return { pick: want, dropped: false, message: "" };
+  return {
+    pick: "",
+    dropped: true,
+    message: `${want} no longer fits this selection, so the chart type is back to "${autoLabel}". Pick another from the list if you want to force one.`
+  };
+}
 
 // src/index.ts
 function registerCityTable(packed) {
@@ -2387,6 +2419,7 @@ export {
   FILTER_ROW_PX,
   FIT_CONTENT_SELECTOR,
   FLIP_MODE_DEFAULT,
+  GENERATION_CANCELLED_MESSAGE,
   GEO_POINT_PRECISIONS,
   GLYPH_SAMPLE_N,
   HOST_CONTAINER_CLASS,
@@ -2426,8 +2459,10 @@ export {
   SCROLL_SLACK_PX,
   SEASONAL_MARKERS_DEFAULT,
   SELECTION_ACTIVE_CLASS,
+  TRANSPORT_LOST_CHECKING_MESSAGE,
   VALUE_AXIS_BASELINE_DEFAULT,
   VALUE_AXIS_MIN_FIT,
+  VIEW_ONLY_UI_STATE_KEYS,
   WHITE_TEXT_BG_LUM,
   XFILTER_REFRESH_EVENT,
   actionFor,
@@ -2480,6 +2515,7 @@ export {
   fitRenderedChart,
   formatSourceDate,
   formatSourceDateFor,
+  generationCancelledMessage,
   geoAssetFor,
   geoFromCache,
   glyphSampleGrid,
@@ -2537,6 +2573,8 @@ export {
   rasterizeSvgToPngDataUrl,
   readQualifyChartRow,
   readQualifyRefusalRow,
+  reconcileChartPick,
+  recoveryAnswerIsCancelled,
   recoveryOwnsTheSentence,
   recoveryPollRunning,
   refusalIsSelectable,
@@ -2555,6 +2593,7 @@ export {
   shouldOpenInlineChooserOnGenerate,
   shouldReview,
   stripEsmExports,
+  stripJsComments,
   svgInkReach,
   svgNaturalSize,
   svgToDataUrl,
@@ -2562,5 +2601,6 @@ export {
   transportFailureShouldRecover,
   unpinScrolledAxis,
   valuePlacementFlag,
-  vegaSpecReadsDatesInLocalTime
+  vegaSpecReadsDatesInLocalTime,
+  withoutViewOnlyKeys
 };

package/dist/react.mjs

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

package/dist/types/chartPick.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A standing chart-type pick, checked against a FRESH qualify list.
+ *
+ * A reader's explicit pick can outlive the generate it was made for - a host that keeps it across a
+ * refusal that spent nothing, or one whose pick is a standing control by design. Either way the fields
+ * can change underneath it, and a pick the data no longer supports would otherwise cost a generate to
+ * discover: the substitution warning arrives after the credit, not before it.
+ *
+ * ONLY AGAINST A FRESH LIST, and only against the server's own answer. The list is what the qualify
+ * endpoint says fits the data as it is now; checking the pick against a client-side re-implementation of
+ * the shape gates would be a second opinion quietly disagreeing with the engine.
+ *
+ * AN EMPTY LIST IS NOT EVIDENCE THE PICK DIED. It is the shape qualifying for nothing, which has its own
+ * message and its own fix; dropping the pick there would add a second, misleading sentence.
+ *
+ * A DROP IS ALWAYS SAID. The message names the type and what the pick went back to, so a pick never
+ * disappears silently. `offered` is every name the host would let the reader pick right now - a host whose
+ * list also offers poor-fit types to pick anyway passes those too, because the pick is still choosable.
+ */
+export interface ChartPickReconciliation {
+    /** The pick after reconciling: the original (trimmed) when still offered, else "" (no pick). */
+    pick: string;
+    /** True when a pick was dropped because the fresh list no longer offers it. */
+    dropped: boolean;
+    /** What to tell the reader when `dropped`; "" otherwise. */
+    message: string;
+}
+export declare function reconcileChartPick(pick: string | null | undefined, offered: readonly (string | null | undefined)[], autoLabel: string): ChartPickReconciliation;

package/dist/types/codeComments.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Generated chart code with its JavaScript COMMENTS removed, and nothing else.
+ *
+ * WHY A HOST NEEDS THIS. A host decides from the code which optional libraries a chart needs before
+ * running it (see `requiredD3Plugins`), and a word in a comment is not a call. The helpers a generator
+ * prepends to every chart are documented in prose, and prose names things: one helper's comment listed the
+ * chart types it serves, "Basic Sankey" among them, so every chart carrying it - bar charts, cards,
+ * tables - read as needing the Sankey plugin, and a host fetched a library it would never call on every
+ * render.
+ *
+ * NOT THE NAIVE STRIP, ON PURPOSE. A regex that deletes from `//` to the end of the line also deletes from
+ * the `//` inside "https://..." to the end of that line - taking any real code after the string with it.
+ * For a check that can only ever REMOVE evidence, over-stripping is the dangerous direction: a plugin name
+ * lost that way is a chart failing several frames deep. So this walks the code once, tracking the three
+ * places a comment marker is not a comment - a string, a template literal (including code inside its
+ * `${...}`), and a regular-expression literal - and removes only what is genuinely a comment.
+ *
+ * THE ONE AMBIGUITY - is a `/` a division or the start of a regex? - is settled by the usual rule: what
+ * came before it. A division misread as a regex only keeps text (the comments after it, up to the next `/`
+ * on that line, stay in the output). The reverse - a regex literal that opens a statement right after `)`
+ * or `}` - is read as a division, and would lose text only if that regex itself contained `//` or `/*`.
+ * Generated chart code does not write that form; it is named here so nobody has to rediscover it.
+ *
+ * A removed comment is replaced by a single space, keeping any newlines a block comment spanned, so tokens
+ * either side never fuse and line numbers are preserved.
+ */
+export declare function stripJsComments(code: string): string;

package/dist/types/contract.d.ts

@@ -1,4 +1,4 @@
-export declare const HOST_CONTRACT_VERSION = "1.10.0";
+export declare const HOST_CONTRACT_VERSION = "1.11.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[];
@@ -17,6 +17,10 @@ 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 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
+ *  for their view to be remembered. Returns the SAME object when there was nothing to remove. */
+export declare function withoutViewOnlyKeys<T extends Record<string, unknown>>(bag: T): T;
 /**
  * WHERE A CHART'S RESTING VIEW-STATE LIVES between draws (contract 1.6.0).
  *

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, 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, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, } from "./contract";
+export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, 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, 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, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, } 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
@@ -34,4 +34,6 @@ export { pinScrolledAxis, unpinScrolledAxis, type AxisPinReport } 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";
-export { PENDING_RECOVERY_WINDOW_MS, PENDING_RECOVERY_POLL_MS, PENDING_RECOVERY_FIRST_POLL_MS, PENDING_RECOVERY_FAST_PHASE_MS, PENDING_RECOVERY_MID_POLL_MS, PENDING_RECOVERY_SLOW_PHASE_MS, PENDING_RECOVERY_SLOW_POLL_MS, pendingRecoveryNextDelayMs, encodePendingGenerate, parsePendingGenerate, markerArmedBlind, isBlindMarker, servedCorrelationProves, sameMarker, decidePendingRecovery, recoveryPollRunning, recoveryOwnsTheSentence, latePickupAction, latePickupKeepsMarker, pollGiveUpKeepsMarker, pendingRecoveryRemainingMs, transportFailureShouldRecover, type PendingGenerateMarker, type PendingRecoveryDecision, type LatePickupAction, } from "./pendingGenerate";
+export { PENDING_RECOVERY_WINDOW_MS, PENDING_RECOVERY_POLL_MS, PENDING_RECOVERY_FIRST_POLL_MS, PENDING_RECOVERY_FAST_PHASE_MS, PENDING_RECOVERY_MID_POLL_MS, PENDING_RECOVERY_SLOW_PHASE_MS, PENDING_RECOVERY_SLOW_POLL_MS, pendingRecoveryNextDelayMs, encodePendingGenerate, parsePendingGenerate, markerArmedBlind, isBlindMarker, servedCorrelationProves, sameMarker, decidePendingRecovery, recoveryPollRunning, recoveryOwnsTheSentence, latePickupAction, latePickupKeepsMarker, pollGiveUpKeepsMarker, pendingRecoveryRemainingMs, transportFailureShouldRecover, TRANSPORT_LOST_CHECKING_MESSAGE, GENERATION_CANCELLED_MESSAGE, recoveryAnswerIsCancelled, generationCancelledMessage, type PendingGenerateMarker, type PendingRecoveryDecision, type LatePickupAction, } from "./pendingGenerate";
+export { stripJsComments } from "./codeComments";
+export { reconcileChartPick, type ChartPickReconciliation } from "./chartPick";

package/dist/types/pendingGenerate.d.ts

@@ -161,3 +161,31 @@ export declare function pendingRecoveryRemainingMs(m: PendingGenerateMarker, now
  * headers means the service never saw it, and retrying is the right move.
  */
 export declare function transportFailureShouldRecover(headersReceived: boolean, genNew: boolean): boolean;
+/**
+ * WHAT A HOST SAYS THE MOMENT A GENERATE'S CONNECTION DROPS - before it knows anything else.
+ *
+ * It used to promise the chart ("it is still being built on the server ... will show it when it lands").
+ * That was never something the host had observed: the server takes a dropped connection as a cancel at its
+ * next safe boundary, charges nothing and hands the slot back, so the chart the reader was promised was
+ * frequently never going to arrive - and a poll then waited out its whole window for it. The honest sentence
+ * is the one that names only what is known: the connection dropped, and the host is checking.
+ */
+export declare const TRANSPORT_LOST_CHECKING_MESSAGE = "The connection dropped while your chart was being generated - checking whether it finished on the server...";
+/**
+ * The words for a recovery answer that says the generation was cancelled, when the server sent none of its
+ * own. The server's errorMessage is preferred - it is the one author of the sentence - and this is the same
+ * sentence, for a server that set the flag and left the message blank.
+ */
+export declare const GENERATION_CANCELLED_MESSAGE = "The connection dropped before the chart finished - nothing was charged. Generate again.";
+/**
+ * Is this recovery answer the server saying the generation was CANCELLED - so nothing will ever be ready?
+ *
+ * A terminal answer, not a "not yet": the poll stops, the reader is told, and Generate is theirs again. A
+ * server that predates the field sends only isVersionNotFound for the same row, which keeps a host polling
+ * until its window closes - the old behaviour, no worse. The field's presence is the capability.
+ */
+export declare function recoveryAnswerIsCancelled(r: {
+    isGenerationCancelled?: boolean | null;
+} | null | undefined): boolean;
+/** The banner for a cancelled generation: the server's own sentence when it sent one, else the same words. */
+export declare function generationCancelledMessage(serverMessage: string | null | undefined): string;

package/dist/types/selectionCard.d.ts

@@ -84,6 +84,13 @@ type Agg = "sum" | "average" | "min" | "max" | "count" | "median" | "distinctcou
  *  spellings fall back to sum rather than throwing: a card is a courtesy, and refusing to draw
  *  one because a host wrote "Total" is a worse outcome than summing. */
 export declare function normaliseAggregation(raw: string | undefined | null): Agg;
+/** THE LINE'S LABEL: "<aggregation> of <column>", unless the column's name already says it.
+ *  An Excel table copied from a pivot, or a Power BI implicit measure, arrives with a column
+ *  named "Sum of Orders"; composing onto that printed "Sum of Sum of Orders" (dev, Excel add-in
+ *  1.0.0.47, a click on the order-fulfilment chart). Only the SAME aggregation's words are
+ *  dropped: "Average of Sum of Orders" is a true statement - it averages per-row sums - and
+ *  stays composed. */
+export declare function measureLineLabel(agg: Agg, name: string): string;
 /**
  * The card for a selection, or NULL when there is nothing to say.
  *

package/package.json

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