@bicharts/chart-host 0.5.81 → 0.5.83

package/dist/index.mjs

@@ -611,14 +611,15 @@ function askApplyImprovements(container, reason, opts = {}) {
 
 // src/qualifyGroups.ts
 function newQualifyGroupState() {
-  return { preview: false, previewClosed: false, projected: false, notRecommended: false };
+  return { preview: false, previewClosed: false, projected: false, notRecommended: false, rankedSeen: false };
 }
 function qualifyGroupHeadingFor(row, state) {
   const preview = row.isPreview === true;
-  if (preview && !state.preview && !state.notRecommended) {
+  if (preview && !state.preview && !state.notRecommended && !state.rankedSeen) {
     state.preview = true;
     return "preview";
   }
+  if (!preview) state.rankedSeen = true;
   if (state.preview && !state.previewClosed && !preview) {
     state.previewClosed = true;
     return "main";
@@ -662,6 +663,11 @@ function qualifyRefusalHeadingFor(row, state) {
 function hasRefusalsToShow(rows) {
   return orderRefusalsForDisplay(rows).length > 0;
 }
+var QUALIFY_REFUSAL_UNSPECIFIED = "refused for the fields as bound - no single requirement to name";
+function qualifyRefusalReason(reason, fallback = QUALIFY_REFUSAL_UNSPECIFIED) {
+  const s = (reason ?? "").trim();
+  return s !== "" ? s : fallback;
+}
 
 // src/qualifyLaunch.ts
 var qualifyPick = (chartType, projectionKey) => ({ kind: "pick", chartType, ...projectionKey ? { projectionKey } : {} });
@@ -1088,6 +1094,7 @@ export {
   PILL_MIN_ALPHA,
   PILL_MIN_COVERAGE,
   PILL_OPAQUE_ALPHA,
+  QUALIFY_REFUSAL_UNSPECIFIED,
   ROW_IDX_ATTR,
   SCROLL_SLACK_PX,
   SEASONAL_MARKERS_DEFAULT,
@@ -1167,6 +1174,7 @@ export {
   qualifyGroupHeadingFor,
   qualifyPick,
   qualifyRefusalHeadingFor,
+  qualifyRefusalReason,
   rasterizeSvgToPngDataUrl,
   readQualifyChartRow,
   readQualifyRefusalRow,

package/dist/types/index.d.ts

@@ -11,7 +11,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 { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, orderRefusalsForDisplay, refusalIsSelectable, hasRefusalsToShow, qualifyRefusalHeadingFor, newQualifyRefusalGroupState, type QualifyRefusalRow, type QualifyRefusalGroupState, type QualifyRefusalHeading, } from "./qualifyGroups";
+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";
 export { computeSelectionCard, normaliseAggregation, type SelectionCardModel, type SelectionCardLine, type SelectionCardOptions, } from "./selectionCard";

package/dist/types/qualifyGroups.d.ts

@@ -15,6 +15,8 @@ export interface QualifyGroupState {
     previewClosed: boolean;
     projected: boolean;
     notRecommended: boolean;
+    /** A ranked (non-preview) row has been seen: from here on a badge is a badge, not a block. */
+    rankedSeen: boolean;
 }
 export declare function newQualifyGroupState(): QualifyGroupState;
 /**
@@ -24,7 +26,13 @@ export declare function newQualifyGroupState(): QualifyGroupState;
  *
  * ORDER OF THE CHECKS IS THE CONTRACT:
  *  1. "preview" opens the block - but never once the not-recommended block has opened, because a
- *     preview type the ontology ruled out is NOT floated and belongs where it landed.
+ *     preview type the ontology ruled out is NOT floated and belongs where it landed. AND NEVER
+ *     ONCE A RANKED ROW HAS BEEN SEEN. The preview BLOCK is the set of rows the server floated
+ *     to the top (preview TYPES, which cannot be scored); a preview LANE sits on a scorable type
+ *     that ranks on its own merits and is deliberately left where it ranks, carrying only its
+ *     badge. Before this clause, one badged lane mid-list opened "New - in preview" above row 13
+ *     and closed it with "Best fit for your data" above row 14 - two headings claiming a
+ *     grouping the list did not have.
  *  2. "main" closes it, at the first row that is not preview. Emitted only if a block opened.
  *  3. "projected" and 4. "notRecommended" are unchanged from the single-host original.
  */
@@ -80,3 +88,30 @@ export declare function qualifyRefusalHeadingFor(row: QualifyRefusalRow, state:
  * no checkbox: it reads as a broken control rather than an empty category.
  */
 export declare function hasRefusalsToShow(rows: readonly QualifyRefusalRow[] | null | undefined): boolean;
+/**
+ * THE SENTENCE FOR A REFUSAL THAT NAMES NO REQUIREMENT.
+ *
+ * A null reason is a REAL answer, not a gap: the server walks a chart's DECLARED structural
+ * requirements and stays silent rather than fabricating a cause when the blocker rests on a
+ * runtime signal it cannot see - a viewport, a facet budget, a raw-observation floor. Both
+ * refusal builders say in so many words that the client renders that null as a fallback
+ * sentence. No host did. All three tested `if (reason)` and skipped the element, so the row
+ * came out as a bare chart name under a heading that claimed to know why it was refused.
+ *
+ * It lives here, beside `refusalIsSelectable`, for the same reason that predicate does: three
+ * hosts answering one question, and a fallback that only two of them remember to write is the
+ * drift this module exists to prevent. Call `qualifyRefusalReason` rather than reading `.reason`
+ * - a host cannot forget a fallback it never has to supply.
+ *
+ * IT DOES NOT GUESS. "We turned this down and cannot point at one requirement" is exactly what
+ * happened, and it is more useful than silence: the reader learns the row is an ANSWER rather
+ * than a rendering that failed to load.
+ */
+export declare const QUALIFY_REFUSAL_UNSPECIFIED = "refused for the fields as bound - no single requirement to name";
+/**
+ * The sentence to render beside a refused chart's name: the server's own words when it has them,
+ * and {@link QUALIFY_REFUSAL_UNSPECIFIED} when it does not. Never empty, which is the point.
+ *
+ * `fallback` lets a host localize without re-implementing the decision.
+ */
+export declare function qualifyRefusalReason(reason: string | null | undefined, fallback?: string): string;

package/package.json

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