@bicharts/chart-host 0.6.80 → 0.6.82

package/README.md

@@ -278,6 +278,79 @@ made for: every word shares a comment with many others, so the default lit most
 click. The cross-filter sent out is the same under both rules. `onSelectionPaint` reports how each
 paint of a declaring chart decided, including when no mark matched and the default was used.
 
+## Remembering what the reader did
+
+A chart keeps its resting state (a sort, an expanded row, a 3D camera angle) in a small bag. It
+reads the bag from `options.uiState` and writes it through `options.setUiState`, and generated code
+never learns where the bag goes. Where it goes is your host's choice, and so is which keys may
+outlive what: a redraw, a close and reopen, or a new version of the chart.
+
+`createChartHost` still takes one `viewState` provider, as before. When your host needs more than
+one store, describe it with a `ViewStateService`:
+
+```ts
+import { sessionViewStateProvider, type ViewStateService } from "@bicharts/chart-host";
+
+const viewState: ViewStateService = {
+    viewing: sessionViewStateProvider(el),   // survives a redraw; a page switch starts clean
+    durable: workbookStore,                  // optional: survives close and reopen
+    policy: {                                // the keys your host scopes, by name
+        camera: { lifetime: "durable", dropOnNewVersion: true, dropOnFreshViewing: false, durableWhen: "rememberView" },
+        userStopped: { lifetime: "durable", dropOnNewVersion: false, dropOnFreshViewing: true },
+    },
+    versionKey: "cameraVersion",             // optional: how a version change is noticed
+};
+```
+
+**What you provide.** `viewing` and `policy` are required (`policy: {}` is fine). Everything else is
+optional, and leaving it out says something about your host:
+
+- no `durable` store: the host can't remember across a close (a static preview, a server-side
+  render). `viewStateIsDurable(service)` is the one definition of "remembers the view", so it can't
+  be claimed without a store to back it. `noopViewStateService()` says "nothing is stored" out loud.
+- no `chartKeys`: keys your policy doesn't name belong to the chart. They're kept, durably, through a
+  new version and a fresh viewing, and the chart validates what it reads. Set `chartKeys` to give
+  them another rule. A host that forgets everything when its chart changes sets `dropOnNewVersion`.
+- no `versionKey`: you apply the version rule yourself, where you learn the chart changed.
+- no `durableMaxChars`: the durable store accepts any size.
+
+**What a key can be.** `lifetime: "viewing"` keeps a key out of the durable store; `"durable"` puts it
+in both. `dropOnNewVersion` drops it when the chart on screen is another version (a camera is aimed
+at one chart's axes). `dropOnFreshViewing` drops it when the bag is read at the start of a viewing
+instead of in the one that wrote it. `durableWhen` names a preference that must be on for the key to
+reach the durable store; the viewing store keeps it either way.
+
+**The rules are plain functions** in `@bicharts/chart-host/view-state`, with no DOM, timers or
+storage of their own:
+
+```ts
+import { resolveViewState, commitViewState } from "@bicharts/chart-host/view-state";
+
+const { bag, dropped } = resolveViewState(viewState, { codeVersion, freshViewing });   // before a render
+commitViewState(next, viewState, prefs);                                               // when the chart writes
+```
+
+`resolveViewState` builds the bag the chart is handed: the viewing store, else the durable one, with
+the policy applied. `commitViewState` decides what a write reaches: the viewing store gets all of
+it, the durable store gets what the policy allows. Both report what they did and neither throws.
+`viewStateAfterSwap(service, bag)` applies the version rule for a host that sees the swap itself.
+
+**Check your stores** with the conformance suite in the testing subpath. It confirms `load` never
+throws and reads `{}` when empty, that `save` replaces, that nested values round-trip, that the
+viewing store survives your host being re-created on the same element, and that the durable store
+holds what it's given across a reopen:
+
+```ts
+import { assertViewStateConformance } from "@bicharts/chart-host/testing";
+
+const report = await assertViewStateConformance(service, {
+    recreate: () => buildService(sameElement),   // the host drawing again
+    reopen: () => buildService(newElement),      // a new viewing over the same saved file
+    settle: () => flushPendingWrites(),          // only if your durable save is debounced
+});
+expect(report.skipped).toEqual([]);              // nothing went unchecked
+```
+
 ## Architecture — three layers, and why it matters if you contribute
 
 Read this before adding code. The package has **three** concerns, and they are independent.

package/dist/card.mjs

@@ -1,8 +1,8 @@
 /*! @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 {
   computeSelectionCard
-} from "./chunk-Y3CCDWVO.mjs";
-import "./chunk-P3HUTWQB.mjs";
+} from "./chunk-7HPVGRQ2.mjs";
+import "./chunk-ZRSEKV4I.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/selectionCardChrome.ts

package/dist/{chunk-Y3CCDWVO.mjs → chunk-7HPVGRQ2.mjs}

@@ -1,18 +1,18 @@
 /*! @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 {
-  L,
-  it,
-  le,
-  oi,
-  rt,
-  ui
-} from "./chunk-P3HUTWQB.mjs";
+  Dr,
+  Z,
+  g,
+  ht,
+  kr,
+  pt
+} from "./chunk-ZRSEKV4I.mjs";
 
 // src/sourceDateFormat.ts
 function formatSourceDate(raw, opts = {}) {
   const d = toDate(raw);
   if (!d) return null;
-  const dayFrame = L(d);
+  const dayFrame = g(d);
   const frame = dayFrame ?? (opts.dialect === "dotnet" ? "local" : "utc");
   const p = partsIn(d, frame);
   const format = cleanFormat(opts.format, opts.dialect);
@@ -33,7 +33,7 @@ var ISO_LIKE_RE = /^\s*\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(
 function toDate(raw) {
   if (raw instanceof Date) return isNaN(raw.getTime()) ? null : raw;
   if (typeof raw !== "string" || !ISO_LIKE_RE.test(raw)) return null;
-  const d = le(raw.trim());
+  const d = Z(raw.trim());
   return d && !isNaN(d.getTime()) ? d : null;
 }
 function partsIn(d, frame) {
@@ -435,15 +435,15 @@ function displayText(col, raw, opts) {
   return String(raw);
 }
 function isSuppressed(col) {
-  return it(col).suppressed;
+  return pt(col).suppressed;
 }
 function resolveAgg(col, requested, auto) {
   const fallback = () => {
-    const d = oi(col);
+    const d = Dr(col);
     return d === "first" ? "count" : d;
   };
   if (auto) return fallback();
-  return rt(col).indexOf(requested) >= 0 ? requested : fallback();
+  return ht(col).indexOf(requested) >= 0 ? requested : fallback();
 }
 function toNumber(v) {
   if (v == null || v === "") return null;
@@ -546,7 +546,7 @@ function computeSelectionCard(payload, selectedRowIdxs, opts = {}) {
     }
     const value = reduce(selVals, colAgg, selRaw);
     let sharePct = null;
-    if (ui(col, colAgg) && value != null) {
+    if (kr(col, colAgg) && value != null) {
       const allVals = [];
       const allRaw = [];
       for (let r = 0; r < rows.length; r++) {

package/dist/{chunk-YYJCE5TO.mjs → chunk-MP5S6MVW.mjs}

@@ -2,10 +2,10 @@
 import {
   Fn,
   J3,
+  X,
   Xn,
-  Yn,
-  ge
-} from "./chunk-P3HUTWQB.mjs";
+  Yn
+} from "./chunk-ZRSEKV4I.mjs";
 import {
   censusHitBands,
   createMarkResolver,
@@ -244,10 +244,10 @@ function f(t) {
 }
 function rgbToLab(r, g, b) {
   const R = linearise(r), G = linearise(g), B = linearise(b);
-  const X = 0.4124564 * R + 0.3575761 * G + 0.1804375 * B;
+  const X2 = 0.4124564 * R + 0.3575761 * G + 0.1804375 * B;
   const Y = 0.2126729 * R + 0.7151522 * G + 0.072175 * B;
   const Z = 0.0193339 * R + 0.119192 * G + 0.9503041 * B;
-  const fx = f(X / Xn2), fy = f(Y / Yn2), fz = f(Z / Zn);
+  const fx = f(X2 / Xn2), fy = f(Y / Yn2), fz = f(Z / Zn);
   return { L: 116 * fy - 16, a: 500 * (fx - fy), b: 200 * (fy - fz) };
 }
 function hexToLab(hex2) {
@@ -302,13 +302,13 @@ function labToHex(lab) {
     return t3 > EPS ? t3 : (116 * t - 16) / KAPPA;
   };
   const fy = (lab.L + 16) / 116, fx = fy + lab.a / 500, fz = fy - lab.b / 200;
-  const X = Xn2 * finv(fx);
+  const X2 = Xn2 * finv(fx);
   const Y = Yn2 * (lab.L > KAPPA * EPS ? fy * fy * fy : lab.L / KAPPA);
   const Z = Zn * finv(fz);
   const lin = [
-    3.2404542 * X - 1.5371385 * Y - 0.4985314 * Z,
-    -0.969266 * X + 1.8760108 * Y + 0.041556 * Z,
-    0.0556434 * X - 0.2040259 * Y + 1.0572252 * Z
+    3.2404542 * X2 - 1.5371385 * Y - 0.4985314 * Z,
+    -0.969266 * X2 + 1.8760108 * Y + 0.041556 * Z,
+    0.0556434 * X2 - 0.2040259 * Y + 1.0572252 * Z
   ];
   return "#" + lin.map((v) => {
     const c = Math.max(0, Math.min(1, v));
@@ -852,7 +852,7 @@ function buildRenderPayload(cols, rowObjs, geo, point, destination, opts) {
   cols = cols.filter((c) => c.name !== ROW_IDX_COLUMN);
   let utcDayColumns = null;
   if (opts?.utcDays) {
-    const norm = ge(cols, rowObjs);
+    const norm = X(cols, rowObjs);
     rowObjs = norm.rows;
     utcDayColumns = norm.columns;
   }
@@ -1866,10 +1866,10 @@ var EMPTY4 = {
 };
 function backedSamples(el, pts) {
   try {
-    const ge2 = el;
-    if (typeof ge2.isPointInFill !== "function" || typeof ge2.getScreenCTM !== "function") return null;
-    const m = ge2.getScreenCTM();
-    const svg = ge2.ownerSVGElement;
+    const ge = el;
+    if (typeof ge.isPointInFill !== "function" || typeof ge.getScreenCTM !== "function") return null;
+    const m = ge.getScreenCTM();
+    const svg = ge.ownerSVGElement;
     if (!m || !svg || typeof svg.createSVGPoint !== "function") return null;
     if (pts.length === 0) return null;
     const inv = m.inverse();
@@ -1878,7 +1878,7 @@ function backedSamples(el, pts) {
       const p = svg.createSVGPoint();
       p.x = pts[i].x;
       p.y = pts[i].y;
-      hit.push(ge2.isPointInFill(p.matrixTransform(inv)));
+      hit.push(ge.isPointInFill(p.matrixTransform(inv)));
     }
     return hit;
   } catch {
@@ -1923,9 +1923,9 @@ function sampleBackgrounds(shapes, pts, pageRGB, effAlpha) {
 function extendPillOver(pill, tr) {
   try {
     if (String(pill.tagName || "").toLowerCase() !== "rect") return false;
-    const ge2 = pill;
-    if (typeof ge2.getScreenCTM !== "function") return false;
-    const m = ge2.getScreenCTM();
+    const ge = pill;
+    if (typeof ge.getScreenCTM !== "function") return false;
+    const m = ge.getScreenCTM();
     if (!m || Math.abs(m.b) > 1e-6 || Math.abs(m.c) > 1e-6 || !(m.a > 0) || !(m.d > 0)) return false;
     const inv = m.inverse();
     const toUser = (x2, y2) => ({ x: inv.a * x2 + inv.c * y2 + inv.e, y: inv.b * x2 + inv.d * y2 + inv.f });