@phis/ui 0.2.1 → 0.4.0

package/components/regions/presets/content-entry-editor-tour.d.ts

@@ -0,0 +1,19 @@
+import type { PhiRuntimeModuleId } from "../../../types";
+import type { PhiTourDefinition } from "../../../types/tours";
+/**
+ * The Tour of a content kind's editor Page (News, Blog): the order a writer meets it in -- the list, finding
+ * and starting an entry, writing and saving, getting it out, the categories. The steps point at the
+ * Table's parts (`cms:<id>:filters` and the like), which the Table Widget offers.
+ *
+ * One text for every kind: the Page is the same Page for each, built by `content-entry-editor-page-tree.ts`,
+ * and its Tour says "entry" where the Page's own words are the kind's. The ids are the Page's, derived from
+ * the same Module, preset and node keys, so the steps point at what that tree draws.
+ *
+ * The Page is drawn for two roles. An Author sees Submit where a Publisher sees Publish and Withdraw, and
+ * only a Publisher sees the categories; the step about getting an entry out says both, and the categories
+ * step is passed over where its Table is not drawn.
+ */
+export declare function buildPhiContentEntryEditorTour({ ownerModuleId, presetKey, }: {
+    ownerModuleId: PhiRuntimeModuleId;
+    presetKey: string;
+}): PhiTourDefinition;

package/components/regions/presets/content-entry-editor-tour.js

@@ -0,0 +1,71 @@
+import { createPhiPresetCmsInstanceIdMap } from "../../../types/cms-instance-id";
+/**
+ * The Tour of a content kind's editor Page (News, Blog): the order a writer meets it in -- the list, finding
+ * and starting an entry, writing and saving, getting it out, the categories. The steps point at the
+ * Table's parts (`cms:<id>:filters` and the like), which the Table Widget offers.
+ *
+ * One text for every kind: the Page is the same Page for each, built by `content-entry-editor-page-tree.ts`,
+ * and its Tour says "entry" where the Page's own words are the kind's. The ids are the Page's, derived from
+ * the same Module, preset and node keys, so the steps point at what that tree draws.
+ *
+ * The Page is drawn for two roles. An Author sees Submit where a Publisher sees Publish and Withdraw, and
+ * only a Publisher sees the categories; the step about getting an entry out says both, and the categories
+ * step is passed over where its Table is not drawn.
+ */
+export function buildPhiContentEntryEditorTour({ ownerModuleId, presetKey, }) {
+    const ids = createPhiPresetCmsInstanceIdMap({ domain: "page", ownerModuleId, presetKey }, [
+        "widgetNews",
+        "widgetCategories",
+    ]);
+    return {
+        id: `${ownerModuleId}/editor`,
+        version: 1,
+        steps: [
+            {
+                key: "entries",
+                target: `cms:${ids.widgetNews}`,
+                title: "Every entry, written and published",
+                description: "Drafts and published entries stand in one list, newest first, with who wrote them, where they are filed and when they went out.",
+                placement: "top",
+            },
+            {
+                key: "finding",
+                target: `cms:${ids.widgetNews}:filters`,
+                title: "Finding an entry",
+                description: "Show only drafts or only what is published, or search by title and address.",
+                placement: "bottom",
+                ifMissing: "skip",
+            },
+            {
+                key: "new",
+                target: `cms:${ids.widgetNews}:toolbar`,
+                title: "A new entry",
+                description: "The plus starts one. It is a draft until it is published, so nobody reads it while you write.",
+                placement: "bottom",
+                ifMissing: "skip",
+            },
+            {
+                key: "writing",
+                target: `cms:${ids.widgetNews}:row-actions`,
+                title: "Writing is saving a draft",
+                description: "Edit opens an entry's text. What you save is a draft: readers keep seeing the published version until the new one is published.",
+                placement: "left",
+            },
+            {
+                key: "release",
+                target: `cms:${ids.widgetNews}:row-actions`,
+                title: "Getting an entry out",
+                description: "An Author submits an entry, and it waits under Releases for a Publisher. A Publisher publishes it here, from a date and until a date if it should, names its author and category, and can take it offline again.",
+                placement: "left",
+            },
+            {
+                key: "categories",
+                target: `cms:${ids.widgetCategories}`,
+                title: "Categories",
+                description: "Each entry is filed under one category or none. The order sorts the categories wherever they are listed, and a list of entries on a Page can be set to show only some of them.",
+                placement: "top",
+                ifMissing: "skip",
+            },
+        ],
+    };
+}

