@bicharts/chart-host 0.5.58 → 0.5.60

package/dist/{chunk-UUH6S5Q5.mjs → chunk-WG4NTR5H.mjs}

@@ -1227,6 +1227,87 @@ function blankRenderFlag(lang, cause) {
   return `blankrender:${clean(lang)}:${clean(cause)}`;
 }
 
+// src/hitBands.ts
+var MIN_HIT_BAND_PX = 8;
+var ELEMENT_CAP2 = 5e3;
+var EMPTY2 = {
+  openStrokes: 0,
+  interactive: 0,
+  hairline: 0,
+  uncovered: 0,
+  widestPx: 0
+};
+var OPEN_TAGS = /* @__PURE__ */ new Set(["path", "line", "polyline"]);
+function styleOf(el, doc) {
+  try {
+    const view = doc?.defaultView;
+    return view?.getComputedStyle ? view.getComputedStyle(el) : null;
+  } catch {
+    return null;
+  }
+}
+function attrOrComputed(el, name, cs) {
+  const a2 = el.getAttribute?.(name);
+  if (a2 !== null && a2 !== void 0 && String(a2).trim() !== "") return String(a2).trim();
+  const c = cs?.[name === "stroke-width" ? "strokeWidth" : name];
+  return c === null || c === void 0 ? "" : String(c).trim();
+}
+function isUnfilled(fill) {
+  const f = fill.toLowerCase();
+  return f === "none" || f === "transparent" || f === "rgba(0, 0, 0, 0)" || f === "rgba(0,0,0,0)";
+}
+function widthPx(raw) {
+  const m2 = /^(-?\d+(?:\.\d+)?)\s*(px)?$/i.exec(raw);
+  if (!m2) return NaN;
+  const n = parseFloat(m2[1]);
+  return isFinite(n) ? n : NaN;
+}
+function censusHitBands(container, doc) {
+  if (!container || typeof container.querySelectorAll !== "function") return EMPTY2;
+  try {
+    const els = Array.from(
+      container.querySelectorAll(`.${MARK_CLASS}, [${ROW_IDX_ATTR}]`)
+    );
+    if (els.length === 0 || els.length > ELEMENT_CAP2) return EMPTY2;
+    const ownerDoc = doc ?? container.ownerDocument;
+    const widestByGeom = /* @__PURE__ */ new Map();
+    const rows = [];
+    for (const el of els) {
+      const tag = String(el.tagName || "").toLowerCase();
+      if (!OPEN_TAGS.has(tag)) continue;
+      const cs = styleOf(el, ownerDoc);
+      const open = isUnfilled(attrOrComputed(el, "fill", cs));
+      const w = widthPx(attrOrComputed(el, "stroke-width", cs) || "1");
+      const geom = String(el.getAttribute?.("d") ?? "") || `${tag}#${String(el.getAttribute?.(ROW_IDX_ATTR) ?? "")}`;
+      const inert = String(cs?.pointerEvents ?? el.style?.pointerEvents ?? "") === "none";
+      rows.push({ el, geom, w, open, inert });
+      if (isFinite(w)) {
+        const prev = widestByGeom.get(geom);
+        if (prev === void 0 || w > prev) widestByGeom.set(geom, w);
+      }
+    }
+    const out = { ...EMPTY2 };
+    for (const r of rows) {
+      if (!r.open) continue;
+      out.openStrokes++;
+      if (r.inert) continue;
+      out.interactive++;
+      if (isFinite(r.w) && r.w > out.widestPx) out.widestPx = Math.round(r.w);
+      if (!(r.w < MIN_HIT_BAND_PX)) continue;
+      out.hairline++;
+      const best = widestByGeom.get(r.geom);
+      if (best === void 0 || best < MIN_HIT_BAND_PX) out.uncovered++;
+    }
+    return out;
+  } catch {
+    return EMPTY2;
+  }
+}
+function hitBandFlag(c) {
+  if (c.interactive === 0) return "";
+  return c.uncovered > 0 ? "hitband:d3:thin" : "hitband:d3:ok";
+}
+
 // src/host.ts
 function sessionViewStateProvider(container) {
   const holder = container;
@@ -1550,6 +1631,12 @@ function createChartHost(container, config) {
         }
       } catch {
       }
