@bicharts/chart-host 0.6.56 → 0.6.59

package/dist/types/dax.d.ts

@@ -0,0 +1,22 @@
+import type { Filter, FilterKey } from "./filterScope";
+/** One value as a DAX literal: text quoted with "" doubled, numbers, TRUE()/FALSE(), dates, BLANK(). */
+export declare function daxLiteral(v: unknown): string;
+/**
+ * TREATAS over a filter's selected keys (or keys given directly), onto the named model columns -
+ * or null when nothing is selected, so `calculateTable` leaves the query unfiltered.
+ */
+export declare function treatAs(selection: Filter | readonly (FilterKey | unknown)[] | null | undefined, ...columnRefs: string[]): string | null;
+/**
+ * CALCULATETABLE(table, filters...) with the null filters dropped - the table expression unchanged
+ * when none is left. `table` is a table expression (SUMMARIZECOLUMNS(...)), not a whole query with
+ * EVALUATE.
+ */
+export declare function calculateTable(table: string, ...filters: Array<string | null | undefined | false>): string;
+/**
+ * A whole query (`[DEFINE ...] EVALUATE <table> [ORDER BY ...]`, as a .dax file holds it) with its table filtered:
+ * the table expression goes inside CALCULATETABLE with the filters, DEFINE and ORDER BY stay where they are. With no
+ * live filter the query comes back unchanged. One EVALUATE only (throws on more).
+ *
+ *   filterQuery(FORECAST_DAX, treatAs(region, "Geography[RegionCode]"))
+ */
+export declare function filterQuery(query: string, ...filters: Array<string | null | undefined | false>): string;

package/dist/types/filterScope.d.ts

@@ -0,0 +1,173 @@
+import type { ChartHost } from "./host";
+import type { Controls } from "./controls";
+/** Why a filter changed. */
+export type FilterChangeReason = "click" | "clear" | "page" | "data";
+/** One selected key: a value per key column, in the filter's column order. */
+export type FilterKey = readonly unknown[];
+export interface FilterOptions {
+    /** What a chip calls this filter ("Country"). Defaults to the key columns. */
+    label?: string;
+    /**
+     * The column(s) a chip shows for a selected key, read from the selected rows ("Country" for a
+     * RegionCode key; ["OriginName", "DestinationName"] for a route, joined " → ").
+     * Defaults to the key columns.
+     */
+    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 "+". */
+    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;
+}
+export interface Filter {
+    readonly id: string;
+    /** Its name in a saved view. */
+    readonly key: string;
+    /** Whether linked hover is on (FilterOptions.hover). */
+    readonly hoverEnabled: boolean;
+    /** The key being hovered on a bound chart now, or null. */
+    readonly hovered: FilterKey | null;
+    /** Set or clear the hovered key (bound charts do this; a page may too). */
+    setHover(key: FilterKey | null): void;
+    /** Subscribe to hover changes. Returns the unsubscribe. */
+    onHover(cb: (key: FilterKey | null) => void): () => void;
+    /** The key column(s). */
+    readonly columns: readonly string[];
+    readonly label: string;
+    /** True while anything is selected. */
+    readonly active: boolean;
+    /** The selected keys, each one value per key column. */
+    readonly keys: readonly FilterKey[];
+    /** The rows the selection was made from (for display names); rows of keys set by value are absent. */
+    readonly rows: readonly Record<string, unknown>[];
+    /** The first selected row, or null. */
+    readonly row: Record<string, unknown> | null;
+    /** The first key's first value, or null - the common one-column, one-pick case. */
+    readonly value: unknown;
+    /** Every selected key's first value. */
+    readonly values: readonly unknown[];
+    /** What a chip shows: the display column(s) of each selected key, "A → B" within a key, ", " between keys. */
+    readonly text: string;
+    /**
+     * 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.
+     */
+    textOf(key: FilterKey | unknown, rows?: readonly Record<string, unknown>[]): 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. */
+    readonly version: number;
+    /** Select these rows' keys (replacing the selection). An empty list clears. */
+    selectRows(rows: readonly Record<string, unknown>[], reason?: FilterChangeReason): 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). */
+    clear(reason?: FilterChangeReason): void;
+    /** Does this row carry a selected key? Read on `columns` (default: the key columns). */
+    has(row: Record<string, unknown>, columns?: readonly string[]): boolean;
+    /**
+     * The rows that carry a selected key - every row while nothing is selected. `columns` names
+     * where this table keeps the key when it differs from the filter's: a one-column filter
+     * matched against several columns keeps a row when ANY of them carries the key (a route
+     * table filtered by a country keeps routes from OR to it). The same array comes back while
+     * the input and the filter are unchanged, so it's safe to call during render.
+     */
+    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;
+}
+/** A page's filters: what a chip bar lists and what clear-all clears. */
+export interface FilterScope {
+    readonly filters: readonly Filter[];
+    /** The filters with something selected. */
+    readonly active: readonly Filter[];
+    /** Make a filter in this scope (see createFilter). */
+    filter(columns: string | readonly string[], opts?: FilterOptions): Filter;
+    /** Add an existing filter. Returns the remove. */
+    add(filter: Filter): () => void;
+    /** Clear every filter. */
+    clearAll(reason?: FilterChangeReason): void;
+    /** Subscribe to any change of any filter or controls, and to either being added or removed. */
+    onChange(cb: (scope: FilterScope) => void): () => void;
+    /** A chart's controls, to be saved and restored with the page's view. Returns the remove. */
+    addControls(key: string, controls: Controls): () => void;
+    /** The registered controls, by key. */
+    readonly controls: ReadonlyMap<string, Controls>;
+    /** The page's view now: every filter's keys and every registered controls' values - JSON-safe. */
+    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 saved page view: what save() returns and restore() takes. */
+export interface PageView {
+    v: 1;
+    filters?: Record<string, unknown[][]>;
+    controls?: Record<string, Record<string, unknown>>;
+}
+/** A view as a URL-safe token (base64url of its JSON), for a link or a bookmark. */
+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;
+/** 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. */
+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.
+     */
+    reconcile(): void;
+    /** Repaint the filter's selection onto the chart's marks. */
+    paint(): void;
+    /** Unwire. The filter keeps its selection. */
+    detach(): void;
+}
+export interface BindFilterOptions {
+    /** The source row (keyed by column name) behind payload row `i`, or null. */
+    rowAt(i: number): Record<string, unknown> | null;
+    /** How many rows the chart is drawing now. */
+    rowCount(): number;
+    /** The chart's container, for linked hover (FilterOptions.hover). Without it the chart takes no part in hover. */
+    container?: HTMLElement | null;
+}
+/** The class a mark wears while its key is hovered on another chart bound to the same filter. */
+export declare const LINKED_HOVER_CLASS = "bic-linked-hover";
+/** The source row behind each payload row, from a payload of { columns, rows: unknown[][] }. */
+export declare function payloadRowReader(getPayload: () => {
+    columns: readonly {
+        name: string;
+    }[];
+    rows: readonly unknown[][];
+} | null | undefined): BindFilterOptions;
+/**
+ * Wire one chart host to one filter. A click on the chart sets the filter (reason "click"), the
+ * chart's own clear gesture clears it (reason "clear"), and any change to the filter - from this
+ * chart, another chart, or the page - is painted onto this chart's marks. Paints notify the host's
+ * subscribers with source "host", which this binding (and a chart group) never republishes.
+ */
+export declare function bindFilter(host: ChartHost, filter: Filter, opts: BindFilterOptions): FilterBinding;
+/** The interaction events @microsoft/fabric-visuals' VegaVisual and DataGrid emit (onInteraction). */
+export interface VegaInteractionEvent {
+    action: string;
+    selections?: Array<{
+        predicates?: Array<{
+            type?: string;
+            name?: string;
+            values?: unknown[];
+        }>;
+    }>;
+}
+/**
+ * Apply a VegaVisual / DataGrid `onInteraction` event list to a filter, so Microsoft's charts take
+ * part in the same page filters as ours: `onInteraction={e => fromVegaInteraction(country, e)}`.
+ * A `select` sets the filter from the set predicates that name its key columns (a selection
+ * missing one of them is skipped); a `clear` clears it. Returns whether the filter changed.
+ */
+export declare function fromVegaInteraction(filter: Filter, events: readonly VegaInteractionEvent[] | null | undefined): boolean;

