@bicharts/chart-host 0.5.106 → 0.5.108

package/dist/react.mjs

@@ -4,7 +4,7 @@ import {
   createChartHost,
   geoFromCache,
   loadGeo
-} from "./chunk-HLNXXQA5.mjs";
+} from "./chunk-RHBT4HTP.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -53,6 +53,7 @@ function BicChart(props) {
     viewState,
     labelContrast,
     onLabelContrast,
+    onInvalidSentinel,
     id,
     filteredBy,
     respondsWith,
@@ -78,6 +79,8 @@ function BicChart(props) {
   onSelectRef.current = onSelect;
   const onLabelContrastRef = useRef(onLabelContrast);
   onLabelContrastRef.current = onLabelContrast;
+  const onInvalidSentinelRef = useRef(onInvalidSentinel);
+  onInvalidSentinelRef.current = onInvalidSentinel;
   const [geoTick, setGeoTick] = useState(0);
   useEffect(() => {
     if (!geoKind || geoFromCache(geoKind)) return;
@@ -104,7 +107,15 @@ function BicChart(props) {
       geoKind,
       viewState,
       labelContrast,
-      onLabelContrast: (r) => onLabelContrastRef.current?.(r)
+      onLabelContrast: (r) => onLabelContrastRef.current?.(r),
+      // A GETTER, not a wrapper: the host decides whether to
+      // swallow the sentinel throw by whether this is SET, so
+      // an always-present wrapper would hide the throw from a
+      // page that never asked. Read at throw time, so the
+      // newest prop wins without a rebuild.
+      get onInvalidSentinel() {
+        return onInvalidSentinelRef.current ? (info) => onInvalidSentinelRef.current?.(info) : void 0;
+      }
     });
     hostRef.current = host;
     const off = host.selection.onChange((payloadIdxs, source) => {

package/dist/types/host.d.ts

@@ -165,6 +165,22 @@ export interface ChartHostConfig {
     labelContrast?: boolean | LabelContrastOptions;
     /** What the label-contrast pass did after each render - counts, so a host can log them. */
     onLabelContrast?: (report: LabelContrastReport) => void;
+    /**
+     * THE CHART SAID THE DATA LACKS SOMETHING IT IS BUILT ON. Generated code has one sanctioned
+     * hard stop at runtime: a column the chart needs is gone from `data.columns`, and it throws
+     * `new Error('INVALID:column "<name>" not found')`. That is a DATA STATE, not a broken chart -
+     * the same code draws again once the column is back - so a host should say what is missing,
+     * keep the code, and re-render on the next data change rather than report a crash.
+     *
+     * Supplied: render() clears the container, calls this with the chart's reason (the text after
+     * `INVALID:` on that line) and the full message, and returns normally - nothing was drawn, so
+     * no post-render pass (label contrast, hit-target heal, census, fit) runs. Absent: render()
+     * throws exactly as it always has, so an existing host is untouched.
+     */
+    onInvalidSentinel?: (info: {
+        reason: string;
+        message: string;
+    }) => void;
 }
 export interface ChartHost {
     render(): void;

package/dist/types/index.d.ts

@@ -12,6 +12,7 @@ export { planTrivialChart, compileTrivialSource, type TrivialPlan, type TrivialS
 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 { mountProductFeedbackBox, normaliseProductFeedbackText, productFeedbackSendable, buildProductFeedbackPayload, PRODUCT_FEEDBACK_MAX_CHARS, PRODUCT_FEEDBACK_MIN_CHARS, type ProductFeedbackBox, type ProductFeedbackBoxOptions, type ProductFeedbackText, type ProductFeedbackSendResult, type ProductFeedbackPayload, type ProductFeedbackIdentity, type ProductFeedbackHost, } from "./productFeedback";
 export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, orderRefusalsForDisplay, refusalIsSelectable, hasRefusalsToShow, qualifyRefusalHeadingFor, newQualifyRefusalGroupState, qualifyRefusalReason, QUALIFY_REFUSAL_UNSPECIFIED, 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 { normalizeFilterTerm, filterQualifyRows, readQualifyChartRow, readQualifyRefusalRow, filterFitsChooser, listNeedsFilter, qualifyFilterGate, inlineFilterGate, FILTER_MIN_TERM_CHARS, FILTER_ROW_PX, FILTER_MIN_WIDTH_PX, FILTER_MIN_HEIGHT_PX, INLINE_FILTER_MIN_ROWS, computeQualifyFilterView, qualifyFilterCountText, type QualifyFilterTier, type QualifyFilterResult, type QualifyFilterRead, type QualifyFilterGateReason, type QualifyFilterGateInput, type QualifyFilterRow, type QualifyFilterGroup, type QualifyFilterView, type QualifyFilterNoteKind, } from "./qualifyFilter";
@@ -22,6 +23,7 @@ export { ensureCrossfilterHitTargets, type HitTargetReport } from "./hitTargets"
 export { applyLabelContrast, LABEL_CONTRAST_DONE_ATTR, LABEL_CONTRAST_CAP, type LabelContrastOptions, type LabelContrastReport, } from "./labelContrastDom";
 export { decideLabelColor, toRGBA, compositeOver, relativeLuminance, contrastRatio, isPillBackdropAlpha, pillBacksGlyph, backingHoldsGlyph, cellSuppressesNormalize, glyphSampleGrid, DARK_TEXT, LIGHT_TEXT, MIN_CONTRAST, WHITE_TEXT_BG_LUM, PILL_MIN_ALPHA, PILL_OPAQUE_ALPHA, PILL_MIN_COVERAGE, PAGE_MATCH_TOLERANCE, BACKING_MAJORITY, GLYPH_SAMPLE_N, type LabelDecision, } from "./labelContrast";
 export { censusMarks, isBlankRender, blankRenderFlag, type MarkCensus, type BlankVerdictInput } from "./blankRender";
+export { isInvalidSentinelError, invalidSentinelReason } from "./invalidSentinel";
 export { censusHitBands, hitBandFlag, MIN_HIT_BAND_PX, type HitBandCensus } from "./hitBands";
 export { censusColourSpread, colourSpreadFlag, SAME_SHADE_DELTA_E, MIN_RAMP_FILLS, type ColourSpreadCensus } from "./colourSpread";
 export { censusValuePlacement, valuePlacementFlag, VALUE_AXIS_MIN_FIT, type ValuePlacementCensus } from "./valuePlacement";

package/dist/types/invalidSentinel.d.ts

@@ -0,0 +1,14 @@
+/**
+ * True when an error message, Python traceback or "Error:"-prefixed result carries the generated
+ * code's INVALID sentinel. Matches the uppercase marker followed by a colon (space allowed before
+ * the colon) anywhere in the text - Python surfaces it inside `ValueError: INVALID:...` at the END
+ * of a multi-line traceback; a D3 throw surfaces it directly in `Error.message`. Lowercase
+ * "Invalid" and the bare word without a colon are ordinary errors.
+ */
+export declare function isInvalidSentinelError(text: string | null | undefined): boolean;
+/**
+ * The reason the chart gave: the text after the first `INVALID:` up to the end of that line,
+ * trimmed, and capped at `max` characters with an ASCII "..." so a host can put it in a one-line
+ * status. Empty string when the text carries no sentinel.
+ */
+export declare function invalidSentinelReason(text: string | null | undefined, max?: number): string;

package/dist/types/productFeedback.d.ts

@@ -0,0 +1,88 @@
+/** The longest message a host will send. Mirrored by the service's own cap. */
+export declare const PRODUCT_FEEDBACK_MAX_CHARS = 2000;
+/** Below this there is nothing a person could act on ("ok", "hi"). */
+export declare const PRODUCT_FEEDBACK_MIN_CHARS = 3;
+/** Which host a message came from. The service files it under that host. */
+export type ProductFeedbackHost = "PBI" | "EXCEL";
+/**
+ * Clean a typed message for sending: control characters other than line breaks and tabs removed,
+ * trailing spaces on each line removed, runs of blank lines collapsed to one, trimmed, and capped.
+ * Pure, so every host sends the same bytes for the same keystrokes.
+ */
+export declare function normaliseProductFeedbackText(raw: string | null | undefined, maxChars?: number): string;
+/** True when a message is long enough to send. */
+export declare function productFeedbackSendable(raw: string | null | undefined, maxChars?: number): boolean;
+/** The credentials a host already holds, forwarded so the service can attach an account when there is one. The
+ *  service resolves identity itself; nothing here names an account. Absent fields are sent empty. */
+export interface ProductFeedbackIdentity {
+    licenseKey?: string;
+    licensee?: string;
+    secretKey?: string;
+    freemiumKey?: string;
+    linkNonce?: string;
+    instanceKey?: string;
+    clientId?: string;
+}
+export interface ProductFeedbackPayload {
+    text: string;
+    host: ProductFeedbackHost;
+    surface: string;
+    clientVersion: string;
+    correlationId: string;
+    clientId: string;
+    licenseKey: string;
+    licensee: string;
+    secretKey: string;
+    freemiumKey: string;
+    linkNonce: string;
+    instanceKey: string;
+}
+/** The request body every host sends (before its own encoding and signing). */
+export declare function buildProductFeedbackPayload(input: {
+    text: string;
+    host: ProductFeedbackHost;
+    surface?: string;
+    clientVersion: string;
+    correlationId: string;
+    identity?: ProductFeedbackIdentity;
+}): ProductFeedbackPayload;
+/** What a host's send callback reports. `message` is shown to the reader when present. */
+export interface ProductFeedbackSendResult {
+    ok: boolean;
+    message?: string;
+}
+/** The words a reader sees. Hosts localize; every field has an English default. */
+export interface ProductFeedbackText {
+    label?: string;
+    placeholder?: string;
+    hint?: string;
+    send?: string;
+    sending?: string;
+    sent?: string;
+    failed?: string;
+}
+export interface ProductFeedbackBoxOptions {
+    /** Delivers the cleaned text. Resolve { ok: false } (or throw) on failure; the box keeps the text either way. */
+    send: (text: string) => Promise<ProductFeedbackSendResult>;
+    text?: ProductFeedbackText;
+    /** Added to the wrapper so the host can skin it; the structure stays the same. */
+    className?: string;
+    maxChars?: number;
+    /** Called once, when the box is mounted - the host's "shown" counter. */
+    onShown?: () => void;
+    /** Called after a successful send - the host's "sent" counter. */
+    onSent?: () => void;
+    /** Called after a failed send, with what failed, so the host can log it. */
+    onFailed?: (reason: string) => void;
+}
+export interface ProductFeedbackBox {
+    element: HTMLElement;
+    /** Removes the box and its listeners. */
+    destroy(): void;
+}
+/**
+ * Build the box inside `container`. The wrapper carries `bic-product-feedback` (plus the host's
+ * class); the textarea, button and status line carry `bic-product-feedback-input`, `-send` and
+ * `-status`, so hosts and tests can find them without depending on the order of elements.
+ */
+export declare function mountProductFeedbackBox(container: HTMLElement, opts: ProductFeedbackBoxOptions): ProductFeedbackBox;

package/dist/types/react.d.ts

@@ -34,6 +34,13 @@ export interface BicChartProps {
     labelContrast?: ChartHostConfig["labelContrast"];
     /** What the label-contrast pass did after each render - counts, for a page that logs. */
     onLabelContrast?: ChartHostConfig["onLabelContrast"];
+    /**
+     * THE CHART STOPPED BECAUSE THE DATA LACKS A COLUMN IT IS BUILT ON. Supplied: the chart's
+     * container is left empty and this is called with the chart's reason, instead of the throw
+     * reaching React - so a page can say what is missing where the chart would be. Absent: the
+     * throw propagates as before. See createChartHost's `onInvalidSentinel`.
+     */
+    onInvalidSentinel?: ChartHostConfig["onInvalidSentinel"];
     /** 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.106",
+  "version": "0.5.108",
   "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",