@bicharts/chart-host 0.6.56 → 0.6.58

package/dist/types/react.d.ts

@@ -2,7 +2,12 @@ import type { ReactNode, RefObject } from "react";
 import { type ChartHostConfig } from "./host";
 import type { ResolveOptionsInput } from "./defaults";
 import type { GeoPointBinding } from "./payload";
+import { 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 { 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 +64,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 +99,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 +130,47 @@ 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>>): Controls;
+/** 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.58",
   "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",