@bicharts/chart-host 0.5.41 → 0.5.43

package/dist/index.mjs

@@ -574,6 +574,40 @@ function qualifyGroupHeadingFor(row, state) {
   return null;
 }
 
+// src/qualifyLaunch.ts
+var qualifyPick = (chartType) => ({ kind: "pick", chartType });
+var qualifyAuto = () => ({ kind: "auto" });
+var qualifyCancel = () => ({ kind: "cancel" });
+function launchGenerates(outcome) {
+  return outcome.kind === "pick" || outcome.kind === "auto";
+}
+function launchFavorStyle(outcome, autoSentinel) {
+  return outcome.kind === "pick" ? outcome.chartType : autoSentinel;
+}
+var CHOOSER_MIN_WIDTH_PX = 400;
+var CHOOSER_MIN_HEIGHT_PX = 240;
+function chooserFitsViewport(width, height) {
+  if (!isFinite(width) || !isFinite(height)) return false;
+  return width >= CHOOSER_MIN_WIDTH_PX && height >= CHOOSER_MIN_HEIGHT_PX;
+}
+function shouldOpenChooserOnGenerate(i) {
+  if (!i.enabled) return false;
+  if (!i.hasData) return false;
+  return chooserFitsViewport(i.width, i.height);
+}
+function shouldOpenInlineChooserOnGenerate(i) {
+  return i.enabled === true && i.hasData === true;
+}
+function canConfirmLaunch(selected) {
+  return typeof selected === "string" && selected.trim() !== "";
+}
+function confirmLaunch(selected) {
+  return canConfirmLaunch(selected) ? qualifyPick(String(selected).trim()) : qualifyCancel();
+}
+function qualifyFailureFallsOpen(viaGenerate) {
+  return viaGenerate === true;
+}
+
 // src/selectionCard.ts
 var SYNTHETIC_PREFIX = "__";
 var NUMERIC_DATATYPE = /int|double|decimal|single|float|number|currency|money/i;
@@ -753,6 +787,8 @@ export {
   ANIM_PLAY_SPEED_MAX,
   ANIM_PLAY_SPEED_MIN,
   AXIS_FILTER_CLASS,
+  CHOOSER_MIN_HEIGHT_PX,
+  CHOOSER_MIN_WIDTH_PX,
   COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
   COLOR_SCALE_SELF_CLAMP_PCT_MAX,
   COLOR_SCALE_SELF_CLAMP_PCT_MIN,
@@ -777,30 +813,41 @@ export {
   bareBase64,
   buildRenderPayload,
   buildReviewWire,
+  canConfirmLaunch,
   captureSvgSnapshot,
   chartOwnsTimeline,
+  chooserFitsViewport,
   clearGeoCache,
   compileRenderFn,
   compileTrivialSource,
   computeSelectionCard,
+  confirmLaunch,
   createChartHost,
   createMarkResolver,
   ensureCrossfilterHitTargets,
   explainRenderFailure,
   geoAssetFor,
   geoFromCache,
+  launchFavorStyle,
+  launchGenerates,
   loadGeo,
   newQualifyGroupState,
   normaliseAggregation,
   periodTickSuppressesFeedback,
   planTrivialChart,
+  qualifyAuto,
+  qualifyCancel,
+  qualifyFailureFallsOpen,
   qualifyGroupHeadingFor,
+  qualifyPick,
   rasterizeSvgToPngDataUrl,
   registerCityTable,
   registerGeo,
   registerGeoAsset,
   requiredD3Plugins,
   resolveOptions,
+  shouldOpenChooserOnGenerate,
+  shouldOpenInlineChooserOnGenerate,
   shouldReview,
   stripEsmExports,
   svgNaturalSize,

package/dist/types/index.d.ts

@@ -12,5 +12,6 @@ export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngData
 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 { 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/qualifyLaunch.d.ts

@@ -0,0 +1,136 @@
+/** How the reader left the chooser. Three outcomes, never two - see the note above. */
+export type QualifyLaunchOutcome = 
+/** A named type. Rides the host's explicit-pick lane for exactly one generation. */
+{
+    kind: "pick";
+    chartType: string;
+}
+/** "Choose for me." Generates with NO preference expressed. */
+ | {
+    kind: "auto";
+}
+/** Backed out. Nothing is generated and no preference is recorded. */
+ | {
+    kind: "cancel";
+};
+export declare const qualifyPick: (chartType: string) => QualifyLaunchOutcome;
+export declare const qualifyAuto: () => QualifyLaunchOutcome;
+export declare const qualifyCancel: () => QualifyLaunchOutcome;
+/** Does this outcome start a generation? False for cancel ALONE. */
+export declare function launchGenerates(outcome: QualifyLaunchOutcome): boolean;
+/**
+ * The value a host should put in its explicit-pick field for this outcome.
+ *
+ * GENERIC OVER THE SENTINEL BECAUSE THE HOSTS DISAGREE ABOUT WHAT "AUTO" IS SPELLED AS, and
+ * that disagreement is real rather than sloppy: one host's field is a nullable string whose
+ * null means "the picker decides", another's is a plain string whose empty value is the wire
+ * form. Neither can adopt the other's without changing a wire contract. So the sentinel is
+ * passed IN and this function only decides WHICH of the two values applies - which is the part
+ * that must not differ.
+ *
+ * Cancel maps to the sentinel too, defensively: a caller that ignores `launchGenerates` and
+ * reads this anyway gets "no preference" rather than a stale pick. It should still not generate.
+ */
+export declare function launchFavorStyle<T>(outcome: QualifyLaunchOutcome, autoSentinel: T): string | T;
+/**
+ * THE SMALLEST TILE THE CHOOSER IS USABLE IN, measured rather than guessed (2026-09-01).
+ *
+ * A sweep of 168 tile sizes in headless Chromium, rendering the real card DOM and CSS, asking
+ * three questions of each: do the three launch buttons sit on one line inside the card, are at
+ * least two list rows visible, and is nothing in the pinned chrome clipped. The measured floor
+ * is 320 x 220 - but the two dimensions are COUPLED, because under 400 px the card's title
+ * wraps to a second line and eats the list's height: at 320-340 wide the height floor rises to
+ * 280, at 360-380 to 260, and only at 400+ does 220 hold.
+ *
+ * 400 x 240 is that envelope with one sweep step of margin on the height. The margin is not
+ * decoration: the measurement used one font stack and one string, and every host localizes the
+ * title, so a longer translation wraps sooner than the sample did.
+ *
+ * ERRING HIGH IS THE CHEAP DIRECTION. Below the floor the host generates immediately, which is
+ * the behaviour it had before the chooser existed - so a tile wrongly judged too small costs a
+ * feature, while one wrongly judged big enough costs a dialog whose buttons are off the card.
+ */
+export declare const CHOOSER_MIN_WIDTH_PX = 400;
+export declare const CHOOSER_MIN_HEIGHT_PX = 240;
+/**
+ * Is there room to DRAW the chooser here?
+ *
+ * MEASURE THE REAL SURFACE, never a size the host reports outward. Where a host lets an author
+ * state a viewport for generation purposes, that stated size is a claim about a tile that does
+ * not exist yet; the dialog has to fit the pixels actually on screen.
+ */
+export declare function chooserFitsViewport(width: number, height: number): boolean;
+export interface ChooserGateInput {
+    /** The host's opt-out setting. False = the reader wants one-click Generate back. */
+    enabled: boolean;
+    /** Real drawable width, in CSS pixels. */
+    width: number;
+    /** Real drawable height, in CSS pixels. */
+    height: number;
+    /**
+     * Is there anything to qualify? A chooser over an empty binding can only say "bind
+     * something first", which the host's own Generate path already says better and without
+     * a round-trip.
+     */
+    hasData: boolean;
+}
+/**
+ * Should pressing Generate open the chooser instead of generating?
+ *
+ * FALSE IS ALWAYS SAFE and that is the design: every false answer here lands on the behaviour
+ * the host had before this feature existed - press Generate, get a chart. So the gate can be
+ * conservative without stranding anybody, and a new reason to decline can be added later
+ * without auditing what it breaks.
+ */
+export declare function shouldOpenChooserOnGenerate(i: ChooserGateInput): boolean;
+/**
+ * The same gate for a host whose chooser is an INLINE, SCROLLING PANEL rather than a modal card
+ * - and it deliberately has no size clause at all.
+ *
+ * THE ASYMMETRY IS THE POINT, AND IT IS MEASURED RATHER THAN ASSUMED. The modal above lives in
+ * a card that CLIPS, so past a certain smallness its buttons are simply not on screen and the
+ * reader is trapped. A panel that flows inside a scrolling pane, with a wrapping button row,
+ * cannot reach that state: swept across 63 pane sizes down to 200x120, every one stayed usable
+ * - the footer wrapped from one line to three (38px to 86px) and stayed inside the panel, and
+ * the list kept four or more rows because it carries its own max-height and scrolls.
+ *
+ * So a size clause here would not protect anybody; it would only switch the feature off for a
+ * default task pane, which is narrower than the modal's floor. Two hosts, two layouts, two
+ * honest answers - written next to each other so the difference reads as a decision rather than
+ * as one of them having forgotten.
+ */
+export declare function shouldOpenInlineChooserOnGenerate(i: {
+    enabled: boolean;
+    hasData: boolean;
+}): boolean;
+/**
+ * Is the confirm button live?
+ *
+ * A SEPARATE QUESTION FROM "is a type selected", because it is the answer to a UI state and the
+ * host asks it on every selection change. Kept here so both hosts agree that selecting a row is
+ * what arms confirm - the alternative, arming it always and validating on click, produces a
+ * button that looks ready and then refuses, which is the interaction this flow replaced.
+ */
+export declare function canConfirmLaunch(selected: string | null | undefined): boolean;
+/**
+ * The outcome of pressing confirm with `selected` highlighted.
+ *
+ * Returns CANCEL rather than auto when nothing is selected, and the choice matters: confirm
+ * with an empty selection is a state the UI should not allow, so if it happens the honest
+ * reading is "this click means nothing", not "this click means spend a credit". The host's
+ * disabled state is the first guard; this is the second.
+ */
+export declare function confirmLaunch(selected: string | null | undefined): QualifyLaunchOutcome;
+/**
+ * WHAT A FAILED QUALIFY MEANS depends on which door the reader came through, and this is the
+ * one place that says so.
+ *
+ * Opened from Generate, the reader asked for a CHART: the chooser is an offer along the way, so
+ * when qualify errors or times out the flow proceeds to generate and the degradation is logged
+ * rather than shown. Opened from a "what fits?" affordance, the reader asked a QUESTION: failing
+ * open there would spend a credit nobody requested, so the error is shown and nothing runs.
+ *
+ * This is the whole reason the two doors are distinguishable at all. Everything else about them
+ * - the list, the buttons, the outcomes - is deliberately identical.
+ */
+export declare function qualifyFailureFallsOpen(viaGenerate: boolean): boolean;

package/package.json

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