@persona/layout-editor-remote-module 0.5.1 → 0.5.3

package/README.md

@@ -139,8 +139,11 @@ The bridge's security model is intentionally narrow:
   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.
+- Messages use a versioned protocol that stays compatible with frames built against older releases
+  (from the release after 0.5.1): receivers ignore message types they don't know and strip keys they
+  don't know, and fields are never removed, renamed or narrowed. `context.layoutType` and
+  `defaultConfig`'s `layoutType` can be layout types added later, so handle values you don't know.
+  Credentials remain in the iframe URL and are never handled through bridge messages.
 - `extraParams` rejects reserved names and credential-like keys.
 
 ### Consuming a manifest

package/dist/bridge-frame.d.mts

@@ -1,4 +1,4 @@
-import { n as Json, t as RemoteModuleContext } from "./protocol-edoRdXpF.mjs";
+import { n as Json, t as RemoteModuleContext } from "./protocol-BljV-Zhi.mjs";
 import { ReactNode } from "react";
 
 //#region src/bridge/origin.d.ts

package/dist/bridge-frame.mjs

@@ -1,4 +1,4 @@
-import { c as resolveAllowedHostOrigins, n as SOURCE, o as candidateParentOrigin, r as parseHostToModuleMessage, s as personaDashboardHostOrigins, t as PROTOCOL_VERSION } from "./protocol-Dz3ZX59L.mjs";
+import { c as resolveAllowedHostOrigins, n as SOURCE, o as candidateParentOrigin, r as parseHostToModuleMessage, s as personaDashboardHostOrigins, t as PROTOCOL_VERSION } from "./protocol-BgGlnuFn.mjs";
 import { Component, useEffect, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 

package/dist/bridge-host.d.mts

@@ -1,4 +1,4 @@
-import { n as Json, t as RemoteModuleContext } from "./protocol-edoRdXpF.mjs";
+import { n as Json, t as RemoteModuleContext } from "./protocol-BljV-Zhi.mjs";
 import { CSSProperties, ReactNode } from "react";
 
 //#region src/bridge/host/buildModuleSrc.d.ts

package/dist/bridge-host.mjs

@@ -1,4 +1,4 @@
-import { a as assertNotSelfOrigin, i as parseModuleToHostMessage, n as SOURCE, t as PROTOCOL_VERSION } from "./protocol-Dz3ZX59L.mjs";
+import { a as assertNotSelfOrigin, i as parseModuleToHostMessage, n as SOURCE, t as PROTOCOL_VERSION } from "./protocol-BgGlnuFn.mjs";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 

package/dist/{define-C-3P4CFz.d.mts → define-D0nvEX_B.d.mts}

@@ -95,7 +95,8 @@ type ModuleCategory = z.infer<typeof moduleCategorySchema>;
  * modules.
  */
 interface RemoteModuleDefaultConfigOptions {
-  layoutType: LayoutType;
+  /** Can be a layout type added after the module's release; handle values you don't know. */
+  layoutType: LayoutType | (string & {});
   position?: {
     x: number;
     y: number;

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as JsonSchemaObject, c as ModuleCategory, d as RemoteModuleExports, f as RemoteModuleRegistrationManifestV1, i as Json, l as RemoteModuleDefaultConfigOptions, m as remoteModuleRegistrationManifestV1Schema, n as LayoutModuleEntry, o as LayoutType, p as RemoteModuleRegistrationManifestV1Schema, r as defineLayoutModule, s as ModuleBadge, t as LayoutModuleDefinitionInput, u as RemoteModuleDelivery } from "./define-C-3P4CFz.mjs";
+import { a as JsonSchemaObject, c as ModuleCategory, d as RemoteModuleExports, f as RemoteModuleRegistrationManifestV1, i as Json, l as RemoteModuleDefaultConfigOptions, m as remoteModuleRegistrationManifestV1Schema, n as LayoutModuleEntry, o as LayoutType, p as RemoteModuleRegistrationManifestV1Schema, r as defineLayoutModule, s as ModuleBadge, t as LayoutModuleDefinitionInput, u as RemoteModuleDelivery } from "./define-D0nvEX_B.mjs";
 import { z } from "zod";
 
 //#region src/manifest-path.d.ts

package/dist/{protocol-Dz3ZX59L.mjs → protocol-BgGlnuFn.mjs}

@@ -122,41 +122,46 @@ const variableMapSchema = z.record(z.string(), z.union([z.string(), z.number()])
 const readySchema = z.object({
 	...envelopeSchema,
 	type: z.literal("ready")
-}).strict();
+});
 const requestDataSchema = z.object({
 	...envelopeSchema,
 	type: z.literal("request-data"),
 	requestId: requestIdSchema
-}).strict();
+});
 const setHeightSchema = z.object({
 	...envelopeSchema,
 	type: z.literal("set-height"),
 	height: z.number()
-}).strict();
+});
 const renderErrorSchema = z.object({
 	...envelopeSchema,
 	type: z.literal("render-error"),
 	message: z.string()
-}).strict();
+});
 const resolveDataPathSchema = z.object({
 	...envelopeSchema,
 	type: z.literal("resolve-data-path"),
 	requestId: requestIdSchema,
 	dataPath: z.string(),
 	variableMap: variableMapSchema.optional()
-}).strict();
+});
+/**
+* Accepts layout types added after this release, so a module should handle a `layoutType` it
+* doesn't know.
+*/
+const contextLayoutTypeSchema = z.union([layoutTypeSchema, z.string()]);
 /**
 * Runtime facts about where the module is rendered, owned by the host and not
 * derivable by the module itself. Distinct from `data`, which is the module's
 * persisted config.
 */
 const remoteModuleContextSchema = z.object({
-	layoutType: layoutTypeSchema,
+	layoutType: contextLayoutTypeSchema,
 	layoutObjectId: z.string().nullable(),
 	isReadOnly: z.boolean(),
 	isInEditor: z.boolean(),
 	isUsingStubData: z.boolean()
-}).strict();
+});
 const moduleToHostMessageSchema = z.discriminatedUnion("type", [
 	readySchema,
 	requestDataSchema,
@@ -169,25 +174,25 @@ const initSchema = z.object({
 	type: z.literal("init"),
 	data: jsonSchema,
 	context: remoteModuleContextSchema
-}).strict();
+});
 const dataSchema = z.object({
 	...envelopeSchema,
 	type: z.literal("data"),
 	requestId: requestIdSchema.optional(),
 	data: jsonSchema
-}).strict();
+});
 const contextSchema = z.object({
 	...envelopeSchema,
 	type: z.literal("context"),
 	context: remoteModuleContextSchema
-}).strict();
+});
 const dataPathResultSchema = z.object({
 	...envelopeSchema,
 	type: z.literal("data-path-result"),
 	requestId: requestIdSchema,
 	result: jsonSchema.optional(),
 	error: z.string().optional()
-}).strict().refine(({ result, error }) => result === void 0 !== (error === void 0));
+}).refine(({ result, error }) => result === void 0 !== (error === void 0));
 const hostToModuleMessageSchema = z.discriminatedUnion("type", [
 	initSchema,
 	dataSchema,

package/dist/{protocol-edoRdXpF.d.mts → protocol-BljV-Zhi.d.mts}

@@ -15,16 +15,12 @@ type JsonValue = Json;
  * persisted config.
  */
 declare const remoteModuleContextSchema: z.ZodObject<{
-  layoutType: z.ZodEnum<{
-    account: "account";
-    case: "case";
-    transaction: "transaction";
-  }>;
+  layoutType: z.ZodType<"account" | "case" | "transaction" | (string & {}), unknown, z.core.$ZodTypeInternals<"account" | "case" | "transaction" | (string & {}), unknown>>;
   layoutObjectId: z.ZodNullable<z.ZodString>;
   isReadOnly: z.ZodBoolean;
   isInEditor: z.ZodBoolean;
   isUsingStubData: z.ZodBoolean;
-}, z.core.$strict>;
+}, z.core.$strip>;
 type RemoteModuleContext = z.infer<typeof remoteModuleContextSchema>;
 //#endregion
 export { Json as n, RemoteModuleContext as t };

package/dist/vite-plugin.d.mts

@@ -1,4 +1,4 @@
-import { n as LayoutModuleEntry, r as defineLayoutModule, t as LayoutModuleDefinitionInput } from "./define-C-3P4CFz.mjs";
+import { n as LayoutModuleEntry, r as defineLayoutModule, t as LayoutModuleDefinitionInput } from "./define-D0nvEX_B.mjs";
 import { Plugin } from "vite";
 
 //#region src/vite-plugin.d.ts

package/dist/vite-plugin.mjs

@@ -135,15 +135,17 @@ function personaLayoutModules(options) {
 	let definitions = [];
 	return {
 		async closeBundle() {
-			if (definitions.length === 0 || resolvedConfig.command !== "build") return;
-			const outDir = path.isAbsolute(resolvedConfig.build.outDir) ? resolvedConfig.build.outDir : path.resolve(root, resolvedConfig.build.outDir);
+			const envConfig = this.environment?.config;
+			if (definitions.length === 0 || envConfig?.command !== "build") return;
+			if (envConfig.consumer !== "client") return;
+			const outDir = path.isAbsolute(envConfig.build.outDir) ? envConfig.build.outDir : path.resolve(root, envConfig.build.outDir);
 			const input = {};
 			for (const definition of definitions) if (definition.render.kind === "code") input[entryNameFor(definition)] = definition.render.absolutePath;
 			let emitted = [];
 			if (Object.keys(input).length > 0) {
 				const shimAlias = await ensureRemoteShimFiles();
 				const result = await build$1({
-					base: resolvedConfig.base,
+					base: envConfig.base,
 					build: {
 						emptyOutDir: false,
 						outDir,
@@ -159,14 +161,14 @@ function personaLayoutModules(options) {
 					mode: "production",
 					plugins: options.modulePlugins?.() ?? [],
 					resolve: { alias: {
-						...resolveAliasForEsbuild(resolvedConfig),
+						...resolveAliasForEsbuild(envConfig),
 						...shimAlias
 					} },
 					root
 				});
 				emitted = (Array.isArray(result) ? result : [result]).flatMap((output) => "output" in output ? output.output : []);
 			}
-			const base = resolvedConfig.base ?? "/";
+			const base = envConfig.base ?? "/";
 			const manifests = [];
 			for (const definition of definitions) {
 				const render = resolveManifestDelivery(definition, definition.render, emitted, root, base);
@@ -188,15 +190,18 @@ function personaLayoutModules(options) {
 			await mkdir(path.dirname(manifestFilePath), { recursive: true });
 			await writeFile(manifestFilePath, JSON.stringify({ modules: manifests }, null, 2), "utf8");
 		},
-		async config(config, env) {
+		async config(config) {
 			root = config.root ? path.resolve(config.root) : process.cwd();
 			definitions = options.modules.map((input) => ({
 				definitionFilePath: input.key,
 				input,
 				render: resolveEntry(root, input.render)
 			}));
+		},
+		configEnvironment(name, envConfig, env) {
 			if (env.command !== "build") return;
-			const existingInputs = absoluteInputPaths(config, root);
+			if ((envConfig.consumer ?? (name === "client" ? "client" : "server")) !== "client") return;
+			const existingInputs = absoluteInputPaths(envConfig, root);
 			const toInject = {};
 			for (const definition of definitions) {
 				const delivery = definition.render;
@@ -205,14 +210,10 @@ function personaLayoutModules(options) {
 					existingInputs.add(delivery.absolutePath);
 				}
 			}
-			if (Object.keys(toInject).length > 0) {
-				config.build ??= {};
-				config.build.rollupOptions ??= {};
-				config.build.rollupOptions.input = {
-					...toInputRecord(config.build.rollupOptions.input, root),
-					...toInject
-				};
-			}
+			if (Object.keys(toInject).length > 0) return { build: { rollupOptions: { input: {
+				...toInputRecord(envConfig.build?.rollupOptions?.input, root),
+				...toInject
+			} } } };
 		},
 		configResolved(config) {
 			resolvedConfig = config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persona/layout-editor-remote-module",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Shared manifest format, Vite plugin, and host/iframe bridge for remotely-defined dashboard layout modules in Persona dashboard apps.",
   "license": "SEE LICENSE",
   "type": "module",
@@ -41,7 +41,7 @@
     "esbuild": ">=0.21.0 <1",
     "react": "^17 || ^18 || ^19",
     "react-dom": "^17 || ^18 || ^19",
-    "vite": "^5 || ^6 || ^7 || ^8",
+    "vite": "^6 || ^7 || ^8",
     "zod": "^4.3"
   },
   "peerDependenciesMeta": {

package/skills/getting-started/SKILL.md

@@ -3,13 +3,14 @@ name: getting-started
 description: >
   Wire up @persona/layout-editor-remote-module in a Persona dashboard app: register
   personaLayoutModules in a typical app's vite.config.ts, author modules with defineLayoutModule
-  using a document (.html) render delivery, add a zod configSchema and an RJSF uiConfigSchema, and
-  talk to the host from the iframed document with LayoutModuleBridge from the bridge-frame entry
-  (layout data, host context such as layoutType / layoutObjectId / isReadOnly, resolveDataPath, and
-  height). Activate when adding a new layout module to an app, integrating this package for the
-  first time, wiring a module document to the dashboard host, or debugging a manifest that fails to
-  build or validate (duplicate key, missing defaultSize entry, render path not found) or a module
-  that never receives data from the host.
+  using a document (.html) render delivery, add a zod configSchema and an RJSF uiConfigSchema
+  (labels, field order, DataSourceField data-source pickers), and talk to the host from the iframed
+  document with LayoutModuleBridge from the bridge-frame entry (layout data, host context such as
+  layoutType / layoutObjectId / isReadOnly, resolveDataPath, and height). Activate when adding a new
+  layout module to an app, integrating this package for the first time, wiring a module document to
+  the dashboard host, or debugging a manifest that fails to build or validate (duplicate key,
+  missing defaultSize entry, render path not found) or a module that never receives data from the
+  host.
 metadata:
   type: core
   library: '@persona/layout-editor-remote-module'
@@ -123,9 +124,9 @@ as static JSON Schema, not re-executed as zod on the consuming side.
 
 ### `uiConfigSchema` — config panel layout
 
-The host renders the config panel with RJSF. Pass an RJSF `uiSchema` (widget choice, field order,
-labels) as `uiConfigSchema`; it is already plain data, so the plugin copies it into the manifest
-unchanged:
+The host renders the config panel with RJSF. Pass an RJSF `uiSchema` as `uiConfigSchema`; it is
+already plain data, so the plugin copies it into the manifest unchanged. Its top-level keys are the
+`configSchema` property names, and each one holds that property's `ui:*` entries:
 
 ```ts
 defineLayoutModule({
@@ -141,6 +142,104 @@ defineLayoutModule({
 });
 ```
 
+- **Labels and help text** come from the property's JSON Schema `title` / `description` — set them
+  with zod's `.meta({ title, description })` — and fall back to the property name. Override them per
+  field with `'ui:options': { title, description }`; the description shows as the label's tooltip.
+- **Field order** is `'ui:order'` at the top level (use `'*'` for "everything else").
+- **Controls are picked from the schema** without a `uiConfigSchema` entry: an enum renders as a
+  dropdown, an array of enum values with `uniqueItems: true` in its JSON Schema as a multi-select, a
+  boolean as a checkbox, and an array of objects as a list whose items open in an editing panel.
+- **Everything is JSON.** The manifest is static JSON, so function-valued RJSF options
+  (`createItem`, `itemLabel`, …) and custom React fields/widgets cannot be supplied by a module —
+  only the `ui:field` names and options the host already registers, listed below.
+
+#### `DataSourceField` — pick a value from the record
+
+`'ui:field': 'DataSourceField'` turns a property into the host's data-source input: an
+autocompleting method-chain input (e.g. `current_case.id`, or `query.<variable>` for a layout
+variable) checked against the platform schema. Declare the property as a **string** — the field then
+stores the chain itself as a string:
+
+```ts
+defineLayoutModule({
+  // ...
+  layouts: ['account'],
+  defaultSize: { account: { width: 6, height: 24 } },
+  configSchema: z.object({
+    accountId: z.string().optional(),
+  }),
+  uiConfigSchema: {
+    accountId: {
+      'ui:field': 'DataSourceField',
+      'ui:options': {
+        title: 'Account ID',
+        description: 'Account whose transactions are monitored',
+      },
+    },
+  },
+});
+```
+
+`ui:options` it reads:
+
+- `title`, `description` — label and tooltip; default to the schema's `title` / `description`.
+- `expectedSchemaType` — the platform object type the chain must resolve to (e.g. `'case'`,
+  `'user'`); a chain resolving to another type is flagged. Unset means any chain is accepted. An
+  empty value is never validated.
+- `rootPath` — limits validation to chains under one top-level property (e.g. `'current_case'`).
+  Only set it when `layouts` names a single layout that has that root; a chain outside `rootPath`
+  still saves but is not validated.
+
+The config holds the **chain, not its value**. Resolve it at render time with `resolveDataPath` from
+`LayoutModuleBridge` (below), skipping an unset field:
+
+```tsx
+import { useEffect, useState } from 'react';
+import {
+  type Json,
+  type LayoutModuleBridgeRenderProps,
+} from '@persona/layout-editor-remote-module/bridge-frame';
+
+function TransactionMonitor({
+  data,
+  resolveDataPath,
+}: Pick<LayoutModuleBridgeRenderProps, 'data' | 'resolveDataPath'>) {
+  const chain = (data as { accountId?: string } | null)?.accountId;
+  const [accountId, setAccountId] = useState<Json>(null);
+
+  useEffect(() => {
+    setAccountId(null);
+    if (!chain) return;
+    let current = true;
+    resolveDataPath(chain).then(
+      (value) => current && setAccountId(value),
+      () => current && setAccountId(null),
+    );
+    return () => {
+      current = false;
+    };
+  }, [chain, resolveDataPath]);
+
+  // ...
+}
+```
+
+The host pushes config updates into the mounted module, so the chain can change or be cleared at any
+time: reset the resolved value whenever it does, and ignore responses to an outdated chain.
+`resolveDataPath` resolves to `null` when the chain can't be resolved on the current record and
+rejects on a host error or timeout, so handle both.
+
+#### Other `ui:options`
+
+- `errorMessages` — per-keyword validation messages, e.g.
+  `{ 'ui:options': { errorMessages: { pattern: 'Use letters only.' } } }` (keys are JSON Schema
+  keywords: `pattern`, `minLength`, `maximum`, …).
+- On an enum multi-select: `unsetSelectsAll: true` shows an unset value as every option selected,
+  for a key whose absence means "all" and should stay absent.
+- On an array of objects: `identifierField` (item property that labels each row), `emptyText`,
+  `editLabel` (the editing panel's title), `listAriaLabel`, and `inlineItems: true` to render the
+  items inline instead of as a list with an editing panel.
+
 ### `bridge-frame` — talking to the host from the iframed document
 
 The host renders a document-delivered module in an iframe and speaks to it over `postMessage`. Wrap
@@ -279,6 +378,21 @@ resolve to `null` and `children` renders, so a stuck fallback is always a host/o
 
 Source: `src/bridge/iframe/createModuleBridge.ts`, `src/bridge/origin.ts`.
 
+### [HIGH] `DataSourceField` on a non-string property, or read as the resolved value
+
+Declare a `DataSourceField` property as `z.string()`. On a non-string property the host stores a
+structured data-source object instead of the chain string, and `resolveDataPath` only accepts a
+string — it resolves to `null`. On a string property the stored value is the method chain the user
+typed (e.g. `"current_account.id"`), not the account ID: pass `data.accountId` to `resolveDataPath`
+rather than using it directly.
+
+### [MEDIUM] A `ui:field` name the host doesn't register
+
+A `ui:field` name the host has no component for falls back to RJSF's default field for the
+property's type — no build or validation error, just a plain input instead of the intended control.
+Spell `'DataSourceField'` exactly; module-supplied field components are not possible (see
+"Everything is JSON" above).
+
 ### [HIGH] `key` uses the wrong charset or collides with another module
 
 Wrong: