@bicharts/chart-host 0.5.59 → 0.5.61

package/dist/index.mjs

@@ -651,6 +651,116 @@ function qualifyFailureFallsOpen(viaGenerate) {
   return viaGenerate === true;
 }
 
+// src/qualifyFilter.ts
+function normalizeFilterTerm(raw) {
+  if (typeof raw !== "string" || raw === "") return "";
+  return raw.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/\s+/g, " ").trim();
+}
+var FILTER_MIN_TERM_CHARS = 2;
+function startsAWord(name, t) {
+  for (let i = name.indexOf(t); i >= 0; i = name.indexOf(t, i + 1)) {
+    if (i === 0) return true;
+    const prev = name.charCodeAt(i - 1);
+    const alnum = prev >= 97 && prev <= 122 || prev >= 48 && prev <= 57;
+    if (!alnum) return true;
+  }
+  return false;
+}
+function filterQualifyRows(rows, term, read) {
+  const all = Array.isArray(rows) ? rows.slice() : [];
+  const t = normalizeFilterTerm(term);
+  if (t.length < FILTER_MIN_TERM_CHARS) return { rows: all, tier: "all", term: "" };
+  const atWordStart = [];
+  const midWord = [];
+  const byDesc = [];
+  for (const row of all) {
+    const f = read(row);
+    const name = normalizeFilterTerm(f.name);
+    if (name === "") continue;
+    if (name.indexOf(t) >= 0) {
+      (startsAWord(name, t) ? atWordStart : midWord).push(row);
+      continue;
+    }
+    if (normalizeFilterTerm(f.description).indexOf(t) >= 0) byDesc.push(row);
+  }
+  if (atWordStart.length > 0) return { rows: atWordStart, tier: "name", term: t };
+  if (midWord.length > 0) return { rows: midWord, tier: "namePart", term: t };
+  if (byDesc.length > 0) return { rows: byDesc, tier: "desc", term: t };
+  return { rows: [], tier: "none", term: t };
+}
+var readQualifyChartRow = (r) => ({ name: r.name, description: r.description });
+var readQualifyRefusalRow = (r) => ({ name: r.name, description: r.reason });
+var FILTER_ROW_PX = 32;
+var FILTER_MIN_WIDTH_PX = 420;
+var FILTER_MIN_HEIGHT_PX = 300;
+function filterFitsChooser(width, height) {
+  return Number.isFinite(width) && Number.isFinite(height) && width >= FILTER_MIN_WIDTH_PX && height >= FILTER_MIN_HEIGHT_PX;
+}
+function listNeedsFilter(scrollHeight, clientHeight) {
+  if (!Number.isFinite(scrollHeight) || !Number.isFinite(clientHeight)) return false;
+  return scrollHeight > clientHeight - FILTER_ROW_PX;
+}
+function qualifyFilterGate(i) {
+  if (!filterFitsChooser(i.cardWidth, i.cardHeight)) return { show: false, why: "too-small" };
+  if (!listNeedsFilter(i.scrollHeight, i.clientHeight)) return { show: false, why: "no-overflow" };
+  return { show: true, why: "shown" };
+}
+function computeQualifyFilterView(groups, term) {
+  const g = Array.isArray(groups) ? groups : [];
+  const read = (r) => ({ name: r.name, description: r.description });
+  const collect = (section) => {
+    const out = [];
+    for (const grp of g) if (grp.section === section) for (const r of grp.rows) out.push(r);
+    return out;
+  };
+  const fitRows = collect("fits");
+  const fit = filterQualifyRows(fitRows, term, read);
+  const ref = filterQualifyRows(collect("refused"), term, read);
+  const visible = /* @__PURE__ */ new Set();
+  for (const r of fit.rows) visible.add(r.el);
+  for (const r of ref.rows) visible.add(r.el);
+  const show = [], hide = [], showHeadings = [], hideHeadings = [];
+  for (const grp of g) {
+    let any = false;
+    for (const r of grp.rows) {
+      if (visible.has(r.el)) {
+        show.push(r.el);
+        any = true;
+      } else {
+        hide.push(r.el);
+      }
+    }
+    if (grp.heading !== null) (any ? showHeadings : hideHeadings).push(grp.heading);
+  }
+  const filtering = fit.tier !== "all";
+  const openRefusals = filtering && fit.rows.length === 0 && ref.rows.length > 0;
+  let note = "none";
+  if (filtering) {
+    if (fit.tier === "desc") note = "descFallback";
+    else if (fit.tier === "none") note = openRefusals ? "onlyRefusals" : "noMatch";
+  }
+  return {
+    show,
+    hide,
+    showHeadings,
+    hideHeadings,
+    tier: fit.tier,
+    matched: fit.rows.length,
+    total: fitRows.length,
+    refusalMatched: ref.rows.length,
+    openRefusals,
+    note,
+    term: fit.term
+  };
+}
+function qualifyFilterCountText(view) {
+  return view.tier === "all" ? String(view.total) : `${view.matched} of ${view.total}`;
+}
+function inlineFilterGate(rowCount) {
+  return rowCount >= INLINE_FILTER_MIN_ROWS ? { show: true, why: "shown" } : { show: false, why: "no-overflow" };
+}
+var INLINE_FILTER_MIN_ROWS = 8;
+
 // src/selectionCard.ts
 var SYNTHETIC_PREFIX = "__";
 var NUMERIC_DATATYPE = /int|double|decimal|single|float|number|currency|money/i;