package/components/regions/presets/content-entry-public-page-trees.d.ts

@@ -0,0 +1,52 @@
+import "server-only";
+import type { PhiContentEntryKind } from "../../../constants/content-entry-kinds";
+import type { PhiCmsPageNode, PhiResolvedCmsPageTree } from "../../../types/cms";
+import type { PhiBlockRuntime, PhiRuntimeModuleId } from "../../../types";
+/**
+ * A kind's Public list Page: the list, inside the frame every Public page wears (`CONTENT_ENTRIES.md`).
+ *
+ * No heading above it: the navigation entry and the Page's title already say "News", and a word that
+ * size over the entries only pushed the first one down. A Site that wants an introduction above its
+ * entries adds one in the Builder without touching the part that reads.
+ *
+ * The list links each title to the kind's detail route, named by its Module Page reference; the slug is
+ * filled per entry.
+ */
+export declare function buildPhiContentEntryListPageTree({ page, kind, ownerModuleId, presetKey, detailPresetKey, presentation, }: {
+    page: PhiCmsPageNode;
+    kind: PhiContentEntryKind;
+    ownerModuleId: PhiRuntimeModuleId;
+    presetKey: string;
+    /** The preset key of the kind's detail route, which the titles link to. */
+    detailPresetKey: string;
+    /** How the list stands: whole entries for News, cards for a Blog (the `entry-list` Widget's setting). */
+    presentation: "stack" | "cards" | "compact";
+}): Promise<PhiResolvedCmsPageTree>;
+/**
+ * A kind's Public detail Page, `/<kind>/:slug`: the entry's header, its text, and the entries related to it.
+ *
+ * The entry is read here, before anything is drawn, because two answers depend on it that the body cannot
+ * give: the Page's title and description, and its status. A slug that names no published entry answers
+ * 404 -- `notFound()` raised during the request resolution, which the Area Layout runs before the shell
+ * flushes, so the status line says so rather than a 200 carrying "not found". The three Widgets are bound to
+ * the entry's record (`types/record-provider.ts`), whose Provider asks the same question
+ * (`loadPhiContentEntryPage`), so it is answered once.
+ *
+ * Three Widgets rather than one article, because each is the Site's to rearrange: a header that shows the
+ * author or not, a body, and a "more like this" list that draws nothing where nothing is related.
+ */
+export declare function buildPhiContentEntryDetailPageTree({ page, runtime, params, kind, ownerModuleId, presetKey, headerParts, related, }: {
+    page: PhiCmsPageNode;
+    runtime: PhiBlockRuntime;
+    params: Readonly<Record<string, string>>;
+    kind: PhiContentEntryKind;
+    ownerModuleId: PhiRuntimeModuleId;
+    presetKey: string;
+    /** What the header shows (`constants/content-entry-parts.ts`): a byline for a Blog, the date for News. */
+    headerParts: number;
+    /** The list under the entry: its presentation, its heading's source text, and its detail route. */
+    related: {
+        presentation: "stack" | "cards" | "compact";
+        title: string;
+    };
+}): Promise<PhiResolvedCmsPageTree>;

package/components/regions/presets/content-entry-public-page-trees.js

