@bicharts/chart-host 0.6.111 → 0.6.112

package/dist/react.mjs

@@ -1,27 +1,18 @@
 /*! @bicharts/chart-host — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; Natural Earth and US Census/TIGER (public domain). Full text: NOTICE in this package. */
 import {
-  LINKED_HOVER_CLASS,
   attachControls,
   badgeKey,
-  bindFilter,
   createControls,
-  createFilter,
-  createFilterScope,
-  filterScopeOf,
-  fromVegaInteraction,
   noteBadges,
-  notesFor,
-  payloadRowReader,
-  viewFromToken,
-  viewToken
-} from "./chunk-FT75ONSB.mjs";
+  notesFor
+} from "./chunk-GTJG3SMD.mjs";
 import {
   assembleD3,
   createChartGroup,
   createChartHost,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-CASW2BIB.mjs";
+} from "./chunk-TE54AFRN.mjs";
 import "./chunk-IL5M7K6Z.mjs";
 import "./chunk-AEO5SFEQ.mjs";
 import "./chunk-KGVNZR23.mjs";
@@ -29,10 +20,23 @@ import "./chunk-7XT5OJ6M.mjs";
 import {
   geoFromCache,
   loadGeo
-} from "./chunk-S564YXNE.mjs";
-import "./chunk-NJWR3DFK.mjs";
+} from "./chunk-5YSZABCS.mjs";
+import "./chunk-FIG5DIW7.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-KY4FI2HA.mjs";
+import {
+  ANY_VALUE,
+  LINKED_HOVER_CLASS,
+  bindFilter,
+  createFilter,
+  createFilterScope,
+  filterScopeOf,
+  fromVegaInteraction,
+  isAnyValue,
+  payloadRowReader,
+  viewFromToken,
+  viewToken
+} from "./chunk-2KLFIGTQ.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/react.tsx
@@ -77,6 +81,8 @@ function BicChart(props) {
     onSelectionGlyphs,
     layoutPass,
     onInvalidSentinel,
+    builtForRows,
+    onRowGrowth,
     id,
     filteredBy,
     respondsWith,
@@ -153,6 +159,10 @@ function BicChart(props) {
   onSelectionGlyphsRef.current = onSelectionGlyphs;
   const onInvalidSentinelRef = useRef(onInvalidSentinel);
   onInvalidSentinelRef.current = onInvalidSentinel;
+  const builtForRowsRef = useRef(builtForRows);
+  builtForRowsRef.current = builtForRows;
+  const onRowGrowthRef = useRef(onRowGrowth);
+  onRowGrowthRef.current = onRowGrowth;
   const onAnnotationClickRef = useRef(onAnnotationClick);
   onAnnotationClickRef.current = onAnnotationClick;
   const annKey = useMemo(() => JSON.stringify(annotations ?? []), [annotations]);
@@ -200,6 +210,14 @@ function BicChart(props) {
       get onInvalidSentinel() {
         return onInvalidSentinelRef.current ? (info) => onInvalidSentinelRef.current?.(info) : void 0;
       },
+      // Getters, the onInvalidSentinel pattern: read at render time, so a new prop needs no
+      // rebuild, and an absent callback stays absent (the console fallback is decided by presence).
+      get builtForRows() {
+        return builtForRowsRef.current ?? null;
+      },
+      get onRowGrowth() {
+        return onRowGrowthRef.current ? (n) => onRowGrowthRef.current?.(n) : void 0;
+      },
       annotations: annotationsRef.current ?? [],
       onAnnotationClick: (a) => onAnnotationClickRef.current?.(a),
       // What a filtering lasso reaches: the page filter (`selects`), or the
@@ -513,6 +531,7 @@ function useMeasuredSize(ref) {
   return size;
 }
 export {
+  ANY_VALUE,
   BicChart,
   BicChartGroup,
   BicDevtools,
@@ -526,6 +545,7 @@ export {
   createFilterScope,
   filterScopeOf,
   fromVegaInteraction,
+  isAnyValue,
   noteBadges,
   notesFor,
   useBicControls,

package/dist/types/filterScope.d.ts

@@ -115,6 +115,17 @@ export interface PageView {
 export declare function viewToken(view: PageView): string;
 /** A token from viewToken back to a view; null when it isn't one. */
 export declare function viewFromToken(token: string | null | undefined): PageView | null;
+/**
+ * A KEY VALUE THAT MATCHES ANY VALUE. A label pick (an axis label naming a region on a chart of region by stage) selects on
+ * the label's own field, so the filter's other key columns are left free: the key is (EMEA, ANY_VALUE), "EMEA in any
+ * stage", and a stage that comes back once another filter clears is still in the pick. JSON-safe: a saved view's
+ * `{ "__bicAny": true }` reads back as the same wildcard.
+ */
+export declare const ANY_VALUE: Readonly<{
+    __bicAny: true;
+}>;
+/** Whether a key value is the wildcard (ANY_VALUE, or its JSON round trip). */
+export declare function isAnyValue(v: unknown): boolean;
 /** Make a filter keyed by `columns` (one name, or several for a compound key such as a route). */
 export declare function createFilter(columns: string | readonly string[], opts?: FilterOptions): Filter;
 /** Make a page's filter scope. */

package/dist/types/focusKeep.d.ts

@@ -4,9 +4,20 @@ export interface FocusMemory {
     start: number | null;
     end: number | null;
     dir: "forward" | "backward" | "none" | null;
+    /** The focused element's data-row-idx, when it carries one: the row it stands for, wherever a redraw puts it. */
+    row?: string;
 }
 /** The focused element inside the container and its caret, or null when focus is elsewhere (or on the container). */
 export declare function rememberFocus(container: HTMLElement): FocusMemory | null;
 /** Give focus back to the same element of the new draw, with its caret. Nothing when the chart already moved focus into
  *  itself, or when the new draw has no such element. Returns whether focus was restored. */
 export declare function restoreFocus(container: HTMLElement, memory: FocusMemory | null): boolean;
+export interface FocusTracker {
+    /** What had focus, when a redraw has since removed it and focus fell to nothing (the page body); null when the
+     *  element is still there, focus went somewhere else, or nothing in the chart had focus. Consumed by the call. */
+    takeLost(): FocusMemory | null;
+    /** Drop the note (the host's own render remembers and restores focus itself). */
+    forget(): void;
+    dispose(): void;
+}
+export declare function trackFocus(container: HTMLElement): FocusTracker;

package/dist/types/geoWorld110m.d.ts

@@ -1 +1,10 @@
+/** [minLon, minLat, maxLon, maxLat], in degrees: wide enough for the territory, clear of its sovereign's other parts. */
+type Window = readonly [number, number, number, number];
+export declare const TERRITORY_PARTS: ReadonlyArray<{
+    from: string;
+    to: string;
+    name: string;
+    window: Window;
+}>;
 export declare const WORLD_110M: any;
+export {};

package/dist/types/host.d.ts

@@ -6,6 +6,9 @@ import { type SelectionRule, type SelectionPaintMode } from "./selection";
  *  the rows in view, so a subscriber that holds keys the data no longer carries keeps them. */
 export interface SelectionChangeMeta {
     keepHidden?: boolean;
+    /** The pick was a category label (an axis label carrying its category's rows), not a mark: a page filter selects on
+     *  the label's own field (bindFilter), leaving the key columns the label doesn't name free. */
+    fromLabel?: boolean;
 }
 export interface SelectionPaintReport {
     rule: SelectionRule;
@@ -22,6 +25,7 @@ import { type ValuePlacementCensus } from "./valuePlacement";
 import { type FitRenderedChartOptions, type FitRenderedChartResult } from "./fitDom";
 import { type LabelContrastOptions, type LabelContrastReport } from "./labelContrastDom";
 import { type IdScopeReport } from "./idScope";
+import { type RowGrowthNotice } from "./rowGrowth";
 import { type MarkAnnotation, type AnnotationReport } from "./annotations";
 import type { ZoomMemoryHook } from "./zoomMemory/zoomMemoryDom";
 export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
@@ -261,6 +265,14 @@ export interface ChartHostConfig {
         reason: string;
         message: string;
     }) => void;
+    /**
+     * The rows this chart's code was generated on (the request's row count). When set, every render compares the rows it
+     * drew with it and calls onRowGrowth when the chart now draws on far more rows than it was built for (rowGrowthNotice).
+     * Absent or null: no comparison - a chart from before the count was kept, or an example.
+     */
+    builtForRows?: number | null;
+    /** Called after a render that drew on far more rows than builtForRows. Absent: the host says it once in the console. */
+    onRowGrowth?: (notice: RowGrowthNotice) => void;
     /**
      * NOTES ON MARKS. Each annotation names a key - a value in a column of this chart's data, such as a
      * country code - and the host draws a badge on that key's mark after every render, wherever a filter,

package/dist/types/index.d.ts

@@ -12,7 +12,7 @@ export { codeReadsDatesInLocalTime, vegaSpecReadsDatesInLocalTime } from "./date
 export { createChartHost, compileRenderFn, stripEsmExports, requiredD3Plugins, explainRenderFailure, sessionViewStateProvider, noopViewStateProvider, assembleD3, D3_PLUGIN_PACKAGES, type ChartHost, type ChartHostConfig, type RenderFn, type SelectionPaintReport, type SelectionChangeMeta } from "./host";
 export { ANNOTATION_CLASS, ANNOTATION_LAYER_CLASS, type MarkAnnotation, type AnnotationReport } from "./annotations";
 export { KEYBOARD_STAMP, KEYBOARD_CLASS, WIRED_ATTR as KEYBOARD_WIRED_ATTR, codeHasKeyboardStamp, installKeyboard, rowNameOf, type KeyboardEnv, type KeyboardHandle } from "./keyboardMarks";
-export { rememberFocus, restoreFocus, type FocusMemory } from "./focusKeep";
+export { rememberFocus, restoreFocus, trackFocus, type FocusMemory, type FocusTracker } from "./focusKeep";
 export type { MarkNoteLike, NoteBadgeOptions } from "./markNotes";
 export type { Controls, ControlInfo, ControlsAttachment } from "./controls";
 export { createChartGroup, toSourceRows, syncMemberSelection, type ChartGroup, type ChartGroupMember, type ChartGroupSelection, type ChartGroupChange, type ChartGroupMemberOptions, type ChartGroupSourceOptions, type ChartGroupPayload } from "./group";
@@ -39,6 +39,7 @@ export { scopeChartIds, newIdScope, type IdScopeReport } from "./idScope";
 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, straddles, straddleSampleGrid, minContrastOver, pickColorOver, STRADDLE_COLS, STRADDLE_ROWS, STRADDLE_MIN_SHARE, STRADDLE_TARGET_CONTRAST, STRADDLE_PILL_ALPHA, type LabelDecision, } from "./labelContrast";
 export { censusMarks, isBlankRender, blankRenderFlag, type MarkCensus, type BlankVerdictInput } from "./blankRender";
 export { isInvalidSentinelError, invalidSentinelReason } from "./invalidSentinel";
+export { rowGrowthNotice, ROW_GROWTH_MIN_RATIO, ROW_GROWTH_MIN_EXTRA, type RowGrowthNotice } from "./rowGrowth";
 export { censusHitBands, hitBandFlag, MIN_HIT_BAND_PX, type HitBandCensus } from "./hitBands";
 export { censusClippedText, clippedTextFlag, CLIP_TOLERANCE_PX, type ClippedTextCensus, type ClippedText } from "./clippedText";
 export { censusColourSpread, colourSpreadFlag, SAME_SHADE_DELTA_E, MIN_RAMP_FILLS, type ColourSpreadCensus } from "./colourSpread";

package/dist/types/page.d.ts

@@ -1,4 +1,4 @@
 export { viewToken, viewFromToken, LINKED_HOVER_CLASS, type PageView } from "./filterScope";
-export { createFilter, createFilterScope, bindFilter, payloadRowReader, fromVegaInteraction, filterScopeOf, type Filter, type FilterScope, type FilterOptions, type FilterKey, type FilterChangeReason, type FilterBinding, type BindFilterOptions, type VegaInteractionEvent } from "./filterScope";
+export { createFilter, createFilterScope, bindFilter, payloadRowReader, fromVegaInteraction, filterScopeOf, ANY_VALUE, isAnyValue, type Filter, type FilterScope, type FilterOptions, type FilterKey, type FilterChangeReason, type FilterBinding, type BindFilterOptions, type VegaInteractionEvent } from "./filterScope";
 export { createControls, attachControls, readControls, type Controls, type ControlInfo, type ControlsAttachment } from "./controls";
 export { noteBadges, badgeKey, notesFor, type MarkNoteLike, type NoteBadgeOptions } from "./markNotes";

package/dist/types/react.d.ts

@@ -8,7 +8,7 @@ import { type Controls } from "./controls";
 export { createControls, type Controls, type ControlInfo } from "./controls";
 export { noteBadges, badgeKey, notesFor, type MarkNoteLike, type NoteBadgeOptions } from "./markNotes";
 export { viewToken, viewFromToken, LINKED_HOVER_CLASS, type PageView } from "./filterScope";
-export { createFilter, createFilterScope, fromVegaInteraction, filterScopeOf, type Filter, type FilterOptions, type FilterScope, type FilterChangeReason } from "./filterScope";
+export { createFilter, createFilterScope, fromVegaInteraction, filterScopeOf, ANY_VALUE, isAnyValue, type Filter, type FilterOptions, type FilterScope, type FilterChangeReason } from "./filterScope";
 export interface BicChartProps {
     /** Generated render() source (an ES module's `code` export, or the raw string). */
     code?: string;
@@ -74,6 +74,10 @@ export interface BicChartProps {
      * throw propagates as before. See createChartHost's `onInvalidSentinel`.
      */
     onInvalidSentinel?: ChartHostConfig["onInvalidSentinel"];
+    /** The rows this chart's code was generated on. Every render compares the rows it drew against it (see createChartHost). */
+    builtForRows?: ChartHostConfig["builtForRows"];
+    /** Called when the rows drawn far outnumber builtForRows. Absent: chart-host says it once in the console. */
+    onRowGrowth?: ChartHostConfig["onRowGrowth"];
     /** 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/dist/types/rowGrowth.d.ts

@@ -0,0 +1,17 @@
+export declare const ROW_GROWTH_MIN_RATIO = 10;
+export declare const ROW_GROWTH_MIN_EXTRA = 500;
+export interface RowGrowthNotice {
+    code: "row-growth";
+    /** The reader's priority, in the vocabulary of a generate result's notices: a fact about the data. */
+    severity: "data";
+    builtFor: number;
+    rendered: number;
+    /** The sentence a host shows when it does not word it itself (English). */
+    text: string;
+    /** The render row's Location token, `grow:<builtFor>` - kept per render row, so the population is countable. */
+    locationToken: string;
+}
+export declare function rowGrowthNotice(builtFor: number | null | undefined, rendered: number | null | undefined, opts?: {
+    canGenerate?: boolean;
+    formatCount?: (n: number) => string;
+}): RowGrowthNotice | null;

package/dist/zoom-memory.mjs

@@ -1,7 +1,7 @@
 /*! @bicharts/chart-host — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; Natural Earth and US Census/TIGER (public domain). Full text: NOTICE in this package. */
 import {
   K
-} from "./chunk-NJWR3DFK.mjs";
+} from "./chunk-FIG5DIW7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/zoomMemory/zoomMemory.ts

package/package.json

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