+      if (config.onHitBandCensus) {
+        try {
+          config.onHitBandCensus(censusHitBands(container, doc));
+        } catch {
+        }
+      }
     },
     setOptions(partial) {
       raw = { ...raw, ...partial };
@@ -1655,6 +1742,9 @@ export {
   censusMarks,
   isBlankRender,
   blankRenderFlag,
+  MIN_HIT_BAND_PX,
+  censusHitBands,
+  hitBandFlag,
   sessionViewStateProvider,
   noopViewStateProvider,
   requiredD3Plugins,

package/dist/index.mjs

@@ -31,12 +31,14 @@ import {
   LIFT_SELECTED_CLASS,
   MARK_CLASS,
   MARK_SELECTED_CLASS,
+  MIN_HIT_BAND_PX,
   ROW_IDX_ATTR,
   SELECTION_ACTIVE_CLASS,
   VALUE_AXIS_BASELINE_DEFAULT,
   XFILTER_REFRESH_EVENT,
   blankRenderFlag,
   buildRenderPayload,
+  censusHitBands,
   censusMarks,
   chartOwnsTimeline,
   clearGeoCache,
@@ -47,6 +49,7 @@ import {
   explainRenderFailure,
   geoAssetFor,
   geoFromCache,
+  hitBandFlag,
   isBlankRender,
   loadGeo,
   ne,
@@ -59,7 +62,7 @@ import {
   sessionViewStateProvider,
   stripEsmExports,
   te
-} from "./chunk-UUH6S5Q5.mjs";
+} from "./chunk-WG4NTR5H.mjs";
 import "./chunk-A2GMXZP7.mjs";
 
 // src/trivial.ts
@@ -648,6 +651,65 @@ 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 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;
@@ -890,14 +952,20 @@ 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,
   MARK_SELECTED_CLASS,
+  MIN_HIT_BAND_PX,
   ROW_IDX_ATTR,
   SELECTION_ACTIVE_CLASS,
   VALUE_AXIS_BASELINE_DEFAULT,
@@ -910,6 +978,7 @@ export {
   buildReviewWire,
   canConfirmLaunch,
   captureSvgSnapshot,
+  censusHitBands,
   censusMarks,
   chartOwnsTimeline,
   chooserFitsViewport,
@@ -922,27 +991,36 @@ export {
   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,
+  qualifyFilterGate,
   qualifyGroupHeadingFor,
   qualifyPick,
   qualifyRefusalHeadingFor,
   rasterizeSvgToPngDataUrl,
+  readQualifyChartRow,
+  readQualifyRefusalRow,
   refusalIsSelectable,
   registerCityTable,
   registerGeo,

package/dist/react.mjs

@@ -4,7 +4,7 @@ import {
   createChartHost,
   geoFromCache,
   loadGeo
-} from "./chunk-UUH6S5Q5.mjs";
+} from "./chunk-WG4NTR5H.mjs";
 import "./chunk-A2GMXZP7.mjs";
 
 // src/react.tsx

package/dist/types/hitBands.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Narrowest stroke, in CSS pixels, that counts as a real click target.
+ *
+ * The generated-code recipe asks for 10-14px. Eight is the floor rather than the target: it is
+ * generous enough that a chart which made a deliberate effort is not counted as a defect, and it
+ * is the same number the server-side rule uses, so the two halves cannot drift into disagreeing
+ * about which strokes are thin.
+ */
+export declare const MIN_HIT_BAND_PX = 8;
+export interface HitBandCensus {
+    /** Tagged marks that are OPEN strokes (`fill` none/transparent with a painted stroke). */
+    openStrokes: number;
+    /** Of those, the ones the chart has not opted out of with `pointer-events:none`. */
+    interactive: number;
+    /** Of the interactive ones, those whose own band is under `MIN_HIT_BAND_PX`. */
+    hairline: number;
+    /** Of the hairlines, those with no wider companion sharing their geometry. THE DEFECT. */
+    uncovered: number;
+    /** Widest band, rounded, seen on any interactive open stroke — for tuning the floor. */
+    widestPx: number;
+}
+/**
+ * Count the declared marks that are open strokes, and how many of them are too thin to hit.
+ *
+ * A companion is any OTHER tagged element sharing this one's geometry (the same `d`, or the same
+ * row index when there is no `d`) whose band clears the floor. That is exactly the recipe's
+ * shape, and it means a chart which drew its hit band correctly reports `uncovered: 0` however it
+ * spelled the transparency — the width is what makes a band a band.
+ *
+ * A mark whose own visible stroke is already wide is its OWN hit band and is never counted as a
+ * hairline. A Sankey link is the case that matters: its thickness is its value, routinely 10-40px,
+ * and asking it for a companion would be asking for a second hit area on top of a good one.
+ *
+ * Never throws — telemetry must not be the reason a delivered render fails. An unreadable width
+ * counts as WIDE (`NaN` fails the `< MIN_HIT_BAND_PX` test), because a census that guesses
+ * "defect" when it cannot measure would report the environment rather than the chart.
+ */
+export declare function censusHitBands(container: any, doc?: any): HitBandCensus;
+/**
+ * The always-on behaviour tag for this census, or "" when there is nothing to say.
+ *
+ * One tag per render in the `hitband:` namespace, so the rate is a `LIKE` away and the three
+ * states sum to every render that drew an open stroke — a rate needs a denominator, and
+ * `hitband:d3:ok` is it. Charts with no open-stroke marks at all emit nothing rather than a
+ * third value nobody will remember to exclude.
+ */
+export declare function hitBandFlag(c: HitBandCensus): string;

package/dist/types/host.d.ts

@@ -1,6 +1,7 @@
 import { type RenderOptions, type ViewStateProvider } from "./contract";
 import { type ResolveOptionsInput } from "./defaults";
 import { type MarkCensus } from "./blankRender";
+import { type HitBandCensus } from "./hitBands";
 export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
 /**
  * THE SESSION PROVIDER — what every host got hard-coded before contract 1.6.0, now named.
@@ -77,6 +78,18 @@ export interface ChartHostConfig {
         census: MarkCensus;
         rows: number;
     }) => void;
+    /**
+     * Called after every render with the hit-band census — how many of this chart's marks are
+     * thin open strokes, and how many of those have no wider companion to catch a click
+     * (2026-09-03). Counts only; the host decides what, if anything, to record. It fires even
+     * when everything is fine, because a rate needs a denominator and `interactive` is it: a
+     * chart with no open-stroke marks reports zeroes and should be excluded, not counted as good.
+     *
+     * This is the half a server-side code check structurally cannot do. A regex reads
+     * `.attr('stroke-width', 2)` and nothing else; `.attr('stroke-width', d => scale(d.v))` is a
+     * number only the browser knows, and this reads the COMPUTED width off the rendered element.
+     */
+    onHitBandCensus?: (census: HitBandCensus) => void;
     /** This chart declares time keyframes: frame one is allowed to be empty, so no blank verdict
      *  is issued for it. */
     animated?: boolean;

package/dist/types/index.d.ts

@@ -13,6 +13,8 @@ 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, type QualifyFilterTier, type QualifyFilterResult, type QualifyFilterRead, type QualifyFilterGateReason, type QualifyFilterGateInput, } 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";
+export { censusHitBands, hitBandFlag, MIN_HIT_BAND_PX, type HitBandCensus } from "./hitBands";

package/dist/types/qualifyFilter.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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;
+};
+/**
+ * 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.58",
+  "version": "0.5.60",
   "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",