@@ -0,0 +1,146 @@
+import "server-only";
+import { notFound } from "next/navigation";
+import { createPhiPresetCmsInstanceIdMap } from "../../../types/cms-instance-id";
+import { PhiCmsPageType } from "../../../constants/phi-cms";
+import { buildPhiBasePageColumnFrame } from "./phi-base-page-column";
+import { createPhiCmsPresetNodes } from "../../../helpers/cms-preset-nodes";
+import { createPhiContentEntryRecordBinding } from "../../../helpers/content-entry-record-binding";
+import { loadPhiContentEntryPage } from "../../../server-helpers/content-entry-page";
+import { createPhiPageReference } from "../../../types/references";
+import { PHI_CONTENT_ENTRY_RELATED_LIMIT } from "../../../gateway/content-entries";
+import { PHI_LAYOUT } from "../../../theme/phi-tokens";
+import { PHI_ENTRY_LIST_DEFAULT_PARTS, PhiContentEntryPart } from "../../../constants/content-entry-parts";
+/** What a list shows in its presentation: a card names who wrote it at the start of its top line. */
+function listPartsFor(presentation) {
+    return presentation === "cards" ? { show: PHI_ENTRY_LIST_DEFAULT_PARTS | PhiContentEntryPart.Author } : {};
+}
+const SYNTHETIC_LIST_REGION_IDS = { regionContent: -320 };
+const SYNTHETIC_DETAIL_REGION_IDS = { regionContent: -321 };
+/**
+ * A kind's Public list Page: the list, inside the frame every Public page wears (`CONTENT_ENTRIES.md`).
+ *
+ * No heading above it: the navigation entry and the Page's title already say "News", and a word that
+ * size over the entries only pushed the first one down. A Site that wants an introduction above its
+ * entries adds one in the Builder without touching the part that reads.
+ *
+ * The list links each title to the kind's detail route, named by its Module Page reference; the slug is
+ * filled per entry.
+ */
+export async function buildPhiContentEntryListPageTree({ page, kind, ownerModuleId, presetKey, detailPresetKey, presentation, }) {
+    const identity = { domain: "page", ownerModuleId, presetKey };
+    const layouts = createPhiPresetCmsInstanceIdMap(identity, ["layoutContent"]);
+    // The node keys are part of every stored placement; the list keeps the one it had before it was shared.
+    const widgets = createPhiPresetCmsInstanceIdMap(identity, ["widgetNewsList"]);
+    const nodes = createPhiCmsPresetNodes(page);
+    return {
+        page: nodes.page({ pageType: PhiCmsPageType.Standard }),
+        overlays: [],
+        // The column of prose every entry Page stands in (`CONTENT_ENTRIES.md`, The frame).
+        ...buildPhiBasePageColumnFrame({
+            page,
+            regionId: SYNTHETIC_LIST_REGION_IDS.regionContent,
+            columnId: layouts.layoutContent,
+            label: `pub ${kind} page`,
+            maxWidth: PHI_LAYOUT.readingMax,
+        }),
+        contentWidgets: nodes.stack(layouts.layoutContent, [
+            {
+                typeKey: "entry-list",
+                id: widgets.widgetNewsList,
+                label: `pub ${kind} list widget`,
+                config: {
+                    kind,
+                    presentation,
+                    ...listPartsFor(presentation),
+                    detailLinkTarget: {
+                        kind: "page",
+                        reference: createPhiPageReference({ kind: "module", ownerModuleId, presetKey: detailPresetKey }),
+                    },
+                },
+            },
+        ]),
+    };
+}
+/**
+ * A kind's Public detail Page, `/<kind>/:slug`: the entry's header, its text, and the entries related to it.
+ *
+ * The entry is read here, before anything is drawn, because two answers depend on it that the body cannot
+ * give: the Page's title and description, and its status. A slug that names no published entry answers
+ * 404 -- `notFound()` raised during the request resolution, which the Area Layout runs before the shell
+ * flushes, so the status line says so rather than a 200 carrying "not found". The three Widgets are bound to
+ * the entry's record (`types/record-provider.ts`), whose Provider asks the same question
+ * (`loadPhiContentEntryPage`), so it is answered once.
+ *
+ * Three Widgets rather than one article, because each is the Site's to rearrange: a header that shows the
+ * author or not, a body, and a "more like this" list that draws nothing where nothing is related.
+ */
+export async function buildPhiContentEntryDetailPageTree({ page, runtime, params, kind, ownerModuleId, presetKey, headerParts, related, }) {
+    const slug = params.slug?.trim() ?? "";
+    const found = slug ? (await loadPhiContentEntryPage(runtime, { kind, slug }))?.entry ?? null : null;
+    if (!found) {
+        notFound();
+    }
+    // What the three Widgets are bound to. The content entry Provider asks the question just asked, so
+    // drawing them costs Core nothing more.
+    const entry = createPhiContentEntryRecordBinding(kind, slug);
+    const identity = { domain: "page", ownerModuleId, presetKey };
+    const layouts = createPhiPresetCmsInstanceIdMap(identity, ["layoutContent"]);
+    const widgets = createPhiPresetCmsInstanceIdMap(identity, ["widgetHeader", "widgetEntry", "widgetRelated"]);
+    const nodes = createPhiCmsPresetNodes(page);
+    return {
+        page: nodes.page({ pageType: PhiCmsPageType.Standard }),
+        /*
+         * The entry's words, already in the page's language: Core answers them translated. `msgId: 0`, because
+         * they are no Site message of their own -- the entry's versions hold them.
+         */
+        pageMeta: {
+            title: { msgId: 0, source: found.title, value: found.title },
+            description: found.subtitle
+                ? { msgId: 0, source: found.subtitle, value: found.subtitle }
+                : null,
+        },
+        overlays: [],
+        // The column of prose every entry Page stands in (`CONTENT_ENTRIES.md`, The frame).
+        ...buildPhiBasePageColumnFrame({
+            page,
+            regionId: SYNTHETIC_DETAIL_REGION_IDS.regionContent,
+            columnId: layouts.layoutContent,
+            label: `pub ${kind} detail page`,
+            maxWidth: PHI_LAYOUT.readingMax,
+        }),
+        contentWidgets: nodes.stack(layouts.layoutContent, [
+            {
+                typeKey: "entry-header",
+                id: widgets.widgetHeader,
+                label: `pub ${kind} detail header widget`,
+                config: { entry, show: headerParts },
+            },
+            {
+                typeKey: "entry-detail",
+                id: widgets.widgetEntry,
+                label: `pub ${kind} detail widget`,
+                // The tags lead the header; after the text only the link is left.
+                config: { entry, show: PhiContentEntryPart.Link },
+            },
+            {
+                typeKey: "entry-list",
+                id: widgets.widgetRelated,
+                label: `pub ${kind} related widget`,
+                config: {
+                    kind,
+                    source: "related",
+                    relatedTo: entry,
+                    presentation: related.presentation,
+                    ...listPartsFor(related.presentation),
+                    title: related.title,
+                    limit: PHI_CONTENT_ENTRY_RELATED_LIMIT,
+                    // Each entry links to its own detail Page -- this one's route, filled with the related entry's slug.
+                    detailLinkTarget: {
+                        kind: "page",
+                        reference: createPhiPageReference({ kind: "module", ownerModuleId, presetKey }),
+                    },
+                },
+            },
+        ]),
+    };
+}

package/components/regions/presets/phi-area-root-redirect-tree.js

@@ -1,4 +1,4 @@
-import { resolvePhiCmsActiveNavigationSurfaces } from "../../../plugins/runtime-modules/descriptor-compiler";
+import { compilePhiCmsActiveRouteTable, resolvePhiCmsActiveNavigationSurfaces, } from "../../../plugins/runtime-modules/descriptor-compiler";
 import { buildPhiCmsEmptyPageTree, buildPhiCmsRedirectPageTree, findFirstPhiCmsNavigationLinkPath, } from "./navigation-redirect";
 /**
  * The default an Area root resolves to.
@@ -25,10 +25,16 @@ export function buildPhiAreaRootRedirectTree({ page, catalog, activeModuleIds, a
      * surface here would give two people in the same Area two different roots -- and it is what made the
      * root a viewer-dependent answer, which ACCESS.md now forbids and which the proxy cannot cache.
      */
+    /*
+     * Compiled here from what the build context carries. This tree is the Area's own root and is served
+     * only while no Site answer changed the table -- a chosen root applicant replaces it, and Public, the
+     * one Area with assignable addresses, has no sidebar root -- so the plain compile is the table.
+     */
     const surface = resolvePhiCmsActiveNavigationSurfaces({
         catalog,
         area,
         activeModuleIds,
+        routeTable: compilePhiCmsActiveRouteTable({ catalog, area, activeModuleIds }),
     }).find((candidate) => candidate.navKey === navKey);
     const targetPath = surface
         ? findFirstPhiCmsNavigationLinkPath(surface.items, page.path)

package/components/regions/presets/phi-area-shell-preset-nodes.d.ts

