@phis/ui 0.2.1 → 0.3.0

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

@@ -1,29 +1,20 @@
 import type { CSSProperties, ReactNode } from "react";
-import type { PhiCmsBorderWidgetConfig } from "../../../types/cms-config";
-import { type PhiCmsBackgroundWidgetConfig } from "../../widgets/config/background";
-import { type PhiLayoutEditRenderInsertControl } from "../phi-layout-contract";
 import { type PhiBaseLayoutProps } from "../phi-layout-view-model";
 import type { PhiAnchorWidgetPlacement } from "../../controls/phi-anchor-control-contract";
-import type { PhiShadow } from "../../../types/layout-style";
+/**
+ * Two cards on the golden ratio.
+ *
+ * The Layout's Surface is worn by both: each card draws its edge, corner,
+ * depth, pane and mode (`PhiSplitCardHalf`), and the Background runs once across the two and shows only
+ * inside them, so a picture or a gradient goes on behind the right card instead of starting again. The
+ * box between and around them is transparent. The padding is each card's inset, the distance from the
+ * card's edge to what stands in it, as it is for every Layout; the gap stands between the cards.
+ */
 export type PhiSplitCardLayoutProps = Omit<PhiBaseLayoutProps, "slots"> & {
     slots: ReactNode[];
     gap?: CSSProperties["gap"];
-    borderRadius?: CSSProperties["borderRadius"];
-    leftPadding?: CSSProperties["padding"];
-    rightPadding?: CSSProperties["padding"];
-    leftBackground?: PhiCmsBackgroundWidgetConfig;
-    rightBackground?: PhiCmsBackgroundWidgetConfig;
-    leftBorder?: PhiCmsBorderWidgetConfig;
-    rightBorder?: PhiCmsBorderWidgetConfig;
-    leftShadow?: PhiShadow;
-    rightShadow?: PhiShadow;
-    editSlotAction?: (slotIndex: number, options?: {
-        defaultPickSection?: "layout" | "widget";
-        allowWidgetSection?: boolean;
-        slotIndex?: number;
-    }) => void;
-    editRenderInsertControl?: PhiLayoutEditRenderInsertControl;
+    /** The larger card on the left instead of the right. */
+    swapRatio?: boolean;
     editSlotAnchor?: PhiAnchorWidgetPlacement | null;
-    style?: CSSProperties;
 };
-export declare function PhiSplitCardLayout({ slots, gap, borderRadius, leftPadding, rightPadding, leftBackground, rightBackground, leftBorder, rightBorder, leftShadow, rightShadow, editSlotAction, editRenderInsertControl, editSlotAnchor, renderMode, layoutKind, labelEnd, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, backgroundLayer, borderSource, border, effect, shadow, style, }: PhiSplitCardLayoutProps): import("react").JSX.Element;
+export declare function PhiSplitCardLayout({ blockId, slots, gap, swapRatio, editSlotAction, editRenderInsertControl, editSlotAnchor, renderMode, layoutKind, labelEnd, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface, style, }: PhiSplitCardLayoutProps): import("react").JSX.Element;

package/components/layouts/clients/phi-split-card-layout-client.js

@@ -1,51 +1,32 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { resolvePhiBorderWidgetStyle } from "../../../helpers/border-widget-style";
-import { resolvePhiBackgroundWidgetStyle, } from "../../widgets/config/background";
-import { normalizePhiCssSize, PHI_LAYOUT_SURFACE_RADIUS, } from "../phi-layout-contract";
+import { normalizePhiCssSize, resolvePhiPaddingStyle, } from "../phi-layout-contract";
 import { PhiLayoutAnchoredOverlay } from "./phi-layout-anchored-overlay";
 import { resolvePhiBaseLayoutChrome, } from "../phi-layout-view-model";
 import { resolvePhiLayoutDefaults } from "../../../helpers/cms-layout-defaults";
-import { combinePhiBoxShadows, resolvePhiShadow } from "../../../helpers/layout-style";
 import { isPhiLayoutAuthoringRender, phiLayoutDebugLayerMarker, phiLayoutSlotClassName, phiLayoutSlotContentMarker, } from "../../../helpers/layout-authoring-markers";
+import { PhiLayoutSurfaceBox } from "../phi-layout-surface-box";
+import { PhiSplitCardHalf } from "./phi-split-card-half";
+import { resolvePhiSplitCardColumns } from "../split-card-geometry";
 const PHI_SPLIT_CARD_LAYOUT_DEFAULTS = resolvePhiLayoutDefaults("split");