package/dist/types/index.d.ts

@@ -9,7 +9,10 @@ export { buildRenderPayload, type RenderPayload, type GeoPointBinding } from "./
 export { codeReadsDatesInLocalTime, vegaSpecReadsDatesInLocalTime } from "./dateCells";
 export { createChartHost, compileRenderFn, stripEsmExports, requiredD3Plugins, explainRenderFailure, sessionViewStateProvider, noopViewStateProvider, assembleD3, D3_PLUGIN_PACKAGES, type ChartHost, type ChartHostConfig, type RenderFn } from "./host";
 export { ANNOTATION_CLASS, ANNOTATION_LAYER_CLASS, type MarkAnnotation, type AnnotationReport } from "./annotations";
+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 { createMarkResolver, isInsideControl, rowIdxsFromMark, nextSelection, collectD3GlyphCenters, clearSelectionGlyphs, paintSelectionGlyphs, SELECTION_GLYPH_CLASS, type MarkResolver, type MarkResolverEnv, type GlyphCenter, type SelectionGlyphStyle, type SelectionModifiers, } from "./selection";
 export { planTrivialChart, compileTrivialSource, type TrivialPlan, type TrivialShapeKind } from "./trivial";
 export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngDataUrl, tableHostOf, chartSvgOf, htmlToSvgDataUrl, htmlNaturalSize, type SnapshotOptions } from "./snapshot";

package/dist/types/markNotes.d.ts

@@ -0,0 +1,30 @@
+import type { MarkAnnotation } from "./annotations";
+import type { Filter, FilterKey } from "./filterScope";
+export interface MarkNoteLike {
+    chart?: string | null;
+    markKey?: unknown;
+    markKeyTo?: unknown;
+    body?: string | null;
+}
+export interface NoteBadgeOptions<N> {
+    /** The chart's key column(s) the note keys live in: "RegionCode", or a route's two ends. */
+    columns: string | readonly string[];
+    /** Only notes whose `chart` is this (one notes table serving several charts). */
+    chart?: string;
+    /** A note's key, one value per column. Default: [markKey] or [markKey, markKeyTo]. */
+    keyOf?: (note: N) => readonly unknown[];
+    /** A note's text. Default: body. */
+    textOf?: (note: N) => string;
+}
+/**
+ * One badge per noted mark: the count of its notes, the latest note as the tooltip (notes are
+ * taken in the order given - pass them newest first). Pass to a chart's `annotations`.
+ */
+export declare function noteBadges<N extends MarkNoteLike>(notes: readonly N[] | null | undefined, opts: NoteBadgeOptions<N>): MarkAnnotation[];
+/** The key values of a badge noteBadges made (for a click: which mark's notes to open). */
+export declare function badgeKey(a: MarkAnnotation): FilterKey;
+/**
+ * The notes on one mark - a key given directly, or the first key selected in a page filter - in
+ * the order given. Keys compare as trimmed text, so a numeric code and its string agree.
+ */
+export declare function notesFor<N extends MarkNoteLike>(notes: readonly N[] | null | undefined, key: Filter | FilterKey | null | undefined, opts: Omit<NoteBadgeOptions<N>, "textOf">): N[];

package/dist/types/page.d.ts