@@ -893,10 +1003,15 @@ export {
   CONTAINER_SLOT_XF_CLEAR,
   DIM_OPACITY_DEFAULT,
   DIM_OPACITY_VAR,
+  FILTER_MIN_HEIGHT_PX,
+  FILTER_MIN_TERM_CHARS,
+  FILTER_MIN_WIDTH_PX,
+  FILTER_ROW_PX,
   FLIP_MODE_DEFAULT,
   GEO_POINT_PRECISIONS,
   HOST_CONTAINER_CLASS,
   HOST_CONTRACT_VERSION,
+  INLINE_FILTER_MIN_ROWS,
   LEGEND_MARK_CLASS,
   LIFT_SELECTED_CLASS,
   MARK_CLASS,
@@ -921,34 +1036,44 @@ export {
   clearGeoCache,
   compileRenderFn,
   compileTrivialSource,
+  computeQualifyFilterView,
   computeSelectionCard,
   confirmLaunch,
   createChartHost,
   createMarkResolver,
   ensureCrossfilterHitTargets,
   explainRenderFailure,
+  filterFitsChooser,
+  filterQualifyRows,
   geoAssetFor,
   geoFromCache,
   hasRefusalsToShow,
   hitBandFlag,
+  inlineFilterGate,
   isBlankRender,
   launchFavorStyle,
   launchGenerates,
+  listNeedsFilter,
   loadGeo,
   newQualifyGroupState,
   newQualifyRefusalGroupState,
   noopViewStateProvider,
   normaliseAggregation,
+  normalizeFilterTerm,
   orderRefusalsForDisplay,
   periodTickSuppressesFeedback,
   planTrivialChart,
   qualifyAuto,
   qualifyCancel,
   qualifyFailureFallsOpen,
+  qualifyFilterCountText,
+  qualifyFilterGate,
   qualifyGroupHeadingFor,
   qualifyPick,
   qualifyRefusalHeadingFor,
   rasterizeSvgToPngDataUrl,
+  readQualifyChartRow,
+  readQualifyRefusalRow,
   refusalIsSelectable,
   registerCityTable,
   registerGeo,

package/dist/types/index.d.ts

@@ -13,6 +13,7 @@ export { shouldReview, buildReviewWire, bareBase64, actionFor, type ReviewGate,
 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 { 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";
 export { ensureCrossfilterHitTargets, type HitTargetReport } from "./hitTargets";
 export { censusMarks, isBlankRender, blankRenderFlag, type MarkCensus, type BlankVerdictInput } from "./blankRender";

package/dist/types/qualifyFilter.d.ts

@@ -0,0 +1,270 @@
+/**
+ * The comparison form of a term or a field.
+ *
+ * Accent folding is not decoration. The catalogue is English, but the reader's keyboard need not
+ * be, and a "Sankey" typed through a dead key has to match the same row a plain one does. NFD
+ * splits a composed character into base + combining marks and the range strip removes the marks,
+ * which is the whole of it - no transliteration, no stemming, nothing that could make two
+ * different chart names collide.
+ *
+ * Whitespace is collapsed rather than stripped: "bar chart" and "bar  chart" are the same query,
+ * but "barchart" is deliberately NOT one. A reader who omits the space is asking for something we
+ * do not have a name for, and silently succeeding there would make the failures inexplicable.
+ */
+export declare function normalizeFilterTerm(raw: string | null | undefined): string;
+/**
+ * THE SHORTEST TERM THAT FILTERS. One character matches most of a 108-row catalogue, so the
+ * list would flicker through a near-identity pass and teach the reader nothing; below this the
+ * list is returned untouched and the host hides its counter.
+ */
+export declare const FILTER_MIN_TERM_CHARS = 2;
+/**
+ * WHICH TIER ANSWERED - the host needs this, not just the rows.
+ *
+ * "all"      - no term (or too short). The rows are the input, unfiltered.
+ * "name"     - the term starts a WORD in at least one name. Every lower tier is suppressed.
+ * "namePart" - it appears mid-word in a name, and nowhere at a word start.
+ * "desc"     - no name matched at all, so the description fallback answered. THE HOST SAYS SO.
+ * "none"     - nothing matched anywhere.
+ *
+ * A HOST ONLY HAS TO ANNOUNCE "desc". The first two are both name matches and need no
+ * explanation; the third is the one a reader would otherwise read as broken matching.
+ */
+export type QualifyFilterTier = "all" | "name" | "namePart" | "desc" | "none";
+export interface QualifyFilterResult<T> {
+    rows: T[];
+    tier: QualifyFilterTier;
+    /** The normalized term actually applied. Empty when the tier is "all". */
+    term: string;
+}
+/** How to read a row's two searchable fields. Kept as a callback because the fitting rows and
+ *  the refused rows carry different field names and must not need two copies of this logic. */
+export type QualifyFilterRead<T> = (row: T) => {
+    name?: string | null;
+    description?: string | null;
+};
+/**
+ * Filter `rows` by `term`, PRESERVING INPUT ORDER EXACTLY in every branch.
+ *
+ * THREE TIERS, AND THE FIRST NON-EMPTY ONE WINS OUTRIGHT. That single rule is what makes this
+ * feel like a name filter instead of a search box:
+ *
+ *   1. the term starts a WORD in the name    - "gan" -> Gantt chart, and NOT Organization chart
+ *   2. it appears mid-word in the name       - "eth" -> Choropleth, which tier 1 cannot reach
+ *   3. it appears in the description         - "hierarchy" -> Organization chart
+ *
+ * Typing "time" returns `Time series plot` and NOT the dozen types whose descriptions happen to
+ * say "over time", which is what a flat name-or-description match produces and which reads,
+ * correctly, as broken.
+ *
+ * The description tier exists so a reader who types a word we carry in no NAME still finds
+ * something rather than an empty list, and it fires only when both name tiers are empty. When it
+ * fires the host has to say so ("No name matches - showing types whose description mentions
+ * 'stacked'"): an unannounced fallback is indistinguishable from bad matching. The two NAME tiers
+ * need no announcement - both are the reader's own word, found where they expected it.
+ *
+ * A row with no name is dropped from every tier. It cannot be labelled, so it cannot be chosen,
+ * and the hosts already drop it at render time.
+ */
+export declare function filterQualifyRows<T>(rows: readonly T[] | null | undefined, term: string | null | undefined, read: QualifyFilterRead<T>): QualifyFilterResult<T>;
+/** Reads a fitting row (`charts[]`): `name` / `description`. */
+export declare const readQualifyChartRow: QualifyFilterRead<{
+    name?: string | null;
+    description?: string | null;
+}>;
+/**
+ * Reads a REFUSED row (`refused[]`). Its second field is the gate's SENTENCE rather than a
+ * description, and searching it is right for the same reason the tier exists: the sentence names
+ * the reader's own columns, so "region" finding every type refused over Region is a useful
+ * answer to "why isn't my chart here" - which is the only question that section is open to ask.
+ */
+export declare const readQualifyRefusalRow: QualifyFilterRead<{
+    name?: string | null;
+    reason?: string | null;
+}>;
+/**
+ * THE HEIGHT THE FILTER ROW COSTS THE LIST - the row plus its 6px bottom margin.
+ *
+ * Measured, not assumed: 32px, and constant across all 195 tile sizes in the sweep below (the
+ * row is a flex line around a 0.85em input, so it does not reflow with the card).
+ */
+export declare const FILTER_ROW_PX = 32;
+/**
+ * THE SMALLEST CARD THE FILTER BOX IS USABLE IN - measured 2026-09-03, and NOT arithmetic off
+ * `CHOOSER_MIN_*`.
+ *
+ * The chooser's own floor (400 x 240) was measured with three pinned elements. The filter row is
+ * a FOURTH, in a card that clips, so the old envelope does not survive the addition and could not
+ * be adjusted by adding 32px to it - the coupling between the two dimensions moves too.
+ *
+ * Same harness as the 2026-09-01 chooser sweep, re-run over 195 sizes with the row present. The
+ * run reproduces the chooser's published coupling exactly when the row is hidden (320-340 wide
+ * needs 280 tall, 360-380 needs 260, 400+ needs 220), which is what says the harness is measuring
+ * the same card and not a different one.
+ *
+ * ONE CRITERION IS TIGHTER, and it is the reason this is a separate floor rather than a bigger
+ * version of the old one: the chooser sweep asked for TWO visible list rows, this asks for
+ * THREE. A filter that leaves two rows visible did not earn the height it cost.
+ *
+ * Measured envelope with the row present:
+ *
+ *     320-340 wide -> 380 tall      400 wide -> 300 tall      420+ wide -> 280 tall
+ *
+ * 420 x 300 is that envelope at its cheapest width, with one sweep step (20px) of margin on the
+ * height for the reason `CHOOSER_MIN_*` states: the measurement used one font stack and one
+ * string, every host localizes the title, and a longer translation wraps sooner than the sample.
+ *
+ * ERRING HIGH IS THE CHEAP DIRECTION, exactly as it is for the chooser. Below this floor the
+ * reader gets the chooser they have today, unchanged; above it wrongly, they get a clipped
+ * control in a card that cannot scroll to reveal it.
+ */
+export declare const FILTER_MIN_WIDTH_PX = 420;
+export declare const FILTER_MIN_HEIGHT_PX = 300;
+/**
+ * Condition A: can this card afford the box at all?
+ *
+ * MEASURE THE REAL SURFACE - the card as drawn, never a viewport the host reports outward. The
+ * chooser's gate says the same thing for the same reason: where an author can state a viewport
+ * for generation purposes, that stated size describes a tile that does not exist yet.
+ */
+export declare function filterFitsChooser(width: number, height: number): boolean;
+/**
+ * Condition B: is the list long enough to be worth filtering?
+ *
+ * A filter box over four rows is clutter that spends pinned height for nothing, so the box
+ * appears only when the list actually scrolls.
+ *
+ * THE `- FILTER_ROW_PX` IS LOAD-BEARING, and leaving it out is how the naive version ships a
+ * flicker loop: inserting the box shrinks the list, which can turn a list that did not overflow
+ * into one that does, which would remove the box, which restores the overflow. Asking whether the
+ * content exceeds the height the list WOULD have is a single stable pass, because `scrollHeight`
+ * is content height and does not change when the container shrinks.
+ */
+export declare function listNeedsFilter(scrollHeight: number, clientHeight: number): boolean;
+/** Why the box is or is not on screen - logged once per open, so the floor can be judged against
+ *  real tiles rather than only against the sweep. */
+export type QualifyFilterGateReason = "shown" | "too-small" | "no-overflow";
+export interface QualifyFilterGateInput {
+    /** Real drawn width of the CARD, in CSS pixels. */
+    cardWidth: number;
+    /** Real drawn height of the card. */
+    cardHeight: number;
+    /** The list's content height and its current viewport height. */
+    scrollHeight: number;
+    clientHeight: number;
+}
+/**
+ * Both conditions, and the reason - which the host logs whichever way it comes out.
+ *
+ * DECIDED ONCE PER OPEN. Neither host re-asks this while the dialog is up: not when the filter
+ * hides rows and the list stops overflowing (a control that vanishes mid-typing is worse than one
+ * that is briefly unnecessary), and not on resize (a dialog whose controls appear and disappear
+ * under a window drag reads as broken).
+ */
+export declare function qualifyFilterGate(i: QualifyFilterGateInput): {
+    show: boolean;
+    why: QualifyFilterGateReason;
+};
+/** One row, as the hosts record it while BUILDING the list - the element handle plus the text it
+ *  is matched on, carried beside the element rather than scraped back out of it later. */
+export interface QualifyFilterRow<E> {
+    el: E;
+    name: string;
+    description: string;
+}
+/** A heading and the rows it introduces, in render order. `section` separates the fitting list
+ *  from the refusal block behind "Show all chart types" - two independently visible surfaces
+ *  answering two different questions, and only one of them can be auto-opened. */
+export interface QualifyFilterGroup<E> {
+    heading: E | null;
+    section: "fits" | "refused";
+    rows: QualifyFilterRow<E>[];
+}
+/** WHICH SENTENCE THE HOST HAS TO SHOW. The host owns the words (it localizes); this owns the
+ *  decision, which is the half that can differ between two hosts without anyone noticing.
+ *
+ *  "none"         - a name tier answered, or nothing is being filtered. Say nothing: the reader's
+ *                   own word was found where they expected it and needs no explanation.
+ *  "descFallback" - no name matched; these matched on description. MUST be said - a silent
+ *                   fall-through is indistinguishable from bad matching.
+ *  "onlyRefusals" - nothing that FITS matches, but something in the refusal block does. Say where
+ *                   it went; that block is now open.
+ *  "noMatch"      - nothing anywhere. NEVER phrase this like "nothing fits your data": one is a
+ *                   statement about a typed string and is fixed with backspace, the other is a
+ *                   statement about the data and is not.
+ */
+export type QualifyFilterNoteKind = "none" | "descFallback" | "onlyRefusals" | "noMatch";
+export interface QualifyFilterView<E> {
+    /** Rows to show, and rows to hide. Two lists rather than one predicate so a host can write
+     *  them in one pass without asking a Set per element. */
+    show: E[];
+    hide: E[];
+    /** Headings to show, and headings that now introduce nothing. A heading with nothing under it
+     *  is a label for an empty category, and the rule it draws reads as a divider between two
+     *  things that are not there. */
+    showHeadings: E[];
+    hideHeadings: E[];
+    tier: QualifyFilterTier;
+    /** Matches and totals for the FITTING list - what the "12 of 137" counter is made of. */
+    matched: number;
+    total: number;
+    refusalMatched: number;
+    /**
+     * Does the refusal block need to be OPEN for this term?
+     *
+     * True only when the term matches nothing that fits and something that does not. "Why isn't
+     * my chart here" is the only question that section is open to ask, and the reader has just
+     * asked it by name - the server's own sentence about why it cannot be drawn is already
+     * rendered, one collapsed checkbox away.
+     *
+     * THE HOST MUST TREAT THIS AS AN OVERRIDE, NOT A SETTING: remember what the reader's own
+     * checkbox said before the first override, and put it back the moment this goes false. An
+     * auto-expansion that sticks leaves the reader with a section they never opened.
+     */
+    openRefusals: boolean;
+    note: QualifyFilterNoteKind;
+    /** The normalized term, for the host to interpolate into whichever sentence it shows. */
+    term: string;
+}
+/**
+ * The filtered view of a whole dialog: fitting rows, refusal rows, headings and the note.
+ *
+ * ORDER IS UNTOUCHED, as everywhere else here - `show` and `hide` come out in the order the
+ * groups were built, so a host writing them in sequence cannot reorder anything by accident.
+ */
+export declare function computeQualifyFilterView<E>(groups: readonly QualifyFilterGroup<E>[], term: string | null | undefined): QualifyFilterView<E>;
+/** The counter beside the box: "12 of 137" while filtering, the plain total otherwise.
+ *
+ *  Digits only, assembled here so both hosts show the same shape of number - the words around it
+ *  (there are none today) would be the host's business, the arithmetic is not. */
+export declare function qualifyFilterCountText(view: {
+    tier: QualifyFilterTier;
+    matched: number;
+    total: number;
+}): string;
+/**
+ * The same question for a host whose chooser is an INLINE, SCROLLING PANEL - and it has no size
+ * clause, for the reason `shouldOpenInlineChooserOnGenerate` already sets out at length.
+ *
+ * THE ASYMMETRY IS THE POINT AND IT IS MEASURED. The modal lives in a card that CLIPS, so past a
+ * certain smallness its controls are simply not on screen. A panel that flows inside a scrolling
+ * pane, with a wrapping footer and a list carrying its own max-height, cannot reach that state -
+ * swept across 63 pane sizes down to 200x120, every one stayed usable. A size clause here would
+ * protect nobody and would switch the feature off in a default Excel task pane, which is narrower
+ * than the modal's floor.
+ *
+ * The OVERFLOW half still applies: a five-row answer does not want a filter box in any host.
+ */
+export declare function inlineFilterGate(rowCount: number): {
+    show: boolean;
+    why: QualifyFilterGateReason;
+};
+/**
+ * The inline panel's stand-in for "the list scrolls".
+ *
+ * A COUNT RATHER THAN A MEASUREMENT, because the panel's list carries a fixed `max-height: 220px`
+ * and rows are one line each - so the count IS the overflow question there, where in the modal
+ * the card's height is the variable and the count is not. Eight rows at ~24px is the point the
+ * 220px list starts scrolling; below it there is nothing to scroll past.
+ */
+export declare const INLINE_FILTER_MIN_ROWS = 8;

package/package.json

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