@optiaxiom/proteus 3.0.6 → 3.2.0

package/dist/esm/proteus-script/useProteusScripts.js

@@ -0,0 +1,176 @@
+"use client";
+"use client";
+import { useEffectEvent } from "../hooks/useEffectEvent.js";
+import { WORKER_SCRIPT } from "./workerScript.js";
+import { useEffect, useRef } from "react";
+import { get } from "jsonpointer";
+//#region src/proteus-script/useProteusScripts.ts
+/**
+* How long a single handler run may take before we give up on it. A script
+* with an infinite loop cannot block the main thread (it runs in the worker),
+* but its `invoke` promise would otherwise never resolve — wedging the
+* triggering control in a `loading` state forever. On timeout we resolve the
+* run to `undefined` (the fail-silent default) and terminate the worker so the
+* runaway handler stops burning a core; the next run lazily respawns it.
+*/
+const INVOKE_TIMEOUT_MS = 5e3;
+/**
+* Spins up a single sandbox Web Worker for the document's `scripts` and returns
+* a `runScript(handler, params)` that invokes a named handler inside it. Events
+* a handler or watcher emits are routed back through `onEmit` (the shell
+* dispatcher) and their results returned to the worker, so `ctx.emit`
+* round-trips work.
+*
+* Watchers (`watch(path, fn)` in a script) are driven from here: the worker
+* reports its watched paths after `init`, and this hook edge-detects each path
+* against `data` on every change, posting `runWatcher` when the value there
+* changes. A watcher does NOT re-fire on data changes caused by a script's own
+* `emit` (see `emitDepthRef`) — watchers observe user/host state changes, which
+* both prevents emit→watcher→emit loops and gives a predictable "reacts to what
+* the user did" semantic.
+*
+* Returns a no-op runner when the document ships no scripts — the worker is
+* spawned eagerly when scripts exist (watchers can fire before any interaction).
+*/
+function useProteusScripts({ data, onEmit, scripts }) {
+	const dataRef = useRef(data);
+	dataRef.current = data;
+	const initialDataRef = useRef(data);
+	const emit = useEffectEvent(onEmit);
+	const hasScripts = !!scripts && Object.keys(scripts).length > 0;
+	const pending = useRef(/* @__PURE__ */ new Map()).current;
+	const nextId = useRef(1);
+	const workerRef = useRef(null);
+	const watchedPaths = useRef([]);
+	const lastEval = useRef([]);
+	const emitDepth = useRef(0);
+	/** Snapshot every watched path from `data` into `lastEval` without firing. */
+	const seedWatchers = useEffectEvent((data) => {
+		lastEval.current = watchedPaths.current.map((path) => JSON.stringify(getByPointer(data, path) ?? null));
+	});
+	/**
+	* Compare each watched path in `data` against its `lastEval` baseline and post
+	* `runWatcher` for any that changed, advancing the baseline. Shared by the
+	* data-change effect and the `watchers` message handler (so a watcher that
+	* registers after the user already changed data still catches that edge).
+	*/
+	const runEdgeDetect = useEffectEvent((data) => {
+		const worker = workerRef.current;
+		if (!worker) return;
+		watchedPaths.current.forEach((path, watchId) => {
+			const current = getByPointer(data, path) ?? null;
+			const serialized = JSON.stringify(current);
+			const prevSerialized = lastEval.current[watchId];
+			if (serialized !== prevSerialized) {
+				lastEval.current[watchId] = serialized;
+				const previous = prevSerialized === void 0 ? void 0 : JSON.parse(prevSerialized);
+				worker.postMessage({
+					current,
+					data,
+					previous,
+					type: "runWatcher",
+					watchId
+				});
+			}
+		});
+	});
+	/** Resolve a pending run (if still pending) and clear its timeout. */
+	const settle = useEffectEvent((invokeId, result) => {
+		const entry = pending.get(invokeId);
+		if (!entry) return;
+		clearTimeout(entry.timer);
+		pending.delete(invokeId);
+		entry.resolve(result);
+	});
+	const spawnWorker = useEffectEvent(() => {
+		const url = URL.createObjectURL(new Blob([WORKER_SCRIPT], { type: "text/javascript" }));
+		const instance = new Worker(url);
+		URL.revokeObjectURL(url);
+		instance.postMessage({
+			scripts,
+			type: "init"
+		});
+		instance.addEventListener("message", async (e) => {
+			const msg = e.data;
+			if (msg.type === "emit") {
+				emitDepth.current += 1;
+				let result;
+				try {
+					result = await emit(msg.event);
+				} finally {
+					emitDepth.current -= 1;
+				}
+				instance.postMessage({
+					emitId: msg.emitId,
+					result,
+					type: "emitResult"
+				});
+			} else if (msg.type === "invokeResult") settle(msg.invokeId, msg.result);
+			else if (msg.type === "watchers") {
+				watchedPaths.current = msg.paths;
+				seedWatchers(initialDataRef.current);
+				runEdgeDetect(dataRef.current);
+			}
+		});
+		return instance;
+	});
+	/** Ensure the worker exists, spawning it on first need. */
+	const ensureWorker = useEffectEvent(() => {
+		if (!workerRef.current) workerRef.current = spawnWorker();
+		return workerRef.current;
+	});
+	/** Tear down the current worker and abandon every in-flight run. */
+	const teardown = useEffectEvent(() => {
+		workerRef.current?.terminate();
+		workerRef.current = null;
+		watchedPaths.current = [];
+		lastEval.current = [];
+		for (const [invokeId] of pending) settle(invokeId, void 0);
+	});
+	useEffect(() => {
+		teardown();
+		if (hasScripts) ensureWorker();
+		return teardown;
+	}, [scripts, hasScripts]);
+	useEffect(() => {
+		if (!workerRef.current || watchedPaths.current.length === 0) return;
+		if (emitDepth.current > 0) {
+			seedWatchers(data);
+			return;
+		}
+		runEdgeDetect(data);
+	}, [data]);
+	return useEffectEvent((handler, params) => {
+		if (!hasScripts) return Promise.resolve(void 0);
+		const worker = ensureWorker();
+		const invokeId = nextId.current++;
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				settle(invokeId, void 0);
+				teardown();
+			}, INVOKE_TIMEOUT_MS);
+			pending.set(invokeId, {
+				resolve,
+				timer
+			});
+			worker.postMessage({
+				data: dataRef.current,
+				handler,
+				invokeId,
+				params: params ?? {},
+				type: "invoke"
+			});
+		});
+	});
+}
+/** Read a JSON-pointer slice, matching the worker's getByPointer semantics. */
+function getByPointer(data, path) {
+	if (!path || path === "/") return data;
+	try {
+		return get(data, path);
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { useProteusScripts };

package/dist/esm/proteus-script/workerScript.js

@@ -0,0 +1,149 @@
+//#region src/proteus-script/workerScript.ts
+/**
+* Source of the sandbox Web Worker, authored as a self-contained string so it
+* can be turned into a Blob URL and run without a separate chunk or same-origin
+* file (mirrors how `ProteusBridge` inlines its shim script).
+*
+* The worker has no DOM, no `window.parent`, and communicates only via
+* structured-clone `postMessage` — a strictly tighter sandbox than an iframe.
+* A handler's sole capability is `ctx.emit`, which posts an existing Proteus
+* event back to the host to be re-dispatched. See `protocol.ts` for the message
+* shapes and `ScriptContext`.
+*
+* INVARIANT: script isolation depends on this worker holding no privileged
+* globals. We `new Function(...)` the document's source below, which is only
+* safe because there is nothing sensitive in scope. Do NOT add `importScripts`,
+* pass host capabilities in via `postMessage`, or expose any API to handler
+* scope — doing so turns `new Function` into an escape hatch.
+*/
+const WORKER_SCRIPT = `
+"use strict";
+
+const handlers = new Map();
+const watchers = [];
+const pendingEmits = new Map();
+let nextEmitId = 1;
+
+// Minimal JSON-pointer getter (same semantics as the host's getProteusValue).
+function getByPointer(data, path) {
+  if (!path || path === "/") return data;
+  const parts = path.replace(/^\\//, "").split("/");
+  let current = data;
+  for (const raw of parts) {
+    if (current == null) return undefined;
+    const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    current = current[key];
+  }
+  return current;
+}
+
+function register(name, fn) {
+  if (typeof name !== "string" || typeof fn !== "function") {
+    throw new Error("register(name, fn) requires a string name and a function");
+  }
+  handlers.set(name, fn);
+}
+
+function watch(path, fn) {
+  if (typeof path !== "string" || typeof fn !== "function") {
+    throw new Error("watch(path, fn) requires a string path and a function");
+  }
+  watchers.push({ fn, path });
+}
+
+// Evaluate one module's source in a scope that exposes \`register\` and \`watch\`.
+// Handlers are keyed by "moduleName:handlerName" via a per-module register
+// wrapper; watchers are collected globally (order = watch id).
+function loadModule(moduleName, source) {
+  const scopedRegister = (name, fn) => register(moduleName + ":" + name, fn);
+  // eslint-disable-next-line no-new-func
+  const factory = new Function("register", "watch", source);
+  factory(scopedRegister, watch);
+}
+
+function emit(event) {
+  const emitId = nextEmitId++;
+  return new Promise((resolve) => {
+    pendingEmits.set(emitId, resolve);
+    self.postMessage({ emitId, event, type: "emit" });
+  });
+}
+
+self.onmessage = async (e) => {
+  const msg = e.data;
+
+  if (msg.type === "init") {
+    for (const [moduleName, source] of Object.entries(msg.scripts ?? {})) {
+      try {
+        loadModule(moduleName, source);
+      } catch (err) {
+        // A broken module leaves its handlers unregistered; invokes for them
+        // surface a "not found" error at call time.
+      }
+    }
+    // Report watched paths so the host can edge-detect and drive runWatcher.
+    self.postMessage({ paths: watchers.map((w) => w.path), type: "watchers" });
+    return;
+  }
+
+  if (msg.type === "emitResult") {
+    const resolve = pendingEmits.get(msg.emitId);
+    if (resolve) {
+      pendingEmits.delete(msg.emitId);
+      resolve(msg.result);
+    }
+    return;
+  }
+
+  if (msg.type === "invoke") {
+    const { data, handler, invokeId, params } = msg;
+    const fn = handlers.get(handler);
+    if (!fn) {
+      self.postMessage({
+        error: 'No script handler registered for "' + handler + '"',
+        invokeId,
+        result: undefined,
+        type: "invokeResult",
+      });
+      return;
+    }
+    const ctx = {
+      emit,
+      getValue: (path) => getByPointer(data, path),
+    };
+    try {
+      const result = await fn(ctx, params ?? {});
+      self.postMessage({ invokeId, result, type: "invokeResult" });
+    } catch (err) {
+      self.postMessage({
+        error: err && err.message ? String(err.message) : String(err),
+        invokeId,
+        result: undefined,
+        type: "invokeResult",
+      });
+    }
+    return;
+  }
+
+  if (msg.type === "runWatcher") {
+    const { current, data, previous, watchId } = msg;
+    const watcher = watchers[watchId];
+    if (!watcher) {
+      return;
+    }
+    const ctx = {
+      emit,
+      getValue: (path) => getByPointer(data, path),
+    };
+    try {
+      // Fire-and-forget: watchers return nothing to any caller. Errors are
+      // swallowed to match the fail-silent default of the other ops.
+      await watcher.fn(ctx, current, previous);
+    } catch (err) {
+      // Intentionally ignored.
+    }
+  }
+};
+`;
+//#endregion
+export { WORKER_SCRIPT };

package/dist/esm/proteus-show/ProteusShow.js

@@ -1,14 +1,15 @@
 "use client";
 import { useProteusDocumentContext } from "../proteus-document/ProteusDocumentContext.js";
 import { useProteusDocumentPathContext } from "../proteus-document/ProteusDocumentPathContext.js";
+import { useProteusDataTableRowContext } from "../proteus-document/ProteusDataTableRowContext.js";
 import { evaluateCondition } from "../proteus-document/resolveProteusValue.js";
 import { Fragment, jsx } from "react/jsx-runtime";
 //#region src/proteus-show/ProteusShow.tsx
-function ProteusShow({ children, when }) {
+function ProteusShow({ children, else: fallback, when }) {
 	const { data } = useProteusDocumentContext("@optiaxiom/proteus/ProteusShow");
 	const { mapIndices, path: parentPath } = useProteusDocumentPathContext("@optiaxiom/proteus/ProteusShow");
-	if (!(Array.isArray(when) ? when : [when]).every((condition) => evaluateCondition(condition, data, parentPath, mapIndices))) return null;
-	return /* @__PURE__ */ jsx(Fragment, { children });
+	const { row: dataTableRow } = useProteusDataTableRowContext("@optiaxiom/proteus/ProteusShow");
+	return /* @__PURE__ */ jsx(Fragment, { children: (Array.isArray(when) ? when : [when]).every((condition) => evaluateCondition(condition, data, parentPath, mapIndices, dataTableRow)) ? children : fallback });
 }
 ProteusShow.displayName = "@optiaxiom/proteus/ProteusShow";
 //#endregion

package/dist/esm/schema/public-schema.js

@@ -921,6 +921,7 @@ var public_schema_default = {
 							{ "type": "number" },
 							{ "type": "boolean" },
 							{ "type": "null" },
+							{ "$ref": "#/definitions/ProteusDataTableRow" },
 							{ "$ref": "#/definitions/ProteusLength" },
 							{ "$ref": "#/definitions/ProteusMapIndex" },
 							{ "$ref": "#/definitions/ProteusValue" }
@@ -941,6 +942,7 @@ var public_schema_default = {
 							{ "type": "number" },
 							{ "type": "boolean" },
 							{ "type": "null" },
+							{ "$ref": "#/definitions/ProteusDataTableRow" },
 							{ "$ref": "#/definitions/ProteusLength" },
 							{ "$ref": "#/definitions/ProteusMapIndex" },
 							{ "$ref": "#/definitions/ProteusValue" }
@@ -961,6 +963,7 @@ var public_schema_default = {
 							{ "type": "number" },
 							{ "type": "boolean" },
 							{ "type": "null" },
+							{ "$ref": "#/definitions/ProteusDataTableRow" },
 							{ "$ref": "#/definitions/ProteusLength" },
 							{ "$ref": "#/definitions/ProteusMapIndex" },
 							{ "$ref": "#/definitions/ProteusValue" }
@@ -981,6 +984,7 @@ var public_schema_default = {
 							{ "type": "number" },
 							{ "type": "boolean" },
 							{ "type": "null" },
+							{ "$ref": "#/definitions/ProteusDataTableRow" },
 							{ "$ref": "#/definitions/ProteusLength" },
 							{ "$ref": "#/definitions/ProteusMapIndex" },
 							{ "$ref": "#/definitions/ProteusValue" }
@@ -1001,6 +1005,7 @@ var public_schema_default = {
 							{ "type": "number" },
 							{ "type": "boolean" },
 							{ "type": "null" },
+							{ "$ref": "#/definitions/ProteusDataTableRow" },
 							{ "$ref": "#/definitions/ProteusLength" },
 							{ "$ref": "#/definitions/ProteusMapIndex" },
 							{ "$ref": "#/definitions/ProteusValue" }
@@ -1021,6 +1026,7 @@ var public_schema_default = {
 							{ "type": "number" },
 							{ "type": "boolean" },
 							{ "type": "null" },
+							{ "$ref": "#/definitions/ProteusDataTableRow" },
 							{ "$ref": "#/definitions/ProteusLength" },
 							{ "$ref": "#/definitions/ProteusMapIndex" },
 							{ "$ref": "#/definitions/ProteusValue" }
@@ -1040,6 +1046,7 @@ var public_schema_default = {
 							{ "type": "number" },
 							{ "type": "boolean" },
 							{ "type": "null" },
+							{ "$ref": "#/definitions/ProteusDataTableRow" },
 							{ "$ref": "#/definitions/ProteusLength" },
 							{ "$ref": "#/definitions/ProteusMapIndex" },
 							{ "$ref": "#/definitions/ProteusValue" }
@@ -1057,6 +1064,7 @@ var public_schema_default = {
 							{ "type": "number" },
 							{ "type": "boolean" },
 							{ "type": "null" },
+							{ "$ref": "#/definitions/ProteusDataTableRow" },
 							{ "$ref": "#/definitions/ProteusLength" },
 							{ "$ref": "#/definitions/ProteusMapIndex" },
 							{ "$ref": "#/definitions/ProteusValue" }
@@ -1210,6 +1218,32 @@ var public_schema_default = {
 						"gap": "16"
 					}],
 					"title": "Create Test Plan"
+				},
+				{
+					"$type": "Document",
+					"actions": [{
+						"$type": "Action",
+						"appearance": "primary",
+						"children": "Greet",
+						"onClick": {
+							"params": { "name": {
+								"$type": "Value",
+								"path": "/name"
+							} },
+							"script": "main:greet"
+						}
+					}],
+					"appName": "Opal",
+					"body": [{
+						"$type": "Field",
+						"children": {
+							"$type": "Input",
+							"name": "name"
+						},
+						"label": "Your name"
+					}],
+					"scripts": { "main": "register('greet', (ctx) => ctx.emit({ message: `Hello, ${ctx.params.name}!` }))" },
+					"title": "Scripted Greeting"
 				}
 			],
 			"properties": {
@@ -1252,6 +1286,11 @@ var public_schema_default = {
 					"type": "object"
 				},
 				"meta": { "description": "Additional metadata not directly consumed by Proteus. Use this to pass along any extra data." },
+				"scripts": {
+					"additionalProperties": { "type": "string" },
+					"description": "Map of module name to JavaScript source. Each module runs in a sandboxed Web Worker and registers named handlers via `register(name, fn)`. Trigger a handler from any event source with `{ script: 'module:handler', params }`; handlers receive a single `ctx` ({ emit, getValue, params }) and can only affect the document by emitting the existing Proteus events through `ctx.emit`.",
+					"type": "object"
+				},
 				"subtitle": {
 					"$ref": "#/definitions/ProteusNode",
 					"description": "A brief description or tagline that provides additional context about the Proteus document's purpose."
@@ -1283,6 +1322,7 @@ var public_schema_default = {
 				{ "$ref": "#/definitions/ProteusChart" },
 				{ "$ref": "#/definitions/ProteusConcat" },
 				{ "$ref": "#/definitions/ProteusDataTable" },
+				{ "$ref": "#/definitions/ProteusDataTableRow" },
 				{ "$ref": "#/definitions/ProteusDateInput" },
 				{ "$ref": "#/definitions/ProteusDisclosure" },
 				{ "$ref": "#/definitions/ProteusDisclosureContent" },
@@ -1338,6 +1378,23 @@ var public_schema_default = {
 					"required": ["interaction"],
 					"type": "object"
 				},
+				{
+					"additionalProperties": false,
+					"description": "Scripted action - runs a named handler from the document's `scripts` map in a sandboxed Web Worker. The handler can emit the other Proteus events via `ctx.emit`.",
+					"properties": {
+						"params": {
+							"additionalProperties": {},
+							"description": "Parameters passed to the handler as `ctx.params`. Values can be ProteusExpressions that resolve at call time.",
+							"type": "object"
+						},
+						"script": {
+							"description": "Handler to run, addressed as `module:handler` (the module key comes from the document's `scripts` map).",
+							"type": "string"
+						}
+					},
+					"required": ["script"],
+					"type": "object"
+				},
 				{
 					"additionalProperties": false,
 					"description": "Client-side message action",
@@ -1441,12 +1498,31 @@ var public_schema_default = {
 					},
 					"required": ["action", "path"],
 					"type": "object"
+				},
+				{
+					"additionalProperties": false,
+					"description": "Runtime data operation - writes `value` at `path` in form data, replacing any existing value (e.g. `/tags/2`). Path resolves like `Value` (absolute `/x`, relative to current parentPath, or `''` for parentPath itself).",
+					"properties": {
+						"action": {
+							"const": "setValue",
+							"description": "The action type",
+							"type": "string"
+						},
+						"path": {
+							"description": "JSON pointer path to write to",
+							"type": "string"
+						},
+						"value": { "description": "The value to write; primitives or objects" }
+					},
+					"required": ["action", "path"],
+					"type": "object"
 				}
 			],
 			"description": "Handler for user interactions - a server-side interaction call, client-side message, or client-side component action"
 		},
 		"ProteusExpression": {
 			"anyOf": [
+				{ "$ref": "#/definitions/ProteusDataTableRow" },
 				{ "$ref": "#/definitions/ProteusLength" },
 				{ "$ref": "#/definitions/ProteusMap" },
 				{ "$ref": "#/definitions/ProteusMapIndex" },
@@ -2486,6 +2562,10 @@ var public_schema_default = {
 								"description": "Key in data objects",
 								"type": "string"
 							},
+							"cell": {
+								"$ref": "#/definitions/ProteusNode",
+								"description": "A Proteus node template rendered for each cell in this column. Read the current row with DataTableRow (e.g. { $type: 'DataTableRow', path: 'status' } reads the row's 'status', or omit 'path' for the whole row). Can be a single element or an array — use Show elements to conditionally render (e.g. a Badge whose intent depends on the row value). When set, takes precedence over 'format'."
+							},
 							"format": {
 								"anyOf": [{
 									"description": "Formatter name",
@@ -2528,6 +2608,22 @@ var public_schema_default = {
 			"required": ["$type"],
 			"type": "object"
 		},
+		"ProteusDataTableRow": {
+			"additionalProperties": false,
+			"examples": [{
+				"$type": "DataTableRow",
+				"path": "status"
+			}],
+			"properties": {
+				"$type": { "const": "DataTableRow" },
+				"path": {
+					"description": "JSON pointer path to a field within the current row (e.g. 'status' or '/status'). When omitted, resolves to the whole row object. Only meaningful inside a DataTable column's `cell`.",
+					"type": "string"
+				}
+			},
+			"required": ["$type"],
+			"type": "object"
+		},
 		"ProteusDateInput": {
 			"additionalProperties": false,
 			"examples": [{
@@ -4292,6 +4388,10 @@ var public_schema_default = {
 					"$ref": "#/definitions/ProteusNode",
 					"description": "Content to show when condition is true"
 				},
+				"else": {
+					"$ref": "#/definitions/ProteusNode",
+					"description": "Content to render when the condition is false. Omitting it renders nothing. Chain nested Show/else to express multi-way choices (e.g. mapping a value to one of several outputs)."
+				},
 				"when": {
 					"anyOf": [{ "$ref": "#/definitions/ProteusCondition" }, {
 						"items": { "$ref": "#/definitions/ProteusCondition" },