@phis/ui 0.2.1 → 0.4.0

package/components/layouts/clients/phi-collapsible-layout-client.js

@@ -1,16 +1,22 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Collapse } from "antd";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useEffectEvent, useMemo, useRef, useState } from "react";
 import { usePhiConfig } from "../../root/phi-config-provider";
 import { createPhiSignalAddress } from "../../../types/signals";
 import { usePhiSignalDispatcher, usePhiSignalListener } from "../../runtime/runtime-signal-bus";
 import { usePhiSignalIdentity } from "../../runtime/runtime-signal-identity";
 import { PhiLayoutAnchoredOverlay } from "./phi-layout-anchored-overlay";
+import { PhiDescriptionHint } from "../../controls/phi-description-tooltip-icon";
+import { PHI_SPACE } from "../../../theme/antd-css-var-contract";
+import { PhiCollapseControl, } from "../../controls/phi-collapse-control";
 import { PhiBaseLayoutSlotStateProvider, usePhiBaseLayoutSlotStates, PhiBaseLayoutSlotScope, } from "./phi-base-layout-client";
 import { resolvePhiBaseLayoutChrome, } from "../phi-layout-view-model";
 import { resolvePhiAnchorPlacement } from "../phi-layout-contract";
 import { isPhiLayoutAuthoringRender, phiLayoutDebugLayerMarker, phiLayoutSlotClassName, phiLayoutSlotContentMarker, } from "../../../helpers/layout-authoring-markers";
+import { PhiSurfaceGroundLayer } from "../../surface/phi-surface-ground";
+import { usePhiLayoutSignalSurface } from "../phi-layout-signal-surface";
+import { PhiSurfaceTone } from "../../surface/phi-surface-tone";
+import { resolvePhiSurfaceToneClassName } from "../../../types/surface";
 function isRenderableSlotChild(child) {
     return child !== null && child !== undefined && child !== false;
 }
@@ -28,12 +34,6 @@ function resolveDefaultOpenSlotKeys(defaultOpenSlotKeys, validSlotKeys, accordio
     }
     return validSlotKeys[0] ? [validSlotKeys[0]] : [];
 }
-function toCollapseActiveKey(keys, accordion) {
-    return accordion ? keys[0] ?? undefined : [...keys];
-}
-function readCollapseKeys(value) {
-    return Array.isArray(value) ? value : value ? [value] : [];
-}
 /**
  * The header's own class, put there by this adapter rather than read off Ant Design.
  *
@@ -42,7 +42,7 @@ function readCollapseKeys(value) {
  * told from the other. The test used to be `.ant-collapse-header`, which is a name the library owns: no
  * import names it, no validator sees it, and swapping Ant Design out would have left the check compiling
  * and silently matching nothing, so every header click in the Builder would have selected the block
- * instead of folding the slot. The primitive takes a class for that element, so the name is ours and the
+ * instead of folding the slot. The Control takes a class for that element, so the name is ours and the
  * element is the same one.
  */
 const PHI_COLLAPSIBLE_HEADER_CLASS = "phi-collapsible-header";
@@ -58,26 +58,10 @@ function shouldStopCollapsibleEditorScaffoldEvent(event) {
     return Boolean(target.closest(`.${PHI_COLLAPSIBLE_HEADER_CLASS}`) ||
         target.closest("[data-phi-collapsible-title-control='true']"));
 }
-function resolveCollapsibleStyles(titleStrong, headerPadding, innerPadding) {
-    /*
-     * The grounds are square, because they are not an edge.
-     *
-     * A header and a panel are the filling of the Layout box, not a box of their own, and the box has
-     * already decided its corner -- from the shape or from what the author configured. Rounding them a
-     * second time means the same number in two places, which is the arrangement that drifts apart the
-     * moment one of the two gains a source the other does not have. Squared, the wrapper's clip is the
-     * only corner there is, and it is the box's.
-     */
-    return {
-        header: { ...(headerPadding == null ? {} : { padding: headerPadding }), borderRadius: 0 },
-        title: titleStrong ? { fontWeight: 600 } : undefined,
-        body: { ...(innerPadding == null ? {} : { padding: innerPadding }), borderRadius: 0 },
-    };
-}
 export function PhiCollapsibleLayout(props) {
     return (_jsx(PhiBaseLayoutSlotStateProvider, { slotCount: props.slots.length, initialSlotStates: props.initialSlotStates, children: _jsx(PhiCollapsibleLayoutBody, { ...props }) }));
 }
-function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMinHeight, accordion = false, slotTitles, onOpenSlotKeysChange, defaultOpenSlotKeys, collapsible = "header", ghost = true, expandIconPlacement = "start", collapseSize = "medium", titleStrong = true, headerPadding, innerPadding, ...layoutProps }) {
+function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMinHeight, accordion = false, slotTitles, slotDescriptions, onOpenSlotKeysChange, defaultOpenSlotKeys, collapsible = "header", ghost = true, expandIconPlacement = "start", collapseSize = "medium", titleStrong = true, headerPadding, innerPadding, ...layoutProps }) {
     // Named fields rather than the rest object: handing the compiler a whole rest object makes every
     // value later destructured out of it look like it may change, which costs the component its memoization.
     const isAuthoringRender = isPhiLayoutAuthoringRender({
@@ -89,7 +73,8 @@ function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMin
     const { token } = usePhiConfig();
     const resolvedHeaderPadding = headerPadding ?? token.paddingSM;
     const resolvedInnerPadding = innerPadding ?? token.padding;
-    const { layoutKind = "collapsible", renderMode, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, backgroundLayer, borderSource, border, borderRadius, effect, shadow, anchor, editSlotAnchor, editSlotAction, editRenderInsertControl, editRenderTitleControl, editSlotLabels, editSlotTitleAction, style, labelEnd, } = layoutProps;
+    const { layoutKind = "collapsible", renderMode, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface: storedSurface, anchor, editSlotAnchor, editSlotAction, editRenderInsertControl, editRenderTitleControl, editSlotLabels, editSlotTitleAction, style, labelEnd, } = layoutProps;
+    const surface = usePhiLayoutSignalSurface(blockId, storedSurface);
     const resolvedRenderMode = renderMode ?? "live";
     const isEditMode = resolvedRenderMode === "editor";
     const resolvedSlotStates = usePhiBaseLayoutSlotStates() ?? [];
@@ -111,11 +96,17 @@ function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMin
      * The keys of the slots that are off the screen. A hidden panel must not be the open one: with an
      * accordion that would leave the Collapse showing nothing at all.
      */
-    const hiddenSlotKeys = new Set(renderedSlotIndices
+    const hiddenSlotKeysSignature = renderedSlotIndices
         .filter((slotIndex) => (resolvedSlotStates[slotIndex] ?? "expanded") === "hidden")
         .map((slotIndex) => validSlotKeys[slotIndex])
-        .filter((key) => Boolean(key)));
-    const baseOpenSlotKeys = useMemo(() => resolveDefaultOpenSlotKeys(defaultOpenSlotKeys, validSlotKeys, accordion), [accordion, defaultOpenSlotKeys, validSlotKeys]);
+        .filter((key) => Boolean(key))
+        .join("\u0000");
+    const hiddenSlotKeys = useMemo(() => new Set(hiddenSlotKeysSignature ? hiddenSlotKeysSignature.split("\u0000") : []), [hiddenSlotKeysSignature]);
+    /*
+     * The default open panel is chosen among the visible ones. Filtering a hidden open panel out only at
+     * the end left an accordion whose one open panel was hidden showing nothing but headers.
+     */
+    const baseOpenSlotKeys = useMemo(() => resolveDefaultOpenSlotKeys(defaultOpenSlotKeys, validSlotKeys.filter((key) => !hiddenSlotKeys.has(key)), accordion), [accordion, defaultOpenSlotKeys, hiddenSlotKeys, validSlotKeys]);
     const baseOpenSlotKeysSignature = useMemo(() => JSON.stringify(baseOpenSlotKeys), [baseOpenSlotKeys]);
     const [controlledOpenSlotKeys, setControlledOpenSlotKeys] = useState(null);
     const resolvedOpenSlotKeysBase = controlledOpenSlotKeys?.signature === baseOpenSlotKeysSignature
@@ -126,13 +117,19 @@ function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMin
         if (!isEditMode || !appendSlotKey) {
             return resolvedOpenSlotKeysBase;
         }
+        /*
+         * An accordion holds one panel open. In the editor that is the empty insertion panel until the
+         * author opens another one; from then on the author's choice is what shows.
+         */
         if (accordion) {
-            return [appendSlotKey];
+            return controlledOpenSlotKeys?.signature === baseOpenSlotKeysSignature
+                ? controlledOpenSlotKeys.keys
+                : [appendSlotKey];
         }
         return resolvedOpenSlotKeysBase.includes(appendSlotKey)
             ? resolvedOpenSlotKeysBase
             : [...resolvedOpenSlotKeysBase, appendSlotKey];
-    }, [accordion, appendSlotKey, isEditMode, resolvedOpenSlotKeysBase]);
+    }, [accordion, appendSlotKey, baseOpenSlotKeysSignature, controlledOpenSlotKeys, isEditMode, resolvedOpenSlotKeysBase]);
     const effectiveCollapsible = isEditMode && collapsible !== "disabled" ? "icon" : collapsible;
     const receiverAddress = useMemo(() => blockId == null ? null : createPhiSignalAddress("cms", blockId), [blockId]);
     const [editingSlotTitle, setEditingSlotTitle] = useState(null);
@@ -151,6 +148,20 @@ function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMin
     const signalScope = usePhiSignalIdentity().scope ?? "page";
     const openSlotKeysSignature = useMemo(() => JSON.stringify(resolvedOpenSlotKeys), [resolvedOpenSlotKeys]);
     const announcedOpenSlotKeys = useMemo(() => JSON.parse(openSlotKeysSignature), [openSlotKeysSignature]);
+    /*
+     * The callback hears what the signals hear: every change of the open panels, the ones a signal or
+     * `openSlot`/`closeSlot`/`toggleSlot` made included -- it used to hear only header clicks. Not the
+     * first render, which is no change.
+     */
+    const reportedOpenSlotKeysRef = useRef(null);
+    const reportOpenSlotKeys = useEffectEvent((keys) => onOpenSlotKeysChange?.(keys));
+    useEffect(() => {
+        const previous = reportedOpenSlotKeysRef.current;
+        reportedOpenSlotKeysRef.current = openSlotKeysSignature;
+        if (previous !== null && previous !== openSlotKeysSignature) {
+            reportOpenSlotKeys(JSON.parse(openSlotKeysSignature));
+        }
+    }, [openSlotKeysSignature]);
     useEffect(() => {
         if (!receiverAddress) {
             return;
@@ -194,8 +205,7 @@ function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMin
             signature: baseOpenSlotKeysSignature,
             keys: normalizedKeys,
         });
-        onOpenSlotKeysChange?.(normalizedKeys);
-    }, [accordion, baseOpenSlotKeysSignature, onOpenSlotKeysChange, validSlotKeys]);
+    }, [accordion, baseOpenSlotKeysSignature, validSlotKeys]);
     const openSlot = useCallback((slotKey) => {
         setControlledOpenSlotKeys((current) => {
             const normalizedSlotKey = slotKey.trim();
@@ -273,25 +283,23 @@ function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMin
         if (signal.action === "toggle") {
             toggleSlot(signal.value);
         }
-    }, [closeSlot, openSlot, receiverAddress, setOpenKeys, toggleSlot, validSlotKeys]), receiverAddress
+    }, [closeSlot, openSlot, receiverAddress, setOpenKeys, toggleSlot, validSlotKeys]), 
+    // Memoized: the bus re-subscribes whenever the filter object changes, and a literal here changed on
+    // every render.
+    useMemo(() => receiverAddress
         ? {
             receiver: receiverAddress,
             channels: ["openSlotKeys", "activeSlotKey", "activeSlotIndex", "slot"],
         }
-        : null);
-    const { style: resolvedLayoutStyle, hasExplicitLayoutBackground, } = resolvePhiBaseLayoutChrome({
+        : null, [receiverAddress]));
+    const { style: resolvedLayoutStyle, ground, hasExplicitLayoutBackground, } = resolvePhiBaseLayoutChrome({
         labelEnd,
         padding,
         paddingTop,
         paddingRight,
         paddingBottom,
         paddingLeft,
-        background,
-        borderSource,
-        border,
-        borderRadius,
-        effect,
-        shadow,
+        surface,
     });
     const resolvedStyle = {
         position: "relative",
@@ -363,12 +371,14 @@ function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMin
                         cursor: "text",
                     }, children: title }))
             : title;
+        const description = slotDescriptions?.[slotIndex]?.trim();
         return {
             key: slotKey,
-            label,
-            collapsible: effectiveCollapsible,
+            label: description
+                ? (_jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: PHI_SPACE.xs }, children: [label, _jsx("span", { style: { display: "inline-flex" }, onClick: (event) => event.stopPropagation(), onKeyDown: (event) => event.stopPropagation(), children: _jsx(PhiDescriptionHint, { description: description }) })] }))
+                : label,
             forceRender: isEditMode || isHiddenSlot,
-            ...(isHiddenSlot ? { style: { display: "none" } } : {}),
+            hidden: isHiddenSlot,
             children: childContent
                 ? childContent
                 : editSlotAction && editRenderInsertControl
@@ -392,41 +402,34 @@ function PhiCollapsibleLayoutBody({ blockId, slots, slotKeys, slotMeta, panelMin
         };
     })
         .filter((item) => item !== null);
-    return (_jsxs("div", { "data-layout-kind": layoutKind, "data-phi-block-render-mode": resolvedRenderMode, "data-phi-layout-debug-layer": phiLayoutDebugLayerMarker(isAuthoringRender), "data-phi-layout-has-explicit-layout-background": hasExplicitLayoutBackground ? "true" : "false", className: "phi-layout", style: resolvedStyle, children: [backgroundLayer, _jsx("div", { 
-                /*
-                 * The grounds inside follow the corner outside.
-                 *
-                 * A Collapse paints its own header and panel grounds, and it rounds them from its own token --
-                 * the Site's surface step, which is the box's corner only as long as nobody set another one.
-                 * Under `custom` the box can be rounded 30px while the ground inside is still rounded 8, and the
-                 * colour then squares off the corner it sits in.
-                 *
-                 * `border-radius: inherit` takes the box's corner literally, whatever it resolved to, and the
-                 * clip makes every ground inside end there -- which works because the grounds are square
-                 * (`resolveCollapsibleStyles`): a clip only ever takes away, so a ground that rounded itself
-                 * more tightly than the box would keep its own corner and the clip would never reach it.
-                 *
-                 * The clip earns its place twice over: it shapes the corner, and it keeps the content of a
-                 * panel inside the panel.
-                 */
-                style: { borderRadius: "inherit", overflow: "hidden" }, onMouseDown: isEditMode
-                    ? (event) => {
-                        if (shouldStopCollapsibleEditorScaffoldEvent(event)) {
-                            event.stopPropagation();
-                        }
-                    }
-                    : undefined, onClick: isEditMode
-                    ? (event) => {
-                        if (shouldStopCollapsibleEditorScaffoldEvent(event)) {
-                            event.stopPropagation();
-                        }
-                    }
-                    : undefined, children: _jsx(Collapse, { accordion: accordion, activeKey: toCollapseActiveKey(resolvedOpenSlotKeys.filter((key) => !hiddenSlotKeys.has(key)), accordion), 
+    return (_jsx(PhiSurfaceTone, { tone: surface?.tone, children: _jsxs("div", { "data-layout-kind": layoutKind, "data-phi-block-render-mode": resolvedRenderMode, "data-phi-layout-debug-layer": phiLayoutDebugLayerMarker(isAuthoringRender), "data-phi-layout-has-explicit-layout-background": hasExplicitLayoutBackground ? "true" : "false", className: ["phi-layout", resolvePhiSurfaceToneClassName(surface?.tone)].filter(Boolean).join(" "), style: resolvedStyle, children: [_jsx(PhiSurfaceGroundLayer, { ground: ground }), _jsx("div", { 
                     /*
-                     * Never its own outline: the Layout box draws it, out of `borderSource`, for every Layout the
-                     * same way. What stays here is `ghost`, which decides the inside -- and Ant Design's borderless
-                     * variant keeps the first header's top corners on `collapsePanelBorderRadius`, the same surface
-                     * step the box takes, so inside and outside meet on one number.
+                     * The grounds inside follow the corner outside.
+                     *
+                     * A Collapse paints its own header and panel grounds, and it rounds them from its own token --
+                     * the Site's surface step, which is the box's corner only as long as nobody set another one.
+                     * Under `custom` the box can be rounded 30px while the ground inside is still rounded 8, and the
+                     * colour then squares off the corner it sits in.
+                     *
+                     * `border-radius: inherit` takes the box's corner literally, whatever it resolved to, and the
+                     * clip makes every ground inside end there -- which works because the grounds are square
+                     * (PhiCollapseControl squares them): a clip only ever takes away, so a ground that rounded itself
+                     * more tightly than the box would keep its own corner and the clip would never reach it.
+                     *
+                     * The clip earns its place twice over: it shapes the corner, and it keeps the content of a
+                     * panel inside the panel.
                      */
-                    bordered: false, ghost: ghost, collapsible: effectiveCollapsible, destroyOnHidden: false, expandIconPlacement: expandIconPlacement, size: collapseSize, classNames: { header: PHI_COLLAPSIBLE_HEADER_CLASS }, items: items, onChange: (nextKeys) => setOpenKeys(readCollapseKeys(nextKeys)), styles: resolveCollapsibleStyles(titleStrong, resolvedHeaderPadding, resolvedInnerPadding), style: { width: "100%" } }) })] }));
+                    style: { borderRadius: "inherit", overflow: "hidden" }, onMouseDown: isEditMode
+                        ? (event) => {
+                            if (shouldStopCollapsibleEditorScaffoldEvent(event)) {
+                                event.stopPropagation();
+                            }
+                        }
+                        : undefined, onClick: isEditMode
+                        ? (event) => {
+                            if (shouldStopCollapsibleEditorScaffoldEvent(event)) {
+                                event.stopPropagation();
+                            }
+                        }
+                        : undefined, children: _jsx(PhiCollapseControl, { accordion: accordion, openKeys: resolvedOpenSlotKeys.filter((key) => !hiddenSlotKeys.has(key)), ghost: ghost, collapsible: effectiveCollapsible, expandIconPlacement: expandIconPlacement, size: collapseSize, headerClassName: PHI_COLLAPSIBLE_HEADER_CLASS, sections: items, onOpenKeysChange: setOpenKeys, titleStrong: titleStrong, headerPadding: resolvedHeaderPadding, bodyPadding: resolvedInnerPadding, style: { width: "100%" } }) })] }) }));
 }

package/components/layouts/clients/phi-content-layout-client.d.ts

@@ -1,39 +1,10 @@
-import type { CSSProperties, ReactNode } from "react";
-import { type PhiLayoutEditRenderInsertControl, type PhiLayoutKind } from "../phi-layout-contract";
+import { type PhiBaseLayoutProps } from "../phi-layout-view-model";
 import type { PhiAnchorWidgetPlacement } from "../../controls/phi-anchor-control-contract";
-import type { PhiRenderableBlockRenderMode, PhiRenderableBlockResponsiveSize } from "../../../types";
-import type { PhiShadow, PhiLayoutEffectId } from "../../../types/layout-style";
-import type { PhiCmsBorderSource } from "../../../types/cms-border-source";
-export type PhiContentLayoutProps = {
-    blockId?: string | number | null;
-    slots?: ReactNode[];
-    renderMode?: PhiRenderableBlockRenderMode;
+import type { PhiRenderableBlockResponsiveSize } from "../../../types";
+export type PhiContentLayoutProps = Pick<PhiBaseLayoutProps, "blockId" | "slots" | "renderMode" | "margin" | "zIndex" | "layoutKind" | "labelEnd" | "padding" | "paddingTop" | "paddingRight" | "paddingBottom" | "paddingLeft" | "surface" | "editSlotAction" | "editRenderInsertControl" | "style"> & {
     size?: PhiRenderableBlockResponsiveSize | null;
     minSize?: PhiRenderableBlockResponsiveSize | null;
     maxSize?: PhiRenderableBlockResponsiveSize | null;
-    margin?: CSSProperties["margin"];
-    zIndex?: number;
-    effect?: PhiLayoutEffectId;
-    shadow?: PhiShadow | null;
-    layoutKind?: PhiLayoutKind;
-    labelEnd?: number;
-    padding?: CSSProperties["padding"];
-    paddingTop?: CSSProperties["paddingTop"];
-    paddingRight?: CSSProperties["paddingRight"];
-    paddingBottom?: CSSProperties["paddingBottom"];
-    paddingLeft?: CSSProperties["paddingLeft"];
-    background?: CSSProperties["background"];
-    backgroundLayer?: ReactNode;
-    border?: CSSProperties["border"];
-    borderSource?: PhiCmsBorderSource;
-    borderRadius?: CSSProperties["borderRadius"];
-    editSlotAction?: (slotIndex: number, options?: {
-        defaultPickSection?: "layout" | "widget";
-        allowWidgetSection?: boolean;
-        slotIndex?: number;
-    }) => void;
-    editRenderInsertControl?: PhiLayoutEditRenderInsertControl;
     editSlotAnchor?: PhiAnchorWidgetPlacement | null;
-    style?: CSSProperties;
 };
-export declare function PhiContentLayout({ blockId, slots, renderMode, margin, layoutKind, labelEnd, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, backgroundLayer, borderSource, border, borderRadius, effect, shadow, editSlotAction, editRenderInsertControl, editSlotAnchor, style, }: PhiContentLayoutProps): import("react").JSX.Element;
+export declare function PhiContentLayout({ blockId, slots, renderMode, margin, layoutKind, labelEnd, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface, editSlotAction, editRenderInsertControl, editSlotAnchor, style, }: PhiContentLayoutProps): import("react").JSX.Element;

package/components/layouts/clients/phi-content-layout-client.js

@@ -1,28 +1,24 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { isRenderablePhiNode } from "../phi-layout-scaffold-utils";
-import { resolvePhiLayoutInset, } from "../phi-layout-contract";
+import { resolvePhiLayoutInset } from "../phi-layout-contract";
 import { resolvePhiBaseLayoutChrome } from "../phi-layout-view-model";
 import { PhiLayoutAnchoredOverlay } from "./phi-layout-anchored-overlay";
 import { isPhiLayoutAuthoringRender, phiLayoutDebugLayerMarker, phiLayoutSlotClassName, phiLayoutSlotContentMarker, } from "../../../helpers/layout-authoring-markers";
-export function PhiContentLayout({ blockId, slots, renderMode = "live", margin = 0, layoutKind = "content", labelEnd, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, backgroundLayer, borderSource, border, borderRadius, effect, shadow, editSlotAction, editRenderInsertControl, editSlotAnchor = "center", style, }) {
+import { PhiLayoutSurfaceBox } from "../phi-layout-surface-box";
+export function PhiContentLayout({ blockId, slots, renderMode = "live", margin = 0, layoutKind = "content", labelEnd, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface, editSlotAction, editRenderInsertControl, editSlotAnchor = "center", style, }) {
     const isAuthoringRender = isPhiLayoutAuthoringRender({ editSlotAction, renderMode });
     const slot0 = Array.isArray(slots) ? slots[0] : undefined;
     const hasSlot0 = isRenderablePhiNode(slot0);
     const shouldFillBlock = true;
     const isEditor = renderMode === "editor";
-    const { style: resolvedLayoutStyle, hasExplicitLayoutBackground, } = resolvePhiBaseLayoutChrome({
+    const { style: resolvedLayoutStyle, ground, hasExplicitLayoutBackground, } = resolvePhiBaseLayoutChrome({
         labelEnd,
         padding,
         paddingTop,
         paddingRight,
         paddingBottom,
         paddingLeft,
-        background,
-        borderSource,
-        border,
-        borderRadius,
-        effect,
-        shadow,
+        surface,
     });
     const resolvedLayoutInset = resolvePhiLayoutInset({
         padding,
@@ -31,14 +27,14 @@ export function PhiContentLayout({ blockId, slots, renderMode = "live", margin =
         paddingBottom,
         paddingLeft,
     });
-    return (_jsxs("div", { "data-layout-kind": layoutKind, "data-phi-block-id": blockId ?? undefined, "data-phi-block-render-mode": renderMode, "data-phi-debug-scaffold": undefined, "data-phi-layout-debug-layer": phiLayoutDebugLayerMarker(isAuthoringRender), "data-phi-layout-has-slot0": hasSlot0 ? "true" : "false", "data-phi-layout-has-explicit-layout-background": hasExplicitLayoutBackground ? "true" : "false", className: "phi-layout", style: {
+    return (_jsxs(PhiLayoutSurfaceBox, { blockId: blockId, surface: surface, ground: ground, "data-layout-kind": layoutKind, "data-phi-block-id": blockId ?? undefined, "data-phi-block-render-mode": renderMode, "data-phi-debug-scaffold": undefined, "data-phi-layout-debug-layer": phiLayoutDebugLayerMarker(isAuthoringRender), "data-phi-layout-has-slot0": hasSlot0 ? "true" : "false", "data-phi-layout-has-explicit-layout-background": hasExplicitLayoutBackground ? "true" : "false", className: "phi-layout", style: {
             position: hasSlot0 || (isEditor && editSlotAction) ? "relative" : undefined,
             minWidth: 0,
             minHeight: 0,
             margin,
             ...resolvedLayoutStyle,
             ...style,
-        }, children: [backgroundLayer, _jsx("div", { className: phiLayoutSlotClassName(isAuthoringRender), "data-phi-layout-has-content": phiLayoutSlotContentMarker(isAuthoringRender, hasSlot0), style: {
+        }, children: [_jsx("div", { className: phiLayoutSlotClassName(isAuthoringRender), "data-phi-layout-has-content": phiLayoutSlotContentMarker(isAuthoringRender, hasSlot0), style: {
                     display: "flex",
                     flexDirection: "column",
                     alignItems: "stretch",

package/components/layouts/clients/phi-flex-layout-client.d.ts

@@ -2,6 +2,13 @@ import { type CSSProperties, type ReactNode } from "react";
 import { type PhiBaseLayoutProps } from "../phi-layout-view-model";
 import type { PhiAnchorWidgetPlacement } from "../../controls/phi-anchor-control-contract";
 type PhiFlexLayoutDistribution = "anchor" | "between" | "around" | "evenly";
+/**
+ * The Flex Layout, in a row or -- as `layoutKind: "verticalflex"` -- in a column.
+ *
+ * The column used to be a second component of its own, 105 lines the same as this one and the rest a
+ * copy that had drifted; this one already branched on the axis everywhere it matters. The row's
+ * distribution, wrapping and separators are the row's; the column states gap and anchor.
+ */
 export type PhiFlexLayoutProps = Omit<PhiBaseLayoutProps, "slots"> & {
     slots: ReactNode[];
     gap?: CSSProperties["gap"];

package/components/layouts/clients/phi-flex-layout-client.js

@@ -5,7 +5,8 @@ import { resolvePhiLayoutSlotChildSizing } from "./phi-layout-anchored-overlay";
 import { resolvePhiLayoutDefaults } from "../../../helpers/cms-layout-defaults";
 import { resolvePhiBaseLayoutChrome, resolvePhiBaseLayoutSlotStates, } from "../phi-layout-view-model";
 import { isPhiLayoutAuthoringRender, phiLayoutDebugLayerMarker, phiLayoutSlotClassName, phiLayoutSlotContentMarker, } from "../../../helpers/layout-authoring-markers";
-const PHI_FLEX_LAYOUT_DEFAULTS = resolvePhiLayoutDefaults("flex");
+import { PhiLayoutSurfaceBox } from "../phi-layout-surface-box";
+import { PHI_CMS_MAX_LAYOUT_SLOTS } from "../../../constants/cms-layout-types";
 export function PhiFlexLayout({ slots, ...layoutProps }) {
     // Named fields rather than the rest object: handing the compiler a whole rest object makes every
     // value later destructured out of it look like it may change, which costs the component its memoization.
@@ -15,25 +16,21 @@ export function PhiFlexLayout({ slots, ...layoutProps }) {
         capabilities: layoutProps.capabilities,
         renderMode: layoutProps.renderMode,
     });
-    const { layoutKind = "flex", gap = PHI_FLEX_LAYOUT_DEFAULTS.gap, distribution = PHI_FLEX_LAYOUT_DEFAULTS.distribution ?? "anchor", wrap = PHI_FLEX_LAYOUT_DEFAULTS.wrap, verticalSeparators = false, separatorBeforeFirst = false, separatorSpan = PHI_FLEX_LAYOUT_DEFAULTS.separatorSpan, editSlotAnchor, renderMode, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, backgroundLayer, borderSource, border, borderRadius, effect, shadow, editSlotAction, editRenderInsertControl, editSlotLabels, style, labelEnd, } = layoutProps;
-    const resolvedVertical = false;
+    const resolvedVertical = layoutProps.layoutKind === "verticalflex";
+    const layoutDefaults = resolvePhiLayoutDefaults(resolvedVertical ? "verticalflex" : "flex");
+    const { layoutKind = "flex", gap = layoutDefaults.gap, distribution = layoutDefaults.distribution ?? "anchor", wrap = layoutDefaults.wrap, verticalSeparators = false, separatorBeforeFirst = false, separatorSpan = layoutDefaults.separatorSpan, editSlotAnchor, renderMode, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface, editSlotAction, editRenderInsertControl, editSlotLabels, style, labelEnd, } = layoutProps;
     const resolvedSlotStates = resolvePhiBaseLayoutSlotStates(slots.length, layoutProps.initialSlotStates);
-    const resolvedGap = normalizePhiCssSize(gap) ?? PHI_FLEX_LAYOUT_DEFAULTS.gap;
+    const resolvedGap = normalizePhiCssSize(gap) ?? layoutDefaults.gap;
     const resolvedRenderMode = renderMode ?? "live";
     const isEditMode = resolvedRenderMode === "editor";
-    const { style: resolvedLayoutStyle, hasExplicitLayoutBackground, } = resolvePhiBaseLayoutChrome({
+    const { style: resolvedLayoutStyle, ground, hasExplicitLayoutBackground, } = resolvePhiBaseLayoutChrome({
         labelEnd,
         padding,
         paddingTop,
         paddingRight,
         paddingBottom,
         paddingLeft,
-        background,
-        borderSource,
-        border,
-        borderRadius,
-        effect,
-        shadow,
+        surface,
     });
     const resolvedSeparatorSpan = normalizePhiCssSize(separatorSpan) ?? "75%";
     const resolvedSeparatorCrossSize = typeof resolvedSeparatorSpan === "string" ? `max(${resolvedSeparatorSpan}, 1rem)` : resolvedSeparatorSpan;
@@ -107,12 +104,62 @@ export function PhiFlexLayout({ slots, ...layoutProps }) {
             return null;
         }
         const slotSizing = resolvePhiLayoutSlotChildSizing(child);
-        const shouldFillMainAxis = resolvedVertical ? slotSizing.stretchesBlock : slotSizing.stretchesInline;
-        const shouldFillCrossAxis = resolvedVertical ? slotSizing.stretchesInline : slotSizing.stretchesBlock;
-        const minMainSize = resolvedVertical ? slotSizing.minBlockSize : slotSizing.minInlineSize;
-        const maxMainSize = resolvedVertical ? slotSizing.maxBlockSize : slotSizing.maxInlineSize;
-        const minCrossSize = resolvedVertical ? slotSizing.minInlineSize : slotSizing.minBlockSize;
-        const maxCrossSize = resolvedVertical ? slotSizing.maxInlineSize : slotSizing.maxBlockSize;
+        const collapsedStyle = slotState === "collapsed"
+            ? {
+                width: 0,
+                minWidth: 0,
+                maxWidth: 0,
+                height: 0,
+                minHeight: 0,
+                maxHeight: 0,
+                flexBasis: 0,
+                flexGrow: 0,
+                flexShrink: 0,
+                overflow: "hidden",
+                opacity: 0,
+                pointerEvents: "none",
+            }
+            : {};
+        if (resolvedVertical) {
+            const shouldFillMainAxis = slotSizing.stretchesBlock;
+            const shouldFillCrossAxis = slotSizing.stretchesInline;
+            return (_jsx("div", { className: phiLayoutSlotClassName(isAuthoringRender), "data-phi-layout-has-content": phiLayoutSlotContentMarker(isAuthoringRender, true), style: {
+                    flexGrow: shouldFillMainAxis ? 1 : 0,
+                    flexShrink: shouldFillMainAxis ? 1 : 0,
+                    flexBasis: "auto",
+                    ...collapsedStyle,
+                    width: shouldFillCrossAxis ? "100%" : undefined,
+                    height: shouldFillMainAxis ? "100%" : undefined,
+                    minWidth: 0,
+                    minHeight: 0,
+                    alignSelf: shouldFillCrossAxis ? "stretch" : undefined,
+                    display: "flex",
+                    flexDirection: "column",
+                    /*
+                     * The slot carries the Layout's own cross-axis alignment, because the slot is scaffolding and
+                     * the anchor is about the content. A slot is as wide as what it holds wants to be, and a child
+                     * that caps its width -- a column of copy at a readable measure -- is narrower than that: it
+                     * then stands at the left edge of a centred slot, which reads as "not centred" and is.
+                     *
+                     * Except where the child fills, which has to be stretched: `width: 100%` inside a shrink-to-fit
+                     * box is circular and resolves to zero, and a centred flex item is shrink-to-fit. That is not
+                     * a reason to give up the placement, though -- a filling child that also caps itself leaves
+                     * room over, and the placement margins put it in the middle of that room
+                     * instead. Stretching and placing are two jobs, and `align-items` can only do one of them.
+                     */
+                    alignItems: shouldFillCrossAxis ? "stretch" : resolvedFlowAlignment.alignItems,
+                    ...resolvePhiSlotPlacementMargins({
+                        inline: shouldFillCrossAxis ? phiPlacementFromWord(resolvedFlowAlignment.alignItems) : null,
+                        block: null,
+                    }),
+                }, children: child }, `content-${index}`));
+        }
+        const shouldFillMainAxis = slotSizing.stretchesInline;
+        const shouldFillCrossAxis = slotSizing.stretchesBlock;
+        const minMainSize = slotSizing.minInlineSize;
+        const maxMainSize = slotSizing.maxInlineSize;
+        const minCrossSize = slotSizing.minBlockSize;
+        const maxCrossSize = slotSizing.maxBlockSize;
         const shouldWrap = resolvedWrap != null && resolvedWrap !== "nowrap";
         const usesMinMainBasis = shouldWrap && minMainSize != null;
         const canShrinkWithinMax = shouldWrap && maxMainSize != null;
@@ -121,50 +168,29 @@ export function PhiFlexLayout({ slots, ...layoutProps }) {
             : shouldFillMainAxis
                 ? 0
                 : "auto";
-        const placesInline = resolvedVertical ? shouldFillCrossAxis : shouldFillMainAxis;
         const slotPlacementMargins = resolvePhiSlotPlacementMargins({
-            inline: placesInline
-                ? phiPlacementFromWord(resolvedVertical ? resolvedFlowAlignment.alignItems : resolvedJustifyContent)
-                : null,
+            inline: shouldFillMainAxis ? phiPlacementFromWord(resolvedJustifyContent) : null,
             block: null,
         });
         return (_jsx("div", { className: phiLayoutSlotClassName(isAuthoringRender), "data-phi-layout-has-content": phiLayoutSlotContentMarker(isAuthoringRender, true), style: {
                 flexGrow: shouldFillMainAxis ? 1 : 0,
                 flexShrink: shouldFillMainAxis || usesMinMainBasis || canShrinkWithinMax ? 1 : 0,
                 flexBasis,
-                ...(slotState === "collapsed"
-                    ? {
-                        width: 0,
-                        minWidth: 0,
-                        maxWidth: 0,
-                        height: 0,
-                        minHeight: 0,
-                        maxHeight: 0,
-                        flexBasis: 0,
-                        flexGrow: 0,
-                        flexShrink: 0,
-                        overflow: "hidden",
-                        opacity: 0,
-                        pointerEvents: "none",
-                    }
-                    : {}),
-                width: resolvedVertical ? (shouldFillCrossAxis ? "100%" : undefined) : undefined,
-                height: resolvedVertical
-                    ? shouldFillMainAxis ? "100%" : undefined
-                    : shouldFillCrossAxis ? "100%" : undefined,
-                minWidth: resolvedVertical ? (minCrossSize ?? 0) : (minMainSize ?? 0),
-                minHeight: resolvedVertical ? (minMainSize ?? 0) : (minCrossSize ?? 0),
-                maxWidth: resolvedVertical ? maxCrossSize : maxMainSize,
-                maxHeight: resolvedVertical ? maxMainSize : maxCrossSize,
+                ...collapsedStyle,
+                height: shouldFillCrossAxis ? "100%" : undefined,
+                minWidth: minMainSize ?? 0,
+                minHeight: minCrossSize ?? 0,
+                maxWidth: maxMainSize,
+                maxHeight: maxCrossSize,
                 alignSelf: shouldFillCrossAxis ? "stretch" : undefined,
                 display: "flex",
                 flexDirection: "column",
                 /*
                  * The inline placement again, as the margins a child that fills and caps itself is moved by.
                  * In a row the inline axis is the main one, so a slot that grows and holds a capped child
-                 * places it by the Layout's `justify-content`; in a column it is the cross axis and the slot's
-                 * own alignment. A slot that does not grow is as wide as its child and states `0`, which is
-                 * what stops a Flex Vertical further up from placing this Layout's children.
+                 * places it by the Layout's `justify-content`. A slot that does not grow is as wide as its
+                 * child and states `0`, which is what stops a Flex Vertical further up from placing this
+                 * Layout's children.
                  */
                 ...slotPlacementMargins,
             }, children: child }, `content-${index}`));
@@ -189,7 +215,7 @@ export function PhiFlexLayout({ slots, ...layoutProps }) {
         : renderableSlots.map(({ child, index }) => renderSlotChild(child, index));
     const renderedContentChildren = contentChildren;
     const insertAfterSlotIndex = slots.length;
-    const insertButton = isEditMode && editSlotAction && editRenderInsertControl ? (_jsx("div", { className: phiLayoutSlotClassName(isAuthoringRender), "data-phi-layout-has-content": phiLayoutSlotContentMarker(isAuthoringRender, false), style: {
+    const insertButton = isEditMode && editSlotAction && editRenderInsertControl && insertAfterSlotIndex < PHI_CMS_MAX_LAYOUT_SLOTS ? (_jsx("div", { className: phiLayoutSlotClassName(isAuthoringRender), "data-phi-layout-has-content": phiLayoutSlotContentMarker(isAuthoringRender, false), style: {
             flexGrow: 0,
             flexShrink: 0,
             flexBasis: "auto",
@@ -212,7 +238,7 @@ export function PhiFlexLayout({ slots, ...layoutProps }) {
         minHeight: 0,
         ...style,
     };
-    return (_jsxs("div", { "data-layout-kind": layoutKind, "data-layout-axis": resolvedVertical ? "vertical" : "horizontal", className: "phi-layout", "data-phi-block-render-mode": resolvedRenderMode, "data-phi-layout-debug-layer": phiLayoutDebugLayerMarker(isAuthoringRender), "data-phi-layout-has-explicit-layout-background": hasExplicitLayoutBackground ? "true" : "false", style: {
+    return (_jsxs(PhiLayoutSurfaceBox, { blockId: layoutProps.blockId, surface: surface, ground: ground, "data-layout-kind": layoutKind, "data-layout-axis": resolvedVertical ? "vertical" : "horizontal", className: "phi-layout", "data-phi-block-render-mode": resolvedRenderMode, "data-phi-layout-debug-layer": phiLayoutDebugLayerMarker(isAuthoringRender), "data-phi-layout-has-explicit-layout-background": hasExplicitLayoutBackground ? "true" : "false", style: {
             display: "flex",
             flexDirection: resolvedVertical ? "column" : "row",
             alignItems: resolvedFlowAlignment.alignItems,
@@ -220,5 +246,5 @@ export function PhiFlexLayout({ slots, ...layoutProps }) {
             flexWrap: resolvedWrap,
             gap: resolvedGap,
             ...resolvedStyle,
-        }, children: [backgroundLayer, renderedContentChildren, insertButton] }));
+        }, children: [renderedContentChildren, insertButton] }));
 }