@phis/ui 0.2.1 → 0.3.0

package/types/cms-overlay.js

@@ -1,16 +1,14 @@
-import { normalizePhiBackgroundWidgetConfig } from "../components/widgets/config/background";
-import { readPhiCmsBorderWidgetConfig } from "./cms-border-config";
-import { isPhiLayoutEffectId, readPhiShadow } from "./layout-style";
+import { isPhiRecord } from "../helpers/is-record";
+import { readPhiSurface } from "./surface";
 import { readPhiSignalRouteSet } from "./signals";
 import { readPhiCmsMountPolicy, } from "./cms-mount-policy";
 import { readPhiControlSize } from "./control";
+import { PhiCmsFlags } from "@phis/contracts/cms";
+import { hasPhiFlag, readPhiFlags } from "../helpers/flags";
 export const PHI_CMS_OVERLAY_TYPES = ["modal", "drawer"];
 export const PHI_OVERLAY_FOOTER_PRESENTATIONS = ["none", "actions", "custom"];
 export const PHI_CMS_OVERLAY_MASK_APPEARANCES = ["transparent", "normal", "blurred"];
 export const PHI_OVERLAY_CLOSE_SOURCES = ["close-button", "mask", "escape"];
-function readBoolean(value, fallback) {
-    return typeof value === "boolean" ? value : fallback;
-}
 function readSize(value) {
     return typeof value === "number" && Number.isFinite(value)
         ? value
@@ -19,7 +17,7 @@ function readSize(value) {
             : undefined;
 }
 function readResponsiveSize(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return undefined;
     const record = value;
     const size = {
@@ -32,40 +30,43 @@ function readResponsiveSize(value) {
         : size;
 }
 function readMask(value) {
-    const record = value && typeof value === "object" && !Array.isArray(value)
+    const record = isPhiRecord(value)
         ? value
         : {};
     const appearance = PHI_CMS_OVERLAY_MASK_APPEARANCES.includes(record.appearance)
         ? record.appearance
         : "normal";
+    return { appearance };
+}
+/**
+ * What the Overlay's flags say, in the words the Controls take.
+ *
+ * The bits name the departure from the plain Overlay (a close button, Escape closes, the mask stops the
+ * pointer and closes on a click), so an unset flag set reads as every default at once.
+ */
+export function resolvePhiCmsOverlayBehaviour(config) {
+    const push = hasPhiFlag(config.flags, PhiCmsFlags.Push)
+        ? (config.pushDistance === undefined ? true : { distance: config.pushDistance })
+        : false;
+    const mask = {
+        appearance: config.mask.appearance,
+        allowOutsideInteraction: hasPhiFlag(config.flags, PhiCmsFlags.MaskPassesPointer),
+        closable: !hasPhiFlag(config.flags, PhiCmsFlags.MaskKeepsOpen),
+    };
     return {
-        appearance,
-        allowOutsideInteraction: readBoolean(record.allowOutsideInteraction, false),
-        closable: readBoolean(record.closable, true),
+        closable: !hasPhiFlag(config.flags, PhiCmsFlags.NoCloseButton),
+        keyboard: !hasPhiFlag(config.flags, PhiCmsFlags.NoEscapeClose),
+        centered: hasPhiFlag(config.flags, PhiCmsFlags.Centered),
+        resizable: hasPhiFlag(config.flags, PhiCmsFlags.Resizable),
+        push,
+        mask,
     };
 }
-function readPush(value) {
-    if (typeof value === "boolean")
-        return value;
-    if (value && typeof value === "object" && !Array.isArray(value)) {
-        const distance = readSize(value.distance);
-        if (distance !== undefined)
-            return { distance };
-    }
-    return false;
-}
-function readBorder(value) {
-    if (typeof value === "boolean")
-        return value;
-    if (typeof value === "string" && value.trim())
-        return value.trim();
-    return readPhiCmsBorderWidgetConfig(value);
-}
 export function isPhiCmsOverlayType(value) {
     return typeof value === "string" && PHI_CMS_OVERLAY_TYPES.includes(value);
 }
 export function readPhiOverlayCloseRequest(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return null;
     const record = value;
     const source = record.source;
@@ -83,12 +84,10 @@ export function parsePhiCmsOverlayConfig(rawConfig, overlayType = "modal") {
     return {
         title: typeof rawConfig.title === "string" && rawConfig.title.trim() ? rawConfig.title.trim() : null,
         controlSize: readPhiControlSize(rawConfig.controlSize),
-        closable: readBoolean(rawConfig.closable, true),
-        keyboard: readBoolean(rawConfig.keyboard, true),
+        flags: readPhiFlags(rawConfig.flags),
         // An Overlay is shut far more often than it is open, so the cheap end is the right default.
         mountPolicy: readPhiCmsMountPolicy(rawConfig.mountPolicy, "remount"),
         mask: readMask(rawConfig.mask),
-        centered: readBoolean(rawConfig.centered, false),
         width: overlayType === "modal"
             ? readSize(rawConfig.width) ?? readResponsiveSize(rawConfig.width)
             : undefined,
@@ -97,21 +96,12 @@ export function parsePhiCmsOverlayConfig(rawConfig, overlayType = "modal") {
             ? placement
             : "right",
         maxSize,
-        resizable: readBoolean(rawConfig.resizable, false),
-        push: readPush(rawConfig.push),
+        pushDistance: readSize(rawConfig.pushDistance),
         closeMode: rawConfig.closeMode === "request" ? "request" : "immediate",
         openActionKey: typeof rawConfig.openActionKey === "string" && rawConfig.openActionKey.trim()
             ? rawConfig.openActionKey.trim()
             : null,
-        background: typeof rawConfig.background === "string" && rawConfig.background.trim()
-            ? rawConfig.background.trim()
-            : undefined,
-        backgroundConfig: rawConfig.backgroundConfig == null
-            ? null
-            : normalizePhiBackgroundWidgetConfig(rawConfig.backgroundConfig),
-        border: readBorder(rawConfig.border),
-        shadow: readPhiShadow(rawConfig.shadow),
-        effect: isPhiLayoutEffectId(rawConfig.effect) ? rawConfig.effect : undefined,
+        surface: readPhiSurface(rawConfig.surface),
         signalRoutes: readPhiSignalRouteSet(rawConfig.signalRoutes),
     };
 }

package/types/cms-plugins.d.ts

@@ -7,6 +7,7 @@ import type { PhiControlOption, PhiControlOptionsProviderConfig } from "../compo
 import type { PhiRenderableBlockAnchor, PhiRenderableBlockBase } from "./renderable-block";
 import type { PhiCmsRegionOwnership } from "../helpers/cms-region-keys";
 import type { PhiSlotSizePolicy } from "./slot-size-policy";
+import type { PhiSurfacePolicy } from "./surface";
 import type { PhiCmsContentWidgetNode, PhiCmsLayoutRenderNode, PhiResolvedCmsAreaPresetTree, PhiResolvedCmsRenderableTree, PhiResolvedCmsPageTree } from "./cms";
 import type { PhiCmsRegionConfig } from "./cms-presets";
 import type { PhiBlockRuntime } from "./widget-runtime";
@@ -22,21 +23,54 @@ import type { PhiBuilderAreaKey } from "../constants/cms-areas";
 import type { PhiBuilderNavigationTree } from "../helpers/cms-navigation-catalog";
 import type { PhiBuilderActivePageCatalog } from "../helpers/cms-page-catalog";
 import type { PhiThemeBlockCatalog } from "../theme/phi-theme-composition";
+import type { PhiThemeTokenKey } from "../theme/phi-theme-tokens";
 type PhiBivariantCallback<TArgs extends unknown[], TResult> = {
     bivarianceHack(...args: TArgs): TResult;
 }["bivarianceHack"];
 export type PhiCmsConfigFieldVisibilityRule = {
     field: string;
+    /**
+     * Where `field` is read. Left out, beside the field itself; `parent` reads the config that holds the
+     * collection a field belongs to -- a Float Button's entries show a label only while the Float Button
+     * is square.
+     */
+    scope?: "parent";
     equals?: string | number | boolean | null;
     notEquals?: string | number | boolean | null;
 };
+/**
+ * What each option of a choice stands for in the Widget's other fields.
+ *
+ * A choice that is a whole answer rather than one setting among others -- the Button's Action, which is
+ * a label, a tooltip, an icon, a variant and a colour at once. While an option is chosen the fields in
+ * `locks` are its to answer: the Inspector shows the option's values in them and lets nobody change
+ * them, and nothing of theirs is stored, because the option is read again wherever it is drawn. Choosing
+ * none hands them back, filled with what the option showed, so the author edits from there instead of
+ * from blank.
+ *
+ * `prefills` are written once when an option is chosen and stay the author's: a starting point, not a
+ * lock -- the Button's signal value, which says what it triggers rather than how it looks.
+ *
+ * Data, not a callback, because a Widget's fields travel from the server to the Inspector.
+ */
+export type PhiCmsConfigFieldOptionPresets = {
+    locks: readonly string[];
+    prefills?: readonly string[];
+    values: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+};
 type PhiCmsConfigFieldBase = {
     key: string;
     label: string;
     description?: string;
     required?: boolean;
     editorPlacement?: "inspector" | "geometry" | "toolbar";
-    visibleWhen?: PhiCmsConfigFieldVisibilityRule;
+    /** When the field is shown; a list holds when every rule in it does. */
+    visibleWhen?: PhiCmsConfigFieldVisibilityRule | readonly PhiCmsConfigFieldVisibilityRule[];
+    /**
+     * A divider with this title drawn above the field: where a group of the fields that follow begins,
+     * as the Command Toolbar's "Toolbar" stands over what holds for every button.
+     */
+    heading?: string;
 };
 export type PhiCmsConfigFieldChoicePresentation = "select" | "segmented" | "tabs" | "autocomplete" | "radio";
 /**
@@ -51,8 +85,13 @@ export type PhiCmsConfigFieldChoicePresentation = "select" | "segmented" | "tabs
  * becomes a column of truncated Controls in it. Which of the two a collection needs is known by the
  * collection and by nothing else, which is why it is declared here rather than decided by the Inspector
  * from the Widget type.
+ *
+ * `select` shows one entry at a time: a select names the entry, and its fields stand under it. It adds
+ * and removes nothing -- it is for a collection whose length is decided elsewhere, as a Command
+ * Toolbar's buttons are counted on its scaffold -- and it keeps a column of identical cards from
+ * growing with every entry when each one has the same handful of settings.
  */
-export type PhiCmsConfigFieldCollectionPresentation = "inline" | "overlay";
+export type PhiCmsConfigFieldCollectionPresentation = "inline" | "overlay" | "select";
 export type PhiCmsConfigFieldChoiceMode = "single" | "multiple";
 export type PhiCmsConfigFieldChoiceValueType = "string" | "string[]";
 export type PhiCmsConfigFieldChoiceCreateBehavior = "none" | "accept-custom" | "create-record";
@@ -65,6 +104,12 @@ export type PhiCmsConfigFieldChoiceFilter = {
 };
 export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
     type: "string" | "url" | "icon";
+    /**
+     * What a cleared box is written as. Left out, clearing removes the key and the Widget's own
+     * fallback answers again; `""` keeps the emptiness, for a text the author may want gone -- a
+     * Button that is only its icon.
+     */
+    emptyValue?: "";
 }) | (PhiCmsConfigFieldBase & {
     /**
      * One link, chosen rather than typed.
@@ -80,6 +125,11 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
      * why the name is what the server has to go on.
      */
     type: "link-target";
+    /**
+     * Keys that mean nothing without a target and go with it: the Card's hover effect, which a card
+     * that leads nowhere does not have. Cleared when the target is.
+     */
+    clearsWhenEmpty?: readonly string[];
 }) | (PhiCmsConfigFieldBase & {
     type: "readonly";
 }) | (PhiCmsConfigFieldBase & {
@@ -127,13 +177,45 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
 }) | (PhiCmsConfigFieldBase & {
     type: "color";
     mode?: PhiCmsConfigFieldColorMode;
+    /**
+     * The Theme token the thing coloured falls back to, shown while the field is empty -- a Badge is
+     * `colorError` until somebody picks otherwise, and an empty field showing the picker's own blue
+     * would say the Badge is blue.
+     */
+    defaultToken?: PhiThemeTokenKey;
     section?: string;
 }) | (PhiCmsConfigFieldBase & {
     type: "boolean";
+}) | (PhiCmsConfigFieldBase & {
+    /**
+     * A picture: an Asset from the media library in a chosen rendition, or an address, with its alt
+     * text. Writes the image source keys (`sourceKind`, `assetId`, `variantKey`, `variantVersion`,
+     * `sourceUrl`) and `alt`, not a key of its own; `key` only names the field.
+     */
+    type: "image";
+}) | (PhiCmsConfigFieldBase & {
+    /**
+     * One short text per slot, stored as a list in slot order -- a Collapsible's panel descriptions.
+     *
+     * The Inspector offers a line for each occupied slot, named by what the slot is called on the
+     * canvas, so the author writes against the panel they see rather than against an index. Like
+     * `slotTitles` the list is the Layout's and does not move with a child (`LAYOUTING.md`).
+     */
+    type: "slot-texts";
 }) | (PhiCmsConfigFieldBase & {
     /** A list of whole numbers, such as the page sizes a table offers; each at least `min`. */
     type: "number-list";
     min?: number;
+}) | (PhiCmsConfigFieldBase & {
+    /**
+     * A set of yes-or-no choices stored as one whole number, one bit per option -- which parts of an
+     * entry a Widget shows. Ticked options are set bits; bits no option names are never written.
+     */
+    type: "flags";
+    options: readonly {
+        value: number;
+        label: string;
+    }[];
 }) | (PhiCmsConfigFieldBase & {
     type: "number";
     min?: number;
@@ -147,6 +229,12 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
      * field is narrow; the unit belongs to the value, so it stands where the value is.
      */
     prefix?: string;
+    /**
+     * A slider instead of a box, for a value that is felt rather than typed -- an opacity. It needs
+     * `min` and `max`; `suffix` stands after the value in the slider's tooltip.
+     */
+    presentation?: "slider";
+    suffix?: string;
 }) | (PhiCmsConfigFieldBase & {
     type: "choice";
     mode?: PhiCmsConfigFieldChoiceMode;
@@ -161,6 +249,7 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
     emptyOption?: PhiControlOption;
     emptyValue?: null | undefined;
     patchOnChange?: Record<string, unknown>;
+    optionPresets?: PhiCmsConfigFieldOptionPresets;
 }) | (PhiCmsConfigFieldBase & {
     type: "collection";
     itemKeyField: string;
@@ -184,7 +273,16 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
     section?: string;
     storage?: PhiCmsConfigFieldValueStorage;
 }) | (PhiCmsConfigFieldBase & {
-    type: "shadow" | "slot-placement";
+    /**
+     * A Surface (`types/surface.ts`) of something the Widget draws inside itself -- each entry of a
+     * list -- edited with the same Control as a Widget's own Surface. `null` is stored for "None", so a
+     * look a Widget is created with is not drawn again under a box that was set to have none.
+     */
+    type: "surface";
+    /** Whether the mode is offered; left out, it is. */
+    tone?: false;
+}) | (PhiCmsConfigFieldBase & {
+    type: "shadow" | "grid-placement" | "column-count";
     section?: string;
 });
 export type PhiCmsLayoutSlotDefinition = {
@@ -283,6 +381,11 @@ export type PhiCmsWidgetSignalSubcontrolCollection = {
     configKey: string;
     keyField: string;
     labelFields?: readonly string[];
+    /**
+     * What a label field's stored value reads as, where it is a key rather than words -- a toolbar
+     * button's `action` is `livePreview`, and the Signals panel should say "Live preview".
+     */
+    labelFieldValues?: Readonly<Record<string, Readonly<Record<string, string>>>>;
 };
 export type PhiRuntimeControllerRequirement = {
     type: `${string}/${string}`;
@@ -308,6 +411,13 @@ export type PhiCmsLayoutPluginRenderArgs<TConfig> = {
     renderChildren: (node: PhiCmsLayoutRenderNode) => ReactNode[];
     renderSequentialSlotChildren: (node: PhiCmsLayoutRenderNode) => ReactNode[];
     renderResolvedSequentialSlotChildren?: (node: PhiCmsLayoutRenderNode) => Promise<ReactNode[]>;
+    /**
+     * The text in the node's own config in the reader's language, for a Layout that `translatesOwnText`:
+     * the renderer answers it, because translating is a server matter and a Layout plugin is loaded in the
+     * browser too. Under the node's `NoTranslate` flag, or where nobody translates, the texts come back
+     * as they were.
+     */
+    translateOwnText?: (texts: readonly string[]) => Promise<string[]>;
 };
 export type PhiCmsWidgetPlugin<TConfig> = {
     kind: "widget";
@@ -335,6 +445,16 @@ export type PhiCmsWidgetPlugin<TConfig> = {
      */
     translatesOwnText?: true;
     slotSizePolicy: PhiSlotSizePolicy;
+    /**
+     * Who draws the node's Surface (`config.surface`).
+     *
+     * `frame` has the slot frame draw it around whatever the Widget renders: ground, edge and depth on the
+     * box the Widget sits in. `own` hands it to the Widget, which reads `config.surface` itself -- a card
+     * whose picture zooms under the pointer needs the ground inside its own box. `none`, the answer when a
+     * Widget says nothing, says the Widget has no Surface at all, and the Inspector offers none: a Widget
+     * gets a Surface only by asking for one.
+     */
+    surface?: PhiSurfacePolicy;
     /**
      * The kind of Region this Widget needs, where standing in the other kind would break it.
      *
@@ -349,19 +469,37 @@ export type PhiCmsWidgetPlugin<TConfig> = {
      */
     requiredRegionOwnership?: PhiCmsRegionOwnership;
     defaultConfig?: Partial<TConfig>;
+    /**
+     * What a placement of this Widget is created with, where that is more than its `defaultConfig`.
+     *
+     * The same split the Layouts make: a default is put back under every placement that leaves the key
+     * out, so it can only hold what an author may not take away. A starting text the author may clear
+     * belongs here -- written into the new placement once, and gone for good when they clear it.
+     */
+    creationConfig?: Partial<TConfig>;
     fields: PhiCmsConfigField[];
     parseConfig: (raw: Record<string, unknown>) => TConfig;
     render: PhiBivariantCallback<[PhiCmsWidgetPluginRenderArgs<TConfig>], ReactNode>;
     renderPreview: PhiBivariantCallback<[PhiCmsWidgetPluginRenderArgs<TConfig>], ReactNode>;
 };
-export type PhiCmsWidgetPluginDefinition<TConfig> = Pick<PhiCmsWidgetPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "signalSubcontrols" | "requiredRuntimeControllers" | "requiredDataProviders" | "contentBinding" | "translatesOwnText" | "slotSizePolicy" | "requiredRegionOwnership" | "defaultConfig" | "fields" | "parseConfig">;
+/**
+ * Everything a Widget declares about itself, and nothing it renders.
+ *
+ * The one declarative shape. The Builder reads only this -- its metadata, Inspector fields and config
+ * parser -- and the Server, the Builder and the Runtime plugins below are this shape plus the function
+ * each of them renders with. There used to be six hand-kept `Pick` lists, and three of them had lost
+ * fields the others had: a Server plugin could not declare `requiredDataProviders`, the Builder meta read
+ * `contentBinding` through an `"x" in plugin` branch, and a Module's `translatesOwnText` travelled on a
+ * plugin whose type did not know it.
+ */
+export type PhiCmsWidgetPluginDefinition<TConfig> = Pick<PhiCmsWidgetPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "signalSubcontrols" | "requiredRuntimeControllers" | "requiredDataProviders" | "contentBinding" | "translatesOwnText" | "slotSizePolicy" | "surface" | "requiredRegionOwnership" | "defaultConfig" | "creationConfig" | "fields" | "parseConfig">;
 export type PhiCmsBuilderWidgetEditorInteraction = "inert" | "authoring";
-export type PhiCmsBuilderWidgetPlugin<TConfig> = Pick<PhiCmsWidgetPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "signalSubcontrols" | "requiredRuntimeControllers" | "requiredDataProviders" | "slotSizePolicy" | "defaultConfig" | "fields" | "parseConfig"> & {
+export type PhiCmsBuilderWidgetPlugin<TConfig> = PhiCmsWidgetPluginDefinition<TConfig> & {
     editorInteraction?: PhiCmsBuilderWidgetEditorInteraction;
     renderEditor: PhiBivariantCallback<[PhiCmsBuilderWidgetRenderArgs<TConfig>], ReactNode>;
     renderEditorTools?: PhiBivariantCallback<[PhiCmsBuilderWidgetRenderArgs<TConfig>], ReactNode>;
 };
-export type PhiCmsServerWidgetPlugin<TConfig> = Pick<PhiCmsWidgetPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "signalSubcontrols" | "requiredRuntimeControllers" | "slotSizePolicy" | "defaultConfig" | "fields" | "parseConfig" | "render" | "renderPreview">;
+export type PhiCmsServerWidgetPlugin<TConfig> = PhiCmsWidgetPluginDefinition<TConfig> & Pick<PhiCmsWidgetPlugin<TConfig>, "render" | "renderPreview">;
 export type PhiCmsRuntimeWidgetPlugin<TConfig> = PhiCmsWidgetPluginDefinition<TConfig> & Pick<PhiCmsWidgetPlugin<TConfig>, "render">;
 export type PhiCmsPreviewWidgetPlugin<TConfig> = PhiCmsWidgetPluginDefinition<TConfig> & Pick<PhiCmsWidgetPlugin<TConfig>, "renderPreview">;
 export type PhiCmsRuntimeRenderRegistry = {
@@ -382,6 +520,8 @@ export type PhiCmsRuntimeRenderRegistry = {
     renderIssuesByLayoutType: ReadonlyMap<string, PhiCmsRenderIssue>;
     ownerModuleIdByWidgetType: ReadonlyMap<string, PhiRuntimeModuleId>;
     widgetSlotSizePoliciesByType: ReadonlyMap<string, PhiSlotSizePolicy | undefined>;
+    /** Each Widget's answer to who draws its Surface; only types that do not leave it to the frame. */
+    widgetSurfacePoliciesByType: ReadonlyMap<string, PhiSurfacePolicy>;
     /**
      * The block base a Widget declares in its `defaultConfig`, for the nodes that declare none.
      *
@@ -401,10 +541,19 @@ export type PhiCmsRuntimeRenderRegistry = {
      * single namespace does not make every other Module answer as well.
      */
     featureResolverLoadersByNamespace: ReadonlyMap<string, () => Promise<PhiRuntimeModuleFeatureResolver>>;
+    /**
+     * How to ask each active Module's `record` Providers, by key. Loaders for the reason the features are:
+     * a page that binds none loads none.
+     */
+    recordProviderLoadersByKey: ReadonlyMap<PhiRuntimeDataProviderKey, () => Promise<import("./record-provider").PhiRuntimeRecordProviderResolver>>;
     dataProviderDescriptorsByKey: ReadonlyMap<PhiRuntimeDataProviderKey, PhiRuntimeModuleDataProviderDescriptor>;
     formDefinitionsById: ReadonlyMap<string, PhiRuntimeModuleFormDefinition>;
 };
-export type PhiCmsRenderIssueCode = "missing-module" | "missing-renderer" | "renderer-load-failed" | "render-failed" | "invalid-render-output";
+export type PhiCmsRenderIssueCode = "missing-module" | "missing-renderer" | "renderer-load-failed" | "render-failed" | "invalid-render-output"
+/** A node whose `visibleWhen` reads a feature namespace whose Module could not be asked this render. */
+ | "feature-unavailable"
+/** A Region or Overlay zone names a root layout node the tree does not contain. */
+ | "missing-node";
 export type PhiCmsRenderIssue = {
     code: PhiCmsRenderIssueCode;
     kind: "widget" | "layout";
@@ -428,6 +577,14 @@ export type PhiCmsLayoutPlugin<TConfig> = {
     runtimeSignals?: PhiSignalPluginMeta | null;
     slotSizePolicy: PhiSlotSizePolicy;
     defaultConfig?: Partial<TConfig>;
+    /**
+     * What a node of this Layout is created with, where that is more than its `defaultConfig`.
+     *
+     * A default is put back under every node that leaves the key out, so it can only hold what an author
+     * may not take away. A look the author may remove -- a Surface, say -- belongs here: written into the
+     * new node once, gone for good when the author clears it.
+     */
+    creationConfig?: Partial<TConfig>;
     defaultAnchor?: PhiRenderableBlockAnchor | null;
     fields: PhiCmsConfigField[];
     slots: PhiCmsLayoutSlotDefinition[];
@@ -440,11 +597,17 @@ export type PhiCmsLayoutPlugin<TConfig> = {
      * two holds anything.
      */
     slotPositions?: "compact" | "fixed";
+    /**
+     * The Layout translates the text written into its own config -- a Collapsible's panel titles -- the
+     * way a Widget that says so does. Turning that off is the node's `NoTranslate` flag, not a config
+     * field, and a Layout that says so here gets the Inspector's switch for it.
+     */
+    translatesOwnText?: true;
     parseConfig: (raw: Record<string, unknown>) => TConfig;
     render: PhiBivariantCallback<[PhiCmsLayoutPluginRenderArgs<TConfig>], ReactNode>;
     renderEditor: PhiBivariantCallback<[PhiCmsLayoutPluginRenderArgs<TConfig>], ReactNode>;
 };
-export type PhiCmsLayoutPluginDefinition<TConfig> = Pick<PhiCmsLayoutPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "slotSizePolicy" | "defaultConfig" | "defaultAnchor" | "fields" | "slots" | "slotPositions">;
+export type PhiCmsLayoutPluginDefinition<TConfig> = Pick<PhiCmsLayoutPlugin<TConfig>, "kind" | "pluginKey" | "typeKey" | "title" | "description" | "category" | "tags" | "icon" | "iconName" | "iconFamily" | "commercial" | "runtimeSignals" | "slotSizePolicy" | "defaultConfig" | "creationConfig" | "defaultAnchor" | "fields" | "slots" | "slotPositions" | "translatesOwnText">;
 export type PhiCmsResolvedRequestLoaderArgs = {
     siteKey: string;
     locale: string;
@@ -471,9 +634,23 @@ export type PhiResolvedCmsRequest = {
     page: PhiResolvedCmsPageTree;
     runtime: PhiBlockRuntime;
     serverCapabilities: import("./server-capabilities").PhiCapabilitySnapshot | null;
+    /**
+     * The Tour the Page's route carries, untranslated, with the language its owning Module writes in.
+     * Translated only where the Area has a Controller to hand it to (types/tours.ts).
+     */
+    pageTour?: {
+        definition: import("./tours").PhiTourDefinition;
+        sourceLocale?: string;
+    } | null;
 };
 export type PhiRuntimeControllerMountScope = "site" | "area" | "page";
-export type PhiRuntimeControllerFlag = "internal" | "multiInstance";
+export type PhiRuntimeControllerFlag = "internal" | "multiInstance"
+/**
+ * Receives the shown Page's Tour as `pageTour` in its config, through a Page overlay
+ * ([types/tours.ts](./tours.ts)). Without a Controller carrying it, a Page's Tour is not offered and its
+ * targets are not drawn with a live frame for it.
+ */
+ | "pageTour";
 export type PhiRuntimeControllerSetting = {
     type: `${string}/${string}`;
     instanceKey: string;
@@ -488,6 +665,8 @@ export type PhiRuntimeControllerServerPreloadArgs<TConfig> = {
     mountScope: PhiRuntimeControllerMountScope;
     runtime: PhiBlockRuntime;
     runtimeModuleCatalog: PhiRuntimeModuleCatalog;
+    /** What phis-server provides on this Site, as the render that mounts the Controller read it. */
+    serverCapabilities: import("./server-capabilities").PhiCapabilitySnapshot | null;
     setting: PhiRuntimeControllerSetting;
     config: TConfig;
 };
@@ -548,6 +727,7 @@ export type PhiRuntimeModuleClientWidgetDefinition = {
     title: string;
     signalSubcontrols?: readonly PhiCmsWidgetSignalSubcontrolCollection[];
     slotSizePolicy: PhiSlotSizePolicy;
+    surface?: PhiSurfacePolicy;
     renderPolicies: PhiRuntimeModuleRenderPolicies;
 };
 export type { PhiRuntimeModuleId } from "./cms-module-descriptors";
@@ -792,8 +972,24 @@ export type PhiRuntimeModuleCatalogEntry = {
      * There is no namespace to declare. A card carries its own id, and that id says whose it is.
      */
     dashboardCards?: {
+        /**
+         * The Areas whose Dashboard these cards belong on, a subset of the Module's `eligibleAreas`.
+         *
+         * Stated here rather than answered by the provider, so an Area that is not named never loads it.
+         * `context.area` still reaches the provider for a card that reads differently from Area to Area; it
+         * is no longer how a provider leaves one out.
+         */
+        areas: readonly PhiCmsAreaKey[];
         load: () => Promise<import("./dashboard-cards").PhiDashboardCardProvider>;
     };
+    /**
+     * The server halves of this Module's `record` Providers, one for each such descriptor in
+     * `dataProviders` (`types/record-provider.ts`).
+     *
+     * Here and not on the descriptor for the reason `dashboardCards` is: the function reads the Site's
+     * store with server credentials, and the descriptor travels to the browser.
+     */
+    recordProviders?: readonly import("./record-provider").PhiRuntimeModuleRecordProviderServerDefinition[];
     load: PhiRuntimeModuleLoader;
 };
 export type PhiRuntimeModuleFeatureContext = {

package/types/cms-presets.d.ts

@@ -4,27 +4,30 @@ import type { PhiCmsInstanceId } from "./cms-instance-id";
 import type { PhiCmsContainerChromeConfig } from "./cms-container";
 import type { PhiRenderableBlockEffects, PhiRenderableBlockResponsiveSize, PhiRenderableBlockSize, PhiRenderableBlockVisibility } from "./renderable-block";
 import type { PhiCssLength } from "./length";
-import type { PhiShadow } from "./layout-style";
-export type PhiCmsAreaKey = "public" | "app" | "admin" | "builder" | "editor" | "accounting";
+import type { PhiLinkTarget } from "./references";
+import type { PhiCmsAreaKey } from "@phis/contracts/cms";
+export type { PhiCmsAreaKey };
 export type PhiCmsRegionKey = "header_top" | "header_main" | "header_bottom" | "sider_left" | "sider_right" | "hero" | "content" | "footer_top" | "footer_main" | "footer_bottom" | "drawer_left" | "drawer_right";
 export type PhiCmsRegionSource = "preset" | "fallback" | "page_override";
 export type PhiCmsLayerConfig = Record<string, unknown> & {
     zIndex?: number;
 };
 export type PhiCmsRegionConfig = Record<string, unknown> & PhiCmsContainerChromeConfig & {
-    borderRadius?: CSSProperties["borderRadius"];
     visibility?: PhiRenderableBlockVisibility;
+    /**
+     * The block runtime's live answer, merged in by the client renderer for the shell resolver; a stored
+     * config never states it (BUILDER.md, renderable blocks).
+     */
     enabled?: boolean;
     mode?: "light" | "dark";
-    sticky?: boolean;
-    fullHeight?: boolean;
-    collapsible?: boolean;
+    /**
+     * The Region's behaviour as `PhiCmsFlags` bits: `Sticky`, `FullHeight`, `Collapsible`, and `Collapsed`
+     * for the Builder preview. Read with `hasPhiFlag`; a Region stored on a Page has no row of its own, so
+     * its behaviour lives here and not on a row's `flags`.
+     */
     flags?: number;
     collapsedWidth?: CSSProperties["width"];
     collapseIcon?: string;
-    centered?: boolean;
-    mobileOnly?: boolean;
-    desktopOnly?: boolean;
     size?: PhiRenderableBlockResponsiveSize;
     minSize?: PhiRenderableBlockResponsiveSize;
     maxSize?: PhiRenderableBlockResponsiveSize;
@@ -35,16 +38,60 @@ export type PhiCmsRegionConfig = Record<string, unknown> & PhiCmsContainerChrome
     lineHeight?: CSSProperties["lineHeight"];
     offsetTop?: PhiCssLength;
     zIndex?: number;
+    /** Which of the Area's Pages show this Shell Region (`helpers/region-page-scope.ts`). */
+    pageScope?: PhiCmsRegionPageScope;
+    /** How `header_top` comes into view (`helpers/region-page-scope.ts`); every other Region ignores it. */
+    reveal?: PhiCmsRegionReveal;
 };
+/**
+ * Which Pages a Shell Region stands on (SHELL.md "Region visibility per Page").
+ *
+ * `all` is every Page of the Area, `root` the Area's own `/`. `include` and `exclude` name `entries`:
+ *
+ * - a Page, by its reference under `pageLinkTarget` -- never by its path, which an author may change at
+ *   any time. The `*LinkTarget` key is what lets the reference index see it (REFERENCES.md). With
+ *   `PhiCmsRegionPageScopeEntryFlag.Subtree` it stands for the Pages below it as well, which only a
+ *   Module Page can have.
+ * - a folder, by its path inside the Area. A folder is not a Page and has no identity of its own -- it is
+ *   the shared start of its Pages' paths -- so the path is all there is to name it by, and it takes
+ *   everything below it, including Pages added later.
+ */
+export declare const PHI_CMS_REGION_PAGE_SCOPE_MODES: readonly ["all", "root", "include", "exclude"];
+export type PhiCmsRegionPageScopeMode = (typeof PHI_CMS_REGION_PAGE_SCOPE_MODES)[number];
+export declare const PhiCmsRegionPageScopeEntryFlag: {
+    readonly Subtree: number;
+};
+export type PhiCmsRegionPageScopeEntry = {
+    pageLinkTarget: PhiLinkTarget;
+    flags?: number;
+} | {
+    folder: string;
+};
+export type PhiCmsRegionPageScope = {
+    mode: PhiCmsRegionPageScopeMode;
+    entries?: PhiCmsRegionPageScopeEntry[];
+};
+/**
+ * A Page scope as the browser asks it: every entry turned into an address inside the Area. The server
+ * resolves the references for each render; the browser compares the visitor's path against the result.
+ */
+export type PhiCmsResolvedRegionPageScope = {
+    mode: "root";
+} | {
+    mode: "include" | "exclude";
+    paths: string[];
+    prefixes: string[];
+};
+/**
+ * How a Region comes into view: `always` stands where it is, `hover` stays out of sight until the pointer
+ * reaches the top edge, `scroll-up` leaves while the visitor reads down and returns as soon as they
+ * scroll back.
+ */
+export declare const PHI_CMS_REGION_REVEAL_MODES: readonly ["always", "hover", "scroll-up"];
+export type PhiCmsRegionReveal = (typeof PHI_CMS_REGION_REVEAL_MODES)[number];
 export type PhiCmsLayoutConfig = PhiCmsLayerConfig & {
     gap?: number | string;
     padding?: number | string;
-    paddingInline?: number | string;
-    paddingBlock?: number | string;
-    background?: string;
-    shadow?: PhiShadow;
-    border?: boolean | CSSProperties["border"];
-    borderRadius?: number | string;
     align?: CSSProperties["alignItems"];
     justify?: CSSProperties["justifyContent"];
     wrap?: boolean | CSSProperties["flexWrap"];