@@ -0,0 +1,49 @@
+import type { PhiCmsPresetPageNodes } from "../../../helpers/cms-preset-nodes";
+import type { PhiBlockRuntime } from "../../../types";
+import type { PhiCmsContentWidgetNode, PhiCmsLayoutNode, PhiCmsRegionNode } from "../../../types/cms";
+import type { PhiCmsInstanceId } from "../../../types/cms-instance-id";
+export type PhiAreaShellPresetNodes = {
+    regions: PhiCmsRegionNode[];
+    layoutNodes: PhiCmsLayoutNode[];
+    contentWidgets: PhiCmsContentWidgetNode[];
+};
+/**
+ * The shell an administrative Area carries: one top band with the Tour button at the left, the page title in
+ * the middle and the account at the right, and a left Sider with the Area's navigation.
+ *
+ * The page title had a main band of its own under the top band, which held nothing else; it now stands in
+ * the top band's middle, and the band under it is gone.
+ *
+ * Admin and Editor built this from the same 150 lines with their own ids and labels, and App its Sider a
+ * third time; a change to the Sider's collapsing or the header's padding had to be made three times and
+ * was made in one. The ids stay the Module's: a node id is derived from Module, preset and node key, so
+ * each Module hands in its own map and the tree it gets is its own.
+ */
+export declare function buildPhiAreaShellHeaderNodes({ nodes, runtime, labelPrefix, ids, }: {
+    nodes: PhiCmsPresetPageNodes;
+    runtime: PhiBlockRuntime;
+    /** The word the Builder shows in front of each node label: "admin", "editor". */
+    labelPrefix: string;
+    ids: {
+        regionHeaderTop: number;
+        layoutHeaderTop: PhiCmsInstanceId;
+        layoutHeaderTopActions: PhiCmsInstanceId;
+        widgetHeaderTopPageTitle: PhiCmsInstanceId;
+        widgetHeaderTopTourButton: PhiCmsInstanceId;
+        widgetHeaderTopAccount: PhiCmsInstanceId;
+    };
+}): PhiAreaShellPresetNodes;
+/** The left Sider with the Area's navigation, whose entries come from the navigation behind `navKey`. */
+export declare function buildPhiAreaShellSiderLeftNodes({ nodes, runtime, labelPrefix, navKey, ids, }: {
+    nodes: PhiCmsPresetPageNodes;
+    runtime: PhiBlockRuntime;
+    labelPrefix: string;
+    navKey: string;
+    ids: {
+        regionSiderLeft: number;
+        layoutSiderLeft: PhiCmsInstanceId;
+        widgetSiderLeftNav: PhiCmsInstanceId;
+    };
+}): PhiAreaShellPresetNodes;
+/** Several node groups as one tree body, in the order given. */
+export declare function concatPhiAreaShellPresetNodes(...groups: PhiAreaShellPresetNodes[]): PhiAreaShellPresetNodes;

package/components/regions/presets/phi-area-shell-preset-nodes.js

@@ -0,0 +1,160 @@
+import { PHI_CMS_DEFAULT_SLOT_INDEX, PHI_CMS_SEQUENTIAL_LAYOUT_SLOTS, PHI_CMS_THREE_COLUMN_LAYOUT_SLOT_INDEX, } from "../../../constants/cms-layout-types";
+import { PhiCmsFlags, PhiCmsRegionType } from "../../../constants/phi-cms";
+import { resolvePhiShellHeaderHeight, resolvePhiShellMetric } from "../../../helpers/shell-region-style";
+import { PHI_LAYOUT } from "../../../theme/phi-tokens";
+import { PHI_SPACE } from "../../../theme/antd-css-var-contract";
+import { buildPhiHeaderTopActionsLayoutNode } from "./phi-header-top-actions-layout";
+/**
+ * The shell an administrative Area carries: one top band with the Tour button at the left, the page title in
+ * the middle and the account at the right, and a left Sider with the Area's navigation.
+ *
+ * The page title had a main band of its own under the top band, which held nothing else; it now stands in
+ * the top band's middle, and the band under it is gone.
+ *
+ * Admin and Editor built this from the same 150 lines with their own ids and labels, and App its Sider a
+ * third time; a change to the Sider's collapsing or the header's padding had to be made three times and
+ * was made in one. The ids stay the Module's: a node id is derived from Module, preset and node key, so
+ * each Module hands in its own map and the tree it gets is its own.
+ */
+export function buildPhiAreaShellHeaderNodes({ nodes, runtime, labelPrefix, ids, }) {
+    const shell = runtime.site.theme?.shell;
+    return {
+        regions: [
+            nodes.region({
+                id: ids.regionHeaderTop,
+                regionType: PhiCmsRegionType.HeaderTop,
+                rootLayoutNodeId: ids.layoutHeaderTop,
+                sortOrder: 10,
+                // Structure only: the frame's look is the Theme's (SHELL.md, Shell Chrome Overlay).
+                // Sticky: it carries the page title, which stays in view while the content scrolls.
+                config: {
+                    flags: PhiCmsFlags.Sticky,
+                    size: { height: `${resolvePhiShellHeaderHeight(shell, "top")}px` },
+                    offsetTop: 0,
+                },
+            }),
+        ],
+        layoutNodes: [
+            nodes.layout({
+                creationPreset: { layoutKind: "threecol", preset: "panel" },
+                typeKey: "three-column",
+                id: ids.layoutHeaderTop,
+                parentLayoutNodeId: null,
+                slotIndex: PHI_CMS_DEFAULT_SLOT_INDEX,
+                sortOrder: 0,
+                label: `${labelPrefix} header top three column`,
+                config: {
+                    balancedSides: true,
+                    contentAlign: "center",
+                    paddingLeft: PHI_SPACE.base,
+                    paddingRight: PHI_SPACE.base,
+                },
+            }),
+            buildPhiHeaderTopActionsLayoutNode(nodes, {
+                id: ids.layoutHeaderTopActions,
+                parentLayoutNodeId: ids.layoutHeaderTop,
+                label: `${labelPrefix} header top actions`,
+            }),
+        ],
+        contentWidgets: [
+            /*
+             * The Tour button is Core's, so this Shell does not depend on the Tour Module. It shows only on a
+             * Page that carries a Tour and only while the Tour Module answers for the Area; otherwise it draws
+             * nothing.
+             */
+            nodes.widget({
+                typeKey: "tour-button",
+                id: ids.widgetHeaderTopTourButton,
+                parentLayoutNodeId: ids.layoutHeaderTop,
+                slotIndex: PHI_CMS_THREE_COLUMN_LAYOUT_SLOT_INDEX.Left,
+                sortOrder: 0,
+                label: `${labelPrefix} header top tour button`,
+                config: {},
+            }),
+            nodes.widget({
+                typeKey: "page-title",
+                id: ids.widgetHeaderTopPageTitle,
+                parentLayoutNodeId: ids.layoutHeaderTop,
+                slotIndex: PHI_CMS_THREE_COLUMN_LAYOUT_SLOT_INDEX.Middle,
+                sortOrder: 0,
+                label: "Page title",
+                config: {},
+            }),
+            nodes.widget({
+                typeKey: "account",
+                id: ids.widgetHeaderTopAccount,
+                parentLayoutNodeId: ids.layoutHeaderTopActions,
+                slotIndex: PHI_CMS_SEQUENTIAL_LAYOUT_SLOTS[2].slotIndex,
+                sortOrder: 20,
+                label: `${labelPrefix} header top account`,
+                config: {},
+            }),
+        ],
+    };
+}
+/** The left Sider with the Area's navigation, whose entries come from the navigation behind `navKey`. */
+export function buildPhiAreaShellSiderLeftNodes({ nodes, runtime, labelPrefix, navKey, ids, }) {
+    const shell = runtime.site.theme?.shell;
+    const shellSiderLeftOffsetTop = resolvePhiShellMetric(shell, "offsetTop", { family: "sider", region: "left" });
+    const resolvedShellLeftWidth = resolvePhiShellMetric(shell, "width", { family: "sider", region: "left" }) ?? PHI_LAYOUT.sidebarWidth;
+    return {
+        regions: [
+            nodes.region({
+                id: ids.regionSiderLeft,
+                regionType: PhiCmsRegionType.SiderLeft,
+                rootLayoutNodeId: ids.layoutSiderLeft,
+                // Between the header and the content, which is where it is read.
+                sortOrder: 25,
+                // Structure only: the frame's look is the Theme's (SHELL.md, Shell Chrome Overlay).
+                config: {
+                    flags: PhiCmsFlags.Sticky | PhiCmsFlags.FullHeight | PhiCmsFlags.Collapsible,
+                    size: { width: `${resolvedShellLeftWidth}px` },
+                    ...(typeof shellSiderLeftOffsetTop === "number" ? { offsetTop: shellSiderLeftOffsetTop } : { offsetTop: 0 }),
+                },
+            }),
+        ],
+        layoutNodes: [
+            nodes.layout({
+                creationPreset: { layoutKind: "verticalflex", preset: "panel" },
+                typeKey: "flex-vertical",
+                id: ids.layoutSiderLeft,
+                parentLayoutNodeId: null,
+                slotIndex: PHI_CMS_DEFAULT_SLOT_INDEX,
+                sortOrder: 0,
+                label: `${labelPrefix} sider left stack`,
+                config: {
+                    anchor: {
+                        horizontal: "center",
+                        vertical: "top",
+                    },
+                    gap: 0,
+                    padding: PHI_SPACE.xs,
+                    paddingTop: 0,
+                },
+            }),
+        ],
+        contentWidgets: [
+            nodes.widget({
+                typeKey: "sidebar-navigation",
+                id: ids.widgetSiderLeftNav,
+                parentLayoutNodeId: ids.layoutSiderLeft,
+                slotIndex: PHI_CMS_DEFAULT_SLOT_INDEX,
+                sortOrder: 0,
+                label: `${labelPrefix} sider left navigation`,
+                config: {
+                    side: "left",
+                    width: resolvedShellLeftWidth,
+                    navKey,
+                },
+            }),
+        ],
+    };
+}
+/** Several node groups as one tree body, in the order given. */
+export function concatPhiAreaShellPresetNodes(...groups) {
+    return {
+        regions: groups.flatMap((group) => group.regions),
+        layoutNodes: groups.flatMap((group) => group.layoutNodes),
+        contentWidgets: groups.flatMap((group) => group.contentWidgets),
+    };
+}

package/components/regions/presets/phi-base-page-column.d.ts

@@ -0,0 +1,26 @@
+import type { PhiCmsInstanceId } from "../../../types/cms-instance-id";
+import type { PhiCmsPageNode } from "../../../types/cms";
+/**
+ * A module Page's content as one column on the base scaffold: the Region, the scaffold, and a vertical
+ * Flex in it that stops at `maxWidth` and wears the wash (LAYOUTING.md; `CONTENT_ENTRIES.md`, The frame).
+ *
+ * The scaffold spans the content Region, carries the page's padding and anchors what stands in it to the
+ * centre, so the column only says where it stops. The width is a maximum: on a phone the column fills the
+ * screen. Its corners are the Theme's -- the wash states no line, and a Surface without its own line takes
+ * the Site's surface step.
+ *
+ * A vertical Flex rather than the `content` Layout, because `content` has a single slot and a second
+ * Widget placed in it is dropped without a word; a column of a page is a sequence. The caller places its
+ * Widgets in the column by `columnId`, in slots from 0.
+ */
+export declare function buildPhiBasePageColumnFrame({ page, regionId, columnId, label, maxWidth, }: {
+    page: PhiCmsPageNode;
+    regionId: number;
+    columnId: PhiCmsInstanceId;
+    label: string;
+    /** Where the column stops, a `PHI_LAYOUT` measure: `readingMax` for prose, `contentMaxWide` for a page. */
+    maxWidth: number;
+}): {
+    regions: import("../../../types").PhiCmsRegionNode[];
+    layoutNodes: import("../../../types").PhiCmsLayoutNode[];
+};

package/components/regions/presets/phi-base-page-column.js

@@ -0,0 +1,42 @@
+import { PHI_CMS_DEFAULT_SLOT_INDEX } from "../../../constants/cms-layout-types";
+import { createPhiCmsPresetNodes } from "../../../helpers/cms-preset-nodes";
+import { PHI_SURFACE_WASH } from "../../../helpers/surface-presets";
+import { PHI_SPACE } from "../../../theme/antd-css-var-contract";
+import { buildPhiBasePageContentScaffold, PHI_BASE_PAGE_LAYOUT_NODE_ID, } from "./phi-base-page-layout";
+/**
+ * A module Page's content as one column on the base scaffold: the Region, the scaffold, and a vertical
+ * Flex in it that stops at `maxWidth` and wears the wash (LAYOUTING.md; `CONTENT_ENTRIES.md`, The frame).
+ *
+ * The scaffold spans the content Region, carries the page's padding and anchors what stands in it to the
+ * centre, so the column only says where it stops. The width is a maximum: on a phone the column fills the
+ * screen. Its corners are the Theme's -- the wash states no line, and a Surface without its own line takes
+ * the Site's surface step.
+ *
+ * A vertical Flex rather than the `content` Layout, because `content` has a single slot and a second
+ * Widget placed in it is dropped without a word; a column of a page is a sequence. The caller places its
+ * Widgets in the column by `columnId`, in slots from 0.
+ */
+export function buildPhiBasePageColumnFrame({ page, regionId, columnId, label, maxWidth, }) {
+    const scaffold = buildPhiBasePageContentScaffold({ page, regionId });
+    return {
+        regions: [scaffold.region],
+        layoutNodes: [
+            scaffold.layoutNode,
+            createPhiCmsPresetNodes(page).layout({
+                creationPreset: { layoutKind: "verticalflex", preset: "panel" },
+                typeKey: "flex-vertical",
+                id: columnId,
+                parentLayoutNodeId: PHI_BASE_PAGE_LAYOUT_NODE_ID,
+                slotIndex: PHI_CMS_DEFAULT_SLOT_INDEX,
+                label,
+                config: {
+                    maxSize: { width: maxWidth },
+                    surface: PHI_SURFACE_WASH,
+                    padding: PHI_SPACE.md,
+                    // The house step between a preset's children; the Widgets keep their own air inside.
+                    gap: PHI_SPACE.sm,
+                },
+            }),
+        ],
+    };
+}

package/components/regions/presets/phi-base-page-layout.d.ts

@@ -13,14 +13,14 @@ import type { PhiCmsLayoutNode, PhiCmsPageNode, PhiCmsRegionNode } from "../../.
  *
  * Bump {@link PHI_BASE_PAGE_LAYOUT_VERSION} when the canonical node changes: every preset built on
  * the scaffold folds it into its `presetVersion`, which is how overridden copies learn about the
- * update. The Settings pages (their own Collapsible shell) and the public/auth pages (landing
- * chrome, centered panels) do not use the scaffold yet.
+ * update. Every module Page stands on it -- the Settings pages with their Collapsible inside, the Public
+ * and auth pages with their column, card or result inside (`phi-base-page-column.ts` for a column on the
+ * wash). The Landing never does: it has its own chrome.
  *
  * Version 3: the content Region no longer carries a reading width (`maxSize`); it spans the page.
  */
 export declare const PHI_BASE_PAGE_LAYOUT_VERSION = 3;
 export declare const PHI_BASE_PAGE_LAYOUT_NODE_ID: import("@phis/contracts/cms").PhiCmsInstanceId;
-export declare const PHI_BASE_PAGE_LAYOUT_LABEL = "Page content";
 /** The canonical scaffold node; `visibilityMask` and `siteId` are the page's, everything else is fixed. */
 export declare function buildPhiBasePageLayoutNode(page: PhiCmsPageNode): PhiCmsLayoutNode;
 /**

package/components/regions/presets/phi-base-page-layout.js

@@ -17,8 +17,9 @@ import { createPhiPresetCmsInstanceId } from "../../../types/cms-instance-id";
  *
  * Bump {@link PHI_BASE_PAGE_LAYOUT_VERSION} when the canonical node changes: every preset built on
  * the scaffold folds it into its `presetVersion`, which is how overridden copies learn about the
- * update. The Settings pages (their own Collapsible shell) and the public/auth pages (landing
- * chrome, centered panels) do not use the scaffold yet.
+ * update. Every module Page stands on it -- the Settings pages with their Collapsible inside, the Public
+ * and auth pages with their column, card or result inside (`phi-base-page-column.ts` for a column on the
+ * wash). The Landing never does: it has its own chrome.
  *
  * Version 3: the content Region no longer carries a reading width (`maxSize`); it spans the page.
  */
@@ -33,7 +34,7 @@ export const PHI_BASE_PAGE_LAYOUT_NODE_ID = createPhiPresetCmsInstanceId({
     presetKey: "page-base-layout",
     nodeKey: "layoutContent",
 });
-export const PHI_BASE_PAGE_LAYOUT_LABEL = "Page content";
+const PHI_BASE_PAGE_LAYOUT_LABEL = "Page content";
 /** The canonical scaffold node; `visibilityMask` and `siteId` are the page's, everything else is fixed. */
 export function buildPhiBasePageLayoutNode(page) {
     return createPhiCmsPresetNodes(page).layout({