@astryxdesign/vega 0.5.2-canary.c9c8564 → 0.5.2-canary.cb13c1e

package/README.md

@@ -17,6 +17,7 @@ Renders [Vega](https://vega.github.io/vega/) and [Vega-Lite](https://vega.github
 | `tsup.config.ts`    | Config    | Build config: CJS + ESM + `.d.ts` outputs                    |
 | `src/index.ts`      | Barrel    | Public API surface                                           |
 | `src/VegaChart.tsx` | Component | Inspects `$schema`, compiles or renders, owns View lifecycle |
+| `src/viewInputs.ts` | Utility   | Detects value changes in the props that own the View         |
 | `src/schema.ts`     | Utility   | Parses and validates Vega/Vega-Lite `$schema` URLs           |
 | `src/types.ts`      | Types     | Shared TypeScript types for this package                     |
 
@@ -133,9 +134,51 @@ import {VegaChart} from '@astryxdesign/vega';
 | -------------------- | --------- | --------------------------------------------------------- |
 | `ast`                | `boolean` | Retain expression AST in the runtime (useful for tooling) |
 
+### View lifecycle
+
+`<VegaChart>` builds a Vega `View` on mount and finalizes it on unmount. In
+between, it rebuilds the View only when `spec`, `compileOptions`,
+`parseConfig`, `parseOptions`, or `viewOptions` **changes value** — these props
+are compared by value against the values the live View was built from, not by
+reference. Two consequences, and you need neither `useMemo` nor a discipline
+about object identity for either:
+
+- an object literal rebuilt inline on every render does **not** tear the chart
+  down;
+- a spec you edit **in place** — held in a ref, a module constant, or shared
+  between renders — **is** picked up, because the comparison is against a copy
+  taken when the View was built, not against the previous props.
+
+Functions inside those props (a `tooltip` handler, `logger`, `loader`, `expr`,
+or `fieldTitle`) and class instances are compared by reference, since their
+behavior lives in methods a copy cannot capture: replace the value rather than
+mutating it.
+
+Two shapes cannot be copied for comparison: a subtree that re-enters an object
+already on its own path (a reference cycle), and one nested deeper than 100
+levels. Those parts are compared **by reference**, so passing the **same**
+object again is stable — a chart built from a cyclic spec is not rebuilt on
+every render — while passing a **new** object rebuilds the View even when it
+holds equal values.
+
+What that costs differs between the two:
+
+- **A cycle hides nothing.** Its re-entry edge points back at an object the
+  copy already walked, so an in-place edit anywhere in a cyclic spec is still
+  detected normally.
+- **Past 100 levels, an in-place edit is invisible** — the reference did not
+  change and the values below were never copied. Replace the object, or drive
+  the View through `onReady`, to update from down there.
+
+Everything the copy did reach is compared by value either way, so a mutation
+elsewhere in the spec is picked up even when part of it is opaque.
+
+Everything else is inert to the lifecycle: `data`, `className`, `style`,
+`onReady`, and `onError` never rebuild the View.
+
 ### Data loading
 
-`data` maps dataset names to tuple arrays and is applied via `view.data(name, tuples)` during View initialization, before the first render. It is _not reactive_; changes after mount are ignored.
+`data` maps dataset names to tuple arrays and is applied via `view.data(name, tuples)` during View initialization, before the first render. It is _not reactive_; changes after mount are ignored, and a new `data` object never rebuilds the View by itself. (When something else rebuilds the View, the new View loads whatever `data` holds at that moment.)
 
 To update data dynamically after render, use `onReady` to get the live View and drive it yourself:
 

package/dist/VegaChart.d.ts

@@ -23,17 +23,24 @@ import type { VegaChartProps } from './types';
  *   new vega.View(runtime, { ...viewOptions, container })
  *
  * Initial dataset values can be provided via `data`. They are loaded once
- * during View initialization, before the first render, and are not reactive.
+ * during View initialization, before the first render, and are not reactive:
+ * a change to `data` alone never rebuilds the View, and is not applied to the
+ * live one. Use `onReady` to drive data after mount.
  *
  * It owns the full `View` lifecycle: creates the view on mount, re-creates
- * it when `spec`, `parseConfig`, `parseOptions`, or `viewOptions` changes,
- * and calls `view.finalize()` on cleanup to release all runtime resources.
+ * it when `spec`, `compileOptions`, `parseConfig`, `parseOptions`, or
+ * `viewOptions` changes, and calls `view.finalize()` on cleanup to release
+ * all runtime resources.
+ *
+ * "Changes" means the value changed, not the reference: those props are
+ * compared by value against a copy taken when the live View was built, so an
+ * inline spec or options object rebuilt on every render keeps the live View
+ * (and its zoom, hover, and signal state), while a spec mutated in place is
+ * still picked up. Nothing needs to be memoized for either to hold.
  *
  * Callbacks (`onReady`, `onError`) are non-reactive Effect Events -- they
  * always see the latest props and never re-run the View lifecycle, so you
- * don't need to memoize them. Pass stable references (or `useMemo`)
- * for `parseConfig`, `parseOptions`, `viewOptions`, and `data` to avoid
- * unnecessary re-renders.
+ * don't need to memoize them.
  *
  * Note: this component does not accept `xstyle` because `@astryxdesign/vega` does not
  * depend on StyleX. Use `className` or `style` for layout overrides.

package/dist/VegaChart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VegaChart.d.ts","sourceRoot":"","sources":["../src/VegaChart.tsx"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,KAA0C,MAAM,OAAO,CAAC;AAI/D,OAAO,KAAK,EAAC,cAAc,EAAyB,MAAM,SAAS,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,IAAI,EACJ,cAAc,EACd,WAAW,EACX,YAAY,EACZ,WAAW,EACX,SAAS,EACT,KAAK,EACL,GAAG,EACH,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,EACpB,GAAG,KAAK,EACT,EAAE,cAAc,qBAiGhB;yBA9Ge,SAAS"}
+{"version":3,"file":"VegaChart.d.ts","sourceRoot":"","sources":["../src/VegaChart.tsx"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,KAAoD,MAAM,OAAO,CAAC;AAMzE,OAAO,KAAK,EAAC,cAAc,EAAyB,MAAM,SAAS,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,IAAI,EACJ,cAAc,EACd,WAAW,EACX,YAAY,EACZ,WAAW,EACX,SAAS,EACT,KAAK,EACL,GAAG,EACH,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,EACpB,GAAG,KAAK,EACT,EAAE,cAAc,qBAsIhB;yBAnJe,SAAS"}

package/dist/VegaChart.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=VegaChart.test.d.ts.map

package/dist/VegaChart.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VegaChart.test.d.ts","sourceRoot":"","sources":["../src/VegaChart.test.tsx"],"names":[],"mappings":""}

package/dist/index.js

@@ -29,6 +29,67 @@ function parseSchema(schema) {
   return { ok: true, library, version };
 }
 
+// src/viewInputs.ts
+var MAX_DEPTH = 100;
+var OPAQUE = /* @__PURE__ */ Symbol("astryx.vega.opaque");
+function opaque(value) {
+  return { [OPAQUE]: value };
+}
+function isOpaque(value) {
+  return typeof value === "object" && value !== null && OPAQUE in value;
+}
+function latchViewInputs(inputs) {
+  return { inputs, snapshot: snapshotValue(inputs, 0, /* @__PURE__ */ new Set()) };
+}
+function latchIsCurrent(latch, inputs) {
+  return matchesSnapshot(latch.snapshot, inputs);
+}
+function snapshotValue(value, depth, path) {
+  if (!isWalkable(value)) {
+    return value;
+  }
+  if (depth >= MAX_DEPTH || path.has(value)) {
+    return opaque(value);
+  }
+  path.add(value);
+  const copy = Array.isArray(value) ? value.map((item) => snapshotValue(item, depth + 1, path)) : Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      snapshotValue(entry, depth + 1, path)
+    ])
+  );
+  path.delete(value);
+  return copy;
+}
+function matchesSnapshot(snapshot, value) {
+  if (isOpaque(snapshot)) {
+    return Object.is(snapshot[OPAQUE], value);
+  }
+  if (Array.isArray(snapshot)) {
+    return Array.isArray(value) && snapshot.length === value.length && snapshot.every((item, index) => matchesSnapshot(item, value[index]));
+  }
+  if (isPlainObject(snapshot)) {
+    if (!isPlainObject(value)) {
+      return false;
+    }
+    const keys = Object.keys(snapshot);
+    return keys.length === Object.keys(value).length && keys.every(
+      (key) => Object.prototype.hasOwnProperty.call(value, key) && matchesSnapshot(snapshot[key], value[key])
+    );
+  }
+  return Object.is(snapshot, value);
+}
+function isWalkable(value) {
+  return Array.isArray(value) || isPlainObject(value);
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
 // src/VegaChart.tsx
 var _jsxruntime = require('react/jsx-runtime');
 function VegaChart({
@@ -46,17 +107,37 @@ function VegaChart({
   ...props
 }) {
   const containerRef = _react.useRef.call(void 0, null);
+  const inputs = {
+    spec,
+    compileOptions,
+    parseConfig,
+    parseOptions,
+    viewOptions
+  };
+  const [latch, setLatch] = _react.useState.call(void 0, () => latchViewInputs(inputs));
+  if (!latchIsCurrent(latch, inputs)) {
+    setLatch(latchViewInputs(inputs));
+  }
   const onReady = _react.useEffectEvent.call(void 0, (view) => {
     _optionalChain([onReadyProp, 'optionalCall', _ => _(view)]);
   });
   const onError = _react.useEffectEvent.call(void 0, (error) => {
     _optionalChain([onErrorProp, 'optionalCall', _2 => _2(error)]);
   });
+  const loadInitialData = _react.useEffectEvent.call(void 0, (view) => {
+    if (!data) {
+      return;
+    }
+    for (const [name, tuples] of Object.entries(data)) {
+      view.data(name, tuples);
+    }
+  });
   _react.useEffect.call(void 0, () => {
     const container = containerRef.current;
     if (!container) {
       return;
     }
+    const { spec: spec2 } = latch.inputs;
     let cancelled = false;
     let view = null;
     const fail = (err) => {
@@ -65,23 +146,23 @@ function VegaChart({
       }
     };
     try {
-      const schemaResult = parseSchema(spec.$schema);
+      const schemaResult = parseSchema(spec2.$schema);
       if (!schemaResult.ok) {
         fail(new Error(schemaResult.error));
         return;
       }
-      const vegaSpec = schemaResult.library === "vega-lite" ? _vegalite.compile.call(void 0, spec, compileOptions).spec : spec;
-      const runtime = _vega.parse.call(void 0, vegaSpec, parseConfig, parseOptions);
+      const vegaSpec = schemaResult.library === "vega-lite" ? _vegalite.compile.call(void 0, spec2, latch.inputs.compileOptions).spec : spec2;
+      const runtime = _vega.parse.call(void 0, 
+        vegaSpec,
+        latch.inputs.parseConfig,
+        latch.inputs.parseOptions
+      );
       view = new (0, _vega.View)(runtime, {
         hover: true,
-        ...viewOptions,
+        ...latch.inputs.viewOptions,
         container
       });
-      if (data) {
-        for (const [name, tuples] of Object.entries(data)) {
-          view.data(name, tuples);
-        }
-      }
+      loadInitialData(view);
       view.runAsync().then(() => {
         if (cancelled) {
           _optionalChain([view, 'optionalAccess', _3 => _3.finalize, 'call', _4 => _4()]);
@@ -98,7 +179,7 @@ function VegaChart({
       cancelled = true;
       _optionalChain([view, 'optionalAccess', _5 => _5.finalize, 'call', _6 => _6()]);
     };
-  }, [spec, data, compileOptions, parseConfig, parseOptions, viewOptions]);
+  }, [latch]);
   return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
     "div",
     {

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/VegaChart.tsx
-import { useEffect, useEffectEvent, useRef } from "react";
+import { useEffect, useEffectEvent, useRef, useState } from "react";
 import { parse, View } from "vega";
 import { compile } from "vega-lite";
 
@@ -29,6 +29,67 @@ function parseSchema(schema) {
   return { ok: true, library, version };
 }
 
+// src/viewInputs.ts
+var MAX_DEPTH = 100;
+var OPAQUE = /* @__PURE__ */ Symbol("astryx.vega.opaque");
+function opaque(value) {
+  return { [OPAQUE]: value };
+}
+function isOpaque(value) {
+  return typeof value === "object" && value !== null && OPAQUE in value;
+}
+function latchViewInputs(inputs) {
+  return { inputs, snapshot: snapshotValue(inputs, 0, /* @__PURE__ */ new Set()) };
+}
+function latchIsCurrent(latch, inputs) {
+  return matchesSnapshot(latch.snapshot, inputs);
+}
+function snapshotValue(value, depth, path) {
+  if (!isWalkable(value)) {
+    return value;
+  }
+  if (depth >= MAX_DEPTH || path.has(value)) {
+    return opaque(value);
+  }
+  path.add(value);
+  const copy = Array.isArray(value) ? value.map((item) => snapshotValue(item, depth + 1, path)) : Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      snapshotValue(entry, depth + 1, path)
+    ])
+  );
+  path.delete(value);
+  return copy;
+}
+function matchesSnapshot(snapshot, value) {
+  if (isOpaque(snapshot)) {
+    return Object.is(snapshot[OPAQUE], value);
+  }
+  if (Array.isArray(snapshot)) {
+    return Array.isArray(value) && snapshot.length === value.length && snapshot.every((item, index) => matchesSnapshot(item, value[index]));
+  }
+  if (isPlainObject(snapshot)) {
+    if (!isPlainObject(value)) {
+      return false;
+    }
+    const keys = Object.keys(snapshot);
+    return keys.length === Object.keys(value).length && keys.every(
+      (key) => Object.prototype.hasOwnProperty.call(value, key) && matchesSnapshot(snapshot[key], value[key])
+    );
+  }
+  return Object.is(snapshot, value);
+}
+function isWalkable(value) {
+  return Array.isArray(value) || isPlainObject(value);
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
 // src/VegaChart.tsx
 import { jsx } from "react/jsx-runtime";
 function VegaChart({
@@ -46,17 +107,37 @@ function VegaChart({
   ...props
 }) {
   const containerRef = useRef(null);
+  const inputs = {
+    spec,
+    compileOptions,
+    parseConfig,
+    parseOptions,
+    viewOptions
+  };
+  const [latch, setLatch] = useState(() => latchViewInputs(inputs));
+  if (!latchIsCurrent(latch, inputs)) {
+    setLatch(latchViewInputs(inputs));
+  }
   const onReady = useEffectEvent((view) => {
     onReadyProp?.(view);
   });
   const onError = useEffectEvent((error) => {
     onErrorProp?.(error);
   });
+  const loadInitialData = useEffectEvent((view) => {
+    if (!data) {
+      return;
+    }
+    for (const [name, tuples] of Object.entries(data)) {
+      view.data(name, tuples);
+    }
+  });
   useEffect(() => {
     const container = containerRef.current;
     if (!container) {
       return;
     }
+    const { spec: spec2 } = latch.inputs;
     let cancelled = false;
     let view = null;
     const fail = (err) => {
@@ -65,23 +146,23 @@ function VegaChart({
       }
     };
     try {
-      const schemaResult = parseSchema(spec.$schema);
+      const schemaResult = parseSchema(spec2.$schema);
       if (!schemaResult.ok) {
         fail(new Error(schemaResult.error));
         return;
       }
-      const vegaSpec = schemaResult.library === "vega-lite" ? compile(spec, compileOptions).spec : spec;
-      const runtime = parse(vegaSpec, parseConfig, parseOptions);
+      const vegaSpec = schemaResult.library === "vega-lite" ? compile(spec2, latch.inputs.compileOptions).spec : spec2;
+      const runtime = parse(
+        vegaSpec,
+        latch.inputs.parseConfig,
+        latch.inputs.parseOptions
+      );
       view = new View(runtime, {
         hover: true,
-        ...viewOptions,
+        ...latch.inputs.viewOptions,
         container
       });
-      if (data) {
-        for (const [name, tuples] of Object.entries(data)) {
-          view.data(name, tuples);
-        }
-      }
+      loadInitialData(view);
       view.runAsync().then(() => {
         if (cancelled) {
           view?.finalize();
@@ -98,7 +179,7 @@ function VegaChart({
       cancelled = true;
       view?.finalize();
     };
-  }, [spec, data, compileOptions, parseConfig, parseOptions, viewOptions]);
+  }, [latch]);
   return /* @__PURE__ */ jsx(
     "div",
     {

package/dist/schema.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema.test.d.ts.map

package/dist/schema.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.test.d.ts","sourceRoot":"","sources":["../src/schema.test.ts"],"names":[],"mappings":""}

package/dist/vegaLiteConfig.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vegaLiteConfig.test.d.ts.map

package/dist/vegaLiteConfig.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vegaLiteConfig.test.d.ts","sourceRoot":"","sources":["../src/vegaLiteConfig.test.ts"],"names":[],"mappings":""}

package/dist/viewInputs.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file viewInputs.ts
+ * @input The VegaChart props that own the Vega View lifecycle
+ * @output The ViewInputs type plus latch/compare helpers VegaChart rebuilds on
+ * @position Internal utility; used by VegaChart to decide when to rebuild
+ *
+ * SYNC: When modified, update /packages/vega/README.md
+ */
+import type { VegaChartProps } from './types';
+/**
+ * The props the Vega runtime is built from. A change to any of them produces
+ * a different runtime, so the View is torn down and rebuilt. `data`,
+ * `className`, `style`, and the callbacks are absent because none of them
+ * change the runtime.
+ */
+export type ViewInputs = Pick<VegaChartProps, 'spec' | 'compileOptions' | 'parseConfig' | 'parseOptions' | 'viewOptions'>;
+/**
+ * The inputs the live View was built from, beside a structural copy of their
+ * values at that moment.
+ *
+ * The copy is the whole point. Comparing the incoming props against the
+ * *previous props* cannot see a spec mutated in place — both sides are the
+ * same object, so the old value is already gone and the chart silently goes
+ * stale. Comparing against a copy taken when the View was built can.
+ *
+ * The copy is also compared during render, so its verdict must be stable for
+ * an unchanged input: a part that always reported "changed" would loop React
+ * forever. See {@link Opaque} for the parts that cannot be copied.
+ */
+export type ViewInputsLatch = {
+    /** The caller's own objects, handed to Vega untouched. */
+    readonly inputs: ViewInputs;
+    readonly snapshot: unknown;
+};
+export declare function latchViewInputs(inputs: ViewInputs): ViewInputsLatch;
+/**
+ * Whether `inputs` still carries the values the latched View was built from.
+ *
+ * Plain objects and arrays are compared entry by entry, so a spec or options
+ * bag rebuilt inline on every render counts as unchanged. Everything else --
+ * functions (tooltip handlers, loggers, loaders, field-title formatters),
+ * class instances, dates -- compares by reference, because two instances can
+ * behave differently even when they look alike, and the View built from them
+ * would too.
+ */
+export declare function latchIsCurrent(latch: ViewInputsLatch, inputs: ViewInputs): boolean;
+//# sourceMappingURL=viewInputs.d.ts.map

package/dist/viewInputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewInputs.d.ts","sourceRoot":"","sources":["../src/viewInputs.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAC3B,cAAc,EACd,MAAM,GAAG,gBAAgB,GAAG,aAAa,GAAG,cAAc,GAAG,aAAa,CAC3E,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B,CAAC;AAuCF,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,eAAe,CAEnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,UAAU,GACjB,OAAO,CAET"}

package/dist/viewInputs.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=viewInputs.test.d.ts.map

package/dist/viewInputs.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewInputs.test.d.ts","sourceRoot":"","sources":["../src/viewInputs.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/vega",
-  "version": "0.5.2-canary.c9c8564",
+  "version": "0.5.2-canary.cb13c1e",
   "description": "Astryx Vega wrapper — chart and data visualization components. Published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -57,6 +57,8 @@
   "scripts": {
     "build": "tsup && tsc --project tsconfig.json --emitDeclarationOnly --declaration --noEmit false --outDir dist",
     "dev": "tsup --watch",
+    "test": "vitest run --root ../..",
+    "test:watch": "vitest --root ../..",
     "typecheck": "tsc --noEmit"
   }
 }