@bicharts/chart-host 0.6.113 → 0.6.116

package/dist/types/dax.d.ts

@@ -20,3 +20,29 @@ export declare function calculateTable(table: string, ...filters: Array<string |
  *   filterQuery(FORECAST_DAX, treatAs(region, "Geography[RegionCode]"))
  */
 export declare function filterQuery(query: string, ...filters: Array<string | null | undefined | false>): string;
+/** A DAX query's result as the semantic-model query hooks return it: headers, then rows of values in header order. */
+export interface QueryTable {
+    columns: readonly {
+        name: string;
+    }[];
+    rows: readonly (readonly unknown[])[];
+}
+/**
+ * A result header's bare name: "Accounts[Account Number]" and "'Sales Owners'[Owner]" give the column's name,
+ * "[Total Revenue]" the measure's; a header that isn't a reference comes back as it is.
+ */
+export declare function columnName(header: string): string;
+/**
+ * A QUERY'S ROWS BY COLUMN NAME, for a query that feeds no chart: a form's choice list, a lookup, a count beside a
+ * chart. A DAX result names its columns "Table[Column]" and its measures "[Measure]"; each row comes back as an object
+ * keyed by the bare name, so `row["Account Number"]` reads Accounts[Account Number]. Two headers with one bare name
+ * (Accounts[Name] beside Owners[Name]) keep their whole headers, so neither hides the other. Takes the table or the
+ * query hook's `data` (a failed or pending result gives no rows):
+ *
+ *   const owners = queryRows(useSemanticModelQuery({ connection, query: OWNERS_DAX }).data);
+ *   owners.map(r => r["Sales owner"])
+ */
+export declare function queryRows(result: QueryTable | {
+    status?: string;
+    table?: QueryTable;
+} | null | undefined): Record<string, unknown>[];

package/dist/types/filterScope.d.ts

@@ -16,13 +16,26 @@ export interface FilterOptions {
     display?: string | readonly string[];
     /** A stable id for this filter within its scope. Generated when absent. */
     id?: string;
-    /** Its name in a saved view (scope.save / a link). Defaults to the key columns joined with "+". */
+    /**
+     * Its name in a saved view (scope.save / a link). Defaults to the key columns joined with "+". Two filters in one
+     * scope never share a name there: the second with one name is saved as "<name>-2", the third "<name>-3", in the order
+     * they joined the scope, so each puts back its own pick (FilterScope.keyOf says which name a filter has).
+     */
     key?: string;
     /**
      * LINKED HOVER: hovering a mark on a chart bound to this filter lights the marks with the same key on every other
      * chart bound to it (a glow, never a filter). Off by default.
      */
     hover?: boolean;
+    /**
+     * ONE PICK ACROSS SEVERAL PANELS. Filters with the same group name in one scope (one page) are one pick: a map, a
+     * table and a scatter that each pick a country, each with its own filter so each panel's query can leave its own pick
+     * out. A pick in one member clears the others, so the most recent pick is the page's one pick, and only the member
+     * holding it is active: one chip, one scope line, and a side list over the members' keys names that pick alone.
+     * Every member's chart shows the pick, so clicking the picked mark again in whichever panel shows it clears it.
+     * The members share their key columns; a filter keyed differently stays out of the group (said once in the console).
+     */
+    group?: string;
 }
 export interface Filter {
     readonly id: string;
@@ -56,9 +69,11 @@ export interface Filter {
     /**
      * The display text for ANY key - a badge's, a key set by value - read from `rows` (a table carrying the display
      * columns, e.g. the chart's own rows) or else from the rows this filter has seen; the key's values when neither
-     * has it.
+     * has it. `parts` names the key columns to say (a query that maps only some of them, see ScopedFilter): a display
+     * column speaks for the key column it is, or for the key column in its place when there is one display column per
+     * key column; a wildcard part says nothing. Absent, or naming every key column: the whole key.
      */
-    textOf(key: FilterKey | unknown, rows?: readonly Record<string, unknown>[]): string;
+    textOf(key: FilterKey | unknown, rows?: readonly Record<string, unknown>[], parts?: readonly string[]): string;
     /** Why the last change happened (null before any). */
     readonly reason: FilterChangeReason | null;
     /** Bumped on every change: a cheap identity for memoising on the filter's state. */
@@ -82,6 +97,15 @@ export interface Filter {
     keep<T extends Record<string, unknown>>(rows: readonly T[], columns?: readonly string[]): T[];
     /** Subscribe to changes. Returns the unsubscribe. */
     onChange(cb: (filter: Filter, reason: FilterChangeReason) => void): () => void;
+    /** Its group's name (FilterOptions.group), or null. */
+    readonly group?: string | null;
+    /**
+     * The filter holding the pick this one shows: the group member a reader last picked in, or this filter itself when it
+     * has no group; null while nothing is picked. A chart bound to a member paints this filter's keys.
+     */
+    readonly pick?: Filter | null;
+    /** Subscribe to the pick changing: this filter's, or any member's of its group. Returns the unsubscribe. */
+    onPick?(cb: () => void): () => void;
 }
 /** A page's filters: what a chip bar lists and what clear-all clears. */
 export interface FilterScope {
@@ -104,6 +128,11 @@ export interface FilterScope {
     save(): PageView;
     /** Put a saved view back: each filter set (or cleared when the view doesn't name it), each controls set. */
     restore(view: PageView | null | undefined): void;
+    /**
+     * A filter's name in this scope's saved views: its key, or "<key>-2", "<key>-3"... for the second and later filters
+     * with one key, in the order they joined the scope. Null for a filter not in the scope.
+     */
+    keyOf?(filter: Filter): string | null;
 }
 /** A saved page view: what save() returns and restore() takes. */
 export interface PageView {
@@ -130,13 +159,32 @@ export declare function isAnyValue(v: unknown): boolean;
 export declare function createFilter(columns: string | readonly string[], opts?: FilterOptions): Filter;
 /** Make a page's filter scope. */
 export declare function createFilterScope(): FilterScope;
+/**
+ * A FILTER AS ONE PANEL'S QUERY TAKES IT, for filterScopeOf and BicChart's scopedBy. A query that maps only some of a
+ * compound key's columns (treatAs(cell, "Accounts[Region]") on a Region x Stage pick) is narrowed by those parts alone,
+ * so its scope line names only them: `{ filter: cell, takes: ["Region"] }` says "Europe", never "Europe → 3-Propose".
+ */
+export interface ScopedFilter {
+    filter: Filter;
+    /** The filter's key columns this panel's query maps (by name, as the filter is keyed). Absent: the whole key. */
+    takes?: readonly string[];
+    /** What the scope line calls it. Default: the filter's label, or the taken columns while the filter has no label of its own. */
+    label?: string;
+}
+/** What filterScopeOf and scopedBy take: a filter whose whole key the query maps, or a ScopedFilter. */
+export type ScopeSource = Filter | ScopedFilter;
+/** The filter behind a scope source, or null. */
+export declare function scopeFilterOf(src: ScopeSource | null | undefined): Filter | null;
 /**
  * THE PAGE FILTERS THAT NARROWED A CHART'S ROWS, as the fact the chart is told (RenderOptions.filterScope, contract
  * 1.23.0). For filters applied to the chart's QUERY, so its rows arrive already narrowed and it can't see the filter.
  * Only the active ones count. The field is each one's label (its key columns when it has none), joined ", "; the values
  * are what its chip shows for each key, in order, each once. Nothing active, nothing to say: undefined.
+ *
+ * A ScopedFilter whose `takes` leaves key columns out says only the taken parts, as treatAs maps them: a pick whose
+ * taken parts are all wildcards keeps every row of that query, so while one is held the filter narrows nothing there.
  */
-export declare function filterScopeOf(filters: Filter | readonly Filter[] | null | undefined): FilterScopeFact | undefined;
+export declare function filterScopeOf(filters: ScopeSource | readonly ScopeSource[] | null | undefined): FilterScopeFact | undefined;
 export interface FilterBinding {
     /**
      * Call after the chart is handed new data. The selection is repainted where its keys are drawn now, and a key the new

package/dist/types/fit.d.ts

@@ -90,11 +90,16 @@ export type AxisPinEdge = "top" | "bottom";
  * one drawn over it.
  */
 export declare function axisPinPlacement(band: AxisBand, scrollTop: number, viewportH: number): AxisPinEdge | null;
-/** A reader's scroll offsets and the identity of the chart they were made on. */
+/** A reader's scroll offsets and the identity of the chart they were made on. `inner` holds the offsets of the chart's own
+ *  scrollers (TABLE_SCROLLER_CLASS), in document order, when any of them was scrolled; absent otherwise. */
 export interface ScrollMemory {
     key: unknown;
     x: number;
     y: number;
+    inner?: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
 }
 /** What the container reports once the overflow is decided. */
 export interface ScrollMetrics {

package/dist/types/fitDom.d.ts

@@ -113,8 +113,21 @@ export declare function unpinScrolledAxis(container: HTMLElement | null | undefi
  * Remember where the container is scrolled, BEFORE the container is cleared. A memory already waiting is kept: a second render that
  * starts before the first one restored sees an emptied (unscrolled) container, and must not overwrite what the reader really did.
  * A diagram that scrolls inside itself remembers its own position, so it is left alone.
+ * A table scrolls its rows inside its own frame (TABLE_SCROLLER_CLASS) while the container stays at the top, so those offsets
+ * are kept too, in document order, whenever one of them is scrolled; restoreInnerScroll puts them back.
  */
 export declare function rememberScroll(container: HTMLElement | null | undefined, key: unknown): void;
+/**
+ * Put a table's own scroll back after the SAME chart has drawn again: each element carrying TABLE_SCROLLER_CLASS gets the
+ * offsets its counterpart (by document order) had in `memory`. Nothing happens for a different chart (another key), a memory
+ * with no inner offsets, or a chart with no such element, so a new chart opens at the top. The browser clamps an offset the new
+ * layout cannot reach. Call it once the chart has drawn, with the memory takeScroll returned. Returns the offsets the scrollers
+ * report afterwards, or null when nothing was restored. Never throws.
+ */
+export declare function restoreInnerScroll(container: HTMLElement | null | undefined, memory: ScrollMemory | null | undefined, key: unknown): Array<{
+    x: number;
+    y: number;
+}> | null;
 /** The waiting memory, removed. The one place it is consumed, so a stale memory can never outlive a render. */
 export declare function takeScroll(container: HTMLElement | null | undefined): ScrollMemory | null;
 export declare function pinScrolledAxis(container: HTMLElement | null | undefined, svg: SVGSVGElement | null | undefined): AxisPinReport;

package/dist/types/host.d.ts

@@ -9,6 +9,9 @@ export interface SelectionChangeMeta {
     /** 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;
+    /** The pick was ONE mark clicked on its own (no Ctrl/Shift, not a lasso): a page filter selects the key columns that
+     *  mark's rows share, leaving the ones they differ on free (bindFilter), so a region row over its stages picks the region. */
+    fromMark?: boolean;
 }
 export interface SelectionPaintReport {
     rule: SelectionRule;
@@ -20,6 +23,7 @@ export interface SelectionPaintReport {
 import { type MarkCensus } from "./blankRender";
 import { type HitBandCensus } from "./hitBands";
 import { type ColourSpreadCensus } from "./colourSpread";
+import type { CategoryColourCensus } from "./categoryColours";
 import { type ClippedTextCensus } from "./clippedText";
 import { type ValuePlacementCensus } from "./valuePlacement";
 import { type FitRenderedChartOptions, type FitRenderedChartResult } from "./fitDom";
@@ -147,6 +151,15 @@ export interface ChartHostConfig {
      * own skew is measured on the raw column while the ramp encodes an aggregate.
      */
     onColourSpreadCensus?: (census: ColourSpreadCensus) => void;
+    /**
+     * HOW CLOSE ARE THE TWO CLOSEST CATEGORY COLOURS, AS PAINTED? Runs after every render, counts only, never repaints;
+     * the census loads on first use, so the report arrives a tick after the render rather than inside it.
+     * One colour per category (the legend's swatches, else the marks' distinct colours), the closest pair by CIEDE2000
+     * at full strength, over the page at each element's own opacity, and at the dim level a selection applies. Generated
+     * code can build its own scale or draw at partial opacity, so the palette that was checked is not always what a
+     * reader compares. Declines on a sequential ramp or a continuous colour channel.
+     */
+    onCategoryColourCensus?: (census: CategoryColourCensus) => void;
     /**
      * IS ANY TEXT CUT OFF BY THE FRAME? Runs after every render, counts only, and never moves anything: a title
      * drawn above its own origin is clipped without anything throwing, so only a measurement against the SVG box
@@ -224,13 +237,14 @@ export interface ChartHostConfig {
     /** What the label-contrast pass did after each render - counts, so a host can log them. */
     onLabelContrast?: (report: LabelContrastReport) => void;
     /**
-     * What the selection-glyph pass did after each paint of an active selection - counts, so a host can log them.
-     * Called only when options.selectionGlyph is "dot" or "check"; `suppressed` is true when the chart's family never
-     * takes a glyph (options.suppressSelectionGlyph, or the same fact in data.meta). A repaint that only follows marks
-     * moving without a render (a pan, a transition) is not reported again.
+     * What the selection-marker pass did after each paint of an active selection - counts, so a host can log them.
+     * Called only when the chart's marker is "dot", "check" or "outline" (options.selectionGlyph, or on a region map
+     * options.mapSelectionGlyph; "auto" decided); `suppressed` is true when the chart's family never takes a marker
+     * (options.suppressSelectionGlyph, or the same fact in data.meta). For an outline, `total` counts the selected
+     * area marks. A repaint that only follows marks moving without a render (a pan, a transition) is not reported again.
      */
     onSelectionGlyphs?: (report: {
-        mode: "dot" | "check";
+        mode: "dot" | "check" | "outline";
         drawn: number;
         total: number;
         suppressed: boolean;

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-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, type FilterScopeFact, } from "./contract";
+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, TABLE_SCROLLER_CLASS, 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, CATEGORY_DELTA_E_FLOOR, 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, type FilterScopeFact, } from "./contract";
 export { resolveOptions, cleanHostSelection, cleanFilterScope, 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";
@@ -16,8 +16,10 @@ export { rememberFocus, restoreFocus, trackFocus, type FocusMemory, type FocusTr
 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";
-export type { Filter, FilterScope, FilterOptions, FilterKey, FilterChangeReason, FilterBinding, BindFilterOptions, VegaInteractionEvent, PageView } from "./filterScope";
+export type { Filter, FilterScope, FilterOptions, FilterKey, FilterChangeReason, FilterBinding, BindFilterOptions, VegaInteractionEvent, PageView, ScopedFilter, ScopeSource } from "./filterScope";
 export { createMarkResolver, isInsideControl, rowIdxsFromMark, nextSelection, DRAG_NOT_CLICK_PX, gestureWasDrag, trackPress, pressOf, clearPress, clickWasDrag, CONTAINER_SLOT_PRESS_AT, type PressPoint, dispatchRowSet, validRowSet, ROW_SET_MAX, selectionRuleOf, markKeyOf, planSelectionPaint, nextClickedMarks, sameRowSet, type SelectionRule, type ClickedMarks, type SelectionPaintMark, type SelectionPaintMode, type SelectionPaintPlan, collectD3GlyphCenters, clearSelectionGlyphs, paintSelectionGlyphs, SELECTION_GLYPH_CLASS, type MarkResolver, type MarkResolverEnv, type GlyphCenter, type SelectionGlyphStyle, type SelectionModifiers, } from "./selection";
+export { readSelectionMarker, readMapSelectionMarker, selectionMarkerFor, SELECTION_MARKER_DEFAULT, MAP_SELECTION_MARKER_DEFAULT, REGION_JOIN_COLUMN, isRegionMapData, NEUTRAL_CENTRE_RAMP_SELECTOR, hasNeutralCentreRamp, isAreaMark, collectOutlineMarks, outlineWindowOf, controlBoxesIn, paintSelectionOutlines, SELECTION_OUTLINE_CLASS, type SelectionMarkerChoice, type MapSelectionMarkerChoice, type SelectionMarker, type SelectionOutlineStyle, type OutlineMarkFilter, } from "./selectionMarker";
+export { followMarks, MARK_MOVE_ATTRIBUTES, type MarkFollower, type MarkFollowerOptions } from "./markFollower";
 export { installLasso, clearLasso, lassoVerdict, lassoRowCap, lassoActions, lassoEffect, registerLassoAction, pointInShape, LASSO_ROW_CAP, LASSO_DRAG_PX, LASSO_SAMPLE_PX, LASSO_MAX_VERTICES, LASSO_RESTORE_MAX_VERTICES, LASSO_RESTORE_MAX_SHAPES, LASSO_EVENT, LASSO_SURFACE_CLASS, LASSO_OUTLINE_CLASS, LASSO_COUNT_CLASS, LASSO_NOTE_CLASS, LASSO_PLOT_CLASS, LASSO_MODE_ATTR, LASSO_KNOB_KEY, LASSO_AXES_SLOT, LASSO_DEFAULT_ACTIONS, LASSO_DEFAULT_EFFECT, type LassoSetting, type LassoVerdict, type LassoEffect, type LassoMode, type LassoSpace, type LassoShape, type LassoStored, type LassoEventDetail, type LassoAxes, type LassoAction, type LassoActionContext, type LassoEnv, type LassoHandle, } from "./lasso";
 export type { AdapterEvent, AdapterHit, AdapterId, AdapterScene, MarkHandle, MarkInfo, MarkRole, PaintRequest, RendererAdapter, RowTable, } from "./adapters/types";
 export { planTrivialChart, compileTrivialSource, type TrivialPlan, type TrivialShapeKind } from "./trivial";
@@ -29,7 +31,7 @@ export { mountShareRateLine, shareRateLineModel, type ShareRateLine, type ShareR
 export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, orderRefusalsForDisplay, refusalIsSelectable, hasRefusalsToShow, qualifyRefusalHeadingFor, newQualifyRefusalGroupState, qualifyRefusalReason, QUALIFY_REFUSAL_UNSPECIFIED, refusalIsTileBound, QUALIFY_TILE_REFUSAL_CODES, QUALIFY_TOO_SMALL_HEADING, 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, DEFAULT_FILTER_MATCH_STYLE, filterMatchStyleOf, type FilterMatchStyle, 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 { qualifyTableRows, type QualifyTableRow, type QualifyTableSource } from "./qualifyTable";
+export { qualifyTableRows, type QualifyTableRow, type QualifyTableSource, QUALIFY_KIND_BADGES, qualifyKindBadgeStyle, type QualifyKind, type QualifyKindBadge, type QualifyKindBadgeColours, type QualifyKindPane, type QualifyKindBadgeStyle, } from "./qualifyTable";
 export { computeSelectionCard, normaliseAggregation, type SelectionCardModel, type SelectionCardLine, type SelectionCardOptions, } from "./selectionCard";
 export { formatSourceDate, formatSourceDateFor, isExcelDateFormat, type SourceFormats, type SourceFormatDialect, type SourceDateOptions, } from "./sourceDateFormat";
 export { composeSummaryText } from "./summaryText";
@@ -43,13 +45,14 @@ export { rowGrowthNotice, ROW_GROWTH_MIN_RATIO, ROW_GROWTH_MIN_EXTRA, type RowGr
 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";
+export type { CategoryColourCensus, CategoryColourCensusOptions } from "./categoryColours";
 export { censusValuePlacement, valuePlacementFlag, VALUE_AXIS_MIN_FIT, type ValuePlacementCensus } from "./valuePlacement";
 export { SCROLL_SLACK_PX, MAX_FRAME_GROW_FACTOR, PHANTOM_FRACTION, FIT_CONTENT_SELECTOR, needsScroll, contentExtentOf, scrollFitFor, planFrameGrow, isPhantomBox, type MeasuredBox, type ContentExtent, type ScrollFit, type FrameGrowPlan, } from "./fit";
 export { fitRenderedChart, fitReadingFor, measureContainerBoxes, svgInkReach, ctmScaleOf, type FitReading, type InkReach, type FitRenderedChartOptions, type FitRenderedChartResult, } from "./fitDom";
 export { AXIS_PIN_MIN_LABELS, AXIS_PIN_BAND_PAD_PX, AXIS_PIN_MAX_BAND_FRACTION, AXIS_PIN_TRACK_REACH_PX, isHorizontalLabelRow, labelBand, planAxisPin, axisPinPlacement, type LabelRowBox, type AxisBand, type AxisPinCandidate, type AxisPinPlan, type AxisPinEdge, } from "./fit";
 export { pinScrolledAxis, unpinScrolledAxis, type AxisPinReport } from "./fitDom";
 export { planScrollRestore, type ScrollMemory, type ScrollMetrics } from "./fit";
-export { rememberScroll, takeScroll } from "./fitDom";
+export { rememberScroll, takeScroll, restoreInnerScroll } from "./fitDom";
 export { MIN_DELTA_E, pickDistinctColorFromSeed, buildPalette, buildPaletteFromSeed, orderMostDistinct, LEGIBLE_LIGHTNESS, type PaletteResult, type SeedForSlot, type PaletteOptions, } from "./palette";
 export { deltaEHex } from "./deltaE";
 export { resolveAutoColorScale, autoRampMinStep, autoRampCanvas, AUTO_RAMP_CLASSES, AUTO_RAMP_DRAWN_OPACITY, AUTO_RAMP_MIN_STEP_DELTA_E, type AutoColorScale, type AutoColorScaleInput } from "./autoRamp";

package/dist/types/keyboardMarks.d.ts

@@ -13,7 +13,7 @@ export interface KeyboardEnv {
     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). */
+    /** True while a click on a mark selects nothing (the marks are then read as images, with no pressed state). */
     inert(): boolean;
     /** Select a mark as a click on it would. */
     select(mark: Element, mods: {

package/dist/types/markFollower.d.ts

@@ -0,0 +1,21 @@
+export interface MarkFollowerOptions {
+    /** Elements whose own writes never count (the host's layers), as a selector. */
+    blind?: string;
+    /** The window whose observers and frames to use. Default: the container's own. */
+    win?: any;
+    /** Called on the next frame after the marks moved; `resized` is true when the container's size changed. */
+    repaint(resized: boolean): void;
+}
+export interface MarkFollower {
+    /** Start (true) or stop (false) following. Connecting twice is harmless. */
+    follow(on: boolean): void;
+    /** Note the container's size now, as painted at: a later size equal to it repaints nothing. Call at each paint. */
+    painted(): void;
+    /** Drop the writes already recorded: call after a paint, whose own writes (the selection's classes) are in it. */
+    takeRecords(): void;
+    /** Whether it is following now. */
+    readonly following: boolean;
+}
+/** The attributes whose writes can move or hide a mark. */
+export declare const MARK_MOVE_ATTRIBUTES: readonly string[];
+export declare function followMarks(container: HTMLElement, opts: MarkFollowerOptions): MarkFollower;

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, ANY_VALUE, isAnyValue, 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, scopeFilterOf, ANY_VALUE, isAnyValue, type Filter, type FilterScope, type FilterOptions, type FilterKey, type FilterChangeReason, type FilterBinding, type BindFilterOptions, type VegaInteractionEvent, type ScopedFilter, type ScopeSource } 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/qualifyTable.d.ts

@@ -1,3 +1,51 @@
+/**
+ * What kind of thing a chart type is, beyond a plain chart, in the chart gallery's own families: an app (a type with
+ * its own controls or logic), a table, a map or a KPI card. A plain chart has no kind and no badge. The same four
+ * strings shape-core's qualify parse accepts (a test pins the two lists equal).
+ */
+export type QualifyKind = "app" | "table" | "map" | "kpi";
+/** A colour pair for one badge: the chip's fill and its text. */
+export interface QualifyKindBadgeColours {
+    background: string;
+    text: string;
+}
+/** How one kind is badged: its word, and its colours on a light pane and on a dark pane. */
+export interface QualifyKindBadge {
+    /** The word on the badge. The word is the signal; colour only repeats it. */
+    label: string;
+    /** On a light pane: the gallery family's own light tint, with the family's colour darkened to 75% as the text. */
+    light: QualifyKindBadgeColours;
+    /** On a dark pane: the family's colour at 50% as the fill, with the gallery's light tint as the text. */
+    dark: QualifyKindBadgeColours;
+}
+/**
+ * The four badges, in the gallery's family order (apps, tables, maps, KPIs). Each host draws them in its own widget,
+ * after the name and before a Preview badge, and a badge never reorders, hides or gates a row.
+ *
+ * The light fills are the chart gallery's family tints exactly. The gallery's own family text colour does not reach
+ * 4.5:1 on three of its tints (about 3.6 to 4.5), so the text is that colour darkened to 75%, which keeps the hue and
+ * clears 5.7:1 on every fill. The dark fills are the family colour at 50%, with the tint as text (above 9:1). Light
+ * tints sit close to each other by nature (the nearest pair is about 8.5 apart by CIEDE2000), so the claim is that
+ * the badges are distinct with the word on them, not that colour alone tells them apart.
+ */
+export declare const QUALIFY_KIND_BADGES: Readonly<Record<QualifyKind, QualifyKindBadge>>;
+/** The pane a badge is drawn on. In high contrast the host's own foreground colour is the only colour used. */
+export type QualifyKindPane = "light" | "dark" | {
+    highContrastForeground: string;
+};
+/** What a host sets on a badge element: its word, fill, text colour and border, as CSS values. */
+export interface QualifyKindBadgeStyle {
+    label: string;
+    background: string;
+    color: string;
+    border: string;
+}
+/**
+ * The style for one kind's badge on one pane, or null for no kind (a plain chart, or a kind this version does not
+ * know). In high contrast the badge has no fill: the text and a 1px border take the host's foreground colour, so the
+ * system's colours decide and the word stays the signal.
+ */
+export declare function qualifyKindBadgeStyle(kind: string | null | undefined, pane: QualifyKindPane): QualifyKindBadgeStyle | null;
 /** What a what-fits row must carry to become a table row (the shape-core parse result satisfies it). */
 export interface QualifyTableSource {
     name: string;
@@ -8,6 +56,8 @@ export interface QualifyTableSource {
     recommended?: boolean | null;
     isPreview?: boolean | null;
     alsoWorthALook?: boolean | null;
+    /** The server's kind for the type ("app", "table", "map", "kpi"); absent or anything else is a plain chart. */
+    kind?: string | null;
 }
 export interface QualifyTableRow {
     /** The position in the order asked for, or null for a row the server did not rank. */
@@ -22,6 +72,8 @@ export interface QualifyTableRow {
     renderer: string | null;
     /** One of the "something different" picks drawn from below the top fits. */
     alsoWorthALook: boolean;
+    /** The type's kind, for its badge (QUALIFY_KIND_BADGES); null for a plain chart. qualifyTableRows always sets it. */
+    kind?: QualifyKind | null;
 }
 /** The rows as table rows, in the order given (the server's order IS the ranking). */
 export declare function qualifyTableRows(rows: readonly QualifyTableSource[]): QualifyTableRow[];

package/dist/types/react.d.ts

@@ -2,13 +2,13 @@ import type { ReactNode, RefObject } from "react";
 import { type ChartHostConfig } from "./host";
 import type { ResolveOptionsInput } from "./defaults";
 import type { GeoPointBinding } from "./payload";
-import { type PageView, type Filter, type FilterOptions } from "./filterScope";
+import { type PageView, type Filter, type FilterOptions, type ScopeSource } from "./filterScope";
 export { assembleD3 } from "./host";
 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, ANY_VALUE, isAnyValue, 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, type ScopedFilter, type ScopeSource } from "./filterScope";
 export interface BicChartProps {
     /** Generated render() source (an ES module's `code` export, or the raw string). */
     code?: string;
@@ -111,8 +111,11 @@ export interface BicChartProps {
      * chip shows), and its titles and comparisons say so ("North America · United States only", "rank 2 of 3 (United
      * States only)"). Cleared again when the filters clear. Not for the filter this chart `selects` unless its own rows
      * are narrowed by it too. Absent: the page's own options.filterScope, if any, goes through untouched.
+     * A query that maps only some of a compound key's columns names them, `{ filter, takes }`: with
+     * `treatAs(cell, "Accounts[Region]")` on a Region x Stage pick, `scopedBy={{ filter: cell, takes: ["Region"] }}` says
+     * the region alone, and a stage-label pick (any region) says nothing, since that query keeps every row.
      */
-    scopedBy?: Filter | readonly Filter[];
+    scopedBy?: ScopeSource | readonly ScopeSource[];
     /**
      * THE CHART'S OWN CONTROLS AS PAGE STATE - from useBicControls(). For a chart that draws
      * sliders (the What-if projection's rate and horizon): `controls.values` holds every
@@ -183,6 +186,11 @@ export declare function BicPage({ children }: {
  * ["OriginCode", "DestinationCode"]). Pass it to a chart's `selects` and read
  * `value` / `values` / `row` / `active` for the rest of the page; `clear()` clears it and the
  * chart's marks. Re-renders the component on every change. The key columns are read once.
+ *
+ * SEVERAL PANELS PICKING ONE KEY ARE ONE PICK: give their filters one `group` ("country") and the most recent pick is
+ * the page's one pick - a pick in one clears the others, the picked mark shows in every member's chart and a click on it
+ * in any of them clears it, and only the member holding it is active (one chip, one scope line). Each panel's query
+ * still takes every member but its own, so the panel a reader picked in keeps all its marks.
  */
 export declare function useBicFilter(columns: string | readonly string[], opts?: FilterOptions): Filter;
 /**

package/dist/types/selectionMarker.d.ts

@@ -0,0 +1,92 @@
+/** The reader's choice for every chart. */
+export type SelectionMarkerChoice = "auto" | "none" | "dot" | "check" | "outline";
+/** The reader's choice for region maps. */
+export type MapSelectionMarkerChoice = "none" | "dot" | "check" | "outline";
+/** What a chart is given, once the choice meets the chart. */
+export type SelectionMarker = "none" | "dot" | "check" | "outline";
+/** The default for every chart: an outline where the chart's ramp has a neutral centre, nothing elsewhere. */
+export declare const SELECTION_MARKER_DEFAULT: SelectionMarkerChoice;
+/** The default for region maps: an outline. */
+export declare const MAP_SELECTION_MARKER_DEFAULT: MapSelectionMarkerChoice;
+/** The choice for every chart from an untrusted value: one of the five words in any case, else the default. */
+export declare function readSelectionMarker(raw: unknown): SelectionMarkerChoice;
+/** The choice for region maps from an untrusted value: one of the four words in any case, else the default. */
+export declare function readMapSelectionMarker(raw: unknown): MapSelectionMarkerChoice;
+/** The column the host adds to a region map's rows: each row's region code, joined to the geometry. */
+export declare const REGION_JOIN_COLUMN = "__geoIso__";
+/** Whether the chart's data joins its rows to regions (a choropleth, a cartogram, a province map). */
+export declare function isRegionMapData(data: {
+    columns?: readonly ({
+        name?: unknown;
+    } | null | undefined)[] | null;
+} | null | undefined): boolean;
+/** The legend the shared value ramp draws for a diverging scale: its centre colour is a neutral just off the canvas. */
+export declare const NEUTRAL_CENTRE_RAMP_SELECTOR = ".llm-value-ramp[data-kind=\"diverging\"]";
+/** Whether the drawn chart declares a colour ramp with a neutral centre. */
+export declare function hasNeutralCentreRamp(container: Element | null | undefined): boolean;
+/** What marks this chart's selection: the map choice on a region map, else the general choice with "auto" decided. */
+export declare function selectionMarkerFor(facts: {
+    choice?: unknown;
+    mapChoice?: unknown;
+    regionMap: boolean;
+    neutralCentreRamp: boolean;
+}): SelectionMarker;
+/** The class on the host's outline layer (one svg in the overlay). */
+export declare const SELECTION_OUTLINE_CLASS = "lch-sel-outline";
+/** Whether `el` is an AREA mark: a path, rect or polygon whose interior is painted. A line (fill none), a point
+ *  (a circle or an ellipse) and a group are not. Reads the computed fill where the platform resolves it, else the
+ *  element's own attribute and inline style; an element with no fill at all is filled, as SVG paints it. */
+export declare function isAreaMark(el: Element): boolean;
+/** Which selected marks get an outline, for a host that draws its own layer: `shown` drops a mark the reader can't see. */
+export interface OutlineMarkFilter {
+    shown?(mark: Element): boolean;
+}
+/**
+ * The selected area marks in `container`, in document order. A selected mark that is a group stands for the filled
+ * shapes inside it. A selected mark whose box strictly encloses another selected mark is a hierarchy's backdrop (a
+ * treemap's parent tile), whose children carry the outlines, and is left out - checked up to 300 marks, as the glyphs
+ * check it.
+ */
+export declare function collectOutlineMarks(container: Element, filter?: OutlineMarkFilter): Element[];
+type ClientWindow = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/** The window a mark is seen through, in client coordinates: its outermost svg's box, narrowed by every clip-path on
+ *  the way up to `stop`. Null when nothing measures (the outline then draws unclipped). */
+export declare function outlineWindowOf(mark: Element, stop?: Element | null): ClientWindow | null;
+export interface SelectionOutlineStyle {
+    /** The outline's colour: the chart's text colour. */
+    color: string;
+    /** The halo under it, in the canvas colour, so it reads on a dark and a light region alike. */
+    halo: string;
+    /** The outline's width in screen pixels. Default 2. */
+    width?: number;
+    /** At most this many are drawn. Default 600, which keeps the DOM light on a huge selection. */
+    max?: number;
+    /** The window each outline is clipped to, in client coordinates, or null for none. Default: outlineWindowOf. */
+    windowOf?(mark: Element): ClientWindow | null;
+    /** Boxes the outline never paints over, in client coordinates: the chart's own controls (controlBoxesIn). */
+    avoid?: readonly ClientWindow[];
+}
+/**
+ * Where a chart's OWN CONTROLS are, in client coordinates: every element it declares a control (CONTROL_CLASS - a map's
+ * zoom pad, a pager, a flip arrow), grown by `pad` px, and boxes within `join` px of each other merged, so a pad of
+ * buttons is one box and no sliver of an outline shows between its buttons. A selection outline is never painted over
+ * them: a mark on the reader's chart must not cover the button that moves it.
+ */
+export declare function controlBoxesIn(root: Element | null | undefined, opts?: {
+    pad?: number;
+    join?: number;
+}): ClientWindow[];
+/**
+ * Draws an outline around each mark (up to `max`) into `overlay`: one svg layer positioned from the overlay's own
+ * top-left corner, never hit-tested and hidden from assistive technology. Each outline is the mark's own shape, placed
+ * through the mark's screen matrix, so it lands on the mark however the chart transformed it; its stroke keeps its
+ * width at any zoom. Returns how many it drew: a mark with no screen matrix or no geometry is skipped. It does not
+ * clear the overlay first: a host clears it (clearSelectionGlyphs) before deciding whether to paint at all.
+ */
+export declare function paintSelectionOutlines(overlay: Element, marks: readonly Element[], style: SelectionOutlineStyle): number;
+export {};

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.6.113",
+  "version": "0.6.116",
   "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",
@@ -74,6 +74,11 @@
       "import": "./dist/zoom-memory.mjs",
       "default": "./dist/zoom-memory.mjs"
     },
+    "./category-colours": {
+      "types": "./dist/types/categoryColours.d.ts",
+      "import": "./dist/category-colours.mjs",
+      "default": "./dist/category-colours.mjs"
+    },
     "./dax": {
       "types": "./dist/types/dax.d.ts",
       "import": "./dist/dax.mjs",