@@ -0,0 +1,4 @@
+export { viewToken, viewFromToken, LINKED_HOVER_CLASS, type PageView } from "./filterScope";
+export { createFilter, createFilterScope, bindFilter, payloadRowReader, fromVegaInteraction, 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

@@ -2,7 +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";
 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, 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;
@@ -59,11 +65,34 @@ export interface BicChartProps {
      * now two props rather than a DOM workaround.
      */
     respondsWith?: "filter" | "highlight";
-    /** Selection callback in SOURCE row indices (group) or payload indices (standalone). */
+    /**
+     * 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.
+     * The page reads `filter.value` / `filter.row` and never writes a select handler. With
+     * `selects`, the filter owns what this chart shows as selected.
+     */
+    selects?: Filter;
+    /**
+     * 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
+     * knob's value from the first draw (no slider has to move first), `controls.info` / `summary`
+     * the chart's own label and readout for each ("growth per year +5.5%"), `controls.set(saved)`
+     * applies a saved scenario and `controls.reset()` returns to the defaults. It owns the chart's
+     * uiState / setUiState.
+     */
+    controls?: Controls;
+    /**
+     * Selection callback in SOURCE row indices (group) or payload indices (standalone). An empty
+     * list means the selection was CLEARED: the same mark clicked again, a click on empty canvas,
+     * or new data that no longer draws what was selected. The chart toggles for you - set your
+     * state from exactly what this gives you, never toggle it again. Prefer `selects`.
+     */
     onSelect?: (rowIdxs: number[]) => void;
     /**
      * Notes on marks: a badge on each key's mark, redrawn after every render - e.g.
-     * `[{ column: "CountryCode", value: "USA", label: "2", title: "..." }]`. Keyed by a value in a column,
+     * `[{ column: "RegionCode", value: "JPN", label: "2", title: "..." }]`. Keyed by a value in a column,
      * never a row position, so a filter or a re-query never moves one.
      */
     annotations?: ChartHostConfig["annotations"];
@@ -71,6 +100,8 @@ export interface BicChartProps {
     onAnnotationClick?: ChartHostConfig["onAnnotationClick"];
     className?: string;
     style?: React.CSSProperties;
+    /** What a screen reader announces for the chart ("Occupancy vs average daily rate, by country"). */
+    ariaLabel?: string;
 }
 /** Read the group's selection from a page — for a "clear" button or a count. */
 export declare function useBicSelection(): {
@@ -100,6 +131,73 @@ export interface BicChartGroupProps {
  */
 export declare function BicChartGroup({ rows, columns, geo, point, destination, children }: BicChartGroupProps): import("react").JSX.Element;
 export declare function BicChart(props: BicChartProps): import("react").JSX.Element;
+/**
+ * A SEPARATE filter scope, for an app with several independent pages or panels mounted at once.
+ * Not needed otherwise: every filter joins the app's one default scope. Call useBicFilter in a
+ * component INSIDE it - a hook can't see a provider its own component renders.
+ */
+export declare function BicPage({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A page filter keyed by one model column ("RegionCode") or several (a route:
+ * ["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.
+ */
+export declare function useBicFilter(columns: string | readonly string[], opts?: FilterOptions): Filter;
+/**
+ * A chart's in-chart controls as page state: pass to the chart's `controls`, read `values`, `info`
+ * and `summary`, `set(saved)` to apply a saved scenario, `reset()` for the defaults. Re-renders the
+ * component on every change. `initial` seeds the values the chart first draws with.
+ */
+export declare function useBicControls(initial?: Readonly<Record<string, unknown>>, opts?: {
+    id?: string;
+}): Controls;
+/**
+ * THE PAGE'S VIEW, SAVED AND PUT BACK: every page filter's keys and every chart's controls (useBicControls). `save()`
+ * returns a JSON-safe view to store (a saved view, a user preference); `restore(view)` puts one back; `token()` /
+ * `restoreToken(t)` do the same as a URL-safe string for a link.
+ */
+export declare function useBicView(): {
+    save: () => PageView;
+    restore: (v: PageView | null | undefined) => void;
+    token: () => string;
+    restoreToken: (t: string | null | undefined) => void;
+};
+/**
+ * THE VIEW IN THE ADDRESS BAR (opt-in): restores the page's filters and controls from `?<param>=` on mount, then keeps
+ * the parameter current as they change (history.replaceState - no navigation, no new history entries). A copied link
+ * opens the page as it was. Call once, in the page component, after its useBicFilter / useBicControls calls.
+ */
+export declare function useBicUrlState(param?: string): void;
+/**
+ * A DEVELOPER'S VIEW OF THE PAGE'S STATE: every filter (its keys, its text, the last change and why), every chart's
+ * controls, and the last changes in order. Collapsed in a corner; render it only in development.
+ */
+export declare function BicDevtools({ max }: {
+    max?: number;
+}): import("react").JSX.Element;
+/** Every filter on the page (or the enclosing <BicPage>), and its clear-all - for a page's own chip bar or count. */
+export declare function useBicFilters(): {
+    filters: readonly Filter[];
+    active: readonly Filter[];
+    clearAll: () => void;
+};
+export interface BicFilterChipsProps {
+    className?: string;
+    /** Each chip's class (the label, the value and its × are inside). */
+    chipClassName?: string;
+    /** The words on the clear-all button, shown when two or more filters are active. Default "Clear all". */
+    clearAllText?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * What the page is filtered by: one chip per active filter ("Country: Japan ×"), a × that
+ * clears it (and its chart's marks), and "Clear all" when two or more are active. Renders nothing
+ * while nothing is filtered. Plain markup with class names to style.
+ */
+export declare function BicFilterChips({ className, chipClassName, clearAllText, style }: BicFilterChipsProps): import("react").JSX.Element;
 /**
  * THE SIZE A CHART SHOULD DRAW AT: the element's measured box, kept current as it resizes.
  *

package/dist/types/testing/index.d.ts

@@ -12,3 +12,4 @@ export declare class ConformanceError extends Error {
  * before returning, whether or not the check passed.
  */
 export declare function assertMarkerStoreConformance(store: MarkerStore): Promise<void>;
+export { chartContainers, marksOf, findMark, clickMark, clickEmpty, selectedRows } from "./interact";

package/dist/types/testing/interact.d.ts

@@ -0,0 +1,17 @@
+/** Every hosted chart container under `root` (a page, a component's element). */
+export declare function chartContainers(root: ParentNode): HTMLElement[];
+/** The chart's data marks, in DOM order. */
+export declare function marksOf(chart: ParentNode): Element[];
+/**
+ * The mark drawing payload row `rowIdx` - or, given a predicate, the first mark it accepts (e.g.
+ * `m => m.getAttribute("data-code") === "JPN"` for a chart that labels its marks).
+ */
+export declare function findMark(chart: ParentNode, which: number | ((mark: Element) => boolean)): Element | null;
+/** Click a mark as a reader does; `add` holds Ctrl to add it to the selection. */
+export declare function clickMark(mark: Element, opts?: {
+    add?: boolean;
+}): void;
+/** Click the chart's empty canvas (no mark): clears its selection. */
+export declare function clickEmpty(chart: Element): void;
+/** The payload rows the chart shows as selected now. */
+export declare function selectedRows(chart: ParentNode): number[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.6.56",
+  "version": "0.6.59",
   "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",
@@ -39,6 +39,16 @@
       "import": "./dist/geo-us-zip3.mjs",
       "default": "./dist/geo-us-zip3.mjs"
     },
+    "./page": {
+      "types": "./dist/types/page.d.ts",
+      "import": "./dist/page.mjs",
+      "default": "./dist/page.mjs"
+    },
+    "./dax": {
+      "types": "./dist/types/dax.d.ts",
+      "import": "./dist/dax.mjs",
+      "default": "./dist/dax.mjs"
+    },
     "./testing": {
       "types": "./dist/types/testing/index.d.ts",
       "import": "./dist/testing.mjs",