@bicharts/chart-host 0.6.107 → 0.6.109

package/dist/types/defaults.d.ts

@@ -1,4 +1,5 @@
-import { type RenderOptions } from "./contract";
+import { type RenderOptions, type HostSelectionFact } from "./contract";
+export declare function cleanHostSelection(v: unknown): HostSelectionFact | undefined;
 export type ResolveOptionsInput = {
     [K in keyof RenderOptions]?: any;
 };

package/dist/types/filterScope.d.ts

@@ -62,8 +62,9 @@ export interface Filter {
     readonly reason: FilterChangeReason | null;
     /** Bumped on every change: a cheap identity for memoising on the filter's state. */
     readonly version: number;
-    /** Select these rows' keys (replacing the selection). An empty list clears. */
-    selectRows(rows: readonly Record<string, unknown>[], reason?: FilterChangeReason): void;
+    /** Select these rows' keys (replacing the selection). An empty list clears. `keep` adds keys held already that these
+     *  rows cannot name (keys another filter hid from the chart that made the selection): they stay selected. */
+    selectRows(rows: readonly Record<string, unknown>[], reason?: FilterChangeReason, keep?: readonly FilterKey[]): void;
     /** Select keys by value: one value per key (a one-column filter) or one array per key. */
     set(keys: readonly unknown[] | readonly FilterKey[] | unknown, reason?: FilterChangeReason): void;
     /** Clear the selection (and every bound chart's marks). */
@@ -119,9 +120,8 @@ export declare function createFilter(columns: string | readonly string[], opts?:
 export declare function createFilterScope(): FilterScope;
 export interface FilterBinding {
     /**
-     * Call after the chart is handed new data. A selection whose key is still drawn is repainted;
-     * one whose key is gone is cleared (reason "data") when this chart made it. An empty payload is
-     * treated as data still arriving, not as the key being gone.
+     * Call after the chart is handed new data. The selection is repainted where its keys are drawn now, and a key the new
+     * rows do not carry stays selected (the chart is told how many through hostSelection.hidden): new data never clears it.
      */
     reconcile(): void;
     /** Repaint the filter's selection onto the chart's marks. */

package/dist/types/focusKeep.d.ts

@@ -0,0 +1,12 @@
+export interface FocusMemory {
+    sig: string;
+    nth: number;
+    start: number | null;
+    end: number | null;
+    dir: "forward" | "backward" | "none" | null;
+}
+/** 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;

package/dist/types/host.d.ts

@@ -2,6 +2,11 @@ import { type RenderOptions, type ViewStateProvider } from "./contract";
 import { type ResolveOptionsInput } from "./defaults";
 import { type SelectionRule, type SelectionPaintMode } from "./selection";
 /** What onSelectionPaint reports: the declared rule, how this paint decided, and how many marks it lit. */
+/** What a selection change carries besides its rows (1.21.0): `keepHidden` when the chart's set is what the reader holds among
+ *  the rows in view, so a subscriber that holds keys the data no longer carries keeps them. */
+export interface SelectionChangeMeta {
+    keepHidden?: boolean;
+}
 export interface SelectionPaintReport {
     rule: SelectionRule;
     mode: SelectionPaintMode;
@@ -275,6 +280,16 @@ export interface ChartHostConfig {
      * `selects` and the group itself. Never throws through: an answer that throws counts as reached.
      */
     selectionReachesPage?: () => boolean;
+    /**
+     * WHETHER A CLICK ON A MARK SELECTS ANYTHING. False: nothing listens to this chart's selection - no
+     * page filter, no group sibling, no callback - so its marks are drawn inert: no pointer cursor (over the chart's own
+     * inline one), no hover dimming of the others, and the reader's click, or a selection the chart dispatches itself,
+     * lights and dims nothing. A selection the page hands in (selection.highlight) still paints. Read at every click and
+     * every paint, so a binding added later counts at once. Absent: true, which every host but React relies on (a Power
+     * BI click always reaches its selection manager; an Excel click always opens a selection card). An answer that
+     * throws counts as true.
+     */
+    marksSelect?: () => boolean;
 }
 export interface ChartHost {
     /** Replace the notes drawn on marks (see ChartHostConfig.annotations); redraws them at once. */
@@ -304,7 +319,7 @@ export interface ChartHost {
     selection: {
         /** Subscribe to cross-filter changes (mark clicks + the chart's own
          *  llm-xfilter-refresh dispatches). rowIdxs = [] means cleared. */
-        onChange(cb: (rowIdxs: number[], source: string) => void): () => void;
+        onChange(cb: (rowIdxs: number[], source: string, meta?: SelectionChangeMeta) => void): () => void;
         /** Clear the chart's own selection (calls __llmXfClear when the chart set it). */
         clear(): void;
         /**
@@ -323,6 +338,12 @@ export interface ChartHost {
          * republish what the other just sent and fight itself.
          */
         highlight(rowIdxs: number[]): void;
+        /**
+         * How many of the selection's identities the data on screen does not carry (1.21.0): a filter keyed by value that
+         * another filter narrowed knows, this host does not. Told to the chart (RenderOptions.hostSelection and the
+         * CONTAINER_SLOT_HOST_SELECTION slot), so a checkbox column can say "2 selected, 2 hidden". A clear resets it.
+         */
+        setHidden?(count: number): void;
         readonly current: number[] | null;
     };
     animation: {

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
-export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, NOTE_STYLE_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, CONTAINER_SLOT_SCROLL, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, DIM_OPACITY_MIN, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, type XfilterRefreshDetail, } from "./contract";
-export { resolveOptions, type ResolveOptionsInput } from "./defaults";
+export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, NOTE_STYLE_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, CONTAINER_SLOT_SCROLL, CONTAINER_SLOT_HOST_SELECTION, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, MARKS_INERT_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, DIM_OPACITY_MIN, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, type XfilterRefreshDetail, type HostSelectionFact, } from "./contract";
+export { resolveOptions, cleanHostSelection, type ResolveOptionsInput } from "./defaults";
 export { hostLinkServices, type HostLinkServices, type ClipboardLike } from "./hostLinks";
 export { tableToCsv, tableToXlsx, buildExportFile, exportFileName, sheetName as exportSheetName, excelNumberFormat, excelSerial, bytesToBase64, exportFormatsFor, exportTableService, browserSaveFile, EXPORT_FORMATS, XLSX_MIME, CSV_MIME, type ExportTable, type ExportColumn, type ExportColumnType, type ExportCell, type ExportFormat, type ExportFile, type SaveFileService, type ExportTableService, } from "./exportTable";
 export { OPTIONS_VOCABULARY, LIVE_OPTION_KEYS, MAX_MAP_POINTS_MIN, MAX_MAP_POINTS_MAX, LIMIT_COUNT_MAX, wireLimitCount, codeReadsOption, type OptionVocabularyEntry, type OptionTiming, type OptionWire, type OptionKey, } from "./optionsVocabulary";
@@ -9,8 +9,10 @@ export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clea
 export declare function registerCityTable(packed: string): void;
 export { buildRenderPayload, type RenderPayload, type GeoPointBinding, type GeoBinding, type GeoProvinceReport, type ProvinceJoin } from "./payload";
 export { codeReadsDatesInLocalTime, vegaSpecReadsDatesInLocalTime } from "./dateCells";
-export { createChartHost, compileRenderFn, stripEsmExports, requiredD3Plugins, explainRenderFailure, sessionViewStateProvider, noopViewStateProvider, assembleD3, D3_PLUGIN_PACKAGES, type ChartHost, type ChartHostConfig, type RenderFn, type SelectionPaintReport } from "./host";
+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 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";

package/dist/types/keyboardMarks.d.ts

@@ -0,0 +1,43 @@
+export declare const KEYBOARD_STAMP = "// bic:keyboard-marks";
+/** Whether the code carries the keyboard stamp in its header. */
+export declare function codeHasKeyboardStamp(code: unknown): boolean;
+/** On the container while its chart works from the keyboard. */
+export declare const KEYBOARD_CLASS = "lch-keyboard";
+/** On each element the host made focusable, so it never touches one the chart made focusable itself. */
+export declare const WIRED_ATTR = "data-lch-kb";
+export interface KeyboardEnv {
+    container: HTMLElement;
+    /** The elements a click selects (the host's click selector). */
+    markSelector: string;
+    /** Elements pressed with Enter: the chart's declared controls and the host's badges. */
+    pressSelector: string;
+    /** Elements never to treat as marks (the host's own layers). */
+    skipSelector: string;
+    /** True while a click on a mark selects nothing (the marks are then not made focusable). */
+    inert(): boolean;
+    /** Select a mark as a click on it would. */
+    select(mark: Element, mods: {
+        ctrl: boolean;
+        shift: boolean;
+    }): void;
+    /** The reader's clear: Ctrl+Shift+C on every host (Power BI's own clear-selection key), and Escape where the host
+     *  lets it (escapeClears). */
+    clear(): void;
+    /** Whether Escape clears. False for a host whose frame uses Escape to move focus out of the chart (Power BI), so
+     *  leaving the chart never wipes the reader's selection there. Default true. */
+    escapeClears?: boolean;
+    isSelected(mark: Element): boolean;
+    /** What a screen reader calls a mark that names nothing itself. */
+    labelOf(mark: Element): string | null;
+    /** A stable key for a mark across redraws (its rows). */
+    keyOf(mark: Element): string;
+}
+export interface KeyboardHandle {
+    /** Re-apply tab stops, roles, names and pressed state after a draw or a selection change. */
+    refresh(): void;
+    destroy(): void;
+}
+/** What a screen reader calls a row: its first few values, numbers in the reader's culture, internal columns left out.
+ *  Shared so every host names a mark the same way. */
+export declare function rowNameOf(columns: ReadonlyArray<unknown>, row: ReadonlyArray<unknown> | null | undefined, culture?: string): string | null;
+export declare function installKeyboard(env: KeyboardEnv): KeyboardHandle;

package/dist/types/react.d.ts

@@ -95,7 +95,7 @@ export interface BicChartProps {
      * THE PAGE FILTER THIS CHART SELECTS - from useBicFilter("RegionCode"). A click sets it, the
      * same click or a click on empty canvas clears it, and the filter's state is painted onto the
      * marks whoever changed it: `filter.clear()` from a page button clears the marks too. New data
-     * keeps a selection whose key is still drawn and clears (reason "data") one whose key is gone.
+     * keeps the selection, a key it no longer draws included; the chart is told how many are hidden.
      * The page reads `filter.value` / `filter.row` and never writes a select handler. With
      * `selects`, the filter owns what this chart shows as selected.
      */

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-SYUJ4TPX.mjs";
+} from "./chunk-TH577JHI.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/zoomMemory/zoomMemory.ts

package/package.json

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