@phis/ui 0.2.1 → 0.3.0

package/helpers/cms-layout-defaults.js

@@ -1,18 +1,35 @@
-import { PHI_COLOR, PHI_MARGIN, PHI_SHADOW, PHI_SPACE } from "../theme/antd-css-var-contract";
+import { PHI_SPACE } from "../theme/antd-css-var-contract";
 import { PHI_RENDERABLE_BLOCK_DEFAULT_ANCHOR } from "./renderable-block-defaults";
 import { isPhiRecord } from "./is-record";
-export const PHI_CONTENT_LAYOUT_DEFAULTS = {
+import { PHI_SURFACE_CARD } from "./surface-presets";
+import { PHI_GRID_LAYOUT_DEFAULT_COLUMNS } from "../components/layouts/phi-grid-contract";
+import { PHI_MASONRY_LAYOUT_DEFAULT_COLUMNS } from "../components/layouts/phi-masonry-contract";
+/*
+ * What a Layout states when its node states nothing.
+ *
+ * Every gap is the small step (`sm`): one rhythm between children, whatever arranges them. The padding
+ * follows what the Layout is for. A Layout that only arranges its children -- Content, Flex, the
+ * vertical Flex, Stack, Carousel, Collapsible, Split Card -- has none, so nesting one in another adds
+ * nothing. A Layout that shows a field of tiles -- Grid, Masonry -- keeps them off its edge by the base
+ * step; a Three-column row runs edge to edge and keeps its sides off the edge. A Region has no padding
+ * at all: a gap between a Region's edge and its root Layout is something an author sets.
+ *
+ * "None" in the Paddings panel writes 0 rather than clearing the key, so a default is switched off for
+ * good. A side stated on its own wins over the uniform padding: a Three-column row loses its sides by
+ * setting each to none.
+ */
+const PHI_CONTENT_LAYOUT_DEFAULTS = {
     margin: 0,
 };
 const PHI_CONTENT_LAYOUT_PANEL_PRESET = {
     margin: 0,
     padding: PHI_SPACE.base,
 };
-export const PHI_FLEX_LAYOUT_DEFAULTS = {
+const PHI_FLEX_LAYOUT_DEFAULTS = {
     distribution: "anchor",
-    // A fresh row starts left-aligned and vertically centred, its children one base margin apart.
+    // A fresh row starts left-aligned and vertically centred, its children one small step apart.
     anchor: { horizontal: "left", vertical: "middle" },
-    gap: PHI_MARGIN.base,
+    gap: PHI_SPACE.sm,
     verticalSeparators: false,
     separatorBeforeFirst: false,
     separatorSpan: "75%",
@@ -20,7 +37,7 @@ export const PHI_FLEX_LAYOUT_DEFAULTS = {
 };
 const PHI_FLEX_LAYOUT_PANEL_PRESET = {
     distribution: "anchor",
-    gap: PHI_MARGIN.base,
+    gap: PHI_SPACE.sm,
     verticalSeparators: false,
     separatorBeforeFirst: false,
     separatorSpan: "75%",
@@ -43,14 +60,12 @@ const PHI_FLEX_LAYOUT_OVERLAY_ACTIONS_PRESET = {
     paddingBottom: PHI_SPACE.xs,
     paddingLeft: PHI_SPACE.base,
     width: "100%",
-    background: "transparent",
-    border: "none",
 };
-export const PHI_FLEX_VERTICAL_LAYOUT_DEFAULTS = {
+const PHI_FLEX_VERTICAL_LAYOUT_DEFAULTS = {
     gap: PHI_SPACE.sm,
 };
 const PHI_FLEX_VERTICAL_LAYOUT_PANEL_PRESET = {
-    gap: PHI_SPACE.base,
+    gap: PHI_SPACE.sm,
     padding: PHI_SPACE.base,
 };
 /**
@@ -59,42 +74,35 @@ const PHI_FLEX_VERTICAL_LAYOUT_PANEL_PRESET = {
  * touching this config -- the preset tree contract rejects a deviating copy.
  */
 const PHI_FLEX_VERTICAL_LAYOUT_PAGE_BASE_PRESET = {
-    gap: PHI_SPACE.base,
+    gap: PHI_SPACE.sm,
     padding: PHI_SPACE.base,
-    width: "100%",
     /*
-     * Transparent, so whatever the theme paints behind the page -- a colour, an image, the frosted
+     * No Surface, so whatever the theme paints behind the page -- a colour, an image, the frosted
      * Chrome pane -- reaches the content region instead of stopping at a grey plate. A page that
      * wants its own ground paints it on a Layout node inside a slot.
      */
-    background: "transparent",
-    border: false,
+    width: "100%",
 };
-export const PHI_GRID_LAYOUT_DEFAULTS = {
-    gap: 0,
-    align: undefined,
-    justify: undefined,
-    wrap: false,
+const PHI_GRID_LAYOUT_DEFAULTS = {
+    gap: PHI_SPACE.sm,
+    padding: PHI_SPACE.base,
+    columns: { ...PHI_GRID_LAYOUT_DEFAULT_COLUMNS },
 };
 const PHI_GRID_LAYOUT_PANEL_PRESET = {
-    gap: PHI_MARGIN.base,
-    // Rows apart, columns flush: stated, because an absent column gap follows the gap now.
-    columnGap: 0,
-    align: undefined,
-    justify: undefined,
-    wrap: false,
+    gap: PHI_SPACE.sm,
     padding: PHI_SPACE.base,
 };
-export const PHI_MASONRY_LAYOUT_DEFAULTS = {
-    columns: 3,
-    gap: PHI_MARGIN.md,
+const PHI_MASONRY_LAYOUT_DEFAULTS = {
+    columns: { ...PHI_MASONRY_LAYOUT_DEFAULT_COLUMNS },
+    gap: PHI_SPACE.sm,
+    padding: PHI_SPACE.base,
 };
 const PHI_MASONRY_LAYOUT_PANEL_PRESET = {
-    columns: 3,
-    gap: PHI_MARGIN.base,
+    columns: { ...PHI_MASONRY_LAYOUT_DEFAULT_COLUMNS },
+    gap: PHI_SPACE.sm,
     padding: PHI_SPACE.base,
 };
-export const PHI_STACK_LAYOUT_DEFAULTS = {
+const PHI_STACK_LAYOUT_DEFAULTS = {
     // One slot at a time is what a Stack is until somebody says otherwise; the pile is the deliberate
     // choice, not the standing one.
     slotDisplay: "single",
@@ -109,7 +117,7 @@ export const PHI_STACK_LAYOUT_DEFAULTS = {
 const PHI_STACK_LAYOUT_PANEL_PRESET = {
     padding: PHI_SPACE.base,
 };
-export const PHI_CAROUSEL_LAYOUT_DEFAULTS = {
+const PHI_CAROUSEL_LAYOUT_DEFAULTS = {
     // A slide is what tells somebody the slots are a run rather than a set, so it is the opening
     // impression rather than a preference to be discovered. Everything else is left absent: the
     // duration then follows the theme, and the window shows one slot until somebody widens it.
@@ -130,11 +138,11 @@ export const PHI_CAROUSEL_LAYOUT_DEFAULTS = {
 const PHI_CAROUSEL_LAYOUT_PANEL_PRESET = {
     padding: PHI_SPACE.base,
 };
-export const PHI_COLLAPSIBLE_LAYOUT_DEFAULTS = {
+const PHI_COLLAPSIBLE_LAYOUT_DEFAULTS = {
     anchor: PHI_RENDERABLE_BLOCK_DEFAULT_ANCHOR,
     accordion: false,
     slotTitles: [],
-    translateSlotTitles: true,
+    slotDescriptions: [],
     defaultOpenSlotKeys: ["slot_0"],
     collapsible: "header",
     ghost: true,
@@ -148,7 +156,7 @@ const PHI_COLLAPSIBLE_LAYOUT_PANEL_PRESET = {
     anchor: PHI_RENDERABLE_BLOCK_DEFAULT_ANCHOR,
     accordion: false,
     slotTitles: [],
-    translateSlotTitles: true,
+    slotDescriptions: [],
     defaultOpenSlotKeys: ["slot_0"],
     collapsible: "header",
     ghost: false,
@@ -161,53 +169,35 @@ const PHI_COLLAPSIBLE_LAYOUT_PANEL_PRESET = {
 };
 /** A split card centres what stands in its cards, on both axes, unless it says otherwise. */
 const PHI_SPLIT_CARD_LAYOUT_DEFAULT_ANCHOR = { horizontal: "center", vertical: "middle" };
+/*
+ * The two cards stand the small step apart. Their padding -- the distance from a card's edge to what
+ * stands in it, as every Layout's padding is the distance from its own edge to its slots -- is none
+ * until somebody states one.
+ */
 export const PHI_SPLIT_CARD_LAYOUT_DEFAULTS = {
     anchor: PHI_SPLIT_CARD_LAYOUT_DEFAULT_ANCHOR,
-    gap: 0,
+    gap: PHI_SPACE.sm,
 };
-const PHI_SPLIT_CARD_LAYOUT_PANEL_PRESET = {
-    anchor: PHI_SPLIT_CARD_LAYOUT_DEFAULT_ANCHOR,
-    gap: PHI_SPACE.base,
-    padding: "1.3125rem",
-    leftPadding: PHI_SPACE.base,
-    rightPadding: PHI_SPACE.base,
-    leftBackground: {
-        base: {
-            kind: "color",
-            color: PHI_COLOR.bgContainer,
-        },
-        overlay: null,
-        effect: null,
-    },
-    rightBackground: {
-        base: {
-            kind: "color",
-            color: PHI_COLOR.bgContainer,
-        },
-        overlay: null,
-        effect: null,
-    },
-    leftBorder: {
-        borderWidth: 1,
-        borderStyle: "solid",
-        borderColor: PHI_COLOR.borderSecondary,
-    },
-    rightBorder: {
-        borderWidth: 1,
-        borderStyle: "solid",
-        borderColor: PHI_COLOR.borderSecondary,
-    },
-    leftShadow: PHI_SHADOW.secondary,
-    rightShadow: PHI_SHADOW.secondary,
+/*
+ * What a Split Card is created with: spaced, and its two halves drawn as cards. The Surface is the
+ * creation's and not a default -- a default is put back under a node that states nothing, and a Split
+ * Card whose author took the cards away would have them back on the next render.
+ */
+export const PHI_SPLIT_CARD_LAYOUT_CREATION_CONFIG = {
+    ...PHI_SPLIT_CARD_LAYOUT_DEFAULTS,
+    surface: PHI_SURFACE_CARD,
 };
-export const PHI_THREE_COLUMN_LAYOUT_DEFAULTS = {
+const PHI_SPLIT_CARD_LAYOUT_PANEL_PRESET = PHI_SPLIT_CARD_LAYOUT_CREATION_CONFIG;
+const PHI_THREE_COLUMN_LAYOUT_DEFAULTS = {
     balancedSides: true,
-    gap: 0,
+    gap: PHI_SPACE.sm,
     wrap: false,
+    paddingLeft: PHI_SPACE.base,
+    paddingRight: PHI_SPACE.base,
 };
 const PHI_THREE_COLUMN_LAYOUT_PANEL_PRESET = {
     balancedSides: true,
-    gap: PHI_MARGIN.base,
+    gap: PHI_SPACE.sm,
     wrap: false,
     paddingTop: 0,
     paddingBottom: 0,

package/helpers/cms-navigation-catalog.d.ts

@@ -35,7 +35,6 @@ export type PhiBuilderNavigationTree = {
     } | null;
 };
 export type PhiBuilderNavigationPresetFamily = "header" | "sidebar" | "footer" | "quicklinks";
-export declare function normalizePhiBuilderNavigationKey(value: string | null | undefined): string;
 export declare function normalizePhiBuilderNavigationLocalKey(value: string | null | undefined): string | null;
 export declare function formatPhiBuilderNavigationScopeKey(area: PhiCmsAreaKey, key: string | null | undefined): string;
 export declare function parsePhiBuilderNavigationScopeKey(value: string | null | undefined): {

package/helpers/cms-navigation-catalog.js

@@ -2,7 +2,7 @@ import { isPhiCmsAreaKey, resolvePhiCmsAreaAsBuilderArea, } from "../constants/c
 import { readPhiCmsNavigationTargetPath } from "../helpers/navigation-target";
 import { resolvePhiCmsNavigationOverlay } from "../plugins/runtime-modules/descriptor-compiler";
 import { resolvePhiBuilderNavigationTargetPath } from "./cms-paths";
-export function normalizePhiBuilderNavigationKey(value) {
+function normalizePhiBuilderNavigationKey(value) {
     return (value ?? "").trim().toLowerCase();
 }
 export function normalizePhiBuilderNavigationLocalKey(value) {

package/helpers/cms-node-factories.d.ts

@@ -16,7 +16,6 @@ type PhiCmsLayoutNodeFactoryCommon = {
 };
 export type PhiCmsWidgetNodeFactoryCommon = Omit<PhiCmsLayoutNodeFactoryCommon, "parentLayoutNodeId"> & {
     parentLayoutNodeId: PhiCmsInstanceId;
-    contentId?: number | null;
 };
 /**
  * The config a Widget placement takes, read off its type key.
@@ -35,7 +34,6 @@ export type PhiCmsWidgetPlacementFields<TTypeKey extends string, TPluginKey exte
     typeKey: TTypeKey;
     config?: PhiCmsWidgetPlacementConfig<TTypeKey, TPluginKey>;
 };
-export declare function buildPhiCmsWidgetTypeKey(pluginKey: string, typeKey: string): string;
 export declare function buildPhiCmsLayoutNode({ pluginKey, typeKey, creationPreset, config, ...common }: PhiCmsLayoutNodeFactoryCommon & {
     /** Optional override; by default the owning module is resolved from the type key. */
     pluginKey?: string;
@@ -46,5 +44,5 @@ export declare function buildPhiCmsLayoutNode({ pluginKey, typeKey, creationPres
     };
     config?: Record<string, unknown>;
 }): PhiCmsLayoutNode;
-export declare function buildPhiCmsWidgetNode<TTypeKey extends string, TPluginKey extends string | undefined = undefined>({ pluginKey, typeKey, config, contentId, ...common }: PhiCmsWidgetNodeFactoryCommon & PhiCmsWidgetPlacementFields<TTypeKey, TPluginKey>): PhiCmsContentWidgetNode;
+export declare function buildPhiCmsWidgetNode<TTypeKey extends string, TPluginKey extends string | undefined = undefined>({ pluginKey, typeKey, config, ...common }: PhiCmsWidgetNodeFactoryCommon & PhiCmsWidgetPlacementFields<TTypeKey, TPluginKey>): PhiCmsContentWidgetNode;
 export {};

package/helpers/cms-node-factories.js

@@ -2,9 +2,6 @@ import { buildPhiCmsLayoutNamespacedTypeKey } from "../constants/cms-layout-type
 import { resolvePhiCmsLayoutPluginKey } from "../constants/cms-layout-type-keys";
 import { buildPhiCmsWidgetNamespacedTypeKey, resolvePhiCmsWidgetPluginKey } from "../constants/cms-widget-types";
 import { resolvePhiLayoutCreationPreset, } from "./cms-layout-defaults";
-export function buildPhiCmsWidgetTypeKey(pluginKey, typeKey) {
-    return buildPhiCmsWidgetNamespacedTypeKey(pluginKey, typeKey);
-}
 export function buildPhiCmsLayoutNode({ pluginKey, typeKey, creationPreset, config, ...common }) {
     return {
         id: common.id,
@@ -30,7 +27,7 @@ export function buildPhiCmsLayoutNode({ pluginKey, typeKey, creationPreset, conf
  * signature a literal fits, and a config with a wrong field fits the untyped one, so the check would
  * pass exactly when it should fail.
  */
-export function buildPhiCmsWidgetNode({ pluginKey, typeKey, config, contentId = null, ...common }) {
+export function buildPhiCmsWidgetNode({ pluginKey, typeKey, config, ...common }) {
     return {
         id: common.id,
         siteId: common.siteId,
@@ -43,6 +40,6 @@ export function buildPhiCmsWidgetNode({ pluginKey, typeKey, config, contentId =
         visibilityMask: common.visibilityMask,
         label: common.label,
         config: (config ?? {}),
-        contentId,
+        contentVersionId: null,
     };
 }

package/helpers/cms-node-visibility.d.ts

@@ -9,6 +9,14 @@ import type { PhiBlockRuntime } from "../types";
  * say it the same way, without a column of its own in the tree.
  */
 export declare function readPhiCmsNodeVisibleWhen(config: Record<string, unknown>): PhiRuntimeConditionExpression | null;
+/**
+ * The feature namespaces a condition reads: the first segment of every `feature` value path.
+ *
+ * A page collects these to know which Modules to ask (`server-helpers/cms-node-features.ts`), and the
+ * renderer reads them again per node to tell a node that waits for the browser from one whose Module
+ * could not be asked at all.
+ */
+export declare function collectPhiCmsNodeFeatureNamespaces(visibleWhen: PhiRuntimeConditionExpression | null): Set<string>;
 /**
  * The address this render was asked for, where the request said what it was.
  *

package/helpers/cms-node-visibility.js

@@ -1,4 +1,4 @@
-import { evaluatePhiRuntimeConditionExpression, readPhiRuntimeConditionExpression, } from "../types/runtime-condition";
+import { collectPhiRuntimeValueConditions, evaluatePhiRuntimeConditionExpression, readPhiRuntimeConditionExpression, } from "../types/runtime-condition";
 /**
  * Whether a node appears at all, read from the node's own config rather than the Widget's.
  *
@@ -10,6 +10,26 @@ import { evaluatePhiRuntimeConditionExpression, readPhiRuntimeConditionExpressio
 export function readPhiCmsNodeVisibleWhen(config) {
     return readPhiRuntimeConditionExpression(config.visibleWhen);
 }
+/**
+ * The feature namespaces a condition reads: the first segment of every `feature` value path.
+ *
+ * A page collects these to know which Modules to ask (`server-helpers/cms-node-features.ts`), and the
+ * renderer reads them again per node to tell a node that waits for the browser from one whose Module
+ * could not be asked at all.
+ */
+export function collectPhiCmsNodeFeatureNamespaces(visibleWhen) {
+    const namespaces = new Set();
+    if (!visibleWhen)
+        return namespaces;
+    for (const condition of collectPhiRuntimeValueConditions(visibleWhen)) {
+        if (condition.source !== "feature")
+            continue;
+        const namespace = condition.valuePath.split(".")[0]?.trim() ?? "";
+        if (namespace)
+            namespaces.add(namespace);
+    }
+    return namespaces;
+}
 /**
  * The address this render was asked for, where the request said what it was.
  *

package/helpers/cms-page-catalog.d.ts

@@ -35,8 +35,7 @@ export type PhiPresetPageNode = {
 export type PhiBuilderModulePresetPagesByArea = Record<PhiBuilderPageCatalogArea, PhiPresetPageNode[]>;
 export declare function createEmptyPhiBuilderModulePresetPagesByArea(): PhiBuilderModulePresetPagesByArea;
 export type PhiBuilderPageCatalogArea = PhiBuilderAreaKey;
-export declare function mergePhiBuilderPageCatalogNodes(presetPages: PhiPresetPageNode[], customPages: PhiPresetPageNode[] | null | undefined): PhiPresetPageNode[];
-export declare function resolvePagePath(area: PhiBuilderPageCatalogArea, pageKey: string, pages: readonly PhiPresetPageNode[]): string;
+export declare function findPhiPageNodePath(pages: PhiPresetPageNode[], targetKey: string, prefix?: PhiPresetPageNode[]): PhiPresetPageNode[] | null;
 export declare function resolvePhiBuilderActivePageKey(requestedPageKey: string | null | undefined, pages: readonly PhiPresetPageNode[]): string | null;
 export declare function resolvePhiBuilderPagePresetSource(pageKey: string, pages: readonly PhiPresetPageNode[]): PhiCmsPresetSource | null;
 export declare function resolvePhiBuilderPageDefaultFlags(pageKey: string, pages: readonly PhiPresetPageNode[]): number;
@@ -72,7 +71,6 @@ export type PhiBuilderPersistedPageCatalogEntry = {
     workingDraftRevisionId?: number | null;
     tombstoned: boolean;
 };
-export declare function mergePhiBuilderPageCatalogWithPersistedPages(area: PhiBuilderPageCatalogArea, presetPages: PhiPresetPageNode[], persistedPages: readonly PhiBuilderPersistedPageCatalogEntry[] | null | undefined, localPages?: PhiPresetPageNode[] | null): PhiPresetPageNode[];
 /** The page catalog of one Area, with preset, local and persisted pages merged. */
 export type PhiBuilderActivePageCatalog = ReturnType<typeof resolvePhiBuilderActivePageCatalog>;
 export declare function resolvePhiBuilderActivePageCatalog(area: PhiBuilderPageCatalogArea, modulePresetPagesByArea: Partial<Record<PhiBuilderPageCatalogArea, PhiPresetPageNode[]>>, localPagesByArea: Partial<Record<PhiBuilderPageCatalogArea, PhiPresetPageNode[]>> | null | undefined, persistedPagesByArea?: Partial<Record<PhiBuilderPageCatalogArea, PhiBuilderPersistedPageCatalogEntry[]>> | null): PhiPresetPageNode[];

package/helpers/cms-page-catalog.js

@@ -18,14 +18,14 @@ function findPagePathSegments(pages, targetKey, prefix = []) {
     }
     return null;
 }
-function findPageNodePath(pages, targetKey, prefix = []) {
+export function findPhiPageNodePath(pages, targetKey, prefix = []) {
     for (const page of pages) {
         const currentPath = [...prefix, page];
         if (page.key === targetKey) {
             return currentPath;
         }
         const childPath = page.children
-            ? findPageNodePath(page.children, targetKey, currentPath)
+            ? findPhiPageNodePath(page.children, targetKey, currentPath)
             : null;
         if (childPath) {
             return childPath;
@@ -42,7 +42,7 @@ function collectPageKeys(pages, keys = new Set()) {
     }
     return keys;
 }
-export function mergePhiBuilderPageCatalogNodes(presetPages, customPages) {
+function mergePhiBuilderPageCatalogNodes(presetPages, customPages) {
     if (!customPages?.length) {
         return presetPages;
     }
@@ -50,7 +50,7 @@ export function mergePhiBuilderPageCatalogNodes(presetPages, customPages) {
     const nextCustomPages = customPages.filter((page) => !existingKeys.has(page.key));
     return nextCustomPages.length > 0 ? [...presetPages, ...nextCustomPages] : presetPages;
 }
-export function resolvePagePath(area, pageKey, pages) {
+function resolvePagePath(area, pageKey, pages) {
     const pathSegments = findPagePathSegments([...pages], pageKey) ?? [pageKey];
     return `/${area}/${pathSegments.join("/")}`;
 }
@@ -69,7 +69,7 @@ function findFirstPhiBuilderPageNodeKey(pages) {
 }
 export function resolvePhiBuilderActivePageKey(requestedPageKey, pages) {
     const normalizedPageKey = requestedPageKey?.trim() ?? "";
-    if (normalizedPageKey && findPageNodePath([...pages], normalizedPageKey)) {
+    if (normalizedPageKey && findPhiPageNodePath([...pages], normalizedPageKey)) {
         return normalizedPageKey;
     }
     /*
@@ -79,10 +79,10 @@ export function resolvePhiBuilderActivePageKey(requestedPageKey, pages) {
     return findFirstPhiBuilderPageNodeKey(pages);
 }
 export function resolvePhiBuilderPagePresetSource(pageKey, pages) {
-    return findPageNodePath([...pages], pageKey)?.at(-1)?.sourcePreset ?? null;
+    return findPhiPageNodePath([...pages], pageKey)?.at(-1)?.sourcePreset ?? null;
 }
 export function resolvePhiBuilderPageDefaultFlags(pageKey, pages) {
-    return findPageNodePath([...pages], pageKey)?.at(-1)?.defaultPageFlags ?? 0;
+    return findPhiPageNodePath([...pages], pageKey)?.at(-1)?.defaultPageFlags ?? 0;
 }
 export function normalizePhiBuilderCmsCatalogPath(value) {
     const trimmed = value.trim();
@@ -114,7 +114,7 @@ function collectPresetStoragePaths(area, pages) {
     return storagePaths;
 }
 export function resolvePhiBuilderCmsStoragePathForCatalog(area, pageKey, pages) {
-    const node = findPageNodePath([...pages], pageKey)?.at(-1);
+    const node = findPhiPageNodePath([...pages], pageKey)?.at(-1);
     if (!node) {
         throw new Error(`Page "${area}:${pageKey}" is not present in the active Builder Page catalog.`);
     }
@@ -133,13 +133,13 @@ export function resolvePhiBuilderCmsStoragePathForCatalog(area, pageKey, pages)
  * than a fault. Asking the throwing function that question took the Page Select down with it.
  */
 export function findPhiBuilderCatalogPathForCatalog(area, pageKey, pages) {
-    return findPageNodePath([...pages], pageKey)
+    return findPhiPageNodePath([...pages], pageKey)
         ? resolvePhiBuilderCatalogPathForCatalog(area, pageKey, pages)
         : null;
 }
 /** Where the Builder shows a Page, which is what its picker offers and its path signal carries. */
 export function resolvePhiBuilderCatalogPathForCatalog(area, pageKey, pages) {
-    const node = findPageNodePath([...pages], pageKey)?.at(-1);
+    const node = findPhiPageNodePath([...pages], pageKey)?.at(-1);
     if (node?.catalogPath) {
         return normalizePhiBuilderCmsCatalogPath(node.catalogPath);
     }
@@ -249,7 +249,7 @@ function clonePageCatalogNodes(nodes) {
         children: node.children ? clonePageCatalogNodes(node.children) : undefined,
     }));
 }
-export function mergePhiBuilderPageCatalogWithPersistedPages(area, presetPages, persistedPages, localPages) {
+function mergePhiBuilderPageCatalogWithPersistedPages(area, presetPages, persistedPages, localPages) {
     const merged = clonePageCatalogNodes(mergePhiBuilderPageCatalogNodes(presetPages, localPages));
     const presetStoragePaths = collectPresetStoragePaths(area, presetPages);
     for (const page of persistedPages ?? []) {

package/helpers/cms-preset-nodes.d.ts

@@ -1,4 +1,5 @@
 import { buildPhiCmsLayoutNode, type PhiCmsWidgetNodeFactoryCommon, type PhiCmsWidgetPlacementFields } from "./cms-node-factories";
+import type { PhiCommandToolbarWidgetPlacement } from "../types/core-widget-placements";
 import type { PhiCmsContentWidgetNode, PhiCmsLayoutNode, PhiCmsOverlayNode, PhiCmsPageNode, PhiCmsRegionNode } from "../types/cms";
 import type { PhiCmsInstanceId } from "../types/cms-instance-id";
 import type { PhiCmsOverlayType, PhiOverlayFooterPresentation } from "../types/cms-overlay";
@@ -59,13 +60,42 @@ export type PhiCmsPresetOverlayInput = {
     footerPresentation: Exclude<PhiOverlayFooterPresentation, "none">;
     footerLayoutNodeId: PhiCmsInstanceId;
 });
+/**
+ * A dialog: the Overlay, its body, and -- where it has actions -- its footer and their Command Toolbar.
+ *
+ * What it decides is what differs between dialogs: its ids, its title and wiring, what extra the body
+ * Layout carries (a form's label column, say), and its buttons. How the body and the actions look is the
+ * one answer every dialog shares (`helpers/cms-dialog.ts`), so it is not an input.
+ */
+export type PhiCmsPresetDialogInput = {
+    id: PhiCmsInstanceId;
+    bodyLayoutNodeId: PhiCmsInstanceId;
+    sortOrder: number;
+    label: string | null;
+    /** The Overlay's config: title, mount and close policy, open action, routes. `width` defaults. */
+    config: Record<string, unknown>;
+    headerLayoutNodeId?: PhiCmsInstanceId | null;
+    /** Config the body Layout carries besides the dialog's own: anything but its gap, padding and ground. */
+    body?: {
+        label?: string;
+        config?: Record<string, unknown>;
+    };
+    /** The actions, where the dialog has any. */
+    commands?: {
+        footerLayoutNodeId: PhiCmsInstanceId;
+        widgetId: PhiCmsInstanceId;
+        label: string;
+        flags?: number;
+        config: Omit<PhiCommandToolbarWidgetPlacement, "compact" | "showLabels" | "controlSize">;
+    };
+};
 /** The two things a Preset changes about the Page row it was built for; everything else is kept. */
 export type PhiCmsPresetPageInput = Partial<Pick<PhiCmsPageNode, "pageType" | "layoutConfig">>;
 /**
  * The parts of a node that a Preset repeats rather than decides.
  *
  * A placement is four things -- what it is, where it sits, what it is called, how it is configured --
- * and it was written as eleven, because `siteId`, `visibilityMask`, `status`, `flags`, `contentId` and
+ * and it was written as eleven, because `siteId`, `visibilityMask`, `status`, `flags`, `contentVersionId` and
  * `sortOrder` are the same for every node of a page and were spelled out on each of them. That is not
  * detail a reader of a Preset needs; it is noise they have to look past to find the four that matter,
  * and it is six chances to write the wrong page's `visibilityMask` on one node out of twenty.
@@ -94,6 +124,16 @@ declare function createPhiCmsPresetNodeSet(defaults: PhiCmsPresetNodeDefaults):
      */
     stack<const TTypeKeys extends readonly string[]>(parentLayoutNodeId: PhiCmsInstanceId, entries: { [TIndex in keyof TTypeKeys]: PhiCmsPresetStackEntry<TTypeKeys[TIndex]>; }, startAt?: number): PhiCmsContentWidgetNode[];
     overlay(input: PhiCmsPresetOverlayInput): PhiCmsOverlayNode;
+    /**
+     * A dialog in one call (`PhiCmsPresetDialogInput`): the nodes it is made of, for the tree's
+     * `overlays`, `layoutNodes` and `contentWidgets`. The widgets of the body are the Preset's own, placed
+     * in `bodyLayoutNodeId` from slot 0.
+     */
+    dialog(input: PhiCmsPresetDialogInput): {
+        overlay: PhiCmsOverlayNode;
+        layouts: PhiCmsLayoutNode[];
+        widgets: PhiCmsContentWidgetNode[];
+    };
 };
 declare function createPhiCmsPresetPageNodeSet(page: PhiCmsPageNode, nodes: PhiCmsPresetNodes): {
     /** The Page the tree returns: the row it was built for, published, with what the Preset decides. */
@@ -110,5 +150,15 @@ declare function createPhiCmsPresetPageNodeSet(page: PhiCmsPageNode, nodes: PhiC
      */
     stack<const TTypeKeys extends readonly string[]>(parentLayoutNodeId: PhiCmsInstanceId, entries: { [TIndex in keyof TTypeKeys]: PhiCmsPresetStackEntry<TTypeKeys[TIndex]>; }, startAt?: number): PhiCmsContentWidgetNode[];
     overlay(input: PhiCmsPresetOverlayInput): PhiCmsOverlayNode;
+    /**
+     * A dialog in one call (`PhiCmsPresetDialogInput`): the nodes it is made of, for the tree's
+     * `overlays`, `layoutNodes` and `contentWidgets`. The widgets of the body are the Preset's own, placed
+     * in `bodyLayoutNodeId` from slot 0.
+     */
+    dialog(input: PhiCmsPresetDialogInput): {
+        overlay: PhiCmsOverlayNode;
+        layouts: PhiCmsLayoutNode[];
+        widgets: PhiCmsContentWidgetNode[];
+    };
 };
 export {};

package/helpers/cms-preset-nodes.js

@@ -1,5 +1,6 @@
 import { buildPhiCmsLayoutNode, buildPhiCmsWidgetNode, } from "./cms-node-factories";
 import { PhiCmsStatus } from "../constants/phi-cms";
+import { PHI_DIALOG_BODY_CONFIG, PHI_DIALOG_COMMANDS_CONFIG, PHI_DIALOG_WIDTH } from "./cms-dialog";
 export function createPhiCmsPresetNodes(defaults) {
     const nodes = createPhiCmsPresetNodeSet(defaults);
     return "pageType" in defaults ? createPhiCmsPresetPageNodeSet(defaults, nodes) : nodes;
@@ -23,7 +24,6 @@ function createPhiCmsPresetNodeSet(defaults) {
             return buildPhiCmsWidgetNode({
                 ...common,
                 sortOrder: input.slotIndex,
-                contentId: null,
                 ...input,
             });
         },
@@ -37,7 +37,6 @@ function createPhiCmsPresetNodeSet(defaults) {
             const stacked = entries;
             return stacked.map((entry, index) => buildPhiCmsWidgetNode({
                 ...common,
-                contentId: null,
                 parentLayoutNodeId,
                 slotIndex: startAt + index,
                 sortOrder: startAt + index,
@@ -67,6 +66,73 @@ function createPhiCmsPresetNodeSet(defaults) {
                 }
                 : node;
         },
+        /**
+         * A dialog in one call (`PhiCmsPresetDialogInput`): the nodes it is made of, for the tree's
+         * `overlays`, `layoutNodes` and `contentWidgets`. The widgets of the body are the Preset's own, placed
+         * in `bodyLayoutNodeId` from slot 0.
+         */
+        dialog(input) {
+            const body = this.layout({
+                typeKey: "flex-vertical",
+                id: input.bodyLayoutNodeId,
+                parentLayoutNodeId: null,
+                slotIndex: 0,
+                label: input.body?.label ?? `${input.label ?? "dialog"} body`,
+                creationPreset: { layoutKind: "verticalflex", preset: "panel" },
+                config: { ...input.body?.config, ...PHI_DIALOG_BODY_CONFIG },
+            });
+            const config = { width: PHI_DIALOG_WIDTH, ...input.config };
+            const commands = input.commands;
+            if (!commands) {
+                return {
+                    overlay: this.overlay({
+                        id: input.id,
+                        overlayType: "modal",
+                        headerLayoutNodeId: input.headerLayoutNodeId ?? null,
+                        bodyLayoutNodeId: input.bodyLayoutNodeId,
+                        sortOrder: input.sortOrder,
+                        label: input.label,
+                        config,
+                    }),
+                    layouts: [body],
+                    widgets: [],
+                };
+            }
+            return {
+                overlay: this.overlay({
+                    id: input.id,
+                    overlayType: "modal",
+                    headerLayoutNodeId: input.headerLayoutNodeId ?? null,
+                    bodyLayoutNodeId: input.bodyLayoutNodeId,
+                    footerPresentation: "actions",
+                    footerLayoutNodeId: commands.footerLayoutNodeId,
+                    sortOrder: input.sortOrder,
+                    label: input.label,
+                    config,
+                }),
+                layouts: [
+                    body,
+                    this.layout({
+                        typeKey: "flex",
+                        id: commands.footerLayoutNodeId,
+                        parentLayoutNodeId: null,
+                        slotIndex: 0,
+                        label: `${input.label ?? "dialog"} footer`,
+                        creationPreset: { layoutKind: "flex", preset: "overlay-actions" },
+                        config: {},
+                    }),
+                ],
+                widgets: [this.widget({
+                        typeKey: "command-toolbar",
+                        id: commands.widgetId,
+                        parentLayoutNodeId: commands.footerLayoutNodeId,
+                        slotIndex: 0,
+                        label: commands.label,
+                        ...(commands.flags == null ? {} : { flags: commands.flags }),
+                        config: { ...commands.config, ...PHI_DIALOG_COMMANDS_CONFIG },
+                    })],
+            };
+        },
     };
 }
 function hasPhiCmsPresetOverlayFooter(input) {

package/helpers/cms-preset-page-tree.d.ts

@@ -0,0 +1,28 @@
+import type { PhiPresetPageNode } from "./cms-page-catalog";
+import type { PhiCmsActiveRouteTable } from "../types/cms-module-descriptors";
+import type { PhiRuntimeModuleId } from "../types";
+/**
+ * Puts one Module route into a Page tree, under the folders its path names.
+ *
+ * Shared by the Builder's catalog of every installed route and by the list of the Pages an Area answers
+ * on today, which a link picker offers (`gateway/page-references-route.ts`).
+ */
+export declare function insertPhiPresetPageTarget(roots: PhiPresetPageNode[], target: {
+    path: string;
+    area: string;
+    title: string;
+    ownerModuleId: PhiRuntimeModuleId;
+    presetKey: string;
+    presetVersion: number;
+    defaultPageFlags?: number;
+    landingPage?: true;
+}): void;
+/**
+ * The Module Pages one Area answers on today, as catalog nodes.
+ *
+ * The routes that answer, not every one that was declared: this is what a link may point at, so a Page
+ * of a Module the Area has switched off is not offered, and of two routes claiming one address only the
+ * one the table lets answer is. A route with a parameter is left out -- `/news/:id` is a family of Pages,
+ * and a link names one -- which reading the exact paths does by itself.
+ */
+export declare function buildPhiAreaActivePresetPages(routeTable: PhiCmsActiveRouteTable): PhiPresetPageNode[];