-function renderSplitCardSlot(isAuthoringRender, key, child, slotRole, slotIndex, editSlotAnchor, editSlotAction, editRenderInsertControl, label, slotPadding, slotBackground, slotBorder, slotShadow, slotBorderRadius) {
+function renderSplitCardSlot(isAuthoringRender, key, child, slotRole, slotIndex, editSlotAnchor, editSlotAction, editRenderInsertControl, label, card) {
     const hasContent = child !== null && child !== undefined && child !== false;
     const showInsertButton = typeof editSlotAction === "function" && editRenderInsertControl != null;
-    const resolvedSlotBackgroundStyle = resolvePhiBackgroundWidgetStyle(slotBackground ?? null);
-    const hasExplicitCardChrome = (slotBackground != null && slotBackground.base.kind !== "none") ||
-        slotBorder != null ||
-        slotShadow != null;
-    /*
-     * The corner reaches the card as four longhands and never as the shorthand, because the slot radius is
-     * a variable wherever nobody configured one, and React refuses a shorthand standing beside the
-     * longhands a configured border writes on the same box.
-     *
-     * A slot that draws no card states no corner: there is no box there to round, and rounding the frame
-     * would clip content against nothing.
-     */
-    const resolvedSlotBorderStyle = resolvePhiBorderWidgetStyle(slotBorder ?? null, {
-        borderRadius: hasExplicitCardChrome ? slotBorderRadius : 0,
-    });
-    return (_jsxs("div", { "data-layout-kind": "split", className: phiLayoutSlotClassName(isAuthoringRender), "data-phi-layout-has-content": phiLayoutSlotContentMarker(isAuthoringRender, hasContent), style: {
+    return (_jsxs(PhiSplitCardHalf, { blockId: card.blockId, surface: card.surface, side: slotRole, gap: card.gap, swapped: card.swapped, "data-layout-kind": "split", className: phiLayoutSlotClassName(isAuthoringRender), "data-phi-layout-has-content": phiLayoutSlotContentMarker(isAuthoringRender, hasContent), style: {
             position: "relative",
             height: "100%",
             minWidth: 0,
             minHeight: 0,
             display: "flex",
             alignItems: "stretch",
-            overflow: hasExplicitCardChrome ? "hidden" : undefined,
-            padding: normalizePhiCssSize(slotPadding),
             boxSizing: "border-box",
-            ...resolvedSlotBorderStyle,
-            ...resolvedSlotBackgroundStyle,
-            boxShadow: combinePhiBoxShadows(resolvedSlotBackgroundStyle.boxShadow, resolvePhiShadow(slotShadow)),
-        }, children: [hasContent ? (_jsx(PhiLayoutAnchoredOverlay, { anchor: editSlotAnchor, slotRole: slotRole === "left" ? "left" : "right", positionMode: "flow", fillAvailableInline: true, fillAvailableBlock: true, children: child })) : null, !hasContent && showInsertButton
+            ...card.inset,
+        }, children: [hasContent ? (_jsx(PhiLayoutAnchoredOverlay, { anchor: editSlotAnchor, slotRole: slotRole, positionMode: "flow", fillAvailableInline: true, fillAvailableBlock: true, children: child })) : null, !hasContent && showInsertButton
                 ? editRenderInsertControl?.({
                     presentation: "overlay",
                     slotIndex,
                     label,
                     anchor: editSlotAnchor,
-                    slotRole: slotRole === "left" ? "left" : "right",
+                    slotRole,
                     onInsert: (targetSlotIndex) => editSlotAction(targetSlotIndex, {
                         defaultPickSection: "widget",
                         allowWidgetSection: true,
@@ -54,42 +35,39 @@ function renderSplitCardSlot(isAuthoringRender, key, child, slotRole, slotIndex,
                 })
                 : null] }, key));
 }
-export function PhiSplitCardLayout({ slots, gap, borderRadius, leftPadding, rightPadding, leftBackground, rightBackground, leftBorder, rightBorder, leftShadow, rightShadow, editSlotAction, editRenderInsertControl, editSlotAnchor = "center", renderMode = "live", layoutKind = "split", labelEnd, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, backgroundLayer, borderSource, border, effect, shadow, style, }) {
+export function PhiSplitCardLayout({ blockId, slots, gap, swapRatio = false, editSlotAction, editRenderInsertControl, editSlotAnchor = "center", renderMode = "live", layoutKind = "split", labelEnd, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface, style, }) {
     const isAuthoringRender = isPhiLayoutAuthoringRender({ editSlotAction, renderMode });
     const resolvedRenderMode = renderMode ?? "live";
     const resolvedGap = normalizePhiCssSize(gap) ?? PHI_SPLIT_CARD_LAYOUT_DEFAULTS.gap;
+    const gapLength = typeof resolvedGap === "number" ? `${resolvedGap}px` : String(resolvedGap);
     /*
-     * A card in a Split Card is a surface, so the corner nobody stated is the Site's to answer -- the same
-     * step a Layout box, a Table and a Tree take, carried on the root as `--phi-surface-radius`
-     * (THEME.md, "Control shape"). The Split Card's Layout defaults name no radius at all, so what stood
-     * here before answered with nothing: under a `pill` Theme the two cards sat square between capsule
-     * Buttons. An author who did state a radius keeps it -- the step answers silence, it caps nobody.
+     * The box itself draws nothing: the Surface is the cards', and outside them the Split Card is
+     * transparent. It is the query container the cards measure the shared Background against.
+     *
+     * The padding is each card's, as every Layout's padding is the distance from its own edge to its
+     * slots; the box has none, so its content box is the two cards and the gap, which is what the
+     * shared Background is measured across.
      */
-    const resolvedSlotRadius = normalizePhiCssSize(borderRadius) ?? PHI_LAYOUT_SURFACE_RADIUS;
-    const { style: resolvedLayoutStyle, hasExplicitLayoutBackground, } = resolvePhiBaseLayoutChrome({
-        labelEnd,
-        padding,
-        paddingTop,
-        paddingRight,
-        paddingBottom,
-        paddingLeft,
-        background,
-        borderSource,
-        border,
-        borderRadius,
-        effect,
-        shadow,
-    });
+    const { style: resolvedLayoutStyle } = resolvePhiBaseLayoutChrome({ labelEnd });
+    const { hasExplicitLayoutBackground } = resolvePhiBaseLayoutChrome({ surface });
+    const card = {
+        blockId,
+        surface,
+        gap: gapLength,
+        swapped: swapRatio,
+        inset: resolvePhiPaddingStyle({ padding, paddingTop, paddingRight, paddingBottom, paddingLeft }),
+    };
     const resolvedStyle = {
         position: "relative",
+        containerType: "inline-size",
         ...resolvedLayoutStyle,
         display: "grid",
-        gridTemplateColumns: "minmax(0, 1fr) minmax(0, 1.61803398875fr)",
+        gridTemplateColumns: resolvePhiSplitCardColumns(swapRatio),
         gap: resolvedGap,
         alignItems: "stretch",
         minWidth: 0,
         minHeight: 0,
         ...style,
     };
-    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, renderSplitCardSlot(isAuthoringRender, "slot-1", slots[0] ?? null, "left", 0, editSlotAnchor, editSlotAction, editRenderInsertControl, "Slot 1", leftPadding, leftBackground, leftBorder, leftShadow, resolvedSlotRadius), renderSplitCardSlot(isAuthoringRender, "slot-2", slots[1] ?? null, "right", 1, editSlotAnchor, editSlotAction, editRenderInsertControl, "Slot 2", rightPadding, rightBackground, rightBorder, rightShadow, resolvedSlotRadius)] }));
+    return (_jsxs(PhiLayoutSurfaceBox, { blockId: blockId, surface: undefined, ground: null, "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: [renderSplitCardSlot(isAuthoringRender, "slot-1", slots[0] ?? null, "left", 0, editSlotAnchor, editSlotAction, editRenderInsertControl, "Slot 1", card), renderSplitCardSlot(isAuthoringRender, "slot-2", slots[1] ?? null, "right", 1, editSlotAnchor, editSlotAction, editRenderInsertControl, "Slot 2", card)] }));
 }

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

@@ -1,26 +1,11 @@
-import type { CSSProperties, ReactNode } from "react";
 import { type PhiMotionEasing } from "../../../helpers/motion";
 import { type PhiCmsMountPolicy } from "../../../types/cms-mount-policy";
-import { type PhiBaseLayoutProps } from "../phi-layout-view-model";
-import type { PhiAnchorWidgetPlacement } from "../../controls/phi-anchor-control-contract";
-export type PhiStackLayoutSlotMeta = {
-    key: string;
-    label: string;
-    slotIndex: number;
-    hasContent?: boolean;
-};
-export type PhiStackLayoutProps = Omit<PhiBaseLayoutProps, "slots"> & {
-    slots: ReactNode[];
-    slotKeys: string[];
-    slotMeta?: PhiStackLayoutSlotMeta[];
-    defaultActiveSlotKey?: string;
+import { type PhiSequenceLayoutProps } from "./use-phi-sequence-layout";
+export type PhiStackLayoutProps = PhiSequenceLayoutProps & {
     slotDisplay?: "single" | "stacked";
     mountPolicy?: PhiCmsMountPolicy;
     slotTransition?: "none" | "fade-over";
     slotTransitionDurationMs?: number;
     slotTransitionEasing?: PhiMotionEasing;
-    slotAnchor?: PhiAnchorWidgetPlacement | null;
-    editSlotAnchor?: PhiAnchorWidgetPlacement | null;
-    style?: CSSProperties;
 };
 export declare function PhiStackLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey, slotDisplay, mountPolicy, slotTransition, slotTransitionDurationMs, slotTransitionEasing, slotAnchor, ...layoutProps }: PhiStackLayoutProps): import("react").JSX.Element;

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

@@ -1,26 +1,26 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useLayoutEffect, useRef, useState } from "react";
 import { clampPhiSequenceTransitionMs, resolvePhiMotionDurationMs, } from "../../../helpers/motion";
 import { shouldPhiCmsContentStayMounted, } from "../../../types/cms-mount-policy";
-import { resolvePhiLayoutInset, } from "../phi-layout-contract";
-import { resolvePhiBaseLayoutChrome, } from "../phi-layout-view-model";
+import { resolvePhiLayoutInset } from "../phi-layout-contract";
+import { resolvePhiBaseLayoutChrome } from "../phi-layout-view-model";
 import { isRenderablePhiNode } from "../phi-layout-scaffold-utils";
+import { PhiLayoutSurfaceBox } from "../phi-layout-surface-box";
 import { PhiLayoutAnchoredOverlay } from "./phi-layout-anchored-overlay";
 import { PhiSequenceSlotEditor } from "./phi-sequence-slot-editor";
-import { resolvePhiSequenceEditableSlotCount, usePhiSlotSequence } from "../use-phi-slot-sequence";
+import { usePhiSequenceLayout } from "./use-phi-sequence-layout";
 import { usePhiConfig } from "../../root/phi-config-provider";
 export function PhiStackLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey, slotDisplay = "single", mountPolicy = "remount", slotTransition = "none", slotTransitionDurationMs, slotTransitionEasing, slotAnchor = "center", ...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 authoring = {
-        editSlotAction: layoutProps.editSlotAction,
-        editSlotLabels: layoutProps.editSlotLabels,
-        capabilities: layoutProps.capabilities,
-    };
     const { token } = usePhiConfig();
-    const { blockId, renderMode, style, layoutKind = "stack", padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, backgroundLayer, borderSource, border, borderRadius, effect, shadow, editSlotAction, editRenderInsertControl, editSlotAnchor = "center", } = layoutProps;
-    const isEditMode = renderMode === "editor";
+    const { blockId, style, isEditMode, storedChrome, activeIndex: resolvedActiveIndex, editor, } = usePhiSequenceLayout({
+        slots,
+        slotKeys,
+        slotMeta,
+        defaultActiveSlotKey,
+        defaultLayoutKind: "stack",
+        layoutProps,
+    });
     /*
      * A pile, not a sequence.
      *
@@ -29,32 +29,8 @@ export function PhiStackLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey
      * way to say which layer a dropped Widget belongs to.
      */
     const isStacked = slotDisplay === "stacked" && !isEditMode;
-    const editableSlotCount = resolvePhiSequenceEditableSlotCount(slots, slotKeys);
-    const chrome = {
-        padding,
-        paddingTop,
-        paddingRight,
-        paddingBottom,
-        paddingLeft,
-        background,
-        borderSource,
-        border,
-        borderRadius,
-        effect,
-        shadow,
-    };
     const outgoingSlotRef = useRef(null);
     const fadeAnimationRef = useRef(null);
-    const { activeIndex: resolvedActiveIndex, slotMeta: resolvedSlotMeta, setActiveIndex, } = usePhiSlotSequence({
-        blockId,
-        slots,
-        slotKeys,
-        // While authoring, the sequence reaches one slot past the last filled one -- the empty slot the
-        // next child goes into. A page has no such slot and steps through what it holds.
-        ...(isEditMode ? { slotCount: editableSlotCount } : {}),
-        ...(slotMeta ? { slotLabels: slotMeta } : {}),
-        ...(defaultActiveSlotKey === undefined ? {} : { defaultActiveSlotKey }),
-    });
     /*
      * Which slots have ever been wanted, which is what `lazy-keep` keeps.
      *
@@ -145,9 +121,10 @@ export function PhiStackLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey
         transitionState.sequence,
     ]);
     if (isEditMode) {
-        return (_jsx(PhiSequenceSlotEditor, { slots: slots, slotKeys: slotKeys, slotLabels: resolvedSlotMeta, slotCount: editableSlotCount, activeIndex: resolvedActiveIndex, onActiveIndexChange: setActiveIndex, slotNoun: "stack slot", layoutKind: layoutKind, renderMode: renderMode, authoring: authoring, chrome: chrome, backgroundLayer: backgroundLayer, editSlotAction: editSlotAction, editRenderInsertControl: editRenderInsertControl, editSlotAnchor: editSlotAnchor, style: style }));
+        return _jsx(PhiSequenceSlotEditor, { ...editor, slotNoun: "stack slot" });
     }
-    const resolvedLayoutInset = resolvePhiLayoutInset(chrome);
+    const resolvedLayoutInset = resolvePhiLayoutInset(storedChrome);
+    const resolvedChrome = resolvePhiBaseLayoutChrome(storedChrome);
     /*
      * The layer that keeps the box a box.
      *
@@ -155,7 +132,7 @@ export function PhiStackLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey
      * content height of its own and a Stack that was not given a height would collapse to nothing.
      */
     const baseStackedSlotIndex = slots.findIndex((slot) => isRenderablePhiNode(slot));
-    return (_jsxs("div", { "data-phi-stack-slot-display": isStacked ? "stacked" : "single", "data-phi-stack-slot-transition": slotTransition, 
+    return (_jsx(PhiLayoutSurfaceBox, { blockId: blockId, surface: storedChrome.surface, ground: resolvedChrome.ground, "data-phi-stack-slot-display": isStacked ? "stacked" : "single", "data-phi-stack-slot-transition": slotTransition, 
         /*
          * The Layout's own box, named as one: the fill rules address `.phi-layout`
          * (`.phi-slot-child--block-fill > .phi-layout`, styles/layout.css), and this box carried a
@@ -167,57 +144,57 @@ export function PhiStackLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey
             minWidth: 0,
             minHeight: 0,
             boxSizing: "border-box",
-            ...resolvePhiBaseLayoutChrome(chrome).style,
+            ...resolvedChrome.style,
             ...style,
-        }, children: [backgroundLayer, _jsx("div", { "data-phi-stack-stage": "true", 
+        }, children: _jsx("div", { "data-phi-stack-stage": "true", 
+            /*
+             * The stage is as tall as the Stack, not as tall as the slot standing in it. A slot that is
+             * only as tall as its content has no room to place that content, so an anchor of bottom or
+             * middle drew at the top. Where the Stack itself has no height, a percentage against an auto
+             * parent stays auto and the stage is content height as before.
+             */
+            style: { position: "relative", width: "100%", height: "100%", minWidth: 0, minHeight: 0 }, children: slots.map((slot, index) => {
+                const isActive = index === resolvedActiveIndex;
+                const isOutgoing = index === outgoingSlotIndex;
+                /*
+                 * The outgoing slot counts as inside the window, which is how a fade survives `remount`:
+                 * the window lags by the length of the transition rather than cutting at the moment the
+                 * index changes.
+                 */
+                const shouldMount = isStacked || shouldPhiCmsContentStayMounted({
+                    policy: mountPolicy,
+                    insideWindow: isActive || isOutgoing,
+                    hasEnteredWindow: visitedSlotIndices.has(index),
+                });
+                if (!shouldMount || !isRenderablePhiNode(slot))
+                    return null;
                 /*
-                 * The stage is as tall as the Stack, not as tall as the slot standing in it. A slot that is
-                 * only as tall as its content has no room to place that content, so an anchor of bottom or
-                 * middle drew at the top. Where the Stack itself has no height, a percentage against an auto
-                 * parent stays auto and the stage is content height as before.
+                 * Every layer stays reachable, and the one on top takes the pointer where they overlap. That
+                 * is what lying over something means; a layer that should let the click through says so with
+                 * its own content rather than by the Stack deciding for all of them.
                  */
-                style: { position: "relative", width: "100%", height: "100%", minWidth: 0, minHeight: 0 }, children: slots.map((slot, index) => {
-                    const isActive = index === resolvedActiveIndex;
-                    const isOutgoing = index === outgoingSlotIndex;
-                    /*
-                     * The outgoing slot counts as inside the window, which is how a fade survives `remount`:
-                     * the window lags by the length of the transition rather than cutting at the moment the
-                     * index changes.
-                     */
-                    const shouldMount = isStacked || shouldPhiCmsContentStayMounted({
-                        policy: mountPolicy,
-                        insideWindow: isActive || isOutgoing,
-                        hasEnteredWindow: visitedSlotIndices.has(index),
-                    });
-                    if (!shouldMount || !isRenderablePhiNode(slot))
-                        return null;
-                    /*
-                     * Every layer stays reachable, and the one on top takes the pointer where they overlap. That
-                     * is what lying over something means; a layer that should let the click through says so with
-                     * its own content rather than by the Stack deciding for all of them.
-                     */
-                    const stackedLayerStyle = index === baseStackedSlotIndex
-                        ? { position: "relative", zIndex: index }
-                        : { position: "absolute", insetBlock: 0, insetInline: 0, zIndex: index };
-                    return (_jsx("div", { ref: isOutgoing ? outgoingSlotRef : undefined, hidden: !isStacked && !isActive && !isOutgoing, inert: !isStacked && !isActive, "aria-hidden": (!isStacked && !isActive) || undefined, "data-phi-stack-slot-state": isStacked ? "stacked" : isActive ? "active" : isOutgoing ? "outgoing" : "inactive", style: {
-                            width: "100%",
-                            height: "100%",
-                            minWidth: 0,
-                            minHeight: 0,
-                            ...(isStacked
-                                ? stackedLayerStyle
-                                : isOutgoing
-                                    ? {
-                                        position: "absolute",
-                                        insetBlock: 0,
-                                        insetInline: 0,
-                                        zIndex: 1,
-                                        pointerEvents: "none",
-                                    }
-                                    : {
-                                        position: "relative",
-                                        zIndex: 0,
-                                    }),
-                        }, children: _jsx(PhiLayoutAnchoredOverlay, { anchor: slotAnchor, positionMode: "flow", fillAvailableInline: true, fillAvailableBlock: true, inset: resolvedLayoutInset, children: slot }) }, slotKeys[index] ?? `slot-${index}`));
-                }) })] }));
+                const stackedLayerStyle = index === baseStackedSlotIndex
+                    ? { position: "relative", zIndex: index }
+                    : { position: "absolute", insetBlock: 0, insetInline: 0, zIndex: index };
+                return (_jsx("div", { ref: isOutgoing ? outgoingSlotRef : undefined, hidden: !isStacked && !isActive && !isOutgoing, inert: !isStacked && !isActive, "aria-hidden": (!isStacked && !isActive) || undefined, "data-phi-stack-slot-state": isStacked ? "stacked" : isActive ? "active" : isOutgoing ? "outgoing" : "inactive", style: {
+                        width: "100%",
+                        height: "100%",
+                        minWidth: 0,
+                        minHeight: 0,
+                        ...(isStacked
+                            ? stackedLayerStyle
+                            : isOutgoing
+                                ? {
+                                    position: "absolute",
+                                    insetBlock: 0,
+                                    insetInline: 0,
+                                    zIndex: 1,
+                                    pointerEvents: "none",
+                                }
+                                : {
+                                    position: "relative",
+                                    zIndex: 0,
+                                }),
+                    }, children: _jsx(PhiLayoutAnchoredOverlay, { anchor: slotAnchor, positionMode: "flow", fillAvailableInline: true, fillAvailableBlock: true, inset: resolvedLayoutInset, children: slot }) }, slotKeys[index] ?? `slot-${index}`));
+            }) }) }));
 }

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

