@phis/ui 0.2.1 → 0.4.0

package/plugins/runtime-modules/builder/persistence.d.ts

@@ -1,7 +1,17 @@
+import type { PhiCmsContentWidgetNode, PhiCmsLayoutNode } from "../../../types/cms";
+import { type PhiCmsInstanceId } from "../../../types/cms-instance-id";
 import type { PhiDeveloperBuilderArea, PhiDeveloperBuilderRegionDraft, PhiDeveloperBuilderWorkspaceState } from "./developer-workspace-types";
+import type { PhiCmsWidgetContentBinding } from "../../../types/cms-plugins";
 import { type PhiPresetPageNode } from "../../../helpers/cms-page-catalog";
 import type { PhiCmsPresetSource } from "../../../types/cms-module-descriptors";
-import type { PhiBuilderPluginMeta } from "../../../types/builder";
+import type { PhiBuilderPluginMeta, PhiBuilderWidgetMeta } from "../../../types/builder";
+export type SerializedRoot = {
+    rootLayoutNodeId: PhiCmsInstanceId;
+    layoutNodes: PhiCmsLayoutNode[];
+    contentWidgets: Array<Omit<PhiCmsContentWidgetNode, "resolvedContent"> & {
+        contentBinding?: PhiCmsWidgetContentBinding | null;
+    }>;
+};
 export type PhiDeveloperBuilderWorkspaceKind = "structure" | "pages";
 /**
  * Creating a Page at a path a Page already holds. The server wrote nothing; the Builder opens the Page
@@ -13,6 +23,17 @@ export declare class PhiBuilderPageExistsError extends Error {
     readonly tombstoned: boolean;
     constructor(path: string, reference: string, tombstoned: boolean);
 }
+/**
+ * Where a widget's content binding comes from.
+ *
+ * `derive` asks the active Canvas metadata what this widget type binds, which is right for a tree the
+ * operator is editing: the answer follows the Widget's current definition rather than what was stored
+ * the last time. `carry` keeps whatever the node already holds and asks nothing -- right for a tree
+ * nobody is editing, and necessary for one: a Shell preset serialized outside a Canvas has no
+ * metadata to ask, and refusing there would mean refusing to store the Shell that already exists.
+ */
+export type PhiBuilderContentBindingSource = "derive" | "carry";
+export declare function serializePhiBuilderRootDraft(draft: PhiDeveloperBuilderRegionDraft, widgetMetasByType: ReadonlyMap<string, PhiBuilderWidgetMeta>, bindings?: PhiBuilderContentBindingSource): SerializedRoot;
 export declare function buildPhiBuilderLiveHref(area: PhiDeveloperBuilderArea, pageKey: string, pages: readonly PhiPresetPageNode[], workspaceKind: PhiDeveloperBuilderWorkspaceKind): string;
 export declare function clearPhiDeveloperBuilderDraftAllocation(input: {
     area: PhiDeveloperBuilderArea;
@@ -41,7 +62,6 @@ export declare function getPhiDeveloperBuilderModulesDraftAllocation(input: {
     nextNodeSequence: number;
     sourcePreset: PhiCmsPresetSource | null;
 } | null>;
-export declare function clearPhiDeveloperBuilderModulesDraftAllocation(area: PhiDeveloperBuilderArea): void;
 /**
  * Saves an Area's Module selection, apart from its structure.
  *
@@ -59,7 +79,7 @@ export declare function clearPhiDeveloperBuilderModulesDraftAllocation(area: Phi
  * already exists in code and that they were not going to change. The preset fills whatever the drafts
  * do not hold, and an open draft still wins where there is one.
  */
-export declare function savePhiDeveloperBuilderModulesDraft(state: Pick<PhiDeveloperBuilderWorkspaceState, "draftAllocations" | "runtimeModuleDefinitions" | "runtimeModuleIdsByArea" | "areaPresetSourcesByArea" | "publicRoutePaths" | "publicRouteClaims">, regionDrafts: Record<string, PhiDeveloperBuilderRegionDraft>, options: {
+export declare function savePhiDeveloperBuilderModulesDraft(state: Pick<PhiDeveloperBuilderWorkspaceState, "draftAllocations" | "runtimeModuleDefinitions" | "runtimeModuleIdsByArea" | "areaPresetSourcesByArea" | "publicRoutePaths" | "publicRouteClaims" | "areaControllerSettings">, regionDrafts: Record<string, PhiDeveloperBuilderRegionDraft>, options: {
     builderPlugins: readonly PhiBuilderPluginMeta[];
     scope: {
         area: PhiDeveloperBuilderArea;
@@ -72,7 +92,7 @@ export declare function savePhiDeveloperBuilderModulesDraft(state: Pick<PhiDevel
     nextNodeSequence: number;
 }>;
 /** Publishes the Area's Module selection. Its structure draft, if one is open, is left exactly as it is. */
-export declare function publishPhiDeveloperBuilderModulesDraft(state: Pick<PhiDeveloperBuilderWorkspaceState, "draftAllocations" | "runtimeModuleDefinitions" | "runtimeModuleIdsByArea" | "areaPresetSourcesByArea" | "publicRoutePaths" | "publicRouteClaims">, regionDrafts: Record<string, PhiDeveloperBuilderRegionDraft>, options: {
+export declare function publishPhiDeveloperBuilderModulesDraft(state: Pick<PhiDeveloperBuilderWorkspaceState, "draftAllocations" | "runtimeModuleDefinitions" | "runtimeModuleIdsByArea" | "areaPresetSourcesByArea" | "publicRoutePaths" | "publicRouteClaims" | "areaControllerSettings">, regionDrafts: Record<string, PhiDeveloperBuilderRegionDraft>, options: {
     builderPlugins: readonly PhiBuilderPluginMeta[];
     scope: {
         area: PhiDeveloperBuilderArea;
@@ -82,12 +102,7 @@ export declare function publishPhiDeveloperBuilderModulesDraft(state: Pick<PhiDe
     version: number;
     nextNodeSequence: number;
 }>;
-/** Discards the Area's Module draft, leaving its structure draft, if any, untouched. */
-export declare function discardPhiDeveloperBuilderModulesDraft(input: {
-    area: PhiDeveloperBuilderArea;
-    areaPresetSource: PhiCmsPresetSource | null;
-}): Promise<void>;
-export declare function savePhiDeveloperBuilderDraft(state: Pick<PhiDeveloperBuilderWorkspaceState, "area" | "pageKey" | "sidebarKey" | "pageMetaDrafts" | "deletedPageDrafts" | "draftAllocations" | "modulePresetPagesByArea" | "customPages" | "persistedPageCatalogByArea" | "areaPresetSourcesByArea" | "areaRootRouteDrafts" | "areaRootRoutes" | "areaMetaDrafts" | "areaMeta">, regionDrafts: Record<string, PhiDeveloperBuilderRegionDraft>, workspaceKind: PhiDeveloperBuilderWorkspaceKind, options: {
+export declare function savePhiDeveloperBuilderDraft(state: Pick<PhiDeveloperBuilderWorkspaceState, "area" | "pageKey" | "sidebarKey" | "pageMetaDrafts" | "deletedPageDrafts" | "draftAllocations" | "modulePresetPagesByArea" | "customPages" | "persistedPageCatalogByArea" | "areaPresetSourcesByArea" | "areaRootRouteDrafts" | "areaRootRoutes" | "areaMetaDrafts" | "areaMeta" | "areaControllerSettings" | "pageControllerSettings">, regionDrafts: Record<string, PhiDeveloperBuilderRegionDraft>, workspaceKind: PhiDeveloperBuilderWorkspaceKind, options: {
     builderPlugins: readonly PhiBuilderPluginMeta[];
     pathname?: string | null;
     scope?: {
@@ -130,7 +145,7 @@ export declare function previewPhiDeveloperBuilderDraft(state: Pick<PhiDeveloper
     revisionId: number;
     previewHref: string;
 }>;
-export declare function publishPhiDeveloperBuilderDraft(state: Pick<PhiDeveloperBuilderWorkspaceState, "area" | "pageKey" | "sidebarKey" | "pageMetaDrafts" | "deletedPageDrafts" | "draftAllocations" | "runtimeModuleDefinitions" | "runtimeModuleIdsByArea" | "modulePresetPagesByArea" | "customPages" | "persistedPageCatalogByArea" | "areaPresetSourcesByArea" | "areaRootRouteDrafts" | "areaRootRoutes" | "areaMetaDrafts" | "areaMeta">, regionDrafts: Record<string, PhiDeveloperBuilderRegionDraft>, workspaceKind: PhiDeveloperBuilderWorkspaceKind, options: {
+export declare function publishPhiDeveloperBuilderDraft(state: Pick<PhiDeveloperBuilderWorkspaceState, "area" | "pageKey" | "sidebarKey" | "pageMetaDrafts" | "deletedPageDrafts" | "draftAllocations" | "runtimeModuleDefinitions" | "runtimeModuleIdsByArea" | "modulePresetPagesByArea" | "customPages" | "persistedPageCatalogByArea" | "areaPresetSourcesByArea" | "areaRootRouteDrafts" | "areaRootRoutes" | "areaMetaDrafts" | "areaMeta" | "areaControllerSettings" | "pageControllerSettings">, regionDrafts: Record<string, PhiDeveloperBuilderRegionDraft>, workspaceKind: PhiDeveloperBuilderWorkspaceKind, options: {
     builderPlugins: readonly PhiBuilderPluginMeta[];
     pathname?: string | null;
     scope?: {

package/plugins/runtime-modules/builder/persistence.js

@@ -5,12 +5,11 @@ import { PhiCmsFlags, PhiCmsStatus } from "../../../constants/phi-cms";
 import { readPhiCmsInstanceId } from "../../../types/cms-instance-id";
 import { getPhiBuilderRegionDraftKey, PHI_BUILDER_PAGE_REGION_KEYS, PHI_BUILDER_SHELL_REGION_KEYS, } from "./region-keys";
 import { getPhiBuilderDefaultRegionDraft } from "./region-defaults";
-import { buildPhiBuilderRootNodeRenderConfig, normalizePhiBuilderRootNodeDraft, readPhiBuilderRootNodeDraftFields, } from "./root-node-normalization";
 import { serializePhiDeveloperBuilderRegionConfig } from "./region-hydration";
 import { stripPhiResolvedAssetProjections } from "../../../components/media/image-presentation";
 import { resolvePhiBuilderCmsStoragePath } from "../../../helpers/cms-paths";
+import { resolvePhiCmsWidgetContentBindingForConfig } from "../../../helpers/cms-content-binding";
 import { resolvePhiCmsRegionType } from "../../../helpers/cms-region-keys";
-import { deleteCmsDraft } from "../../../helpers/cms-draft-delete";
 import { resolvePhiAuthUiProviderModuleId, resolvePhiDeclaredMediaSpaces, resolvePhiDeclaredSeeds, resolvePhiDeclaredThreadKinds, resolvePhiRuntimeModuleIdsForArea, } from "../../../plugins/runtime-modules/settings";
 import { isPhiRuntimeAreaBaseModuleId } from "../../../plugins/runtime-modules/area-definitions";
 import { createPhiBuilderDraftAllocationKey } from "./draft-allocation-key";
@@ -84,12 +83,8 @@ function collectDraftNodeIds(draft) {
             pushId(childWidget.id);
         }
     };
-    pushId(draft.rootNodeId);
-    for (const childLayout of draft.rootNodeChildLayouts ?? []) {
-        visitLayout(childLayout);
-    }
-    for (const childWidget of draft.rootNodeChildWidgets ?? []) {
-        pushId(childWidget.id);
+    if (draft.rootNode) {
+        visitLayout(draft.rootNode);
     }
     return ids;
 }
@@ -104,10 +99,6 @@ function assertUniqueDraftNodeIds(drafts) {
         }
     }
 }
-function hasPersistedConfigValue(config, fieldKey) {
-    const value = config?.[fieldKey];
-    return typeof value === "string" ? value.trim().length > 0 : value != null;
-}
 function buildPhiBuilderWidgetMetaMap(pluginMetas) {
     return new Map(pluginMetas
         .filter((meta) => meta.kind === "widget")
@@ -118,21 +109,11 @@ function resolvePhiCmsWidgetContentBinding(widgetMetasByType, widgetType, config
     if (!meta) {
         throw new Error(`Active Canvas module metadata does not provide widget type "${widgetType}".`);
     }
-    const binding = meta.contentBinding ?? null;
-    if (!binding) {
-        return null;
-    }
-    if (binding.skipWhenConfigField && hasPersistedConfigValue(config, binding.skipWhenConfigField)) {
-        return null;
-    }
-    if (binding.skipWhenConfigFieldValue &&
-        config?.[binding.skipWhenConfigFieldValue.field] === binding.skipWhenConfigFieldValue.value) {
-        return null;
-    }
-    return binding;
+    return resolvePhiCmsWidgetContentBindingForConfig(meta.contentBinding, config);
 }
-function serializeRootDraft(draft, widgetMetasByType, bindings = "derive") {
-    if (!draft.rootNodeTypeKey || !draft.rootNodeKind || draft.rootNodeKind === "widget") {
+export function serializePhiBuilderRootDraft(draft, widgetMetasByType, bindings = "derive") {
+    const rootNode = draft.rootNode;
+    if (!rootNode) {
         throw new Error("CMS persistence requires a layout root node.");
     }
     const layoutNodes = [];
@@ -176,36 +157,18 @@ function serializeRootDraft(draft, widgetMetasByType, bindings = "derive") {
         }
         return inputId;
     }
-    const normalizedRootNode = normalizePhiBuilderRootNodeDraft({
-        id: draft.rootNodeId ?? null,
-        typeKey: draft.rootNodeTypeKey,
-        kind: draft.rootNodeKind,
-        packageName: draft.rootNodePackageName ?? null,
-        ...readPhiBuilderRootNodeDraftFields(draft),
-    });
-    const rootLayoutNodeId = readPersistableNodeId(draft.rootNodeId);
+    const rootLayoutNodeId = readPersistableNodeId(rootNode.id);
     if (rootLayoutNodeId == null) {
         throw new Error("CMS persistence requires a canonical root instance id.");
     }
-    layoutNodes.push({
+    // The root Layout is stored like every Layout below it; only its place in the Region is fixed.
+    serializeLayout({
+        ...rootNode,
         id: rootLayoutNodeId,
-        siteId: -1,
-        parentLayoutNodeId: null,
-        widgetType: normalizedRootNode.typeKey,
         slotIndex: 0,
         sortOrder: 0,
-        status: 0,
-        flags: 0,
-        visibilityMask: 0,
-        label: normalizedRootNode.title ?? "Root",
-        config: stripTransientConfig(buildPhiBuilderRootNodeRenderConfig(normalizedRootNode, "editor")),
-    });
-    for (const childLayout of normalizedRootNode.childLayouts ?? []) {
-        serializeLayout(childLayout, rootLayoutNodeId);
-    }
-    for (const childWidget of normalizedRootNode.childWidgets ?? []) {
-        serializeWidget(childWidget, rootLayoutNodeId);
-    }
+        label: rootNode.label ?? "Root",
+    }, null);
     return {
         rootLayoutNodeId,
         layoutNodes,
@@ -403,7 +366,7 @@ export async function getPhiDeveloperBuilderModulesDraftAllocation(input) {
     storePhiDeveloperBuilderDraftAllocation(allocationKey, draft);
     return draft;
 }
-export function clearPhiDeveloperBuilderModulesDraftAllocation(area) {
+function clearPhiDeveloperBuilderModulesDraftAllocation(area) {
     const allocationKey = createPhiBuilderDraftAllocationKey(area, area, "modules");
     builderWorkspaceStore.patch("public", (current) => {
         if (!current.draftAllocations[allocationKey]) {
@@ -414,6 +377,18 @@ export function clearPhiDeveloperBuilderModulesDraftAllocation(area) {
         return { ...current, draftAllocations };
     });
 }
+/**
+ * What a tree tells its Controllers, as it arrived with the workspace. The Builder edits none of it but
+ * every save states the tree whole, so a scope whose settings never arrived is not saved at all: sending
+ * none would erase what the stored tree or the Module's preset said.
+ */
+function requirePhiBuilderControllerSettings(settingsByKey, key, label) {
+    const settings = settingsByKey[key];
+    if (!settings) {
+        throw new Error(`${label} cannot be saved before its Controller settings have loaded.`);
+    }
+    return settings;
+}
 /**
  * Saves an Area's Module selection, apart from its structure.
  *
@@ -515,6 +490,7 @@ export async function savePhiDeveloperBuilderModulesDraft(state, regionDrafts, o
                 overlays: structurePayload.overlays,
                 layoutNodes: structurePayload.layoutNodes,
                 contentWidgets: structurePayload.contentWidgets,
+                controllerSettings: requirePhiBuilderControllerSettings(state.areaControllerSettings, area, `Area "${area}"`),
             },
         });
     }
@@ -538,15 +514,6 @@ export async function publishPhiDeveloperBuilderModulesDraft(state, regionDrafts
     clearPhiDeveloperBuilderModulesDraftAllocation(area);
     return saved;
 }
-/** Discards the Area's Module draft, leaving its structure draft, if any, untouched. */
-export async function discardPhiDeveloperBuilderModulesDraft(input) {
-    await deleteCmsDraft("/api/site/cms/area/modules", {
-        area: resolvePhiBuilderAreaAsCmsArea(input.area),
-        ownerModuleId: input.areaPresetSource?.ownerModuleId ?? "",
-        presetKey: input.areaPresetSource?.presetKey ?? "",
-    });
-    clearPhiDeveloperBuilderModulesDraftAllocation(input.area);
-}
 /**
  * Serializes an Area's Shell drafts into the shape a write payload carries -- regions, layout nodes,
  * content widgets. Nothing here touches `preset.config`: `config.modules` belongs to the Module
@@ -568,12 +535,12 @@ function buildAreaStructureWritePayload(area, regionDrafts, widgetMetasByType, b
     if (allAreaDrafts.length !== PHI_BUILDER_SHELL_REGION_KEYS.length) {
         throw new Error("Area preset save needs all area region drafts loaded to avoid deleting unchanged shell regions.");
     }
-    const areaDraftEntries = allAreaDrafts.filter((entry) => entry[1].rootNodeTypeKey != null);
+    const areaDraftEntries = allAreaDrafts.filter((entry) => entry[1].rootNode != null);
     const layoutNodes = [];
     const contentWidgets = [];
     assertUniqueDraftNodeIds(areaDraftEntries.map(([, draft]) => draft));
     const regions = areaDraftEntries.map(([regionKey, draft], index) => {
-        const serializedRegion = serializeRootDraft(draft, widgetMetasByType, bindings);
+        const serializedRegion = serializePhiBuilderRootDraft(draft, widgetMetasByType, bindings);
         layoutNodes.push(...serializedRegion.layoutNodes);
         contentWidgets.push(...serializedRegion.contentWidgets);
         return {
@@ -653,7 +620,7 @@ export async function savePhiDeveloperBuilderDraft(state, regionDrafts, workspac
         .map((regionKey) => [regionKey, regionDrafts[getPhiBuilderRegionDraftKey(area, regionKey, pageKey)] ?? null])
         .filter((entry) => entry[1] != null);
     const pageDraftEntries = allPageDraftEntries
-        .filter((entry) => entry[1]?.rootNodeTypeKey != null);
+        .filter((entry) => entry[1]?.rootNode != null);
     let savedScopes = 0;
     let revisionId = null;
     let savedDraftState = null;
@@ -681,6 +648,8 @@ export async function savePhiDeveloperBuilderDraft(state, regionDrafts, workspac
             overlays: [],
             layoutNodes: [],
             contentWidgets: [],
+            // A deleted Page runs nothing, so it tells nothing anything.
+            controllerSettings: [],
         });
         storePhiDeveloperBuilderDraftAllocation(allocationKey, result);
         savedDraftState = result;
@@ -697,7 +666,7 @@ export async function savePhiDeveloperBuilderDraft(state, regionDrafts, workspac
         ]));
         assertUniqueDraftNodeIds(pageDraftEntries.map(([, draft]) => draft));
         for (const [regionKey, draft] of pageDraftEntries) {
-            const serializedRegion = serializeRootDraft(draft, widgetMetasByType);
+            const serializedRegion = serializePhiBuilderRootDraft(draft, widgetMetasByType);
             pageRootIds[regionKey] = serializedRegion.rootLayoutNodeId;
             layoutNodes.push(...serializedRegion.layoutNodes);
             contentWidgets.push(...serializedRegion.contentWidgets);
@@ -725,6 +694,7 @@ export async function savePhiDeveloperBuilderDraft(state, regionDrafts, workspac
             overlays: [],
             layoutNodes,
             contentWidgets,
+            controllerSettings: requirePhiBuilderControllerSettings(state.pageControllerSettings, getPhiBuilderRegionDraftKey(area, "page_meta", pageKey), `Page "${pageKey}"`),
         });
         storePhiDeveloperBuilderDraftAllocation(allocationKey, result);
         savedDraftState = result;
@@ -768,6 +738,7 @@ export async function savePhiDeveloperBuilderDraft(state, regionDrafts, workspac
                 overlays: structurePayload.overlays,
                 layoutNodes: structurePayload.layoutNodes,
                 contentWidgets: structurePayload.contentWidgets,
+                controllerSettings: requirePhiBuilderControllerSettings(state.areaControllerSettings, area, `Area "${area}"`),
             });
             storePhiDeveloperBuilderDraftAllocation(allocationKey, result);
             /*
@@ -804,20 +775,7 @@ export function createPhiDeveloperBuilderInitialPageDrafts(input) {
     for (const regionKey of PHI_BUILDER_PAGE_REGION_KEYS) {
         drafts[getPhiBuilderRegionDraftKey(input.area, regionKey, input.pageKey)] = {
             ...getPhiBuilderDefaultRegionDraft(regionKey),
-            rootNodeId: null,
-            rootNodeTypeKey: null,
-            rootNodeKind: null,
-            rootNodeTitle: null,
-            rootNodePackageName: null,
-            rootNodeConfig: null,
-            rootNodeGeometry: null,
-            rootNodeAnchor: null,
-            rootNodePadding: null,
-            rootNodeBackground: null,
-            rootNodeBorder: null,
-            rootNodeShadow: null,
-            rootNodeChildLayouts: [],
-            rootNodeChildWidgets: [],
+            rootNode: null,
         };
     }
     return drafts;
@@ -856,6 +814,8 @@ export async function createPhiDeveloperBuilderPageDraft(input) {
         overlays: [],
         layoutNodes: [],
         contentWidgets: [],
+        // A Page somebody just made has no Controllers to tell anything yet.
+        controllerSettings: [],
     });
     storePhiDeveloperBuilderDraftAllocation(createPhiBuilderDraftAllocationKey(input.area, input.pageKey, "page"), result);
     return {

package/plugins/runtime-modules/builder/plugin-meta-labels.js

@@ -36,7 +36,16 @@ function mapPhiConfigFieldText(field, mapText) {
         ...field,
         label: mapOptionalText(field.label, mapText) ?? field.label,
         ...(field.description == null ? {} : { description: mapOptionalText(field.description, mapText) }),
+        ...(field.heading == null ? {} : { heading: mapOptionalText(field.heading, mapText) }),
     };
+    if (mapped.type === "choice" && mapped.valueType === "number") {
+        return {
+            ...mapped,
+            options: mapped.options.map((option) => mapPhiControlOptionText(option, mapText)),
+            ...(mapped.emptyOption == null ? {} : { emptyOption: mapPhiControlOptionText(mapped.emptyOption, mapText) }),
+            ...(mapped.placeholder == null ? {} : { placeholder: mapOptionalText(mapped.placeholder, mapText) }),
+        };
+    }
     if (mapped.type === "choice") {
         return {
             ...mapped,
@@ -51,6 +60,7 @@ function mapPhiConfigFieldText(field, mapText) {
             itemFields: mapped.itemFields.map((itemField) => mapPhiConfigFieldText(itemField, mapText)),
             ...(mapped.addLabel == null ? {} : { addLabel: mapOptionalText(mapped.addLabel, mapText) }),
             ...(mapped.emptyLabel == null ? {} : { emptyLabel: mapOptionalText(mapped.emptyLabel, mapText) }),
+            ...(mapped.editLabel == null ? {} : { editLabel: mapOptionalText(mapped.editLabel, mapText) }),
         };
     }
     return mapped;

package/plugins/runtime-modules/builder/plugin-meta-labels.server.d.ts

@@ -1,4 +1,19 @@
 import "server-only";
 import type { PhiBlockRuntime } from "../../../types/widget-runtime";
 import type { PhiBuilderModuleAuthoringCatalogEntry } from "./module-authoring-catalog";
+/**
+ * The authoring catalog in the language the Builder is being used in.
+ *
+ * The catalog crosses to the Client once, as a prop, and everything the Inspector shows about a
+ * plugin comes out of it -- so this is the one place the words can be turned, and turning them here
+ * costs one round trip for a whole Area's worth of plugins.
+ *
+ * It is a bulk translation rather than a label set on purpose. A label set needs every string written
+ * down in advance under a key, which works for a Control we ship and cannot work for a field an
+ * outside Module declares. The same reasoning already governs Module titles next door.
+ *
+ * Nothing is kept here between requests. `trBulk` keeps every answer in the translation cache, which a
+ * translation write empties in every process (gateway/CACHES.md); a map of its own beside it kept the
+ * old words until the process restarted.
+ */
 export declare function localizePhiBuilderModuleAuthoringCatalog(runtime: Pick<PhiBlockRuntime, "locale">, entries: readonly PhiBuilderModuleAuthoringCatalogEntry[]): Promise<PhiBuilderModuleAuthoringCatalogEntry[]>;

package/plugins/runtime-modules/builder/plugin-meta-labels.server.js

@@ -1,7 +1,9 @@
 import "server-only";
 import { PHI_TR_CTX_WEB_UI_LABEL, createGlobalTranslator } from "../../../gateway/tr";
 import { readPhiServerApiCredentials } from "../../../helpers/phis-server-credentials";
+import { logRuntimeEvent } from "../../../net/log";
 import { mapPhiBuilderPluginMetaText } from "./plugin-meta-labels";
+import { PHI_CANONICAL_SOURCE_LOCALE, isPhiLocaleReadableAsSource, resolvePhiTranslationLocale, } from "../../../helpers/locale";
 /**
  * The authoring catalog in the language the Builder is being used in.
  *
@@ -12,54 +14,80 @@ import { mapPhiBuilderPluginMetaText } from "./plugin-meta-labels";
  * It is a bulk translation rather than a label set on purpose. A label set needs every string written
  * down in advance under a key, which works for a Control we ship and cannot work for a field an
  * outside Module declares. The same reasoning already governs Module titles next door.
+ *
+ * Nothing is kept here between requests. `trBulk` keeps every answer in the translation cache, which a
+ * translation write empties in every process (gateway/CACHES.md); a map of its own beside it kept the
+ * old words until the process restarted.
  */
-const PLUGIN_TEXT_CACHE = new Map();
-function resolveLocaleCache(locale) {
-    const key = locale.trim().toLowerCase();
-    const cached = PLUGIN_TEXT_CACHE.get(key);
-    if (cached) {
-        return cached;
-    }
-    const created = new Map();
-    PLUGIN_TEXT_CACHE.set(key, created);
-    return created;
-}
 export async function localizePhiBuilderModuleAuthoringCatalog(runtime, entries) {
     const locale = runtime.locale.current;
-    const translations = resolveLocaleCache(locale);
+    const targetLocale = resolvePhiTranslationLocale(locale);
+    /* Keyed by source locale and text: "Titel" written in German is not the same unit as an English one. */
+    const translations = new Map();
+    const translationKey = (sourceLocale, text) => `${sourceLocale}\u0000${text}`;
     /*
      * The same walk twice: once to learn what is there, once to put the answers back. Collected into a
-     * set, so "Padding" -- which nearly every Layout declares -- is asked for once and not twelve
-     * times, and so the second walk looks its answer up by the text itself rather than by a position
-     * the two walks would have to agree on.
+     * set per source locale, so "Padding" -- which nearly every Layout declares -- is asked for once and
+     * not twelve times, and so the second walk looks its answer up by the text itself rather than by a
+     * position the two walks would have to agree on.
+     *
+     * Grouped by the Module's source locale, because a Module that is not ours may write its fields in
+     * its own language (TRANSLATIONS.md, "Runtime Module metadata"). Every Module of ours writes English,
+     * the canonical source, and is asked for exactly as before: without a source locale, so the units
+     * its texts are keyed by stay the ones they always were.
      */
-    const pending = new Set();
+    const pendingBySourceLocale = new Map();
     for (const entry of entries) {
+        const sourceLocale = resolvePhiTranslationLocale(entry.sourceLocale);
+        /* A reader of the Module's own language reads its words as written. */
+        if (isPhiLocaleReadableAsSource(targetLocale, sourceLocale))
+            continue;
+        const pending = pendingBySourceLocale.get(sourceLocale) ?? new Set();
         for (const plugin of entry.plugins) {
             mapPhiBuilderPluginMetaText(plugin, (text) => {
-                if (!translations.has(text)) {
-                    pending.add(text);
-                }
+                pending.add(text);
                 return text;
             });
         }
+        pendingBySourceLocale.set(sourceLocale, pending);
     }
-    if (pending.size > 0) {
+    await Promise.all([...pendingBySourceLocale].map(async ([sourceLocale, pending]) => {
+        if (pending.size === 0)
+            return;
         const sources = [...pending];
         const translator = createGlobalTranslator({
             apiBaseUrl: readPhiServerApiCredentials().apiBaseUrl,
             internalToken: readPhiServerApiCredentials().internalToken,
             locale,
+            ...(sourceLocale === PHI_CANONICAL_SOURCE_LOCALE ? {} : { sourceLocale }),
         });
-        const translated = await translator
-            .trBulk(sources, PHI_TR_CTX_WEB_UI_LABEL)
-            .catch(() => sources);
-        sources.forEach((source, index) => {
-            translations.set(source, translated[index] ?? source);
-        });
-    }
-    return entries.map((entry) => ({
-        ...entry,
-        plugins: entry.plugins.map((plugin) => mapPhiBuilderPluginMetaText(plugin, (text) => translations.get(text) ?? text)),
+        /*
+         * A failed batch leaves the source texts for this request, and the failure is logged; the next
+         * request asks again, because nothing failed is kept (`trBulk` keeps only answers).
+         */
+        let translated = null;
+        try {
+            translated = await translator.trBulk(sources, PHI_TR_CTX_WEB_UI_LABEL);
+        }
+        catch (error) {
+            logRuntimeEvent("warn", "builder.plugin_labels.translation_failed", {
+                message: "Plugin labels could not be translated; the source texts are shown for this request.",
+                area: "builder",
+                error,
+                meta: { locale, sourceLocale, count: sources.length },
+            });
+        }
+        if (translated) {
+            sources.forEach((source, index) => {
+                translations.set(translationKey(sourceLocale, source), translated[index] ?? source);
+            });
+        }
     }));
+    return entries.map((entry) => {
+        const sourceLocale = resolvePhiTranslationLocale(entry.sourceLocale);
+        return {
+            ...entry,
+            plugins: entry.plugins.map((plugin) => mapPhiBuilderPluginMetaText(plugin, (text) => translations.get(translationKey(sourceLocale, text)) ?? text)),
+        };
+    });
 }

package/plugins/runtime-modules/builder/plugin-metas.d.ts

@@ -3,4 +3,11 @@ import type { PhiCmsLayoutPluginDefinition } from "../../../types/cms-plugins";
 export declare function buildPhiBuilderPluginMeta(plugin: PhiAnyCmsBuilderPlugin): PhiBuilderPluginMeta;
 export declare function buildPhiBuilderLayoutPluginMetas(definition: PhiCmsLayoutPluginDefinition<unknown>): readonly PhiBuilderContainerMeta[];
 export declare function resolvePhiBuilderPluginDefaultConfig(meta: PhiBuilderPluginMeta | null | undefined): Record<string, unknown> | null;
+/**
+ * A Widget's defaults under its draft, group by group. The Widget parses its config deeply, so a draft
+ * that states one field of `features.pagination` keeps the defaults of the others; merged flat, the
+ * stated group replaced the whole default group and a `visibleWhen` on a sibling read nothing. A value
+ * the draft states wins as it is, `null` included; lists are values, not groups.
+ */
+export declare function mergePhiBuilderConfigDefaults(defaults: Record<string, unknown> | null | undefined, config: Record<string, unknown> | null | undefined): Record<string, unknown>;
 export declare function resolvePhiBuilderWidgetDraftConfig<TConfig extends Record<string, unknown>>(meta: PhiBuilderWidgetMeta | null | undefined, draftConfig: Record<string, unknown> | null | undefined): Partial<TConfig>;

package/plugins/runtime-modules/builder/plugin-metas.js

@@ -1,3 +1,4 @@
+import { isPhiRecord } from "../../../helpers/is-record";
 function normalizeWidgetIconFamily(category) {
     return category === "other" ? "content" : category;
 }
@@ -5,7 +6,7 @@ function resolveBuilderIconKey(pluginKey, iconName) {
     return iconName ? `${pluginKey}:${iconName}` : null;
 }
 function cloneDefaultConfig(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? { ...value } : null;
+    return isPhiRecord(value) ? { ...value } : null;
 }
 export function buildPhiBuilderPluginMeta(plugin) {
     const kind = plugin.kind === "widget" ? "widget" : "layout";
@@ -31,13 +32,15 @@ export function buildPhiBuilderPluginMeta(plugin) {
             category,
             tags: plugin.tags ?? null,
             runtimeSignals: plugin.runtimeSignals ?? null,
-            contentBinding: "contentBinding" in plugin ? plugin.contentBinding ?? null : null,
-            ...("translatesOwnText" in plugin && plugin.translatesOwnText ? { translatesOwnText: true } : {}),
+            contentBinding: plugin.contentBinding ?? null,
+            ...(plugin.translatesOwnText ? { translatesOwnText: true } : {}),
             signalSubcontrols: plugin.signalSubcontrols,
-            slotSizePolicy: plugin.slotSizePolicy ?? null,
-            requiredRegionOwnership: "requiredRegionOwnership" in plugin ? plugin.requiredRegionOwnership ?? null : null,
+            slotSizePolicy: plugin.slotSizePolicy,
+            surface: plugin.surface ?? null,
+            requiredRegionOwnership: plugin.requiredRegionOwnership ?? null,
             defaultConfig,
             resolvedDefaultConfig,
+            creationConfig: cloneDefaultConfig(plugin.creationConfig),
             leaf: true,
             fields: plugin.fields,
         };
@@ -59,8 +62,10 @@ export function buildPhiBuilderPluginMeta(plugin) {
         slotSizePolicy: plugin.slotSizePolicy ?? null,
         defaultConfig,
         resolvedDefaultConfig,
+        creationConfig: cloneDefaultConfig("creationConfig" in plugin ? plugin.creationConfig : null),
         slots,
         slotPositions: plugin.slotPositions ?? "compact",
+        ...("translatesOwnText" in plugin && plugin.translatesOwnText ? { translatesOwnText: true } : {}),
         fields: plugin.fields,
         allowReorder: true,
         defaultAnchor: plugin.defaultAnchor ?? slots.find((slot) => slot.defaultAnchor != null)?.defaultAnchor ?? null,
@@ -81,9 +86,22 @@ export function buildPhiBuilderLayoutPluginMetas(definition) {
 export function resolvePhiBuilderPluginDefaultConfig(meta) {
     return cloneDefaultConfig(meta?.resolvedDefaultConfig ?? meta?.defaultConfig);
 }
+/**
+ * A Widget's defaults under its draft, group by group. The Widget parses its config deeply, so a draft
+ * that states one field of `features.pagination` keeps the defaults of the others; merged flat, the
+ * stated group replaced the whole default group and a `visibleWhen` on a sibling read nothing. A value
+ * the draft states wins as it is, `null` included; lists are values, not groups.
+ */
+export function mergePhiBuilderConfigDefaults(defaults, config) {
+    const merged = { ...(defaults ?? {}) };
+    for (const [key, value] of Object.entries(config ?? {})) {
+        const fallback = merged[key];
+        merged[key] = isPhiRecord(fallback) && isPhiRecord(value)
+            ? mergePhiBuilderConfigDefaults(fallback, value)
+            : value;
+    }
+    return merged;
+}
 export function resolvePhiBuilderWidgetDraftConfig(meta, draftConfig) {
-    return {
-        ...(resolvePhiBuilderPluginDefaultConfig(meta) ?? {}),
-        ...(draftConfig ?? {}),
-    };
+    return mergePhiBuilderConfigDefaults(resolvePhiBuilderPluginDefaultConfig(meta), draftConfig);
 }