@bicharts/chart-host 0.6.76 → 0.6.78

package/dist/react.mjs

@@ -22,7 +22,9 @@ import {
   loadGeo,
   syncMemberSelection,
   toSourceRows
-} from "./chunk-ZEXMBZHP.mjs";
+} from "./chunk-BFN4NY22.mjs";
+import "./chunk-L554L6HF.mjs";
+import "./chunk-MGAO2DR7.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-7JWL6LYE.mjs";
 import "./chunk-GHODWOAL.mjs";

package/dist/types/adapters/d3.d.ts

@@ -0,0 +1,3 @@
+import type { RendererAdapter } from "./types";
+/** The adapter for a chart drawn with D3: a mark is a DOM element, and its rows are in `data-row-idx`. */
+export declare function createD3Adapter(): RendererAdapter<Element>;

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

@@ -0,0 +1,3 @@
+export { NULL_ADAPTER } from "./types";
+export type { AdapterEvent, AdapterHit, AdapterScene, MarkHandle, MarkInfo, MarkRole, PaintRequest, RendererAdapter, AdapterId, RowTable, } from "./types";
+export { createD3Adapter } from "./d3";

package/dist/types/adapters/types.d.ts

@@ -0,0 +1,108 @@
+import type { RendererId } from "../host/services";
+import type { SelectionModifiers, SelectionPaintPlan, SelectionRule, GlyphCenter } from "../selection";
+/** What a renderer calls a mark. Opaque to the core: D3 an Element, Plotly {curve, point}, Vega a scenegraph item. */
+export type MarkHandle = unknown;
+/** What a mark is for: a data mark, a legend swatch, or an axis label that filters. */
+export type MarkRole = "mark" | "legend" | "axis";
+/** Which renderer an adapter binds: the same vocabulary a host declares it supports (host/services.ts). */
+export type AdapterId = RendererId | "NONE";
+/** The rows a renderer that works in values (Vega) resolves a click against. */
+export interface RowTable {
+    rows: readonly Record<string, unknown>[];
+    columns: readonly {
+        name?: string;
+        isMeasure?: boolean;
+    }[];
+}
+/** Everything an adapter may need about the chart it is bound to. */
+export interface AdapterScene {
+    container: HTMLElement;
+    doc: Document;
+    /** How many rows the chart has: the bound a renderer that reads row numbers from its own data must check. */
+    rowCount?: number;
+    /** The row table, for a renderer whose marks name values. */
+    table?: RowTable;
+    /** The diagnostics sink; the resolution logic logs through it and never throws. */
+    log(tag: string, data?: object): void;
+}
+/** One mark as the core sees it. */
+export interface MarkInfo<H = MarkHandle> {
+    handle: H;
+    role: MarkRole;
+    /** The data rows the mark stands for. */
+    rows: readonly number[];
+    /** The mark's identity under the "clicked-marks" selection rule. */
+    key: string;
+}
+/** A click as the core hands it over. `native` is whatever the renderer's own event is. */
+export interface AdapterEvent {
+    native: unknown;
+    clientX?: number;
+    clientY?: number;
+    modifiers: SelectionModifiers;
+}
+/**
+ * What a click turned out to be. The four are different gestures and the core answers each differently, so an
+ * adapter must say which:
+ *   mark    - a mark (furniture included; `role` says which);
+ *   control - inside a control the chart drew: neither a selection nor a click on empty canvas;
+ *   empty   - the empty canvas: the core MAY clear the selection (D3);
+ *   ignored - a click that resolves to nothing the adapter can use: log it and change nothing (Vega).
+ */
+export type AdapterHit<H = MarkHandle> = {
+    kind: "mark";
+    mark: MarkInfo<H>;
+} | {
+    kind: "control";
+} | {
+    kind: "empty";
+} | {
+    kind: "ignored";
+    reason: string;
+};
+/** A request to draw a selection. `plan` is present when the renderer's marks can be listed (D3). */
+export interface PaintRequest<H = MarkHandle> {
+    selection: ReadonlySet<number>;
+    active: boolean;
+    dimOpacity: number;
+    plan?: {
+        marks: readonly MarkInfo<H>[];
+        result: SelectionPaintPlan;
+    };
+}
+/**
+ * One renderer's binding. Every capability but identity is optional, because renderers differ in what they own: a
+ * renderer that subscribes to its own click events implements `bind` and leaves `hit` out; one the core's container
+ * listener serves implements `hit`.
+ */
+export interface RendererAdapter<H = MarkHandle> {
+    readonly id: AdapterId;
+    /** Who delivers clicks: the core's container listener, the adapter's own subscription, or nobody. */
+    readonly input: "container-click" | "adapter-bound" | "none";
+    /** Subscribe to the renderer's own click events; returns the unsubscribe. */
+    bind?(scene: AdapterScene, onHit: (hit: AdapterHit<H>, modifiers: SelectionModifiers) => void): () => void;
+    /** Every mark the chart drew, as opaque handles. */
+    marks?(scene: AdapterScene): readonly MarkInfo<H>[];
+    /** Resolve a click to what it hit. */
+    hit?(event: AdapterEvent, scene: AdapterScene): AdapterHit<H>;
+    /** The data rows a mark stands for. */
+    rowsOf?(handle: H, scene: AdapterScene, role?: MarkRole): number[];
+    /** How a selection lights this chart's marks; "any-row" when the chart declared nothing. */
+    declaredRule?(scene: AdapterScene): SelectionRule;
+    /** Draw a selection. */
+    paint?(request: PaintRequest<H>, scene: AdapterScene): void | Promise<void>;
+    /** Where each selected mark's glyph goes, in pixels from `base`. */
+    glyphAnchors?(base: {
+        left: number;
+        top: number;
+    }, scene: AdapterScene): GlyphCenter[];
+    /** Make the render hittable after it draws; returns what it changed. */
+    prepare?(scene: AdapterScene): unknown;
+    /** A behavior tag and detail for the render, or null when there is nothing to say. */
+    census?(scene: AdapterScene): {
+        flag: string;
+        detail: object;
+    } | null;
+}
+/** No marks and no binding: legal, and what a chart that cannot be selected from is. */
+export declare const NULL_ADAPTER: RendererAdapter;