@@ -1,18 +1,13 @@
 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, PhiRenderableBlockSize } from "../../../types";
-import type { PhiShadow, PhiLayoutEffectId } from "../../../types/layout-style";
-import type { PhiCmsBorderSource } from "../../../types/cms-border-source";
-export type PhiThreeColumnLayoutProps = {
-    blockId?: string | number | null;
+import type { PhiRenderableBlockResponsiveSize, PhiRenderableBlockSize } from "../../../types";
+export type PhiThreeColumnLayoutProps = Pick<PhiBaseLayoutProps, "blockId" | "gap" | "surface" | "renderMode" | "zIndex" | "layoutKind" | "labelEnd" | "padding" | "paddingTop" | "paddingRight" | "paddingBottom" | "paddingLeft" | "editSlotAction" | "editRenderInsertControl" | "style"> & {
     slots: ReactNode[];
     balancedSides?: boolean;
-    gap?: CSSProperties["gap"];
     wrap?: boolean | CSSProperties["flexWrap"];
     align?: CSSProperties["alignItems"];
     justify?: CSSProperties["justifyContent"];
-    borderSource?: PhiCmsBorderSource;
     leftWidth?: CSSProperties["width"];
     middleWidth?: CSSProperties["width"];
     rightWidth?: CSSProperties["width"];
@@ -20,28 +15,6 @@ export type PhiThreeColumnLayoutProps = {
     minSize?: PhiRenderableBlockResponsiveSize | null;
     maxSize?: PhiRenderableBlockResponsiveSize | null;
     collapsedSizeHint?: PhiRenderableBlockSize | null;
-    renderMode?: PhiRenderableBlockRenderMode;
-    zIndex?: number;
-    shadow?: PhiShadow | null;
-    effect?: PhiLayoutEffectId;
-    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"];
-    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 PhiThreeColumnLayout({ blockId, slots, balancedSides, gap, wrap, align, justify, leftWidth, middleWidth, rightWidth, editSlotAnchor, editSlotAction, editRenderInsertControl, renderMode, ...layoutProps }: PhiThreeColumnLayoutProps): import("react").JSX.Element;

package/components/layouts/clients/phi-three-column-layout-client.js

@@ -4,6 +4,7 @@ import { resolvePhiBaseLayoutChrome } from "../phi-layout-view-model";
 import { resolvePhiLayoutDefaults } from "../../../helpers/cms-layout-defaults";
 import { PHI_CMS_THREE_COLUMN_LAYOUT_SLOTS } from "../../../constants/cms-layout-types";
 import { isPhiLayoutAuthoringRender, phiLayoutDebugLayerMarker, phiLayoutSlotClassName, phiLayoutSlotContentMarker, } from "../../../helpers/layout-authoring-markers";
+import { PhiLayoutSurfaceBox } from "../phi-layout-surface-box";
 const PHI_THREE_COLUMN_LAYOUT_DEFAULTS = resolvePhiLayoutDefaults("threecol");
 function renderColumn(isAuthoringRender, key, child, width, flex, anchor, slotRole, editSlotAction, editRenderInsertControl, slotIndex, label, showInsertButton) {
     const resolvedWidth = normalizePhiCssSize(width);
@@ -76,7 +77,7 @@ function renderColumn(isAuthoringRender, key, child, width, flex, anchor, slotRo
 }
 export function PhiThreeColumnLayout({ blockId, slots, balancedSides = true, gap = PHI_THREE_COLUMN_LAYOUT_DEFAULTS.gap, wrap = PHI_THREE_COLUMN_LAYOUT_DEFAULTS.wrap, align, justify, leftWidth, middleWidth, rightWidth, editSlotAnchor = "center", editSlotAction, editRenderInsertControl, renderMode = "live", ...layoutProps }) {
     const isAuthoringRender = isPhiLayoutAuthoringRender({ editSlotAction, renderMode });
-    const { style, layoutKind = "threecol", padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, backgroundLayer, borderSource, border, borderRadius, effect, shadow, labelEnd, size, minSize, maxSize, collapsedSizeHint, } = layoutProps;
+    const { style, layoutKind = "threecol", padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface, labelEnd, size, minSize, maxSize, collapsedSizeHint, } = layoutProps;
     const resolvedRenderMode = renderMode ?? "live";
     const resolvedLeftWidth = normalizePhiCssSize(leftWidth);
     const resolvedMiddleWidth = normalizePhiCssSize(middleWidth);
@@ -85,21 +86,16 @@ export function PhiThreeColumnLayout({ blockId, slots, balancedSides = true, gap
     const middleFlex = resolvedMiddleWidth ? `0 0 ${resolvedMiddleWidth}` : "1 1 0";
     const rightFlex = resolvedRightWidth ? `0 0 ${resolvedRightWidth}` : balancedSides ? "1 1 0" : "0 1 auto";
     const showInsertButton = 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,
     });
-    return (_jsxs("div", { "data-layout-kind": layoutKind, "data-phi-block-id": blockId ?? undefined, className: "phi-layout", "data-phi-block-render-mode": resolvedRenderMode, "data-phi-debug-scaffold": undefined, "data-phi-layout-debug-layer": phiLayoutDebugLayerMarker(isAuthoringRender), "data-phi-layout-has-explicit-layout-background": hasExplicitLayoutBackground ? "true" : "false", style: {
+    return (_jsxs(PhiLayoutSurfaceBox, { blockId: blockId, surface: surface, ground: ground, "data-layout-kind": layoutKind, "data-phi-block-id": blockId ?? undefined, className: "phi-layout", "data-phi-block-render-mode": resolvedRenderMode, "data-phi-debug-scaffold": undefined, "data-phi-layout-debug-layer": phiLayoutDebugLayerMarker(isAuthoringRender), "data-phi-layout-has-explicit-layout-background": hasExplicitLayoutBackground ? "true" : "false", style: {
             position: "relative",
             minWidth: 0,
             minHeight: 0,
@@ -121,5 +117,5 @@ export function PhiThreeColumnLayout({ blockId, slots, balancedSides = true, gap
             justifyContent: justify,
             gap: normalizePhiCssSize(gap) ?? resolvePhiLayoutDefaults("threecol").gap,
             ...style,
-        }, children: [backgroundLayer, renderColumn(isAuthoringRender, "slot-1", slots[0] ?? null, leftWidth, leftFlex, editSlotAnchor, "left", editSlotAction, editRenderInsertControl, 0, PHI_CMS_THREE_COLUMN_LAYOUT_SLOTS[0]?.label, showInsertButton), renderColumn(isAuthoringRender, "slot-2", slots[1] ?? null, middleWidth, middleFlex, editSlotAnchor, "middle", editSlotAction, editRenderInsertControl, 1, PHI_CMS_THREE_COLUMN_LAYOUT_SLOTS[1]?.label, showInsertButton), renderColumn(isAuthoringRender, "slot-3", slots[2] ?? null, rightWidth, rightFlex, editSlotAnchor, "right", editSlotAction, editRenderInsertControl, 2, PHI_CMS_THREE_COLUMN_LAYOUT_SLOTS[2]?.label, showInsertButton)] }));
+        }, children: [renderColumn(isAuthoringRender, "slot-1", slots[0] ?? null, leftWidth, leftFlex, editSlotAnchor, "left", editSlotAction, editRenderInsertControl, 0, PHI_CMS_THREE_COLUMN_LAYOUT_SLOTS[0]?.label, showInsertButton), renderColumn(isAuthoringRender, "slot-2", slots[1] ?? null, middleWidth, middleFlex, editSlotAnchor, "middle", editSlotAction, editRenderInsertControl, 1, PHI_CMS_THREE_COLUMN_LAYOUT_SLOTS[1]?.label, showInsertButton), renderColumn(isAuthoringRender, "slot-3", slots[2] ?? null, rightWidth, rightFlex, editSlotAnchor, "right", editSlotAction, editRenderInsertControl, 2, PHI_CMS_THREE_COLUMN_LAYOUT_SLOTS[2]?.label, showInsertButton)] }));
 }

package/components/layouts/clients/use-phi-sequence-layout.d.ts

@@ -0,0 +1,44 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { PhiAnchorWidgetPlacement } from "../../controls/phi-anchor-control-contract";
+import type { PhiSequenceSlotEditorProps } from "./phi-sequence-slot-editor";
+import type { PhiLayoutKind } from "../phi-layout-contract";
+import type { PhiBaseLayoutProps } from "../phi-layout-view-model";
+export type PhiSequenceLayoutSlotMeta = {
+    key: string;
+    label: string;
+    slotIndex: number;
+    hasContent?: boolean;
+};
+/** What a Stack and a Carousel are both handed; each adds the props of its own act. */
+export type PhiSequenceLayoutProps = Omit<PhiBaseLayoutProps, "slots"> & {
+    slots: ReactNode[];
+    slotKeys: string[];
+    slotMeta?: PhiSequenceLayoutSlotMeta[];
+    defaultActiveSlotKey?: string;
+    slotAnchor?: PhiAnchorWidgetPlacement | null;
+    editSlotAnchor?: PhiAnchorWidgetPlacement | null;
+    style?: CSSProperties;
+};
+/**
+ * The part of a Stack and a Carousel that comes before they differ.
+ *
+ * Both own an index through `usePhiSlotSequence`, both answer Surface Signals on their root, and both
+ * are authored one slot at a time by `PhiSequenceSlotEditor` (see there). What is left to each is what an
+ * index means on the page: one slot in a box, or a window on a track.
+ *
+ * `editor` is everything the slot editor needs but the noun the counter speaks of.
+ */
+export declare function usePhiSequenceLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey, defaultLayoutKind, layoutProps, }: Pick<PhiSequenceLayoutProps, "slots" | "slotKeys" | "slotMeta" | "defaultActiveSlotKey"> & {
+    defaultLayoutKind: PhiLayoutKind;
+    layoutProps: Omit<PhiSequenceLayoutProps, "slots" | "slotKeys" | "slotMeta" | "defaultActiveSlotKey" | "slotAnchor">;
+}): {
+    blockId: string | number | null | undefined;
+    layoutKind: PhiLayoutKind;
+    style: CSSProperties | undefined;
+    isEditMode: boolean;
+    storedChrome: Pick<PhiBaseLayoutProps, "padding" | "paddingTop" | "paddingRight" | "paddingBottom" | "paddingLeft" | "surface">;
+    activeIndex: number;
+    slotMeta: import("../stack-signals").PhiStackSignalSlotMeta[];
+    setActiveIndex: (index: number) => void;
+    editor: Omit<PhiSequenceSlotEditorProps, "slotNoun">;
+};

package/components/layouts/clients/use-phi-sequence-layout.js

@@ -0,0 +1,69 @@
+"use client";
+import { usePhiLayoutSignalSurface } from "../phi-layout-signal-surface";
+import { resolvePhiSequenceEditableSlotCount, usePhiSlotSequence } from "../use-phi-slot-sequence";
+/**
+ * The part of a Stack and a Carousel that comes before they differ.
+ *
+ * Both own an index through `usePhiSlotSequence`, both answer Surface Signals on their root, and both
+ * are authored one slot at a time by `PhiSequenceSlotEditor` (see there). What is left to each is what an
+ * index means on the page: one slot in a box, or a window on a track.
+ *
+ * `editor` is everything the slot editor needs but the noun the counter speaks of.
+ */
+export function usePhiSequenceLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey, defaultLayoutKind, 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 authoring = {
+        editSlotAction: layoutProps.editSlotAction,
+        editSlotLabels: layoutProps.editSlotLabels,
+        capabilities: layoutProps.capabilities,
+    };
+    const { blockId, renderMode, style, layoutKind = defaultLayoutKind, padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface: storedSurface, editSlotAction, editRenderInsertControl, editSlotAnchor = "center", } = layoutProps;
+    const surface = usePhiLayoutSignalSurface(blockId, storedSurface);
+    const isEditMode = renderMode === "editor";
+    const editableSlotCount = resolvePhiSequenceEditableSlotCount(slots, slotKeys);
+    const { activeIndex, slotMeta: resolvedSlotMeta, setActiveIndex, } = usePhiSlotSequence({
+        blockId,
+        slots,
+        slotKeys,
+        // While authoring, the sequence reaches one slot past the last filled one -- the empty slot the
+        // next child goes into. A page has no such slot and steps through what it holds.
+        ...(isEditMode ? { slotCount: editableSlotCount } : {}),
+        ...(slotMeta ? { slotLabels: slotMeta } : {}),
+        ...(defaultActiveSlotKey === undefined ? {} : { defaultActiveSlotKey }),
+    });
+    const paddings = { padding, paddingTop, paddingRight, paddingBottom, paddingLeft };
+    // The Builder draws with the signalled Surface; the page hands `PhiLayoutSurfaceBox` the stored one
+    // and lets it swap in what Signals left.
+    const chrome = { ...paddings, surface };
+    // Named rather than inferred: the inferred type spells csstype's padding types, which the package's
+    // declarations cannot name (TS2883).
+    const storedChrome = { ...paddings, surface: storedSurface };
+    const editor = {
+        slots,
+        slotKeys,
+        slotLabels: resolvedSlotMeta,
+        slotCount: editableSlotCount,
+        activeIndex,
+        onActiveIndexChange: setActiveIndex,
+        layoutKind,
+        renderMode,
+        authoring,
+        chrome,
+        editSlotAction,
+        editRenderInsertControl,
+        editSlotAnchor,
+        style,
+    };
+    return {
+        blockId,
+        layoutKind,
+        style,
+        isEditMode,
+        storedChrome,
+        activeIndex,
+        slotMeta: resolvedSlotMeta,
+        setActiveIndex,
+        editor,
+    };
+}