@persona/layout-editor-remote-module 0.0.0-bootstrap.0 → 0.5.0

package/README.md

@@ -0,0 +1,147 @@
+# @persona/layout-editor-remote-module
+
+Shared manifest format and Vite plugin for remotely-defined dashboard layout modules — used by
+app-builder Apps and `sa-*` subapps to declare a layout module directly in their own
+`vite.config.ts`, without editing persona-web.
+
+## Install
+
+```sh
+yarn add @persona/layout-editor-remote-module
+```
+
+`vite`, `esbuild`, and `zod` are peer dependencies. The plugin's dev-mode bundling uses `esbuild`
+directly, and declaring it as a peer means it resolves to the same copy `vite` already pulls in
+rather than a second version. With Yarn's `node-modules` linker the hoisted transitive copy usually
+satisfies it; add `esbuild` to your own `devDependencies` if your package manager warns about an
+unmet peer.
+
+The optional `react` and `react-dom` peer dependencies are required only when using the React bridge
+components.
+
+The package is published to the public npm registry.
+
+## Usage
+
+```ts
+// vite.config.ts
+import {
+  defineLayoutModule,
+  personaLayoutModules,
+} from '@persona/layout-editor-remote-module/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    personaLayoutModules({
+      modules: [
+        defineLayoutModule({
+          key: 'risk_summary',
+          displayName: 'Risk Summary',
+          descriptionShort: 'Show the account risk score',
+          allowAddingToLayout: true,
+          layouts: ['case'],
+          defaultSize: { case: { width: 4, height: 20 } },
+          // `.tsx`/`.js` — a `code` delivery, imported and rendered directly
+          // in the host's own React tree.
+          render: { entry: './src/layout-modules/risk-summary/render.tsx' },
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+An empty or omitted `layouts` makes the module available in every layout. When `layouts` lists
+specific layouts, `defaultSize` must provide an entry for each one.
+
+An `.html` entry (rather than `.tsx`/`.js`) is a `document` delivery instead — the host iframes it
+rather than importing anything. See `LayoutModuleEntry`'s doc comment in `src/define.ts` for the
+full contract, including the optional `path` field for a client-routed SPA.
+
+## Communicating with the host
+
+Document-delivered modules can use the browser bridge to receive layout data, report their height,
+and resolve data paths through the host. The host renders the document with `RemoteModuleFrame`:
+
+```tsx
+import { RemoteModuleFrame } from '@persona/layout-editor-remote-module/bridge-host';
+
+<RemoteModuleFrame
+  documentUrl={registration.document}
+  moduleOrigin={registration.origin}
+  title='Risk summary'
+  sandbox='allow-scripts allow-same-origin'
+  data={moduleData}
+  context={moduleContext}
+  dynamicHeight
+  resolveDataPath={resolveDataPath}
+/>;
+```
+
+The required `sandbox` value is chosen by the host.
+
+The document entry uses `LayoutModuleBridge` as a render-prop component:
+
+```tsx
+import { LayoutModuleBridge } from '@persona/layout-editor-remote-module/bridge-frame';
+
+<LayoutModuleBridge>
+  {({ data, context, resolveDataPath }) => (
+    <RiskSummary data={data} context={context} resolveDataPath={resolveDataPath} />
+  )}
+</LayoutModuleBridge>;
+```
+
+Alongside `data` (the module's persisted config), the host sends a typed `context` payload
+(`RemoteModuleContext`) describing where the module is rendered — facts the host owns and the module
+cannot derive itself:
+
+- `layoutType` — which layout kind the module is placed on (`account`, `case`, or `transaction`)
+- `layoutObjectId` — the ID of the object the layout is rendered for (e.g. the viewed case's ID on a
+  `case` layout), or `null` when there is none
+- `isReadOnly` — the host object is locked for edits
+- `isInEditor` — the module is rendered inside the layout editor rather than on a live record
+- `isUsingStubData` — the host is feeding placeholder/stub data instead of a real record
+
+`context` is sent with `init` and pushed again whenever it changes, just like `data`; inside the
+iframe it arrives through `ready()`, `getContext()`, and the `context` render prop (all
+`RemoteModuleContext | null` until init).
+
+The host still appends `access_token`, `environment_id`, and `locale` as query parameters. The
+builder app or `sa-*` subapp hosting the module consumes and strips those parameters itself, so by
+the time `LayoutModuleBridge` runs they have already been handled; the bridge neither reads nor
+strips them. Keep the host iframe's `referrerpolicy` at its default `no-referrer` (or use
+`strict-origin`) so the URL parameters cannot leak through subsequent requests.
+
+The bridge's security model is intentionally narrow:
+
+- The host sends only to the exact module origin and accepts messages only from that origin and
+  iframe window.
+- The iframe accepts only messages from its parent window and an allowed host origin, then pins the
+  first trusted origin for the lifetime of the bridge.
+- The iframe derives the ready target from `ancestorOrigins` or the referrer, and the host retries
+  `init` until the frame answers.
+- Messages use a strict, versioned protocol. Credentials remain in the iframe URL and are never
+  handled through bridge messages.
+- `extraParams` rejects reserved names and credential-like keys.
+
+### Consuming a manifest
+
+The plugin emits `{ modules: RemoteModuleRegistrationManifestV1[] }` at `manifestPath`. A host
+fetching that document should run it through `parseRemoteModuleManifest` — it validates the
+envelope, every module, and key uniqueness, and returns the typed document:
+
+```ts
+import {
+  parseRemoteModuleManifest,
+  RemoteModuleManifestParseError,
+} from '@persona/layout-editor-remote-module';
+
+const response = await fetch(`${appOrigin}/_layout_modules_manifest.json`);
+const { modules } = parseRemoteModuleManifest(await response.json());
+```
+
+It throws `RemoteModuleManifestParseError` (with `.issues` and a prettified `.message`) on a
+malformed document; `safeParseRemoteModuleManifest` returns `{ success, data | error }` instead of
+throwing.

package/dist/bridge-frame.d.mts

@@ -0,0 +1,45 @@
+import { n as Json, t as RemoteModuleContext } from "./protocol-edoRdXpF.mjs";
+import { ReactNode } from "react";
+
+//#region src/bridge/iframe/createModuleBridge.d.ts
+type ModuleBridgeInitPayload = {
+  data: Json;
+  context: RemoteModuleContext | null;
+};
+type CreateModuleBridgeOptions = {
+  allowedHostOrigins?: (string | RegExp)[] | ((origin: string) => boolean);
+  resolveTimeoutMs?: number;
+};
+type ModuleBridge = {
+  ready: () => Promise<ModuleBridgeInitPayload>;
+  getData: () => Json;
+  getContext: () => RemoteModuleContext | null;
+  subscribe: (listener: () => void) => () => void;
+  reportRenderError: (message: string) => void;
+  resolveDataPath: (dataPath: string, variableMap?: Record<string, string | number>) => Promise<Json>;
+  observeHeight: (element: Element) => () => void;
+  destroy: () => void;
+};
+//#endregion
+//#region src/bridge/iframe/LayoutModuleBridge.d.ts
+type LayoutModuleBridgeRenderProps = {
+  data: ReturnType<ModuleBridge['getData']>;
+  context: RemoteModuleContext | null;
+  resolveDataPath: ModuleBridge['resolveDataPath'];
+};
+type LayoutModuleBridgeProps = {
+  allowedHostOrigins?: CreateModuleBridgeOptions['allowedHostOrigins'];
+  resolveTimeoutMs?: number;
+  observeHeight?: boolean;
+  fallback?: ReactNode;
+  children: (props: LayoutModuleBridgeRenderProps) => ReactNode;
+};
+declare function LayoutModuleBridge({
+  allowedHostOrigins,
+  resolveTimeoutMs,
+  observeHeight,
+  fallback,
+  children
+}: LayoutModuleBridgeProps): ReactNode;
+//#endregion
+export { type Json, LayoutModuleBridge, type LayoutModuleBridgeProps, type LayoutModuleBridgeRenderProps, type RemoteModuleContext };

package/dist/bridge-frame.mjs

@@ -0,0 +1,350 @@
+import { c as resolveAllowedHostOrigins, n as SOURCE, o as candidateParentOrigin, r as parseHostToModuleMessage, s as personaDashboardHostOrigins, t as PROTOCOL_VERSION } from "./protocol-DMsysRFd.mjs";
+import { Component, useEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/bridge/rpc.ts
+var BridgeDestroyedError = class extends Error {
+	constructor(message = "Bridge has been destroyed") {
+		super(message);
+		this.name = "BridgeDestroyedError";
+	}
+};
+var BridgeTimeoutError = class extends Error {
+	constructor(message = "Bridge request timed out") {
+		super(message);
+		this.name = "BridgeTimeoutError";
+	}
+};
+function createRequestId() {
+	const cryptoApi = globalThis.crypto;
+	if (cryptoApi?.randomUUID) return cryptoApi.randomUUID();
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function createPendingRequests() {
+	const pending = /* @__PURE__ */ new Map();
+	return {
+		add(timeoutMs) {
+			const requestId = createRequestId();
+			return {
+				requestId,
+				promise: new Promise((resolve, reject) => {
+					const timer = setTimeout(() => {
+						pending.delete(requestId);
+						reject(new BridgeTimeoutError());
+					}, timeoutMs);
+					pending.set(requestId, {
+						resolve,
+						reject,
+						timer
+					});
+				})
+			};
+		},
+		settle(requestId, settlement) {
+			const request = pending.get(requestId);
+			if (!request) return false;
+			pending.delete(requestId);
+			clearTimeout(request.timer);
+			if ("error" in settlement) request.reject(settlement.error);
+			else request.resolve(settlement.result);
+			return true;
+		},
+		rejectAll(error) {
+			for (const [requestId, request] of pending) {
+				pending.delete(requestId);
+				clearTimeout(request.timer);
+				request.reject(error);
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/bridge/iframe/createModuleBridge.ts
+function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins, resolveTimeoutMs = 3e4 } = {}) {
+	const isEmbedded = typeof window !== "undefined" && window.parent !== window;
+	const allowedOrigin = resolveAllowedHostOrigins(allowedHostOrigins);
+	if (!isEmbedded) {
+		const notEmbeddedError = new BridgeDestroyedError("Bridge is not embedded");
+		return {
+			ready: async () => ({
+				data: null,
+				context: null
+			}),
+			getData: () => null,
+			getContext: () => null,
+			subscribe: () => () => {},
+			reportRenderError: () => {},
+			resolveDataPath: async () => {
+				throw notEmbeddedError;
+			},
+			observeHeight: () => () => {},
+			destroy: () => {}
+		};
+	}
+	let destroyed = false;
+	let hostOrigin;
+	let data = null;
+	let context = null;
+	let readyResolved = false;
+	const listeners = /* @__PURE__ */ new Set();
+	const observers = /* @__PURE__ */ new Set();
+	const pendingRequests = createPendingRequests();
+	const queuedRequests = /* @__PURE__ */ new Map();
+	let resolveReady;
+	let rejectReady;
+	const readyPromise = new Promise((resolve, reject) => {
+		resolveReady = resolve;
+		rejectReady = reject;
+	});
+	const post = (message) => {
+		if (hostOrigin) window.parent.postMessage(message, hostOrigin);
+	};
+	const flushQueuedRequests = () => {
+		if (!hostOrigin) return;
+		for (const [requestId, request] of queuedRequests) {
+			post({
+				source: SOURCE,
+				protocolVersion: PROTOCOL_VERSION,
+				type: "resolve-data-path",
+				requestId,
+				dataPath: request.dataPath,
+				...request.variableMap === void 0 ? {} : { variableMap: request.variableMap }
+			});
+			queuedRequests.delete(requestId);
+		}
+	};
+	const pinHostOrigin = (origin) => {
+		if (!allowedOrigin(origin)) return false;
+		if (hostOrigin !== void 0 && hostOrigin !== origin) return false;
+		hostOrigin = origin;
+		flushQueuedRequests();
+		return true;
+	};
+	const notify = () => {
+		for (const listener of listeners) listener();
+	};
+	const onMessage = (event) => {
+		if (destroyed || event.source !== window.parent) return;
+		const message = parseHostToModuleMessage(event.data);
+		if (!message || !pinHostOrigin(event.origin)) return;
+		switch (message.type) {
+			case "init":
+				data = message.data;
+				context = message.context;
+				notify();
+				if (!readyResolved) {
+					readyResolved = true;
+					resolveReady({
+						data,
+						context
+					});
+				}
+				break;
+			case "data":
+				data = message.data;
+				notify();
+				break;
+			case "context":
+				context = message.context;
+				notify();
+				break;
+			case "data-path-result":
+				if (message.error !== void 0) pendingRequests.settle(message.requestId, { error: new Error(message.error) });
+				else pendingRequests.settle(message.requestId, { result: message.result ?? null });
+				break;
+		}
+	};
+	window.addEventListener("message", onMessage);
+	const parentOrigin = candidateParentOrigin();
+	if (parentOrigin && allowedOrigin(parentOrigin)) window.parent.postMessage({
+		source: SOURCE,
+		protocolVersion: PROTOCOL_VERSION,
+		type: "ready"
+	}, parentOrigin);
+	return {
+		ready: () => readyPromise,
+		getData: () => data,
+		getContext: () => context,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		reportRenderError(message) {
+			post({
+				source: SOURCE,
+				protocolVersion: PROTOCOL_VERSION,
+				type: "render-error",
+				message
+			});
+		},
+		resolveDataPath(dataPath, variableMap) {
+			if (destroyed) return Promise.reject(new BridgeDestroyedError());
+			const { requestId, promise } = pendingRequests.add(resolveTimeoutMs);
+			queuedRequests.set(requestId, {
+				dataPath,
+				variableMap
+			});
+			flushQueuedRequests();
+			return promise;
+		},
+		observeHeight(element) {
+			if (destroyed || typeof ResizeObserver === "undefined") return () => {};
+			let lastHeight;
+			let frame;
+			let disconnected = false;
+			const postHeight = (height) => {
+				if (disconnected || height === lastHeight) return;
+				lastHeight = height;
+				post({
+					source: SOURCE,
+					protocolVersion: PROTOCOL_VERSION,
+					type: "set-height",
+					height
+				});
+			};
+			const observer = new ResizeObserver((entries) => {
+				const entry = entries[0];
+				if (!entry) return;
+				const borderBoxSize = entry.borderBoxSize;
+				const height = (Array.isArray(borderBoxSize) ? borderBoxSize[0]?.blockSize : void 0) ?? entry.contentRect.height;
+				if (frame !== void 0) return;
+				const callback = () => {
+					frame = void 0;
+					postHeight(height);
+				};
+				frame = typeof window.requestAnimationFrame === "function" ? window.requestAnimationFrame(callback) : window.setTimeout(callback, 0);
+			});
+			observers.add(observer);
+			observer.observe(element);
+			return () => {
+				disconnected = true;
+				if (frame !== void 0) {
+					window.cancelAnimationFrame?.(frame);
+					window.clearTimeout(frame);
+				}
+				observer.disconnect();
+				observers.delete(observer);
+			};
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			window.removeEventListener("message", onMessage);
+			for (const observer of observers) observer.disconnect();
+			observers.clear();
+			queuedRequests.clear();
+			const error = new BridgeDestroyedError();
+			pendingRequests.rejectAll(error);
+			if (!readyResolved) rejectReady(error);
+		}
+	};
+}
+
+//#endregion
+//#region src/bridge/iframe/useRemoteModuleBridge.ts
+const rejectNotReady = async () => {
+	throw new BridgeDestroyedError("Bridge is not ready");
+};
+function useRemoteModuleBridge(options = {}) {
+	const optionsRef = useRef(options);
+	const [bridge, setBridge] = useState(null);
+	const [ready, setReady] = useState(false);
+	const [data, setData] = useState(null);
+	const [context, setContext] = useState(null);
+	useEffect(() => {
+		let active = true;
+		const currentBridge = createModuleBridge(optionsRef.current);
+		setBridge(currentBridge);
+		setData(currentBridge.getData());
+		setContext(currentBridge.getContext());
+		const unsubscribe = currentBridge.subscribe(() => {
+			if (active) {
+				setData(currentBridge.getData());
+				setContext(currentBridge.getContext());
+			}
+		});
+		currentBridge.ready().then(({ data: initialData, context: initialContext }) => {
+			if (active) {
+				setData(initialData);
+				setContext(initialContext);
+				setReady(true);
+			}
+		}, () => {
+			if (active) setReady(false);
+		});
+		return () => {
+			active = false;
+			unsubscribe();
+			currentBridge.destroy();
+			setBridge(null);
+			setData(null);
+			setContext(null);
+			setReady(false);
+		};
+	}, []);
+	return {
+		bridge,
+		context,
+		data,
+		ready,
+		resolveDataPath: bridge?.resolveDataPath ?? rejectNotReady
+	};
+}
+
+//#endregion
+//#region src/bridge/iframe/LayoutModuleBridge.tsx
+let mountedBridgeCount = 0;
+function BridgeErrorContent({ render }) {
+	return render();
+}
+var BridgeErrorBoundary = class extends Component {
+	state = { error: null };
+	static getDerivedStateFromError(error) {
+		return { error };
+	}
+	componentDidCatch(error, _errorInfo) {
+		this.props.bridge.reportRenderError(error.message);
+	}
+	render() {
+		return this.state.error ? this.props.fallback : /* @__PURE__ */ jsx(BridgeErrorContent, { render: this.props.render });
+	}
+};
+function LayoutModuleBridge({ allowedHostOrigins, resolveTimeoutMs, observeHeight = true, fallback = null, children }) {
+	const { bridge, context, data, ready, resolveDataPath } = useRemoteModuleBridge({
+		allowedHostOrigins,
+		resolveTimeoutMs
+	});
+	const rootRef = useRef(null);
+	useEffect(() => {
+		mountedBridgeCount += 1;
+		if (typeof process !== "undefined" && mountedBridgeCount > 1) console.warn("Multiple LayoutModuleBridge instances are mounted in the same document; this is unsupported.");
+		return () => {
+			mountedBridgeCount -= 1;
+		};
+	}, []);
+	useEffect(() => {
+		if (!ready || !observeHeight || !rootRef.current || !bridge) return;
+		return bridge.observeHeight(rootRef.current);
+	}, [
+		bridge,
+		observeHeight,
+		ready
+	]);
+	if (!ready || !bridge) return fallback;
+	return /* @__PURE__ */ jsx(BridgeErrorBoundary, {
+		bridge,
+		fallback,
+		render: () => /* @__PURE__ */ jsx("div", {
+			ref: rootRef,
+			children: children({
+				context,
+				data,
+				resolveDataPath
+			})
+		})
+	});
+}
+
+//#endregion
+export { LayoutModuleBridge };

package/dist/bridge-host.d.mts

@@ -0,0 +1,61 @@
+import { n as Json, t as RemoteModuleContext } from "./protocol-edoRdXpF.mjs";
+import { CSSProperties, ReactNode } from "react";
+
+//#region src/bridge/host/buildModuleSrc.d.ts
+type BuildModuleSrcOptions = {
+  accessToken?: string;
+  environmentId?: string;
+  locale?: string;
+  extraParams?: Record<string, string>;
+};
+//#endregion
+//#region src/bridge/host/createHostBridge.d.ts
+type ResolveDataPath = (dataPath: string, variableMap?: Record<string, string | number>) => Promise<Json | undefined> | Json | undefined;
+//#endregion
+//#region src/bridge/host/RemoteModuleFrame.d.ts
+type RemoteModuleFrameProps = {
+  documentUrl: string;
+  moduleOrigin: string;
+  accessToken?: string;
+  environmentId?: string;
+  locale?: string;
+  extraParams?: BuildModuleSrcOptions['extraParams'];
+  title: string;
+  sandbox: string;
+  referrerPolicy?: ReferrerPolicy;
+  initRetryMs?: number;
+  initRetryTimeoutMs?: number;
+  dynamicHeight?: boolean;
+  heightOffset?: number;
+  minHeight?: number;
+  className?: string;
+  style?: CSSProperties;
+  data: Json;
+  context: RemoteModuleContext;
+  resolveDataPath: ResolveDataPath;
+  onRenderError?: (message: string) => void;
+};
+declare function RemoteModuleFrame({
+  documentUrl,
+  moduleOrigin,
+  accessToken,
+  environmentId,
+  locale,
+  extraParams,
+  title,
+  sandbox,
+  referrerPolicy,
+  initRetryMs,
+  initRetryTimeoutMs,
+  dynamicHeight,
+  heightOffset,
+  minHeight,
+  className,
+  style,
+  data,
+  context,
+  resolveDataPath,
+  onRenderError
+}: RemoteModuleFrameProps): ReactNode;
+//#endregion
+export { type Json, type RemoteModuleContext, RemoteModuleFrame, type RemoteModuleFrameProps, type ResolveDataPath };