@bicharts/chart-host 0.6.56 → 0.6.59

package/dist/index.mjs

@@ -1,63 +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 {
-  ACTIVE_TICK_CLASS,
-  ANIMATION_OPTION_KEYS,
-  ANIM_LOOP_DELAY_DEFAULT,
-  ANIM_LOOP_DELAY_MIN,
-  ANIM_MAX_IDEAL_FRAMES_DEFAULT,
-  ANIM_MAX_IDEAL_FRAMES_MAX,
-  ANIM_MAX_IDEAL_FRAMES_MIN,
-  ANIM_PLAY_SPEED_DEFAULT,
-  ANIM_PLAY_SPEED_MAX,
-  ANIM_PLAY_SPEED_MIN,
   ANNOTATION_CLASS,
   ANNOTATION_LAYER_CLASS,
-  APPROXIMATE_POSITIONS_DEFAULT,
   AUTO_RAMP_CLASSES,
   AUTO_RAMP_DRAWN_OPACITY,
   AUTO_RAMP_MIN_STEP_DELTA_E,
-  AXIS_FILTER_CLASS,
   AXIS_PIN_BAND_PAD_PX,
   AXIS_PIN_MAX_BAND_FRACTION,
   AXIS_PIN_MIN_LABELS,
   AXIS_PIN_TRACK_REACH_PX,
   BACKING_MAJORITY,
-  COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
-  COLOR_SCALE_SELF_CLAMP_PCT_MAX,
-  COLOR_SCALE_SELF_CLAMP_PCT_MIN,
-  CONTAINER_SLOT_ANIM_STOP,
-  CONTAINER_SLOT_INITIAL_XF_MARK,
-  CONTAINER_SLOT_UI_STATE,
-  CONTAINER_SLOT_XF_CLEAR,
-  CONTROL_CLASS,
   D3_PLUGIN_PACKAGES,
   DARK_TEXT,
-  DIM_OPACITY_DEFAULT,
-  DIM_OPACITY_VAR,
   FIT_CONTENT_SELECTOR,
-  FLIP_DIRECTION_DEFAULT,
-  FLIP_INTERVAL_MAX_MS,
-  FLIP_INTERVAL_MIN_MS,
-  FLIP_MODE_DEFAULT,
-  GEO_POINT_PRECISIONS,
   GLYPH_SAMPLE_N,
-  HOST_CONTAINER_CLASS,
-  HOST_CONTRACT_VERSION,
   L,
   LABEL_CONTRAST_CAP,
   LABEL_CONTRAST_DONE_ATTR,
   LABEL_PILL_CLASS,
-  LEGEND_MARK_CLASS,
-  LIFT_SELECTED_CLASS,
   LIGHT_TEXT,
-  MARK_CLASS,
-  MARK_SELECTED_CLASS,
   MAX_FRAME_GROW_FACTOR,
-  MAX_MAP_POINTS_DEFAULT,
   MIN_CONTRAST,
   MIN_HIT_BAND_PX,
   MIN_RAMP_FILLS,
-  NO_ROW_MARKS_ATTR,
   PAGE_MATCH_TOLERANCE,
   PHANTOM_FRACTION,
   PILL_MIN_ALPHA,
@@ -65,23 +30,16 @@ import {
   PILL_OPAQUE_ALPHA,
   Qe,
   Qn,
-  ROW_IDX_ATTR,
   SAME_SHADE_DELTA_E,
   SCROLL_SLACK_PX,
-  SEASONAL_MARKERS_DEFAULT,
-  SELECTION_ACTIVE_CLASS,
   SELECTION_GLYPH_CLASS,
-  SNAPSHOT_SVG_ATTR,
   STRADDLE_COLS,
   STRADDLE_MIN_SHARE,
   STRADDLE_PILL_ALPHA,
   STRADDLE_ROWS,
   STRADDLE_TARGET_CONTRAST,
-  VALUE_AXIS_BASELINE_DEFAULT,
   VALUE_AXIS_MIN_FIT,
-  VIEW_ONLY_UI_STATE_KEYS,
   WHITE_TEXT_BG_LUM,
-  XFILTER_REFRESH_EVENT,
   Zn,
   _3,
   applyLabelContrast,
@@ -97,7 +55,6 @@ import {
   censusHitBands,
   censusMarks,
   censusValuePlacement,
-  chartOwnsTimeline,
   clearGeoCache,
   clearSelectionGlyphs,
   collectD3GlyphCenters,
@@ -138,7 +95,6 @@ import {
   noopViewStateProvider,
   o,
   paintSelectionGlyphs,
-  periodTickSuppressesFeedback,
   pickColorOver,
   pillBacksGlyph,
   pinScrolledAxis,
@@ -163,10 +119,56 @@ import {
   toRGBA,
   toSourceRows,
   unpinScrolledAxis,
-  valuePlacementFlag,
-  withoutViewOnlyKeys
-} from "./chunk-CMHGGW3Y.mjs";
+  valuePlacementFlag
+} from "./chunk-5NSU3MYW.mjs";
 import "./chunk-A2GMXZP7.mjs";
+import {
+  ACTIVE_TICK_CLASS,
+  ANIMATION_OPTION_KEYS,
+  ANIM_LOOP_DELAY_DEFAULT,
+  ANIM_LOOP_DELAY_MIN,
+  ANIM_MAX_IDEAL_FRAMES_DEFAULT,
+  ANIM_MAX_IDEAL_FRAMES_MAX,
+  ANIM_MAX_IDEAL_FRAMES_MIN,
+  ANIM_PLAY_SPEED_DEFAULT,
+  ANIM_PLAY_SPEED_MAX,
+  ANIM_PLAY_SPEED_MIN,
+  APPROXIMATE_POSITIONS_DEFAULT,
+  AXIS_FILTER_CLASS,
+  COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
+  COLOR_SCALE_SELF_CLAMP_PCT_MAX,
+  COLOR_SCALE_SELF_CLAMP_PCT_MIN,
+  CONTAINER_SLOT_ANIM_STOP,
+  CONTAINER_SLOT_INITIAL_XF_MARK,
+  CONTAINER_SLOT_UI_STATE,
+  CONTAINER_SLOT_XF_CLEAR,
+  CONTROL_CLASS,
+  DIM_OPACITY_DEFAULT,
+  DIM_OPACITY_VAR,
+  FLIP_DIRECTION_DEFAULT,
+  FLIP_INTERVAL_MAX_MS,
+  FLIP_INTERVAL_MIN_MS,
+  FLIP_MODE_DEFAULT,
+  GEO_POINT_PRECISIONS,
+  HOST_CONTAINER_CLASS,
+  HOST_CONTRACT_VERSION,
+  LEGEND_MARK_CLASS,
+  LIFT_SELECTED_CLASS,
+  MARK_CLASS,
+  MARK_SELECTED_CLASS,
+  MAX_MAP_POINTS_DEFAULT,
+  NO_ROW_MARKS_ATTR,
+  ROW_IDX_ATTR,
+  SEASONAL_MARKERS_DEFAULT,
+  SELECTION_ACTIVE_CLASS,
+  SNAPSHOT_SVG_ATTR,
+  VALUE_AXIS_BASELINE_DEFAULT,
+  VIEW_ONLY_UI_STATE_KEYS,
+  XFILTER_REFRESH_EVENT,
+  chartOwnsTimeline,
+  periodTickSuppressesFeedback,
+  withoutViewOnlyKeys
+} from "./chunk-WNGJUPEI.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/optionsVocabulary.ts

package/dist/page.mjs

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

package/dist/react.mjs

@@ -1,4 +1,19 @@
 /*! @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 {
+  LINKED_HOVER_CLASS,
+  attachControls,
+  badgeKey,
+  bindFilter,
+  createControls,
+  createFilter,
+  createFilterScope,
+  fromVegaInteraction,
+  noteBadges,
+  notesFor,
+  payloadRowReader,
+  viewFromToken,
+  viewToken
+} from "./chunk-XIAL6EEC.mjs";
 import {
   assembleD3,
   createChartGroup,
@@ -7,13 +22,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 +72,10 @@ function BicChart(props) {
     annotations,
     onAnnotationClick,
     className,
-    style
+    style,
+    selects,
+    controls,
+    ariaLabel
   } = props;
   const ref = useRef(null);
   const hostRef = useRef(null);
@@ -72,6 +91,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 +133,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 +161,54 @@ 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, {
+      container: ref.current,
+      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 +221,220 @@ 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, opts) {
+  const scope = useContext(PageCtx);
+  const ref = useRef(null);
+  if (!ref.current) ref.current = createControls(initial);
+  const c = ref.current;
+  useEffect(() => scope.addControls(opts?.id ?? "controls", c), [scope, c, opts?.id]);
+  useSyncExternalStore((cb) => c.onChange(() => cb()), () => c.version, () => c.version);
+  return c;
+}
+function useBicView() {
+  const scope = useContext(PageCtx);
+  return useMemo(() => ({
+    save: () => scope.save(),
+    restore: (v) => scope.restore(v),
+    token: () => viewToken(scope.save()),
+    restoreToken: (t) => scope.restore(viewFromToken(t))
+  }), [scope]);
+}
+function useBicUrlState(param = "view") {
+  const scope = useContext(PageCtx);
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const url = new URL(window.location.href);
+    scope.restore(viewFromToken(url.searchParams.get(param)));
+    return scope.onChange(() => {
+      const u = new URL(window.location.href);
+      const view = scope.save();
+      const empty = !view.filters && !view.controls;
+      if (empty) u.searchParams.delete(param);
+      else u.searchParams.set(param, viewToken(view));
+      if (u.href !== window.location.href) window.history.replaceState(window.history.state, "", u.href);
+    });
+  }, [scope, param]);
+}
+function BicDevtools({ max = 20 }) {
+  const scope = useContext(PageCtx);
+  const [, tick] = useState(0);
+  const log = useRef([]);
+  useEffect(() => scope.onChange(() => {
+    const at = (/* @__PURE__ */ new Date()).toLocaleTimeString();
+    const changed = scope.filters.map((f) => `${f.label}: ${f.active ? f.text : "(none)"}${f.reason ? ` [${f.reason}]` : ""}`);
+    log.current = [`${at}  ${changed.join(" | ")}`, ...log.current].slice(0, max);
+    tick((t) => t + 1);
+  }), [scope, max]);
+  const box = {
+    position: "fixed",
+    right: 8,
+    bottom: 8,
+    zIndex: 2147483e3,
+    maxWidth: 420,
+    maxHeight: "50vh",
+    overflow: "auto",
+    font: "12px/1.4 ui-monospace, monospace",
+    background: "Canvas",
+    color: "CanvasText",
+    border: "1px solid GrayText",
+    borderRadius: 6,
+    padding: 6,
+    opacity: 0.95
+  };
+  return /* @__PURE__ */ jsxs("details", { className: "bic-devtools", style: box, children: [
+    /* @__PURE__ */ jsxs("summary", { style: { cursor: "pointer" }, children: [
+      "chart-host: ",
+      scope.active.length,
+      " filter(s) active"
+    ] }),
+    scope.filters.map((f) => /* @__PURE__ */ jsxs("div", { children: [
+      /* @__PURE__ */ jsx("b", { children: f.label }),
+      " [",
+      f.key,
+      "] ",
+      f.active ? JSON.stringify(f.keys) : "(none)",
+      " ",
+      f.text && `"${f.text}"`,
+      f.reason ? ` - last: ${f.reason}` : "",
+      " v",
+      f.version
+    ] }, f.id)),
+    [...scope.controls].map(([k, c]) => /* @__PURE__ */ jsxs("div", { children: [
+      /* @__PURE__ */ jsx("b", { children: "controls" }),
+      " [",
+      k,
+      "] ",
+      c.summary || JSON.stringify(c.values)
+    ] }, k)),
+    /* @__PURE__ */ jsx("div", { style: { marginTop: 4, opacity: 0.8 }, children: log.current.map((l, i) => /* @__PURE__ */ jsx("div", { children: l }, i)) })
+  ] });
+}
+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 +457,25 @@ function useMeasuredSize(ref) {
 export {
   BicChart,
   BicChartGroup,
+  BicDevtools,
+  BicFilterChips,
+  BicPage,
+  LINKED_HOVER_CLASS,
   assembleD3,
+  badgeKey,
+  createControls,
+  createFilter,
+  createFilterScope,
+  fromVegaInteraction,
+  noteBadges,
+  notesFor,
+  useBicControls,
+  useBicFilter,
+  useBicFilters,
   useBicSelection,
-  useMeasuredSize
+  useBicUrlState,
+  useBicView,
+  useMeasuredSize,
+  viewFromToken,
+  viewToken
 };

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;