package/dist/types/card.d.ts

@@ -0,0 +1 @@
+export { createSelectionCards, type SelectionCards, type SelectionCardsDeps } from "./selectionCardChrome";

package/dist/types/index.d.ts

@@ -14,6 +14,7 @@ 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, 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 type { AdapterEvent, AdapterHit, AdapterId, AdapterScene, MarkHandle, MarkInfo, MarkRole, PaintRequest, RendererAdapter, RowTable, } from "./adapters/types";
 export { planTrivialChart, compileTrivialSource, type TrivialPlan, type TrivialShapeKind } from "./trivial";
 export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngDataUrl, tableHostOf, chartSvgOf, htmlToSvgDataUrl, htmlNaturalSize, type SnapshotOptions } from "./snapshot";
 export { shouldReview, buildReviewWire, bareBase64, actionFor, type ReviewGate, type ReviewWire, type ReviewVerdict, type ReviewAction } from "./review";

package/dist/types/selectionCardChrome.d.ts

@@ -0,0 +1,29 @@
+import type { SourceFormats } from "./sourceDateFormat";
+export interface SelectionCardsDeps {
+    /** The positioned ancestor the cards live inside. Nothing the visual draws escapes its
+     *  frame, and a card is visual-drawn, so this is a hard boundary rather than a preference. */
+    container: HTMLElement;
+    /** The payload the chart was drawn from. A getter, not a value: the chart is redrawn on
+     *  resize, on a cell edit and on a live restyle, and a captured payload would age out. */
+    getPayload: () => any;
+    /** The chart's own aggregation, so the card cannot contradict the picture it sits on. */
+    getAggregation: () => string;
+    /** The source's own per-column date formats (a worksheet's number formats, a model's format
+     *  strings), so a click on a date is answered in the reader's formatting rather than in the
+     *  payload's ISO instant. A getter for the same reason `getPayload` is one - the source is
+     *  re-read on every resize and every edit. Optional: without it the card still renders a
+     *  locale date, never the ISO. */
+    getSourceFormats?: () => SourceFormats | null;
+    getEnabled: () => boolean;
+    getPinLimit: () => number;
+    cultureCode?: string;
+    log?: (tag: string, detail?: unknown) => void;
+}
+export interface SelectionCards {
+    /** Hand it the row set chart-host resolved. Empty clears. */
+    onSelect(rowIdxs: number[]): void;
+    /** Drop the transient card AND every pin - used when the chart itself goes away. */
+    clear(): void;
+    destroy(): void;
+}
+export declare function createSelectionCards(deps: SelectionCardsDeps): SelectionCards;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.6.76",
+  "version": "0.6.78",
   "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",
@@ -44,6 +44,16 @@
       "import": "./dist/page.mjs",
       "default": "./dist/page.mjs"
     },
+    "./card": {
+      "types": "./dist/types/card.d.ts",
+      "import": "./dist/card.mjs",
+      "default": "./dist/card.mjs"
+    },
+    "./adapters": {
+      "types": "./dist/types/adapters/index.d.ts",
+      "import": "./dist/adapters.mjs",
+      "default": "./dist/adapters.mjs"
+    },
     "./dax": {
       "types": "./dist/types/dax.d.ts",
       "import": "./dist/dax.mjs",