@phis/ui 0.2.1 → 0.4.0

package/types/cms-config.d.ts

@@ -4,11 +4,9 @@ import { type PhiCmsMountPolicy } from "./cms-mount-policy";
 import { type PhiMotionEasing, type PhiSequenceAnchor, type PhiSequenceTransition } from "../helpers/motion";
 import { type PhiCssLength } from "./length";
 import type { PhiResponsiveValue } from "./responsive";
-import { type PhiCmsBackgroundWidgetConfig } from "../components/widgets/config/background";
 import type { PhiRenderableBlockBase, PhiRenderableBlockAnchor, PhiRenderableBlockResponsiveSize } from "./renderable-block";
-import { type PhiShadow, type PhiLayoutEffectId } from "./layout-style";
 import type { PhiBaseLayoutSlotStates } from "../components/layouts/phi-layout-contract";
-import { type PhiCmsBorderSource } from "./cms-border-source";
+import { type PhiSpacingScaleKey } from "../components/widgets/config/spacing-options";
 export type PhiCmsPluginConfigBase = Record<string, unknown>;
 export type PhiCmsRenderableBlockConfigBase = PhiCmsPluginConfigBase & PhiRenderableBlockBase;
 export type PhiCmsLayerBase = PhiCmsRenderableBlockConfigBase & {
@@ -28,22 +26,6 @@ export type PhiCmsLayerBase = PhiCmsRenderableBlockConfigBase & {
     paddingRight?: CSSProperties["paddingRight"];
     paddingBottom?: CSSProperties["paddingBottom"];
     paddingLeft?: CSSProperties["paddingLeft"];
-    background?: CSSProperties["background"];
-    /**
-     * Where a Layout's outline comes from, which is a different question from what it looks like.
-     *
-     * `none` draws none, `theme` draws the Site's own line -- its border colour and line width, with the
-     * corner the shape already gives every surface -- and `custom` draws what `border` says. Absent means
-     * `custom` where a border was configured and `none` everywhere else, which is how a Site written
-     * before this field reads correctly without being rewritten.
-     *
-     * The point of stating it is that "no border" and "nobody has said yet" stop being the same absence,
-     * and that a Layout with its own frame -- a Collapsible outlining its panels -- no longer has to be a
-     * second way of asking the same thing.
-     */
-    borderSource?: PhiCmsBorderSource;
-    border?: CSSProperties["border"];
-    borderRadius?: CSSProperties["borderRadius"];
 };
 export type PhiCmsDirectionalLayoutConfigBase = PhiCmsLayerBase & {
     gap?: CSSProperties["gap"];
@@ -139,7 +121,8 @@ export type PhiCmsCarouselLayoutConfig = PhiCmsLayerBase & {
     transition?: PhiSequenceTransition;
     transitionDurationMs?: number;
     transitionEasing?: PhiMotionEasing;
-    slotGap?: string;
+    /** A step of the spacing scale between the slots of a window. */
+    slotGap?: PhiSpacingScaleKey;
     /** Which of its own controls the Carousel draws. Pager Widgets work regardless of this. */
     controls?: "none" | "arrows" | "dots" | "both";
     loop?: boolean;
@@ -153,7 +136,8 @@ export type PhiCmsCollapsibleLayoutConfig = PhiCmsLayerBase & {
     panelMinHeight?: PhiCssLength;
     accordion?: boolean;
     slotTitles?: string[];
-    translateSlotTitles?: boolean;
+    /** The hint behind each panel's title, in slot order like `slotTitles`; an empty one draws none. */
+    slotDescriptions?: string[];
     defaultOpenSlotKeys?: string[];
     collapsible?: "header" | "icon" | "disabled";
     ghost?: boolean;
@@ -168,14 +152,17 @@ export type PhiCmsGridLayoutSlotPlacementConfig = {
     span?: PhiResponsiveValue<number>;
     offset?: PhiResponsiveValue<number>;
 };
-export type PhiCmsGridLayoutConfig = PhiCmsDirectionalLayoutConfigBase & {
+/**
+ * A Grid: how many slots a row holds at each width, and the slots that are wider or indented.
+ *
+ * `gap` is the distance between slots, across and down; `anchor` places each slot's content in its
+ * cell (LAYOUTING.md, "Grid slot placement").
+ */
+export type PhiCmsGridLayoutConfig = PhiCmsLayerBase & {
+    gap?: CSSProperties["gap"];
     anchor?: PhiRenderableBlockAnchor;
-    columnGap?: CSSProperties["columnGap"];
+    columns?: PhiResponsiveValue<number>;
     slotPlacements?: PhiCmsGridLayoutSlotPlacementConfig[];
-    slotBackground?: string;
-    slotBorder?: string;
-    slotBorderRadius?: CSSProperties["borderRadius"];
-    slotShadow?: PhiShadow;
 };
 export type PhiCmsThreeColumnLayoutConfig = PhiCmsDirectionalLayoutConfigBase & {
     balancedSides?: boolean;
@@ -184,33 +171,21 @@ export type PhiCmsThreeColumnLayoutConfig = PhiCmsDirectionalLayoutConfigBase &
     rightWidth?: PhiCssLength;
     contentAlign?: CSSProperties["alignItems"];
 };
+/**
+ * Two cards on the golden ratio. The Layout's Surface is the cards' -- each half draws its edge, corner,
+ * depth and pane -- and its Background runs once across both and shows only inside them. What stands in
+ * a half sets its own inset; a half has none of its own.
+ */
 export type PhiCmsSplitCardLayoutConfig = PhiCmsLayerBase & {
     gap?: CSSProperties["gap"];
-    effect?: PhiLayoutEffectId;
-    leftPadding?: CSSProperties["padding"];
-    rightPadding?: CSSProperties["padding"];
-    leftBackground?: PhiCmsBackgroundWidgetConfig;
-    rightBackground?: PhiCmsBackgroundWidgetConfig;
-    leftBorder?: PhiCmsBorderWidgetConfig;
-    rightBorder?: PhiCmsBorderWidgetConfig;
-    leftShadow?: PhiShadow;
-    rightShadow?: PhiShadow;
+    /** The golden ratio the other way round: the left card the larger one. */
+    swapRatio?: boolean;
 };
+/** Children in columns at their own heights: how many columns at each width, and the gap between them. */
 export type PhiCmsMasonryLayoutConfig = PhiCmsLayerBase & {
-    columns?: number;
-    minColumnWidth?: PhiCssLength;
+    columns?: PhiResponsiveValue<number>;
     gap?: CSSProperties["gap"];
-    itemPadding?: CSSProperties["padding"];
-    itemBackground?: string;
-    itemBorder?: string;
-    itemBorderRadius?: CSSProperties["borderRadius"];
-    itemShadow?: PhiShadow;
 };
-/**
- * A shared Layout field, read the same way wherever it appears: a line on the 24-track form grid, so
- * anything outside 2..24 is not a narrower column but a mistake, and is dropped rather than clamped.
- */
-export declare function readPhiLayoutLabelEnd(value: unknown): number | undefined;
 export declare function parsePhiCmsContentLayoutConfig(config: Record<string, unknown>): PhiCmsContentLayoutConfig;
 export declare function parsePhiCmsFlexLayoutConfig(config: Record<string, unknown>): PhiCmsFlexLayoutConfig;
 export declare function parsePhiCmsFlexVerticalLayoutConfig(config: Record<string, unknown>): PhiCmsFlexVerticalLayoutConfig;

package/types/cms-config.js

@@ -1,17 +1,16 @@
+import { normalizePhiRenderableBlockResponsiveSize } from "../helpers/renderable-block-normalizers";
 import { readPhiControlSize } from "./control";
 import { readPhiCmsMountPolicy } from "./cms-mount-policy";
 import { clampPhiSequenceTransitionMs, readPhiMotionEasing, PHI_SEQUENCE_ANCHORS, PHI_SEQUENCE_TRANSITIONS, } from "../helpers/motion";
 import { readPhiLengthValue } from "./length";
-import { readPhiCmsBorderWidgetConfig } from "./cms-border-config";
 import { isPhiAnchorWidgetPlacement, resolvePhiRenderableBlockAnchor, } from "../components/controls/phi-anchor-control-contract";
-import { readBoolean, readCssSize, readNumber, readRenderableBlockConfig, readRenderableBlockSize, readString, } from "../components/widgets/config/parser-primitives";
-import { normalizePhiBackgroundWidgetConfig, } from "../components/widgets/config/background";
-import { isPhiLayoutEffectId, readPhiShadow, } from "./layout-style";
+import { readBoolean, readCssSize, readNumber, readRenderableBlockConfig, readString, } from "../components/widgets/config/parser-primitives";
 import { applyPhiLayoutDefaults } from "../helpers/cms-layout-defaults";
 import { resolvePhiLayoutDefaults } from "../helpers/cms-layout-defaults";
 import { normalizeRenderableBlockAnchor } from "../helpers/renderable-block-anchor";
 import { isPhiRecord } from "../helpers/is-record";
-import { readPhiCmsBorderSource } from "./cms-border-source";
+import { PHI_SPACING_SCALE_KEYS } from "../components/widgets/config/spacing-options";
+import { PHI_GRID_COLUMN_COUNTS, isPhiGridColumnCount } from "../constants/grid-columns";
 function readInitialSlotStates(value) {
     if (Array.isArray(value)) {
         const normalized = value.map((candidate) => candidate === "expanded" || candidate === "collapsed" || candidate === "hidden" ? candidate : undefined);
@@ -43,7 +42,7 @@ function readStringArray(value) {
     return [...new Set(next)];
 }
 export function normalizePhiPaddingWidgetConfig(config) {
-    if (!config || typeof config !== "object" || Array.isArray(config)) {
+    if (!isPhiRecord(config)) {
         return null;
     }
     const raw = config;
@@ -154,23 +153,27 @@ function readRenderableBlockAnchorOrPlacement(value) {
         ? resolvePhiRenderableBlockAnchor(value)
         : undefined;
 }
-function readGridResponsivePlacement(value, minimum, maximum) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+function readGridResponsiveCount(value, accepts) {
+    if (!isPhiRecord(value))
         return undefined;
     const record = value;
     const read = (key) => {
         const candidate = readNumber(record[key]);
-        return Number.isInteger(candidate) && candidate != null && candidate >= minimum && candidate <= maximum
-            ? candidate
-            : undefined;
+        return candidate != null && Number.isInteger(candidate) && accepts(candidate) ? candidate : undefined;
     };
     const responsive = { compact: read("compact"), medium: read("medium"), wide: read("wide") };
     return responsive.compact != null || responsive.medium != null || responsive.wide != null
         ? responsive
         : undefined;
 }
+const PHI_GRID_MAX_COLUMNS = Math.max(...PHI_GRID_COLUMN_COUNTS);
+/*
+ * Counted in the Grid's columns, so a span is at most the widest row and an indent one less. Whether
+ * they fit the row at a given width is answered where the row is known, by clamping
+ * (`resolvePhiGridSlotPlacement`): a Grid whose columns were reduced keeps its stated placements.
+ */
 function readGridSlotPlacement(value, slotIndexFromArray) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const slot = value;
@@ -178,44 +181,17 @@ function readGridSlotPlacement(value, slotIndexFromArray) {
     if (!Number.isInteger(slotIndex) || slotIndex == null || slotIndex < 0) {
         return null;
     }
-    const span = readGridResponsivePlacement(slot.span, 1, 24);
-    const offset = readGridResponsivePlacement(slot.offset, 0, 23);
+    const span = readGridResponsiveCount(slot.span, (candidate) => candidate >= 1 && candidate <= PHI_GRID_MAX_COLUMNS);
+    const offset = readGridResponsiveCount(slot.offset, (candidate) => candidate >= 0 && candidate < PHI_GRID_MAX_COLUMNS);
     if (!span && !offset)
         return null;
-    /*
-     * The rule is about two numbers an author stated, so a profile where no span was stated has nothing
-     * to check.
-     *
-     * A span of six used to be invented here for the check, matching the one constant the Grid fell back
-     * to. The fallback is a profile value now (`PHI_GRID_LAYOUT_DEFAULT_SPAN`, 24/12/6), and repeating it
-     * here would reject stored placements rather than describe them: at `compact` the default fills the
-     * row, so any stated offset beside an absent span would fail a rule the author never broke. What
-     * happens instead is what always happened to an offset with no room -- `resolvePhiGridSlotColumns`
-     * clamps it to the tracks that are left.
-     */
-    const statedSpan = {
-        compact: span?.compact,
-        medium: span?.medium ?? span?.compact,
-        wide: span?.wide ?? span?.medium ?? span?.compact,
-    };
-    const resolvedOffset = {
-        compact: offset?.compact ?? 0,
-        medium: offset?.medium ?? offset?.compact ?? 0,
-        wide: offset?.wide ?? offset?.medium ?? offset?.compact ?? 0,
-    };
-    for (const profile of ["compact", "medium", "wide"]) {
-        const profileSpan = statedSpan[profile];
-        if (profileSpan != null && resolvedOffset[profile] + profileSpan > 24) {
-            throw new Error(`Grid slot ${slotIndex} ${profile} offset plus span exceeds 24.`);
-        }
-    }
     return { slotIndex, span, offset };
 }
 /**
  * A shared Layout field, read the same way wherever it appears: a line on the 24-track form grid, so
  * anything outside 2..24 is not a narrower column but a mistake, and is dropped rather than clamped.
  */
-export function readPhiLayoutLabelEnd(value) {
+function readPhiLayoutLabelEnd(value) {
     const labelEnd = readNumber(value);
     return labelEnd !== undefined && Number.isInteger(labelEnd) && labelEnd >= 2 && labelEnd <= 24
         ? labelEnd
@@ -230,7 +206,7 @@ export function parsePhiCmsContentLayoutConfig(config) {
          * siblings are what a block turns into on its way to CSS, not something a preset writes. The
          * constraints never had the second way at all -- nothing has ever read a flat `maxWidth`.
          */
-        size: readRenderableBlockSize(config.size),
+        size: normalizePhiRenderableBlockResponsiveSize(config.size),
         margin: readCssSize(config.margin),
         labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
         padding: readCssSize(config.padding),
@@ -238,10 +214,6 @@ export function parsePhiCmsContentLayoutConfig(config) {
         paddingRight: readCssSize(config.paddingRight),
         paddingTop: readCssSize(config.paddingTop),
         paddingBottom: readCssSize(config.paddingBottom),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
         /*
          * Handed on as the block anchor, like every other Layout's. This one used to be folded into a
          * placement name here, and the renderer then asked the name for its `horizontal` -- a string has
@@ -262,10 +234,6 @@ export function parsePhiCmsFlexLayoutConfig(config) {
         paddingRight: readCssSize(config.paddingRight),
         paddingTop: readCssSize(config.paddingTop),
         paddingBottom: readCssSize(config.paddingBottom),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
         gap: readCssSize(config.gap),
         verticalSeparators: readBoolean(config.verticalSeparators) ?? false,
         separatorBeforeFirst: readBoolean(config.separatorBeforeFirst) ?? false,
@@ -289,10 +257,6 @@ export function parsePhiCmsFlexVerticalLayoutConfig(config) {
         paddingRight: readCssSize(config.paddingRight),
         paddingTop: readCssSize(config.paddingTop),
         paddingBottom: readCssSize(config.paddingBottom),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
         gap: readCssSize(config.gap),
         anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
     }, resolvePhiLayoutDefaults("verticalflex"));
@@ -302,18 +266,12 @@ export function parsePhiCmsMasonryLayoutConfig(config) {
         ...readRenderableBlockConfig(config),
         labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
         padding: readCssSize(config.padding),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
-        columns: readNumber(config.columns),
-        minColumnWidth: readPhiLengthValue(config.minColumnWidth) ?? undefined,
+        paddingLeft: readCssSize(config.paddingLeft),
+        paddingRight: readCssSize(config.paddingRight),
+        paddingTop: readCssSize(config.paddingTop),
+        paddingBottom: readCssSize(config.paddingBottom),
+        columns: readGridResponsiveCount(config.columns, isPhiGridColumnCount),
         gap: readCssSize(config.gap),
-        itemPadding: readCssSize(config.itemPadding),
-        itemBackground: readString(config.itemBackground),
-        itemBorder: readString(config.itemBorder),
-        itemBorderRadius: readCssSize(config.itemBorderRadius),
-        itemShadow: readPhiShadow(config.itemShadow),
     }, resolvePhiLayoutDefaults("masonry"));
 }
 export function parsePhiCmsStackLayoutConfig(config) {
@@ -321,10 +279,6 @@ export function parsePhiCmsStackLayoutConfig(config) {
         ...readRenderableBlockConfig(config),
         labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
         padding: readCssSize(config.padding),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
         defaultActiveSlotKey: readString(config.defaultActiveSlotKey),
         slotDisplay: config.slotDisplay === "stacked" ? "stacked" : "single",
         mountPolicy: readPhiCmsMountPolicy(config.mountPolicy, "remount"),
@@ -381,27 +335,22 @@ export function parsePhiCmsCarouselLayoutConfig(config) {
     const loop = readCarouselFlag(config.loop, "loop");
     const autoplayMs = readCarouselCount(config.autoplayMs, "autoplayMs", 0);
     const lookahead = readCarouselCount(config.lookahead, "lookahead", 0);
+    const slotGap = readCarouselMember(config.slotGap, PHI_SPACING_SCALE_KEYS, "slotGap");
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
         labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
         padding: readCssSize(config.padding),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
         defaultActiveSlotKey: readString(config.defaultActiveSlotKey),
         ...(visibleSlots === undefined ? {} : { visibleSlots }),
         ...(windowAnchor === undefined ? {} : { windowAnchor }),
         ...(transition === undefined ? {} : { transition }),
-        // Absent means "whatever the theme does", which is why nothing is written here rather than a
-        // number this parser invented.
         ...(config.transitionDurationMs === undefined || config.transitionDurationMs === null ? {} : {
             transitionDurationMs: clampPhiSequenceTransitionMs(config.transitionDurationMs),
         }),
         ...(config.transitionEasing === undefined ? {} : {
             transitionEasing: readPhiMotionEasing(config.transitionEasing, undefined),
         }),
-        slotGap: readString(config.slotGap),
+        ...(slotGap === undefined ? {} : { slotGap }),
         ...(controls === undefined ? {} : { controls }),
         ...(loop === undefined ? {} : { loop }),
         // Zero is how "does not move on its own" is written, so it is the one number below the floor
@@ -421,15 +370,15 @@ function readCollapsibleSize(value) {
 function readExpandIconPlacement(value) {
     return value === "start" || value === "end" ? value : undefined;
 }
-function readSlotTitles(value) {
+function readSlotTexts(value) {
     if (!Array.isArray(value)) {
         return undefined;
     }
-    const titles = value.map((candidate) => (typeof candidate === "string" ? candidate.trim() : ""));
-    while (titles.length > 0 && !titles[titles.length - 1]) {
-        titles.pop();
+    const texts = value.map((candidate) => (typeof candidate === "string" ? candidate.trim() : ""));
+    while (texts.length > 0 && !texts[texts.length - 1]) {
+        texts.pop();
     }
-    return titles.length > 0 ? titles : undefined;
+    return texts.length > 0 ? texts : undefined;
 }
 export function parsePhiCmsCollapsibleLayoutConfig(config) {
     return applyPhiLayoutDefaults({
@@ -441,15 +390,11 @@ export function parsePhiCmsCollapsibleLayoutConfig(config) {
         paddingRight: readCssSize(config.paddingRight),
         paddingTop: readCssSize(config.paddingTop),
         paddingBottom: readCssSize(config.paddingBottom),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
         anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
         panelMinHeight: readPhiLengthValue(config.panelMinHeight) ?? undefined,
         accordion: readBoolean(config.accordion),
-        slotTitles: readSlotTitles(config.slotTitles),
-        translateSlotTitles: readBoolean(config.translateSlotTitles),
+        slotTitles: readSlotTexts(config.slotTitles),
+        slotDescriptions: readSlotTexts(config.slotDescriptions),
         defaultOpenSlotKeys: readStringArray(config.defaultOpenSlotKeys),
         collapsible: readCollapsibleTrigger(config.collapsible),
         ghost: readBoolean(config.ghost),
@@ -465,27 +410,18 @@ export function parsePhiCmsGridLayoutConfig(config) {
         ...readRenderableBlockConfig(config),
         labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
         padding: readCssSize(config.padding),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
+        paddingLeft: readCssSize(config.paddingLeft),
+        paddingRight: readCssSize(config.paddingRight),
+        paddingTop: readCssSize(config.paddingTop),
+        paddingBottom: readCssSize(config.paddingBottom),
         gap: readCssSize(config.gap),
         anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
-        columnGap: readCssSize(config.columnGap),
-        align: readString(config.align),
-        justify: readString(config.justify),
-        wrap: readBoolean(config.wrap) ??
-            readString(config.wrap) ??
-            false,
+        columns: readGridResponsiveCount(config.columns, isPhiGridColumnCount),
         slotPlacements: Array.isArray(config.slotPlacements)
             ? config.slotPlacements
                 .map((slot, slotIndex) => readGridSlotPlacement(slot, slotIndex))
                 .filter((slot) => slot !== null)
             : undefined,
-        slotBackground: readString(config.slotBackground),
-        slotBorder: readString(config.slotBorder),
-        slotBorderRadius: readCssSize(config.slotBorderRadius),
-        slotShadow: readPhiShadow(config.slotShadow),
     }, resolvePhiLayoutDefaults("grid"));
 }
 export function parsePhiCmsThreeColumnLayoutConfig(config) {
@@ -497,10 +433,6 @@ export function parsePhiCmsThreeColumnLayoutConfig(config) {
         paddingRight: readCssSize(config.paddingRight),
         paddingTop: readCssSize(config.paddingTop),
         paddingBottom: readCssSize(config.paddingBottom),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
         balancedSides: readBoolean(config.balancedSides) ?? true,
         gap: readCssSize(config.gap),
         anchor: readRenderableBlockAnchorOrPlacement(config.anchor),
@@ -520,22 +452,9 @@ export function parsePhiCmsSplitCardLayoutConfig(config) {
         ...readRenderableBlockConfig(config),
         labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
         gap: readCssSize(config.gap),
+        swapRatio: readBoolean(config.swapRatio),
         padding: readCssSize(config.padding),
         paddingTop: readCssSize(config.paddingTop),
         paddingBottom: readCssSize(config.paddingBottom),
-        background: readString(config.background),
-        borderSource: readPhiCmsBorderSource(config.borderSource),
-        border: readString(config.border),
-        borderRadius: readCssSize(config.borderRadius),
-        effect: isPhiLayoutEffectId(config.effect) ? config.effect : undefined,
-        shadow: readPhiShadow(config.shadow),
-        leftPadding: readCssSize(config.leftPadding),
-        rightPadding: readCssSize(config.rightPadding),
-        leftBackground: normalizePhiBackgroundWidgetConfig(config.leftBackground),
-        rightBackground: normalizePhiBackgroundWidgetConfig(config.rightBackground),
-        leftBorder: readPhiCmsBorderWidgetConfig(config.leftBorder),
-        rightBorder: readPhiCmsBorderWidgetConfig(config.rightBorder),
-        leftShadow: readPhiShadow(config.leftShadow),
-        rightShadow: readPhiShadow(config.rightShadow),
     }, resolvePhiLayoutDefaults("split"));
 }

package/types/cms-container.d.ts

@@ -1,16 +1,16 @@
 import type { CSSProperties } from "react";
-import type { PhiCmsBackgroundWidgetConfig } from "../components/widgets/config/background";
-import type { PhiCmsBorderWidgetConfig } from "./cms-config";
-import type { PhiLayoutEffectId, PhiShadow } from "./layout-style";
+import type { PhiSurface } from "./surface";
+/**
+ * What a Region or an Overlay container looks like: its inset, and its Surface.
+ *
+ * The Surface is the same shape a Layout and a Widget carry (`types/surface.ts`); padding stays beside it
+ * because it is geometry, not appearance.
+ */
 export type PhiCmsContainerChromeConfig = {
     padding?: CSSProperties["padding"];
     paddingTop?: CSSProperties["paddingTop"];
     paddingRight?: CSSProperties["paddingRight"];
     paddingBottom?: CSSProperties["paddingBottom"];
     paddingLeft?: CSSProperties["paddingLeft"];
-    background?: CSSProperties["background"];
-    backgroundConfig?: PhiCmsBackgroundWidgetConfig | null;
-    border?: boolean | CSSProperties["border"] | PhiCmsBorderWidgetConfig;
-    shadow?: PhiShadow;
-    effect?: PhiLayoutEffectId;
+    surface?: PhiSurface | null;
 };

package/types/cms-module-descriptors.d.ts

@@ -8,22 +8,6 @@ import type { PhiViewerAccessPolicy } from "./access";
 import type { PhiSignalRoute } from "./signals";
 import type { PhiCmsInstanceId } from "./cms-instance-id";
 export type PhiRuntimeModuleId = `${string}/${string}`;
-export type PhiCmsRouteMountKey = string;
-/**
- * A published name a Module can hang a navigation entry under.
- *
- * A mount says nothing about paths -- every route outside Public is under its own package already, so
- * the address is unique without it. What it still does is let one package put its entry inside a
- * container another package owns, without hardcoding that container's item key.
- */
-export type PhiCmsAreaRouteMountDescriptor = {
-    mountKey: PhiCmsRouteMountKey;
-    navKey: `${PhiCmsAreaKey}:${string}`;
-    parentItemKey: string;
-};
-export type PhiCmsRouteMountReference = {
-    mountKey: PhiCmsRouteMountKey;
-};
 export type PhiCmsPresetIdentity = {
     ownerModuleId: PhiRuntimeModuleId;
     presetKey: string;
@@ -37,7 +21,6 @@ export type PhiCmsAreaDefinition = {
     shellPresetKey: string;
     accessPolicy: PhiViewerAccessPolicy;
     navigationSurfaces?: readonly PhiCmsNavigationSurfaceDescriptor[];
-    routeMounts?: readonly PhiCmsAreaRouteMountDescriptor[];
 };
 export type PhiCmsAreaShellCompositionSource = PhiCmsPresetIdentity & {
     omitRegionTypes?: readonly PhiCmsRegionTypeValue[];
@@ -78,7 +61,6 @@ export type PhiCmsRoutePresetDescriptor = PhiCmsPresetIdentity & {
      * not an address it needs to do its work.
      */
     landingPage?: true;
-    mount?: PhiCmsRouteMountReference;
     title: string;
     /**
      * The `PhiCmsFlags` a Page of this route starts out with.
@@ -94,6 +76,12 @@ export type PhiCmsRoutePresetDescriptor = PhiCmsPresetIdentity & {
         params: Readonly<Record<string, string>>;
     }) => PhiResolvedCmsPageTree | Promise<PhiResolvedCmsPageTree>;
     navigation?: readonly PhiCmsNavigationInjectionDescriptor[];
+    /**
+     * The Page's guided Tour, in the owning Module's language (design/TOURS.md). Read with the route, not
+     * from the tree, so a Page the Site has edited keeps it; offered only where a Controller in the Area
+     * takes Page Tours. Its steps point at this preset's own nodes.
+     */
+    tour?: import("./tours").PhiTourDefinition;
 };
 export type PhiCmsThemePresetDescriptor = PhiCmsPresetIdentity & {
     presetVersion: number;
@@ -125,6 +113,15 @@ export type PhiCmsThemeBlockDescriptor = PhiCmsPresetIdentity & {
 export type PhiCmsNavigationLabel = {
     defaultMessage: string;
     messageId?: string;
+    /**
+     * The language `defaultMessage` is written in, when it is the text a Module shipped.
+     *
+     * Set where a Module's entry is resolved, and gone wherever the Site's operator replaces the text: a
+     * label without it is the operator's and written in the Site's source language. Without the
+     * difference a Site whose source language is not the Module's took the Module's English for its own
+     * German and never translated it.
+     */
+    sourceLocale?: string;
 };
 /**
  * Where an Area's own entry stands among the ones Modules contribute.
@@ -373,13 +370,6 @@ export type PhiCmsNavigationOverlayResolution = {
     surface: PhiCmsResolvedNavigationSurface;
     diagnostics: readonly PhiCmsNavigationOverlayDiagnostic[];
 };
-export type PhiCmsModulePresetDescriptors = {
-    areaShells?: readonly PhiCmsAreaShellPresetDescriptor[];
-    areaOverlays?: readonly PhiCmsAreaOverlayPresetDescriptor[];
-    routes?: readonly PhiCmsRoutePresetDescriptor[];
-    themes?: readonly PhiCmsThemePresetDescriptor[];
-    themeBlocks?: readonly PhiCmsThemeBlockDescriptor[];
-};
 export type PhiCmsAreaShellPresetBinding = {
     descriptor: PhiCmsAreaShellPresetDescriptor;
 };
@@ -427,6 +417,8 @@ export type PhiCmsCompiledDescriptorCatalog = {
     themeByKey: ReadonlyMap<string, PhiCmsThemePresetBinding>;
     /** Keyed by `<kind>:<blockKey>`, so a style and a ground may share a name. */
     themeBlockByKey: ReadonlyMap<string, PhiCmsThemeBlockBinding>;
+    /** Each Module's source language: the one the text its descriptors ship is written in. */
+    sourceLocaleByModuleId: ReadonlyMap<PhiRuntimeModuleId, string>;
 };
 export type PhiCmsActiveRouteTable = {
     area: PhiCmsAreaKey;

package/types/cms-mount-policy.d.ts

@@ -17,7 +17,6 @@
  */
 export declare const PHI_CMS_MOUNT_POLICIES: readonly ["remount", "lazy-keep", "eager"];
 export type PhiCmsMountPolicy = (typeof PHI_CMS_MOUNT_POLICIES)[number];
-export declare function isPhiCmsMountPolicy(value: unknown): value is PhiCmsMountPolicy;
 /**
  * A stored value, or the container's own default where none is stored.
  *

package/types/cms-mount-policy.js

@@ -16,7 +16,7 @@
  * definition says.
  */
 export const PHI_CMS_MOUNT_POLICIES = ["remount", "lazy-keep", "eager"];
-export function isPhiCmsMountPolicy(value) {
+function isPhiCmsMountPolicy(value) {
     return typeof value === "string" && PHI_CMS_MOUNT_POLICIES.includes(value);
 }
 /**

package/types/cms-overlay.d.ts

@@ -9,11 +9,23 @@ export declare const PHI_OVERLAY_FOOTER_PRESENTATIONS: readonly ["none", "action
 export type PhiOverlayFooterPresentation = (typeof PHI_OVERLAY_FOOTER_PRESENTATIONS)[number];
 export declare const PHI_CMS_OVERLAY_MASK_APPEARANCES: readonly ["transparent", "normal", "blurred"];
 export type PhiCmsOverlayMaskAppearance = (typeof PHI_CMS_OVERLAY_MASK_APPEARANCES)[number];
+/**
+ * The stored mask: how it is drawn. Whether it stops the pointer and whether a click on it closes the
+ * Overlay are the Overlay's `flags` (`MaskPassesPointer`, `MaskKeepsOpen`), read into
+ * `PhiOverlayMaskBehaviour` for the Controls.
+ */
 export type PhiCmsOverlayMaskConfig = {
     appearance: PhiCmsOverlayMaskAppearance;
+};
+/** The mask as a Control is handed it: its look and the two answers the flags give. */
+export type PhiOverlayMaskBehaviour = PhiCmsOverlayMaskConfig & {
     allowOutsideInteraction: boolean;
     closable: boolean;
 };
+/** Whether a Drawer pushes a nested one aside, and how far when it says. */
+export type PhiOverlayPushBehaviour = boolean | {
+    distance: PhiCmsOverlaySize;
+};
 export type PhiCmsOverlaySize = string | number;
 /** A Modal width per responsive mode; unset modes cascade from the nearest smaller one that is set. */
 export type PhiCmsOverlayResponsiveSize = PhiResponsiveValue<PhiCmsOverlaySize>;
@@ -26,19 +38,20 @@ type PhiOverlayChromeConfig = Omit<PhiCmsContainerChromeConfig, "padding" | "pad
 export type PhiCmsOverlayConfig = PhiOverlayChromeConfig & {
     title: string | null;
     controlSize?: PhiControlSize;
-    closable: boolean;
-    keyboard: boolean;
+    /**
+     * The Overlay's yes-or-no answers as `PhiCmsFlags` bits: `NoCloseButton`, `NoEscapeClose`, `Centered`,
+     * `Resizable`, `Push`, `MaskPassesPointer`, `MaskKeepsOpen`. Unset is the plain Overlay;
+     * `resolvePhiCmsOverlayBehaviour` reads them into what the Controls take.
+     */
+    flags: number;
     mountPolicy: PhiCmsMountPolicy;
     mask: PhiCmsOverlayMaskConfig;
-    centered: boolean;
     width?: PhiCmsOverlaySize | PhiCmsOverlayResponsiveSize;
     size?: PhiCmsOverlaySize;
     placement: "top" | "right" | "bottom" | "left";
     maxSize?: number;
-    resizable: boolean;
-    push: boolean | {
-        distance: string | number;
-    };
+    /** How far a pushing Drawer (`Push`) moves the one beneath; unset leaves it the Control's distance. */
+    pushDistance?: PhiCmsOverlaySize;
     closeMode: "immediate" | "request";
     /**
      * Which Table action this Overlay opens for, when it is opened by one.
@@ -57,6 +70,20 @@ export type PhiCmsOverlayConfig = PhiOverlayChromeConfig & {
     openActionKey: string | null;
     signalRoutes: PhiSignalRouteSet | null;
 };
+/**
+ * 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 declare function resolvePhiCmsOverlayBehaviour(config: Pick<PhiCmsOverlayConfig, "flags" | "mask" | "pushDistance">): {
+    closable: boolean;
+    keyboard: boolean;
+    centered: boolean;
+    resizable: boolean;
+    push: PhiOverlayPushBehaviour;
+    mask: PhiOverlayMaskBehaviour;
+};
 export declare function isPhiCmsOverlayType(value: unknown): value is PhiCmsOverlayType;
 export declare function readPhiOverlayCloseRequest(value: unknown): PhiOverlayCloseRequest | null;
 export declare function parsePhiCmsOverlayConfig(rawConfig: Record<string, unknown>, overlayType?: PhiCmsOverlayType): PhiCmsOverlayConfig;