@bicharts/chart-host 0.6.56 → 0.6.58

package/dist/page.mjs

@@ -0,0 +1,28 @@
+/*! @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 {
+  attachControls,
+  badgeKey,
+  bindFilter,
+  createControls,
+  createFilter,
+  createFilterScope,
+  fromVegaInteraction,
+  noteBadges,
+  notesFor,
+  payloadRowReader,
+  readControls
+} from "./chunk-ZEZXNAFL.mjs";
+import "./chunk-GHODWOAL.mjs";
+export {
+  attachControls,
+  badgeKey,
+  bindFilter,
+  createControls,
+  createFilter,
+  createFilterScope,
+  fromVegaInteraction,
+  noteBadges,
+  notesFor,
+  payloadRowReader,
+  readControls
+};

package/dist/react.mjs

@@ -1,4 +1,16 @@
 /*! @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 {
+  attachControls,
+  badgeKey,
+  bindFilter,
+  createControls,
+  createFilter,
+  createFilterScope,
+  fromVegaInteraction,
+  noteBadges,
+  notesFor,
+  payloadRowReader
+} from "./chunk-ZEZXNAFL.mjs";
 import {
   assembleD3,
   createChartGroup,
@@ -7,13 +19,14 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-CMHGGW3Y.mjs";
+} from "./chunk-5NSU3MYW.mjs";
 import "./chunk-A2GMXZP7.mjs";
+import "./chunk-WNGJUPEI.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/react.tsx
-import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
 var Ctx = createContext(null);
 function useBicSelection() {
   const g = useContext(Ctx);
@@ -56,7 +69,10 @@ function BicChart(props) {
     annotations,
     onAnnotationClick,
     className,
-    style
+    style,
+    selects,
+    controls,
+    ariaLabel
   } = props;
   const ref = useRef(null);
   const hostRef = useRef(null);
@@ -72,6 +88,18 @@ function BicChart(props) {
   }, [group, ctx?.source, filterSel && filterSel.join(",")]);
   const data = built ? built.payload : props.data;
   rowMapRef.current = built ? built.rowMap : null;
+  const dataRef = useRef(data);
+  dataRef.current = data;
+  const groupRef = useRef(group);
+  groupRef.current = group;
+  const bindingRef = useRef(null);
+  const controlsRef = useRef(null);
+  const readControlsSoon = () => {
+    const h = hostRef.current, c = controlsRef.current;
+    if (h && c) h.rendered.then(c.read, () => {
+    });
+  };
+  const userSelectedRef = useRef(false);
   const optKey = useMemo(() => JSON.stringify(options ?? {}), [options]);
   const builtWithRef = useRef(null);
   const onSelectRef = useRef(onSelect);
@@ -102,11 +130,14 @@ function BicChart(props) {
   useLayoutEffect(() => {
     const el = ref.current;
     if (!el || !code && !renderFn || !data) return;
+    const ctl = controls ? attachControls(() => hostRef.current, el, controls) : null;
+    controlsRef.current = ctl;
+    const hostOptions = ctl ? { ...options ?? {}, ...ctl.options } : options;
     const host = createChartHost(el, {
       code,
       renderFn,
       data,
-      options,
+      options: hostOptions,
       d3,
       geoKind,
       viewState,
@@ -127,23 +158,53 @@ function BicChart(props) {
     builtAnnKeyRef.current = annKey;
     const off = host.selection.onChange((payloadIdxs, source) => {
       if (source === "host") return;
+      userSelectedRef.current = payloadIdxs.length > 0;
       const sourceIdxs = toSourceRows(rowMapRef.current, payloadIdxs);
       if (group && id) group.publish(id, sourceIdxs);
       onSelectRef.current?.(sourceIdxs);
     });
     host.render();
+    readControlsSoon();
     builtWithRef.current = { data, optKey };
     return () => {
       off();
+      ctl?.detach();
+      if (controlsRef.current === ctl) controlsRef.current = null;
       host.destroy();
       hostRef.current = null;
     };
-  }, [code, renderFn, d3, geoKind, labelContrast]);
+  }, [code, renderFn, d3, geoKind, labelContrast, controls]);
+  useLayoutEffect(() => {
+    const host = hostRef.current;
+    if (!host || !selects) return;
+    const payloadRows = payloadRowReader(() => dataRef.current);
+    const b = bindFilter(host, selects, {
+      rowAt(i) {
+        const g = groupRef.current, map = rowMapRef.current;
+        if (g && map) {
+          const s = map[i];
+          return s === void 0 ? null : g.rows[s] ?? null;
+        }
+        return payloadRows.rowAt(i);
+      },
+      rowCount() {
+        const map = rowMapRef.current;
+        return groupRef.current && map ? map.length : payloadRows.rowCount();
+      }
+    });
+    bindingRef.current = b;
+    b.reconcile();
+    return () => {
+      b.detach();
+      if (bindingRef.current === b) bindingRef.current = null;
+    };
+  }, [selects, code, renderFn, d3, geoKind, labelContrast]);
   useEffect(() => {
     if (!hostRef.current || !options) return;
     if (builtWithRef.current?.optKey === optKey) return;
     builtWithRef.current = { ...builtWithRef.current, optKey };
     hostRef.current.setOptions(options);
+    readControlsSoon();
   }, [optKey]);
   const builtAnnKeyRef = useRef(null);
   useEffect(() => {
@@ -156,13 +217,139 @@ function BicChart(props) {
     if (builtWithRef.current?.data === data) return;
     builtWithRef.current = { ...builtWithRef.current, data };
     hostRef.current.setData(data);
+    bindingRef.current?.reconcile();
+    readControlsSoon();
   }, [data]);
+  const lastSourceRef = useRef(ctx?.source);
   useEffect(() => {
     const host = hostRef.current;
     if (!host || !ctx) return;
+    const sourceChanged = lastSourceRef.current !== ctx.source;
+    lastSourceRef.current = ctx.source;
+    if (selects) return;
+    const before = (host.selection.current ?? []).length;
     syncMemberSelection(host, ctx.selection, id, highlightMode, incoming, rowMapRef.current);
-  }, [ctx?.selection, id, ctx, highlightMode, incoming && incoming.join(",")]);
-  return /* @__PURE__ */ jsx("div", { ref, className, style });
+    if (sourceChanged && before && !(host.selection.current ?? []).length && userSelectedRef.current) {
+      userSelectedRef.current = false;
+      onSelectRef.current?.([]);
+    }
+  }, [ctx?.selection, id, ctx, highlightMode, incoming && incoming.join(","), selects]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref,
+      className,
+      style,
+      role: ariaLabel ? "figure" : void 0,
+      "aria-label": ariaLabel || void 0
+    }
+  );
+}
+var defaultScope = createFilterScope();
+var PageCtx = createContext(defaultScope);
+function BicPage({ children }) {
+  const ref = useRef(null);
+  if (!ref.current) ref.current = createFilterScope();
+  return /* @__PURE__ */ jsx(PageCtx.Provider, { value: ref.current, children });
+}
+function useBicFilter(columns, opts) {
+  const scope = useContext(PageCtx);
+  const ref = useRef(null);
+  if (!ref.current) ref.current = createFilter(columns, opts);
+  const f = ref.current;
+  useEffect(() => scope.add(f), [scope, f]);
+  useSyncExternalStore((cb) => f.onChange(() => cb()), () => f.version, () => f.version);
+  return f;
+}
+function useBicControls(initial) {
+  const ref = useRef(null);
+  if (!ref.current) ref.current = createControls(initial);
+  const c = ref.current;
+  useSyncExternalStore((cb) => c.onChange(() => cb()), () => c.version, () => c.version);
+  return c;
+}
+function useBicFilters() {
+  const scope = useContext(PageCtx);
+  const [, tick] = useState(0);
+  useEffect(() => scope.onChange(() => tick((t) => t + 1)), [scope]);
+  return { filters: scope.filters, active: scope.active, clearAll: () => scope.clearAll() };
+}
+function BicFilterChips({ className, chipClassName, clearAllText = "Clear all", style }) {
+  const { active, clearAll } = useBicFilters();
+  if (!active.length) return null;
+  const chip = {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: 6,
+    padding: "2px 4px 2px 10px",
+    border: "1px solid currentColor",
+    borderRadius: 999,
+    font: "inherit",
+    lineHeight: 1.6
+  };
+  const x = {
+    border: 0,
+    background: "transparent",
+    color: "inherit",
+    cursor: "pointer",
+    font: "inherit",
+    padding: "0 6px",
+    lineHeight: 1
+  };
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: ["bic-filter-chips", className].filter(Boolean).join(" "),
+      role: "group",
+      "aria-label": "Filters",
+      style: { display: "flex", flexWrap: "wrap", gap: 8, alignItems: "center", ...style },
+      children: [
+        active.map((f) => /* @__PURE__ */ jsxs(
+          "span",
+          {
+            className: ["bic-filter-chip", chipClassName].filter(Boolean).join(" "),
+            style: chipClassName ? void 0 : chip,
+            children: [
+              /* @__PURE__ */ jsxs("span", { className: "bic-filter-chip-label", children: [
+                f.label,
+                ": "
+              ] }),
+              /* @__PURE__ */ jsx("span", { className: "bic-filter-chip-value", children: f.text }),
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  className: "bic-filter-chip-clear",
+                  "aria-label": `Clear ${f.label}`,
+                  style: chipClassName ? void 0 : x,
+                  onClick: () => f.clear(),
+                  children: "\xD7"
+                }
+              )
+            ]
+          },
+          f.id
+        )),
+        active.length > 1 && /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            className: "bic-filter-chips-clear-all",
+            onClick: clearAll,
+            style: {
+              font: "inherit",
+              background: "transparent",
+              border: 0,
+              color: "inherit",
+              textDecoration: "underline",
+              cursor: "pointer"
+            },
+            children: clearAllText
+          }
+        )
+      ]
+    }
+  );
 }
 function useMeasuredSize(ref) {
   const [size, setSize] = useState({ width: 0, height: 0 });
@@ -185,7 +372,19 @@ function useMeasuredSize(ref) {
 export {
   BicChart,
   BicChartGroup,
+  BicFilterChips,
+  BicPage,
   assembleD3,
+  badgeKey,
+  createControls,
+  createFilter,
+  createFilterScope,
+  fromVegaInteraction,
+  noteBadges,
+  notesFor,
+  useBicControls,
+  useBicFilter,
+  useBicFilters,
   useBicSelection,
   useMeasuredSize
 };

package/dist/testing.mjs

@@ -1,6 +1,45 @@
 /*! @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 {
+  HOST_CONTAINER_CLASS,
+  MARK_CLASS,
+  MARK_SELECTED_CLASS,
+  ROW_IDX_ATTR
+} from "./chunk-WNGJUPEI.mjs";
 import "./chunk-GHODWOAL.mjs";
 
+// src/testing/interact.ts
+function chartContainers(root) {
+  return Array.from(root.querySelectorAll(`.${HOST_CONTAINER_CLASS}`));
+}
+function marksOf(chart) {
+  return Array.from(chart.querySelectorAll(`.${MARK_CLASS}[${ROW_IDX_ATTR}]`)).filter((m) => (m.getAttribute(ROW_IDX_ATTR) ?? "") !== "");
+}
+function findMark(chart, which) {
+  const marks = marksOf(chart);
+  if (typeof which === "function") return marks.find(which) ?? null;
+  return marks.find((m) => (m.getAttribute(ROW_IDX_ATTR) ?? "").split(",").map(Number).includes(which)) ?? null;
+}
+function clickMark(mark, opts = {}) {
+  const win = mark.ownerDocument?.defaultView;
+  const Ev = win?.MouseEvent ?? MouseEvent;
+  mark.dispatchEvent(new Ev("click", { bubbles: true, cancelable: true, ctrlKey: !!opts.add }));
+}
+function clickEmpty(chart) {
+  const win = chart.ownerDocument?.defaultView;
+  const Ev = win?.MouseEvent ?? MouseEvent;
+  chart.dispatchEvent(new Ev("click", { bubbles: true, cancelable: true }));
+}
+function selectedRows(chart) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of Array.from(chart.querySelectorAll(`.${MARK_CLASS}.${MARK_SELECTED_CLASS}`))) {
+    for (const p of (m.getAttribute(ROW_IDX_ATTR) ?? "").split(",")) {
+      const n = parseInt(p, 10);
+      if (Number.isFinite(n)) out.add(n);
+    }
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
 // src/testing/index.ts
 var ConformanceError = class extends Error {
   contract;
@@ -63,5 +102,11 @@ async function assertMarkerStoreConformance(store) {
 }
 export {
   ConformanceError,
-  assertMarkerStoreConformance
+  assertMarkerStoreConformance,
+  chartContainers,
+  clickEmpty,
+  clickMark,
+  findMark,
+  marksOf,
+  selectedRows
 };

package/dist/types/controls.d.ts

@@ -0,0 +1,50 @@
+import type { ChartHost } from "./host";
+export interface ControlInfo {
+    /** The knob's name in the chart's bag ("rate", "horizon"). */
+    key: string;
+    /** Its value as the chart stores it (a number, or an ISO date string for a date knob). */
+    value: unknown;
+    /** The label the chart draws beside it ("growth per year"), or "" if none. */
+    label: string;
+    /** The readout the chart draws ("+5.5%", "7 years") - the value in the chart's own words. */
+    text: string;
+}
+export interface Controls {
+    /** Every knob's current value, by key - the opening values as soon as the chart has drawn. */
+    readonly values: Readonly<Record<string, unknown>>;
+    /** Each knob in the order the chart draws them, with its label and readout. */
+    readonly info: readonly ControlInfo[];
+    /** "growth per year +5.5% · horizon 7 years": what to show beside a saved scenario. */
+    readonly summary: string;
+    /** True once a chart has drawn and reported its controls. */
+    readonly ready: boolean;
+    /** Bumped on every change. */
+    readonly version: number;
+    /** Apply values (a saved scenario): the chart redraws with them. Unknown keys are ignored by the chart. */
+    set(values: Readonly<Record<string, unknown>>): void;
+    /** Back to the chart's own defaults. */
+    reset(): void;
+    onChange(cb: (c: Controls) => void): () => void;
+}
+/** What attachControls hands the host: the uiState pair the chart reads and writes. */
+export interface ControlsAttachment {
+    /** Merge into the host's options at creation (and they stay: setOptions merges). */
+    readonly options: {
+        uiState: Record<string, unknown>;
+        setUiState: (s: unknown) => void;
+    };
+    /** Read the chart's controls now (call once a render has settled). */
+    read(): void;
+    detach(): void;
+}
+/** Make a controls handle: give it to one chart (a BicChart's `controls`, or attachControls). */
+export declare function createControls(initial?: Readonly<Record<string, unknown>>): Controls;
+/** Read each knob off a rendered chart: values from the bag, label and readout from what it drew. */
+export declare function readControls(container: HTMLElement): ControlInfo[];
+/**
+ * Wire a controls handle to one chart. Call it before creating the host and pass
+ * `attachment.options` into createChartHost's options (a raw uiState / setUiState pair takes
+ * precedence over any viewState provider); `getHost` returns the host once it exists. Call
+ * `read()` after each render settles.
+ */
+export declare function attachControls(getHost: () => ChartHost | null, container: HTMLElement, controls: Controls): ControlsAttachment;

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,133 @@
+import type { ChartHost } from "./host";
+/** 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;
+}
+export interface Filter {
+    readonly id: string;
+    /** 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, and to filters being added or removed. */
+    onChange(cb: (scope: FilterScope) => void): () => void;
+}
+/** 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 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 } 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,3 @@
+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";