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

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.2",
   "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: