@phis/ui 0.2.0 → 0.3.0

package/gateway/user-state.js

@@ -1,34 +1,22 @@
-import { cache } from "react";
+import { isPhiRecord } from "../helpers/is-record";
+import { definePhiRequestMemo } from "../server-helpers/request-memo";
 import "server-only";
-import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
 import { isPhisUserStateKey } from "../constants/user-state";
-import { throwPhiCmsGatewayError } from "./errors";
-export const getPhiUserState = cache(async function getPhiUserState({ apiBaseUrl, internalToken, siteKey, cookieHeader, }) {
-    if (!apiBaseUrl.trim()) {
-        throw new Error("Missing apiBaseUrl for getPhiUserState.");
-    }
-    if (!internalToken.trim()) {
-        throw new Error("Missing internalToken for getPhiUserState.");
-    }
+import { fetchPhiSiteApi } from "./site-api-request";
+export const getPhiUserState = definePhiRequestMemo(async function getPhiUserState({ apiBaseUrl, internalToken, siteKey, cookieHeader, }) {
     if (!cookieHeader.trim()) {
         throw new Error("User state needs the viewer's session.");
     }
-    const response = await fetch(buildApiUrl(apiBaseUrl, "/api/site/user-state"), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            includeToken: true,
-            includeSiteKey: true,
-            gateway: true,
-            cookie: cookieHeader,
-        }),
-        cache: "no-store",
+    const payload = await fetchPhiSiteApi({
+        context: "getPhiUserState",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/site/user-state",
+        cookieHeader,
+        failure: "Failed to read user state",
     });
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to read user state (${response.status}).`, response.status);
-    }
-    const payload = (await response.json());
-    if (!payload.state || typeof payload.state !== "object" || Array.isArray(payload.state)) {
+    if (!isPhiRecord(payload?.state)) {
         throw new Error("User state answered without a state object.");
     }
     /*
@@ -39,7 +27,7 @@ export const getPhiUserState = cache(async function getPhiUserState({ apiBaseUrl
      * reader from having to wonder, and there is nothing a caller could do with it anyway.
      */
     const state = {};
-    for (const [key, value] of Object.entries(payload.state)) {
+    for (const [key, value] of Object.entries(payload?.state)) {
         if (isPhisUserStateKey(key)) {
             state[key] = value;
         }

package/helpers/access.d.ts

@@ -1,6 +1 @@
-export type ResolvedCmsPath = {
-    areaMask: number;
-    path: string;
-};
 export declare function resolveAreaFromPath(path: string | null | undefined): number;
-export declare function resolveCmsPath(path: string | null | undefined): ResolvedCmsPath;

package/helpers/access.js

@@ -21,22 +21,3 @@ export function resolveAreaFromPath(path) {
     }
     return PhiCmsVisibilityContext.PublicArea;
 }
-export function resolveCmsPath(path) {
-    const normalized = normalizeRequestPath(path);
-    const segments = normalized === "/" ? [] : normalized.slice(1).split("/");
-    const areaMask = resolveAreaFromPath(normalized);
-    if (segments.length === 0) {
-        return { areaMask, path: "/" };
-    }
-    const first = segments[0]?.toLowerCase();
-    const knownArea = first === "app" ||
-        first === "admin" ||
-        first === "builder" ||
-        first === "editor" ||
-        first === "accounting";
-    if (!knownArea) {
-        return { areaMask, path: normalized };
-    }
-    const remaining = segments.slice(1).join("/");
-    return { areaMask, path: remaining ? `/${remaining}` : "/" };
-}

package/helpers/antd-locale.d.ts

@@ -1,5 +1,2 @@
 import type { Locale } from "antd/es/locale";
-type PhiAntdLocaleKey = "ar_EG" | "bg_BG" | "cs_CZ" | "da_DK" | "de_DE" | "el_GR" | "en_GB" | "en_US" | "es_ES" | "es_US" | "et_EE" | "fi_FI" | "fr_FR" | "he_IL" | "hu_HU" | "id_ID" | "it_IT" | "ja_JP" | "ko_KR" | "lt_LT" | "lv_LV" | "nb_NO" | "nl_NL" | "pl_PL" | "pt_BR" | "pt_PT" | "ro_RO" | "ru_RU" | "sk_SK" | "sl_SI" | "sv_SE" | "th_TH" | "tr_TR" | "uk_UA" | "vi_VN" | "zh_CN" | "zh_TW";
-export declare function resolvePhiAntdLocaleKey(locale: string | null | undefined): PhiAntdLocaleKey;
 export declare function loadPhiAntdLocale(locale: string | null | undefined): Promise<Locale>;
-export {};

package/helpers/antd-locale.js

@@ -1,10 +1,8 @@
-function normalizeLocaleKey(input) {
-    return input?.trim().replace(/_/g, "-").toLowerCase() ?? "";
-}
+import { normalizePhiLocaleKey } from "./locale";
 const PHI_ANTD_LOCALE_KEY_BY_LOCALE = new Map();
 function registerAntdLocaleKey(key, locales) {
     for (const locale of locales) {
-        const normalized = normalizeLocaleKey(locale);
+        const normalized = normalizePhiLocaleKey(locale);
         if (normalized) {
             PHI_ANTD_LOCALE_KEY_BY_LOCALE.set(normalized, key);
         }
@@ -86,8 +84,8 @@ const PHI_ANTD_LOCALE_LOADERS = {
     zh_CN: () => import("antd/locale/zh_CN"),
     zh_TW: () => import("antd/locale/zh_TW"),
 };
-export function resolvePhiAntdLocaleKey(locale) {
-    const normalized = normalizeLocaleKey(locale);
+function resolvePhiAntdLocaleKey(locale) {
+    const normalized = normalizePhiLocaleKey(locale);
     return PHI_ANTD_LOCALE_KEY_BY_LOCALE.get(normalized) ?? "en_GB";
 }
 export async function loadPhiAntdLocale(locale) {

package/helpers/cms-area-config.d.ts

@@ -17,16 +17,6 @@ import { type PhiPageReference } from "../types/references";
  */
 export declare const PHI_AREA_CONFIG_SHELL_NAMESPACE: "shell";
 export declare const PHI_AREA_CONFIG_MODULES_NAMESPACE: "modules";
-export type PhiAreaConfigNamespace = typeof PHI_AREA_CONFIG_SHELL_NAMESPACE | typeof PHI_AREA_CONFIG_MODULES_NAMESPACE;
-export declare function readPhiAreaConfigNamespace(config: Record<string, unknown> | null | undefined, namespace: PhiAreaConfigNamespace): Record<string, unknown> | undefined;
-/**
- * The Module selection an Area preset carries.
- *
- * `runtimeModuleIds` is the resolved field the payload already carries when it has one; the stored
- * config is what a Site that persisted its Area falls back to. Both readings sit here so the namespace
- * appears once rather than at every call site that needs the selection.
- */
-export declare function readPhiAreaPresetRuntimeModules(tree: Pick<PhiResolvedCmsAreaPresetTree, "runtimeModuleIds" | "preset"> | null | undefined): unknown;
 /**
  * The Modules an Area preset actually activates.
  *
@@ -59,7 +49,21 @@ export type PhiAreaRootRoute = {
     target?: PhiPageReference;
 } | {
     mode: "redirect";
-    target: PhiPageReference;
+    targetLinkTarget: PhiAreaRootRouteTarget;
+};
+/**
+ * Where a forwarding root leads: a Page and nothing else.
+ *
+ * The two modes name a Page for different reasons, and that is why they keep it under different keys.
+ * A landing's `target` chooses which Module's applicant stands in the slot -- a choice among Modules,
+ * compared by identity and never followed, and a Module Page is never indexed anyway. A redirect's
+ * target is somewhere the visitor is sent, so it is stored the way every persisted target is, under a
+ * `*LinkTarget` key, and the reference index sees it (REFERENCES.md). It carries the Page alone: a
+ * forward has no fragment, no parameters, no new tab, and it never leaves its Area.
+ */
+export type PhiAreaRootRouteTarget = {
+    kind: "page";
+    reference: PhiPageReference;
 };
 export declare function readPhiAreaRootRoute(config: Record<string, unknown> | null | undefined): PhiAreaRootRoute | null;
 /**

package/helpers/cms-area-config.js

@@ -1,6 +1,7 @@
+import { isPhiRecord } from "./is-record";
 import { createPhiDefaultAreaRuntimeModuleIds } from "../plugins/runtime-modules/area-module-defaults";
 import { readPhiRuntimeModuleIds } from "../plugins/runtime-modules/settings";
-import { createPhiPresetCmsPageId, readPhiPageReference, } from "../types/references";
+import { createPhiPresetCmsPageId, readPhiLinkTarget, readPhiPageReference, } from "../types/references";
 /**
  * The two halves of an Area preset config, expressed as a path rather than as a list of field names.
  *
@@ -15,9 +16,9 @@ import { createPhiPresetCmsPageId, readPhiPageReference, } from "../types/refere
  */
 export const PHI_AREA_CONFIG_SHELL_NAMESPACE = "shell";
 export const PHI_AREA_CONFIG_MODULES_NAMESPACE = "modules";
-export function readPhiAreaConfigNamespace(config, namespace) {
+function readPhiAreaConfigNamespace(config, namespace) {
     const value = config?.[namespace];
-    return value && typeof value === "object" && !Array.isArray(value)
+    return isPhiRecord(value)
         ? value
         : undefined;
 }
@@ -28,7 +29,7 @@ export function readPhiAreaConfigNamespace(config, namespace) {
  * config is what a Site that persisted its Area falls back to. Both readings sit here so the namespace
  * appears once rather than at every call site that needs the selection.
  */
-export function readPhiAreaPresetRuntimeModules(tree) {
+function readPhiAreaPresetRuntimeModules(tree) {
     return tree?.runtimeModuleIds
         ?? readPhiAreaConfigNamespace(tree?.preset.config, PHI_AREA_CONFIG_MODULES_NAMESPACE)?.runtimeModules;
 }
@@ -52,7 +53,7 @@ export function readPhiAreaPresetRuntimeModuleIds(tree, area) {
 export const PHI_AREA_ROOT_ROUTE_KEY = "rootRoute";
 export function readPhiAreaRootRoute(config) {
     const value = readPhiAreaConfigNamespace(config, PHI_AREA_CONFIG_SHELL_NAMESPACE)?.[PHI_AREA_ROOT_ROUTE_KEY];
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const record = value;
@@ -70,10 +71,12 @@ export function readPhiAreaRootRoute(config) {
     if (record.mode !== "redirect") {
         return null;
     }
-    // An unreadable reference is the same answer as none: the preset decides, and the Builder sees the
+    // An unreadable target is the same answer as none: the preset decides, and the Builder sees the
     // selector fall back to what actually happens rather than to what was stored.
-    const reference = readPhiPageReference(record.target);
-    return reference ? { mode: "redirect", target: reference.reference } : null;
+    const target = readPhiLinkTarget(record.targetLinkTarget);
+    return target?.kind === "page"
+        ? { mode: "redirect", targetLinkTarget: { kind: "page", reference: target.reference } }
+        : null;
 }
 export function readPhiAreaLandingSelection(config) {
     return resolvePhiAreaLandingSelection(readPhiAreaRootRoute(config));
@@ -165,7 +168,7 @@ export const PHI_AREA_META_PUBLIC_DEFAULTS = { index: true, sitemap: true };
 export const PHI_AREA_TITLE_TEMPLATE_PLACEHOLDER = "%s";
 export function readPhiAreaMeta(config) {
     const value = readPhiAreaConfigNamespace(config, PHI_AREA_CONFIG_SHELL_NAMESPACE)?.[PHI_AREA_META_KEY];
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const record = value;
@@ -195,7 +198,7 @@ export function isPhiAssignablePublicRoutePath(value) {
         segments.slice(1).every((segment) => PHI_PUBLIC_ROUTE_PATH_SEGMENT_PATTERN.test(segment));
 }
 function readPublicRoutePathAssignment(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const record = value;

package/helpers/cms-area-root-route.d.ts

@@ -1,6 +1,6 @@
 import type { PhiCmsAreaKey } from "../constants/cms-areas";
 import type { PhiResolvedCmsPagePayload, PhiResolvedCmsPageTree } from "../types/cms";
-import type { PhiCmsCompiledDescriptorCatalog, PhiRuntimeModuleId } from "../types/cms-module-descriptors";
+import type { PhiCmsActiveRouteTable } from "../types/cms-module-descriptors";
 import { type PhiPageReference } from "../types/references";
 /**
  * The Area root, as the Builder configured it.
@@ -27,11 +27,10 @@ export type PhiAreaRootRouteDecision = {
  * Not against the viewer. This is what an Area's root forwards to, and a front door that moved with the
  * reader is the thing ACCESS.md forbids.
  */
-export declare function resolvePhiAreaModulePageReferencePath({ reference, area, catalog, activeModuleIds, }: {
+export declare function resolvePhiAreaModulePageReferencePath({ reference, routeTable, }: {
     reference: PhiPageReference;
-    area: PhiCmsAreaKey;
-    catalog: PhiCmsCompiledDescriptorCatalog;
-    activeModuleIds: ReadonlySet<PhiRuntimeModuleId>;
+    /** The Area's active route table: a Page not in it is not served, and a Page in it answers on its path. */
+    routeTable: PhiCmsActiveRouteTable;
 }): string | null;
 /**
  * The decision, applied to whatever the ordinary resolution produced.

package/helpers/cms-area-root-route.js

@@ -1,5 +1,4 @@
 import { PhiCmsPageType, PhiCmsStatus } from "../constants/phi-cms";
-import { resolvePhiCmsRouteDescriptorByPageId } from "../plugins/runtime-modules/descriptor-compiler";
 import { readPhiPageReference } from "../types/references";
 /**
  * A reference to a Page a Module carries, as the Area-relative path it names.
@@ -11,15 +10,12 @@ import { readPhiPageReference } from "../types/references";
  * Not against the viewer. This is what an Area's root forwards to, and a front door that moved with the
  * reader is the thing ACCESS.md forbids.
  */
-export function resolvePhiAreaModulePageReferencePath({ reference, area, catalog, activeModuleIds, }) {
+export function resolvePhiAreaModulePageReferencePath({ reference, routeTable, }) {
     const parsed = readPhiPageReference(reference);
     if (parsed?.target.kind !== "module") {
         return null;
     }
-    const route = resolvePhiCmsRouteDescriptorByPageId(catalog, parsed.target.pageId);
-    return route && route.area === area && activeModuleIds.has(route.ownerModuleId)
-        ? route.path
-        : null;
+    return routeTable.byPageId.get(parsed.target.pageId)?.path ?? null;
 }
 /**
  * The decision, applied to whatever the ordinary resolution produced.

package/helpers/cms-config-field-validation.d.ts

@@ -1,6 +1,10 @@
 import type { PhiCmsConfigField } from "../types/cms-plugins";
-export declare function readPhiCmsConfigFieldViolation(field: PhiCmsConfigField, value: unknown): string | null;
-export declare function findPhiCmsConfigViolations(fields: readonly PhiCmsConfigField[], config: Record<string, unknown>): string[];
+/**
+ * The fields `config` gets wrong. With `previous`, only the fields this write changes are judged: a
+ * value stored before an option was withdrawn would otherwise refuse every later edit of the node,
+ * including the one that corrects it.
+ */
+export declare function findPhiCmsConfigViolations(fields: readonly PhiCmsConfigField[], config: Record<string, unknown>, previous?: Record<string, unknown>): string[];
 /**
  * The write itself, refused loudly.
  *
@@ -8,4 +12,4 @@ export declare function findPhiCmsConfigViolations(fields: readonly PhiCmsConfig
  * does not take, and nothing says why. A throw reaches the console with the field named, and the
  * edit visibly does not apply.
  */
-export declare function assertPhiCmsConfigFields(fields: readonly PhiCmsConfigField[], config: Record<string, unknown>, label: string): void;
+export declare function assertPhiCmsConfigFields(fields: readonly PhiCmsConfigField[], config: Record<string, unknown>, label: string, previous?: Record<string, unknown>): void;

package/helpers/cms-config-field-validation.js

@@ -21,7 +21,7 @@ function optionValues(field) {
 function describe(value) {
     return typeof value === "string" ? JSON.stringify(value) : String(value);
 }
-export function readPhiCmsConfigFieldViolation(field, value) {
+function readPhiCmsConfigFieldViolation(field, value) {
     // Absent is not wrong. A key nobody wrote leaves the decision to the Widget's own defaults, and
     // clearing a setting has to stay possible.
     if (value === undefined || value === null)
@@ -50,6 +50,22 @@ export function readPhiCmsConfigFieldViolation(field, value) {
                 ? null
                 : `${field.key} must list whole numbers${field.min !== undefined ? ` of at least ${field.min}` : ""}, not ${describe(stray)}.`;
         }
+        case "slot-texts": {
+            if (!Array.isArray(value)) {
+                return `${field.key} must be a list of texts, not ${describe(value)}.`;
+            }
+            const stray = value.find((item) => typeof item !== "string");
+            return stray === undefined ? null : `${field.key} must list texts, not ${describe(stray)}.`;
+        }
+        case "flags": {
+            if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+                return `${field.key} must be a whole number of flags, not ${describe(value)}.`;
+            }
+            const known = field.options.reduce((mask, option) => mask | option.value, 0);
+            return (value & ~known) === 0
+                ? null
+                : `${field.key} sets flags no option names: ${value & ~known}.`;
+        }
         case "choice": {
             /*
              * Only a closed list can be checked. A field whose options are fetched, or which accepts what
@@ -72,11 +88,36 @@ export function readPhiCmsConfigFieldViolation(field, value) {
             return null;
     }
 }
-export function findPhiCmsConfigViolations(fields, config) {
+/*
+ * A field's value where its key is a dot path (`presentation.controlSize`), and whether the config states
+ * it at all. Reading only top-level keys left every nested field unchecked.
+ */
+function readStatedConfigValue(config, key) {
+    let current = config;
+    for (const segment of key.split(".")) {
+        if (current === null || typeof current !== "object" || !Object.prototype.hasOwnProperty.call(current, segment)) {
+            return { stated: false, value: undefined };
+        }
+        current = current[segment];
+    }
+    return { stated: true, value: current };
+}
+/**
+ * The fields `config` gets wrong. With `previous`, only the fields this write changes are judged: a
+ * value stored before an option was withdrawn would otherwise refuse every later edit of the node,
+ * including the one that corrects it.
+ */
+export function findPhiCmsConfigViolations(fields, config, previous) {
     return fields.flatMap((field) => {
-        if (!Object.prototype.hasOwnProperty.call(config, field.key))
+        const next = readStatedConfigValue(config, field.key);
+        if (!next.stated)
             return [];
-        const violation = readPhiCmsConfigFieldViolation(field, config[field.key]);
+        if (previous) {
+            const before = readStatedConfigValue(previous, field.key);
+            if (before.stated && JSON.stringify(before.value) === JSON.stringify(next.value))
+                return [];
+        }
+        const violation = readPhiCmsConfigFieldViolation(field, next.value);
         return violation ? [violation] : [];
     });
 }
@@ -87,8 +128,8 @@ export function findPhiCmsConfigViolations(fields, config) {
  * does not take, and nothing says why. A throw reaches the console with the field named, and the
  * edit visibly does not apply.
  */
-export function assertPhiCmsConfigFields(fields, config, label) {
-    const violations = findPhiCmsConfigViolations(fields, config);
+export function assertPhiCmsConfigFields(fields, config, label, previous) {
+    const violations = findPhiCmsConfigViolations(fields, config, previous);
     if (violations.length > 0) {
         throw new Error(`Invalid ${label} configuration. ${violations.join(" ")}`);
     }

package/helpers/cms-container-chrome.d.ts

@@ -1,3 +1,11 @@
-import type { CSSProperties } from "react";
 import type { PhiCmsContainerChromeConfig } from "../types/cms-container";
-export declare function resolvePhiCmsContainerChromeStyle(config: PhiCmsContainerChromeConfig): CSSProperties;
+import { type PhiResolvedSurface } from "./surface-style";
+/**
+ * An Overlay container's Surface, as the container draws it.
+ *
+ * The Surface resolver answers it like any other box's, with one difference that belongs to Overlays
+ * (OVERLAYS.md, "Chrome"): an omitted Background keeps the Overlay's own elevated ground, while a
+ * Background whose Base is `none` is a deliberate transparency and has to say so, or the ground beneath
+ * would show through as the default after all.
+ */
+export declare function resolvePhiCmsContainerSurface(config: PhiCmsContainerChromeConfig): PhiResolvedSurface;

package/helpers/cms-container-chrome.js

@@ -1,32 +1,23 @@
-import { resolvePhiBorderWidgetStyle } from "./border-widget-style";
-import { combinePhiBoxShadows, composePhiLayoutEffectStyle, resolvePhiLayoutEffectStyle, resolvePhiShadow, } from "./layout-style";
-import { resolvePhiBackgroundWidgetStyle } from "../components/widgets/config/background";
-export function resolvePhiCmsContainerChromeStyle(config) {
-    const backgroundStyle = config.backgroundConfig != null
-        ? config.backgroundConfig.base.kind === "none"
-            ? { background: "transparent" }
-            : resolvePhiBackgroundWidgetStyle({ ...config.backgroundConfig, effect: null })
-        : config.background == null
-            ? {}
-            : { background: config.background };
-    const effectStyle = resolvePhiLayoutEffectStyle({
-        effect: config.effect,
-        background: backgroundStyle.background ?? backgroundStyle.backgroundColor,
-    }) ?? {};
-    const borderStyle = config.border == null || config.border === false
-        ? {}
-        : config.border === true
-            ? resolvePhiBorderWidgetStyle(null, {
-                border: "1px solid var(--ant-color-border-secondary)",
-            })
-            : typeof config.border !== "object"
-                ? { border: config.border }
-                : resolvePhiBorderWidgetStyle(config.border);
-    const boxShadow = combinePhiBoxShadows(backgroundStyle.boxShadow, effectStyle.boxShadow, resolvePhiShadow(config.shadow));
-    const chromeStyle = composePhiLayoutEffectStyle(backgroundStyle, effectStyle);
-    return {
-        ...chromeStyle,
-        ...borderStyle,
-        ...(boxShadow == null ? {} : { boxShadow }),
-    };
+import { normalizePhiBackgroundWidgetConfig } from "../components/widgets/config/background";
+import { resolvePhiSurfaceStyle } from "./surface-style";
+/**
+ * An Overlay container's Surface, as the container draws it.
+ *
+ * The Surface resolver answers it like any other box's, with one difference that belongs to Overlays
+ * (OVERLAYS.md, "Chrome"): an omitted Background keeps the Overlay's own elevated ground, while a
+ * Background whose Base is `none` is a deliberate transparency and has to say so, or the ground beneath
+ * would show through as the default after all.
+ */
+export function resolvePhiCmsContainerSurface(config) {
+    const resolved = resolvePhiSurfaceStyle(config.surface, { groundLayer: false });
+    const background = config.surface?.background
+        ? normalizePhiBackgroundWidgetConfig(config.surface.background)
+        : null;
+    if (!background || background.base.kind !== "none" || background.overlay != null) {
+        return resolved;
+    }
+    const style = resolved.style.backgroundColor == null
+        ? { ...resolved.style, backgroundColor: "transparent" }
+        : resolved.style;
+    return { ...resolved, style };
 }

package/helpers/cms-content-binding.d.ts

@@ -0,0 +1,13 @@
+import type { PhiCmsContentWidgetNode } from "../types/cms";
+import type { PhiCmsWidgetContentBinding } from "../types/cms-plugins";
+/**
+ * The binding that applies to this config, or `null` where the Widget's current mode keeps nothing --
+ * a Markdown or HTML Widget reading a URL, an Image pointing at one.
+ */
+export declare function resolvePhiCmsWidgetContentBindingForConfig(binding: PhiCmsWidgetContentBinding | null | undefined, config: Record<string, unknown> | null | undefined): PhiCmsWidgetContentBinding | null;
+/**
+ * Whether a bound Widget has nothing to show on the live Site: no published content and no value of its
+ * own. That is a Widget the Site created whose content was never published -- the Builder's placeholder
+ * is not live until somebody publishes it. A preset node keeps its shipped value and is never empty.
+ */
+export declare function isPhiCmsWidgetContentUnpublished(binding: PhiCmsWidgetContentBinding | null | undefined, widget: Pick<PhiCmsContentWidgetNode, "config" | "resolvedContent">): boolean;

package/helpers/cms-content-binding.js

@@ -0,0 +1,32 @@
+/*
+ * A Widget's bound content (phis-server CONTENT.md): the config field it names in `contentBinding` is kept
+ * by phi-server apart from the tree, drafted and published apart from structure.
+ */
+function hasConfigValue(config, fieldKey) {
+    const value = config?.[fieldKey];
+    return typeof value === "string" ? value.trim().length > 0 : value != null;
+}
+/**
+ * The binding that applies to this config, or `null` where the Widget's current mode keeps nothing --
+ * a Markdown or HTML Widget reading a URL, an Image pointing at one.
+ */
+export function resolvePhiCmsWidgetContentBindingForConfig(binding, config) {
+    if (!binding)
+        return null;
+    if (binding.skipWhenConfigField && hasConfigValue(config, binding.skipWhenConfigField))
+        return null;
+    if (binding.skipWhenConfigFieldValue &&
+        config?.[binding.skipWhenConfigFieldValue.field] === binding.skipWhenConfigFieldValue.value) {
+        return null;
+    }
+    return binding;
+}
+/**
+ * Whether a bound Widget has nothing to show on the live Site: no published content and no value of its
+ * own. That is a Widget the Site created whose content was never published -- the Builder's placeholder
+ * is not live until somebody publishes it. A preset node keeps its shipped value and is never empty.
+ */
+export function isPhiCmsWidgetContentUnpublished(binding, widget) {
+    const applied = resolvePhiCmsWidgetContentBindingForConfig(binding, widget.config);
+    return applied != null && widget.resolvedContent == null && !hasConfigValue(widget.config, applied.sourceField);
+}

package/helpers/cms-dialog.d.ts

@@ -0,0 +1,51 @@
+/** The body Layout's config: a vertical Flex with the `panel` creation preset under it. */
+export declare const PHI_DIALOG_BODY_CONFIG: {
+    readonly gap: "var(--ant-padding-sm)";
+    readonly margin: 0;
+    readonly padding: "var(--ant-padding)";
+    readonly surface: {
+        readonly background: {
+            readonly base: {
+                readonly kind: "color";
+                readonly color: "var(--ant-color-fill-quaternary)";
+            };
+            readonly overlay: null;
+            readonly filter: null;
+        };
+        readonly borderSource: "none";
+        readonly shadow: "none";
+    };
+};
+/** The body of a dialog whose content runs to its edges: the dialog's ground, without the inset. */
+export declare const PHI_DIALOG_BLEED_BODY_CONFIG: {
+    readonly margin: 0;
+    readonly padding: 0;
+    readonly surface: {
+        readonly background: {
+            readonly base: {
+                readonly kind: "color";
+                readonly color: "var(--ant-color-fill-quaternary)";
+            };
+            readonly overlay: null;
+            readonly filter: null;
+        };
+        readonly borderSource: "none";
+        readonly shadow: "none";
+    };
+};
+/** The Command Toolbar in the footer, less its key, buttons and routes. */
+export declare const PHI_DIALOG_COMMANDS_CONFIG: {
+    readonly compact: true;
+    readonly showLabels: true;
+    readonly controlSize: "medium";
+};
+/**
+ * A dialog's width where it names none: the reading measure, which is also where a Form's own cap lies,
+ * so a Form fills the dialog it opens in. A wider one -- a table, a preview -- says so, and takes its
+ * width from the same sequence (`PHI_LAYOUT`).
+ */
+export declare const PHI_DIALOG_WIDTH: {
+    readonly compact: "calc(100vw - 32px)";
+    readonly medium: 610;
+    readonly wide: 610;
+};

package/helpers/cms-dialog.js

@@ -0,0 +1,50 @@
+import { PHI_SPACE } from "../theme/antd-css-var-contract";
+import { PHI_SURFACE_WASH } from "./surface-presets";
+import { PHI_LAYOUT } from "../theme/phi-tokens";
+/*
+ * What every dialog looks like, said once.
+ *
+ * A dialog is an Overlay with a body and a row of actions (OVERLAYS.md, "Structured dialogs"). Its footer
+ * was always canonical -- the `overlay-actions` Layout preset, checked by the descriptor compiler -- and
+ * its body and its buttons were not, so thirty dialogs drew four different bodies and three different
+ * button rows. These are the other two halves of that contract, for a Preset that builds its dialog node
+ * by node; `dialog` on `createPhiCmsPresetNodes` builds all of it from them.
+ *
+ * - The body is the zone's ground: the Theme's wash, the base step in from the edge and the small step
+ *   between what stands in it. It has no corner of its own -- the Modal has the one there is
+ *   (`styles/layout.css`).
+ *   A body its content fills to the edge -- an image to crop, a canvas to draw on -- takes the bleed body
+ *   instead: the same ground, no inset, and its content draws no corner of its own either.
+ * - The actions are one compact group, labelled, at the medium size: a dialog asks one question and its
+ *   answers belong together.
+ * - The width is the reading measure of a form, full width less the gutter on a phone.
+ */
+/** The body Layout's config: a vertical Flex with the `panel` creation preset under it. */
+export const PHI_DIALOG_BODY_CONFIG = {
+    gap: PHI_SPACE.sm,
+    margin: 0,
+    padding: PHI_SPACE.base,
+    surface: PHI_SURFACE_WASH,
+};
+/** The body of a dialog whose content runs to its edges: the dialog's ground, without the inset. */
+export const PHI_DIALOG_BLEED_BODY_CONFIG = {
+    margin: 0,
+    padding: 0,
+    surface: PHI_SURFACE_WASH,
+};
+/** The Command Toolbar in the footer, less its key, buttons and routes. */
+export const PHI_DIALOG_COMMANDS_CONFIG = {
+    compact: true,
+    showLabels: true,
+    controlSize: "medium",
+};
+/**
+ * A dialog's width where it names none: the reading measure, which is also where a Form's own cap lies,
+ * so a Form fills the dialog it opens in. A wider one -- a table, a preview -- says so, and takes its
+ * width from the same sequence (`PHI_LAYOUT`).
+ */
+export const PHI_DIALOG_WIDTH = {
+    compact: "calc(100vw - 32px)",
+    medium: PHI_LAYOUT.contentMax,
+    wide: PHI_LAYOUT.contentMax,
+};

package/helpers/cms-layout-defaults.d.ts

@@ -2,16 +2,26 @@ import type { PhiLayoutKind } from "../components/layouts/phi-layout-contract";
 type JsonRecord = Record<string, unknown>;
 export type PhiLayoutDefaults = JsonRecord;
 export type PhiLayoutCreationPreset = "panel" | "overlay-actions" | "page-base";
-export declare const PHI_CONTENT_LAYOUT_DEFAULTS: PhiLayoutDefaults;
-export declare const PHI_FLEX_LAYOUT_DEFAULTS: PhiLayoutDefaults;
-export declare const PHI_FLEX_VERTICAL_LAYOUT_DEFAULTS: PhiLayoutDefaults;
-export declare const PHI_GRID_LAYOUT_DEFAULTS: PhiLayoutDefaults;
-export declare const PHI_MASONRY_LAYOUT_DEFAULTS: PhiLayoutDefaults;
-export declare const PHI_STACK_LAYOUT_DEFAULTS: PhiLayoutDefaults;
-export declare const PHI_CAROUSEL_LAYOUT_DEFAULTS: PhiLayoutDefaults;
-export declare const PHI_COLLAPSIBLE_LAYOUT_DEFAULTS: PhiLayoutDefaults;
 export declare const PHI_SPLIT_CARD_LAYOUT_DEFAULTS: PhiLayoutDefaults;
-export declare const PHI_THREE_COLUMN_LAYOUT_DEFAULTS: PhiLayoutDefaults;
+export declare const PHI_SPLIT_CARD_LAYOUT_CREATION_CONFIG: {
+    readonly surface: {
+        readonly background: {
+            readonly base: {
+                readonly kind: "color";
+                readonly color: "var(--ant-color-bg-container)";
+            };
+            readonly overlay: null;
+            readonly filter: null;
+        };
+        readonly borderSource: "custom";
+        readonly border: {
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly borderColor: "var(--ant-color-border-secondary)";
+        };
+        readonly shadow: "soft";
+    };
+};
 export declare function resolvePhiLayoutDefaults(layoutKind: PhiLayoutKind): JsonRecord;
 export declare function resolvePhiLayoutCreationPreset(layoutKind: PhiLayoutKind, preset: PhiLayoutCreationPreset): JsonRecord;
 export declare function applyPhiLayoutDefaults<T extends JsonRecord>(value: Partial<T> | null | undefined, defaults: JsonRecord): T;