@phis/ui 0.2.1 → 0.4.0

package/components/layouts/phi-grid-contract.js

@@ -1,43 +1,46 @@
-import { resolvePhiResponsiveValue, } from "../../types/responsive";
 import { PHI_CONTAINER_BREAKPOINT_COL3, PHI_CONTAINER_BREAKPOINT_CONTENT, } from "../../theme/phi-container-breakpoints";
+// The counts live in the contract layer (`constants/grid-columns.ts`), where the config parser reads
+// them without pulling a Layout module into `@phis/ui/types`; the Layout keeps offering them here.
+import { isPhiGridColumnCount, PHI_GRID_COLUMN_COUNTS } from "../../constants/grid-columns";
+export { isPhiGridColumnCount, PHI_GRID_COLUMN_COUNTS };
 /**
- * What a slot spans when its Grid was never told.
+ * How many slots a row holds when the Grid was never told.
  *
- * One constant for all three profiles stood here before -- six tracks, four per row -- and a Grid whose
- * slots carry no authored span therefore never reflowed: four abreast at 320px and at 1600px alike,
- * only narrower, because the 24 tracks are `minmax(0, 1fr)` and shrink. The wrapping that did happen was
- * the cursor running past column 24, not an answer to the room.
- *
- * So the default is a profile value like every other placement: the whole row where there is no room to
- * share, two abreast in the middle, four where the Grid is at least as wide as the content column. An
- * author who names a span still names it and nothing here applies.
- *
- * At `compact` the row is full, so an offset has nothing left to push into and is clamped away. That is
- * the answer rather than an accident: a slot cannot be indented in a room that holds one slot.
+ * The whole row where there is no room to share, two abreast in the middle, four where the Grid is at
+ * least as wide as the content column. One constant for all three widths stood here before -- four per
+ * row -- and a Grid nobody told never reflowed: four abreast at 320px and at 1600px alike, only
+ * narrower.
  */
-export const PHI_GRID_LAYOUT_DEFAULT_SPAN = {
-    compact: 24,
-    medium: 12,
-    wide: 6,
+export const PHI_GRID_LAYOUT_DEFAULT_COLUMNS = {
+    compact: 1,
+    medium: 2,
+    wide: 4,
 };
-export function resolvePhiGridSlotPlacement(slotPlacements, slotIndex, profile, fallbackSpan) {
+/** The Grid's columns at every width: what was stated where it is a column count, the default elsewhere. */
+export function resolvePhiGridColumns(columns) {
+    const read = (profile) => {
+        const stated = columns?.[profile];
+        return isPhiGridColumnCount(stated) ? stated : PHI_GRID_LAYOUT_DEFAULT_COLUMNS[profile];
+    };
+    return { compact: read("compact"), medium: read("medium"), wide: read("wide") };
+}
+/**
+ * What a slot spans and skips at one width, in the 24 tracks.
+ *
+ * Clamped to the row: a slot wider than the row is the row, and an indent that leaves no room is
+ * dropped -- a Grid whose columns were reduced keeps its slots rather than losing them.
+ */
+export function resolvePhiGridSlotPlacement(slotPlacements, slotIndex, profile, columns) {
     const placement = slotPlacements?.find((candidate) => candidate.slotIndex === slotIndex);
-    const span = resolvePhiResponsiveValue(placement?.span, {
-        compact: fallbackSpan,
-        medium: fallbackSpan,
-        wide: fallbackSpan,
-    })[profile];
-    const offset = resolvePhiResponsiveValue(placement?.offset, {
-        compact: 0,
-        medium: 0,
-        wide: 0,
-    })[profile];
-    return { span, offset };
+    const span = Math.max(1, Math.min(columns, placement?.span?.[profile] ?? 1));
+    const offset = Math.max(0, Math.min(columns - span, placement?.offset?.[profile] ?? 0));
+    const tracks = 24 / columns;
+    return { span: span * tracks, offset: offset * tracks };
 }
 /**
  * Where each slot stands on the 24 tracks, in flow.
  *
- * `offset` counts unused columns before a slot, the way a Grid column's offset does elsewhere, so a
+ * `offset` counts unused tracks before a slot, the way a Grid column's offset does elsewhere, so a
  * slot with none starts where the previous one ended and a row holds as many slots as fit. Written as
  * an absolute line (`offset + 1`) instead, every slot without an offset started on column 1 -- and a
  * definite start on column 1 for every item is a new row for every item, so three cards spanning six
@@ -45,20 +48,18 @@ export function resolvePhiGridSlotPlacement(slotPlacements, slotIndex, profile,
  * the ones before it; the grid then places rows for itself, and it agrees with this cursor: an item whose
  * start line is left of the previous item's goes to the next row, exactly where the cursor wrapped.
  */
-export function resolvePhiGridSlotColumns(slotPlacements, slotIndices, profile, fallbackSpan, columns = 24) {
+export function resolvePhiGridSlotColumns(slotPlacements, slotIndices, profile, columns) {
     const resolved = new Map();
     let cursor = 1;
     for (const slotIndex of slotIndices) {
-        const placement = resolvePhiGridSlotPlacement(slotPlacements, slotIndex, profile, fallbackSpan);
-        const span = Math.max(1, Math.min(columns, placement.span));
-        const offset = Math.max(0, Math.min(columns - span, placement.offset));
+        const { span, offset } = resolvePhiGridSlotPlacement(slotPlacements, slotIndex, profile, columns);
         let start = cursor + offset;
-        if (start + span - 1 > columns) {
+        if (start + span - 1 > 24) {
             start = 1 + offset;
         }
         resolved.set(slotIndex, { start, span });
         cursor = start + span;
-        if (cursor > columns) {
+        if (cursor > 24) {
             cursor = 1;
         }
     }
@@ -88,8 +89,8 @@ export const PHI_GRID_RESPONSIVE_MIN_WIDTH = {
  * one. All three answers are known without measuring anything, so all three go into the markup and a
  * container query picks one (`styles/layout.css`), the way the Form grid does.
  */
-export function resolvePhiGridSlotProfileColumns(slotPlacements, slotIndices) {
-    const [compact, medium, wide] = PHI_GRID_LAYOUT_PROFILES.map((profile) => resolvePhiGridSlotColumns(slotPlacements, slotIndices, profile, PHI_GRID_LAYOUT_DEFAULT_SPAN[profile]));
+export function resolvePhiGridSlotProfileColumns(slotPlacements, slotIndices, columns = PHI_GRID_LAYOUT_DEFAULT_COLUMNS) {
+    const [compact, medium, wide] = PHI_GRID_LAYOUT_PROFILES.map((profile) => resolvePhiGridSlotColumns(slotPlacements, slotIndices, profile, columns[profile]));
     const resolved = new Map();
     for (const slotIndex of slotIndices) {
         const byProfile = {

package/components/layouts/phi-layout-contract.d.ts

@@ -1,8 +1,7 @@
 import type { CSSProperties, ReactNode } from "react";
 import { type PhiAnchorWidgetPlacement } from "../controls/phi-anchor-control-contract";
 import type { PhiRenderableBlockRenderMode, PhiRenderableBlockAnchor, PhiRenderableBlockResponsiveSize, PhiRenderableBlockSize } from "../../types";
-import type { PhiShadow, PhiLayoutEffectId } from "../../types/layout-style";
-import { type PhiCmsBorderSource } from "../../types/cms-border-source";
+import type { PhiSurface } from "../../types/surface";
 import { type PhiRenderableBlockGeometryInput } from "../../types/renderable-block-geometry";
 export type PhiLayoutProps = {
     size?: PhiRenderableBlockResponsiveSize;
@@ -14,8 +13,6 @@ export type PhiLayoutProps = {
     enabled?: boolean;
     zIndex?: number;
     opacity?: number;
-    effect?: PhiLayoutEffectId;
-    shadow?: PhiShadow | null;
     flags?: number;
     initialSlotStates?: PhiBaseLayoutSlotStates;
     editRenderInsertControl?: PhiLayoutEditRenderInsertControl;
@@ -25,11 +22,8 @@ export type PhiLayoutProps = {
     paddingRight?: CSSProperties["paddingRight"];
     paddingBottom?: CSSProperties["paddingBottom"];
     paddingLeft?: CSSProperties["paddingLeft"];
-    background?: CSSProperties["background"];
-    backgroundLayer?: ReactNode;
-    borderSource?: PhiCmsBorderSource;
-    border?: CSSProperties["border"];
-    borderRadius?: CSSProperties["borderRadius"];
+    /** What the Layout's box looks like (`types/surface.ts`); absent, it paints nothing. */
+    surface?: PhiSurface | null;
 };
 export type PhiLayoutEditInsertControl = {
     key?: string;
@@ -75,13 +69,14 @@ export declare function normalizePhiCssSize(value: number | string | undefined):
  */
 export declare function resolvePhiLayoutBoxStyle({ size, minSize, maxSize, collapsedSizeHint, visibility, }: PhiRenderableBlockGeometryInput): CSSProperties;
 /**
- * The Site's answer for a Layout that states no corner of its own; see `resolvePhiLayoutStyle`.
+ * The Site's answer for a Layout that states no corner of its own: the surface step of the Control shape,
+ * carried on the root as `--phi-surface-radius` (THEME.md, "Control shape"). An author who stated a corner
+ * keeps it -- the step answers silence, it caps nobody.
  *
- * Exported because a Layout's box is not the only surface a Layout draws: the Split Card draws two, one
- * per slot, and they answer the same question with the same value.
+ * The fallback is `0` rather than a token: a Layout rendered outside the Provider does not start rounding
+ * on its own.
  */
 export declare const PHI_LAYOUT_SURFACE_RADIUS = "var(--phi-surface-radius, 0)";
-export declare function resolvePhiLayoutStyle({ padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, borderSource, border, borderRadius, }: Pick<PhiLayoutProps, "padding" | "paddingTop" | "paddingRight" | "paddingBottom" | "paddingLeft" | "background" | "borderSource" | "border" | "borderRadius">): CSSProperties;
 /**
  * The four sides a `padding` shorthand names, in the order CSS reads them.
  *
@@ -148,7 +143,7 @@ export type PhiPlacementRole = "mirrorInline" | "pinInlineStart" | "pinInlineEnd
  */
 export declare function resolvePhiPlacement(anchor: PhiAnchorWidgetPlacement | PhiRenderableBlockAnchor | null | undefined, role?: PhiPlacementRole): PhiPlacement;
 /** The flex spelling, and `undefined` where the anchor said nothing, so a caller's own value stands. */
-export declare function phiFlexPlacementWord(placement: PhiAxisPlacement | null): "center" | "flex-end" | "flex-start" | undefined;
+export declare function phiFlexPlacementWord(placement: PhiAxisPlacement | null): "center" | "flex-start" | "flex-end" | undefined;
 /** The grid spelling, and `undefined` where the anchor said nothing. */
 export declare function phiGridPlacementWord(placement: PhiAxisPlacement | null): PhiAxisPlacement | undefined;
 /**

package/components/layouts/phi-layout-contract.js

@@ -1,7 +1,5 @@
 import { resolvePhiAnchorWidgetPlacement, } from "../controls/phi-anchor-control-contract";
-import { resolvePhiCmsBorderSource } from "../../types/cms-border-source";
 import { resolvePhiRenderableBlockGeometry, } from "../../types/renderable-block-geometry";
-import { PHI_THEME_BORDER_LINE } from "../../helpers/border-widget-style";
 export function normalizePhiCssSize(value) {
     if (typeof value === "number") {
         return `${value}px`;
@@ -32,64 +30,14 @@ export function resolvePhiLayoutBoxStyle({ size, minSize, maxSize, collapsedSize
     };
 }
 /**
- * The Site's answer for a Layout that states no corner of its own; see `resolvePhiLayoutStyle`.
+ * The Site's answer for a Layout that states no corner of its own: the surface step of the Control shape,
+ * carried on the root as `--phi-surface-radius` (THEME.md, "Control shape"). An author who stated a corner
+ * keeps it -- the step answers silence, it caps nobody.
  *
- * Exported because a Layout's box is not the only surface a Layout draws: the Split Card draws two, one
- * per slot, and they answer the same question with the same value.
+ * The fallback is `0` rather than a token: a Layout rendered outside the Provider does not start rounding
+ * on its own.
  */
 export const PHI_LAYOUT_SURFACE_RADIUS = "var(--phi-surface-radius, 0)";
-export function resolvePhiLayoutStyle({ padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, borderSource, border, borderRadius, }) {
-    /*
-     * Where the outline comes from, asked before anything about what it looks like.
-     *
-     * `theme` is the Site's own line -- the border colour and the line width it already states -- so a
-     * Layout can take the house style without anybody typing a colour into it, and it moves when the
-     * Theme moves. `custom` is the configured line, and the one source that reads a configured corner.
-     * `none` draws nothing, and is what a Layout that was never asked says now that "no line" and
-     * "nobody said" are two different answers.
-     */
-    const resolvedBorderSource = resolvePhiCmsBorderSource(borderSource, border);
-    const resolvedBorderRadius = resolvedBorderSource === "custom"
-        ? normalizePhiCssSize(borderRadius)
-        : null;
-    return {
-        ...(background == null ? {} : { background }),
-        ...(resolvedBorderSource === "theme"
-            ? { border: PHI_THEME_BORDER_LINE }
-            : resolvedBorderSource === "custom" && border != null
-                ? { border }
-                : {}),
-        /*
-         * A Layout is a surface, so an author who said nothing about its corner gets the Site's answer to
-         * that question -- and so does one who said something but is no longer asking for it: a corner is
-         * the author's only under `custom`, which is the one state where the fields that set it are even
-         * shown. Switching to `theme` or `none` therefore shows the shape at once, square or capsule,
-         * instead of keeping the radii of a border that is no longer being drawn.
-         *
-         * The rest of that question -- the same step a Table and a Tree take, carried on the root as
-         * `--phi-surface-radius` (THEME.md, "Control shape"). An author who did say something keeps it: the
-         * step answers silence, it does not cap anybody.
-         *
-         * The fallback is `0` rather than a token, because that is what this returned before there was a
-         * step to take, and a Layout rendered outside the Provider should not start rounding on its own.
-         *
-         * Four corners rather than the shorthand, and only in this branch. A Widget states a single corner
-         * as a longhand (`borderTopLeftRadius`), and React refuses to have a shorthand standing beside a
-         * longhand it may have to remove on the next render -- which is what a shorthand written on every
-         * Layout, configured or not, created. Where the author DID state a radius the shorthand stays: it
-         * is their one value, and it was already the only thing on the box.
-         */
-        ...(resolvedBorderRadius == null
-            ? {
-                borderTopLeftRadius: PHI_LAYOUT_SURFACE_RADIUS,
-                borderTopRightRadius: PHI_LAYOUT_SURFACE_RADIUS,
-                borderBottomRightRadius: PHI_LAYOUT_SURFACE_RADIUS,
-                borderBottomLeftRadius: PHI_LAYOUT_SURFACE_RADIUS,
-            }
-            : { borderRadius: resolvedBorderRadius }),
-        ...resolvePhiPaddingStyle({ padding, paddingTop, paddingRight, paddingBottom, paddingLeft }),
-    };
-}
 /**
  * The four sides a `padding` shorthand names, in the order CSS reads them.
  *

package/components/layouts/phi-layout-signal-surface.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+import type { PhiCmsInstanceId } from "../../types/cms-instance-id";
+import type { PhiSurface } from "../../types/surface";
+/**
+ * A Layout's Surface as Signals have left it.
+ *
+ * A Layout draws its Surface itself, from its config, so the Signals that change a Surface
+ * (`background/change`, `border/change`, `shadow/change`) arrive somewhere else: at the Layout's slot
+ * frame, which runs the block runtime and keeps what they set. The frame hands the result down through
+ * this context, and only once a Signal has changed something -- until then the Layout's own config is
+ * the answer, which in the Builder is the draft being edited.
+ *
+ * The value names the block it belongs to. A Layout nested inside reads the same context when its own
+ * frame provides none, and must not take its parent's Surface for its own.
+ */
+type PhiLayoutSignalSurface = {
+    blockId: PhiCmsInstanceId;
+    surface: PhiSurface | null;
+};
+export declare function PhiLayoutSignalSurfaceProvider({ value, children, }: {
+    value: PhiLayoutSignalSurface | null;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The Surface a Layout draws: the one Signals left for this block, or the one it was given. */
+export declare function usePhiLayoutSignalSurface(blockId: PhiCmsInstanceId | string | number | null | undefined, surface: PhiSurface | null | undefined): PhiSurface | null | undefined;
+export {};

package/components/layouts/phi-layout-signal-surface.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const PhiLayoutSignalSurfaceContext = createContext(null);
+export function PhiLayoutSignalSurfaceProvider({ value, children, }) {
+    return (_jsx(PhiLayoutSignalSurfaceContext.Provider, { value: value, children: children }));
+}
+/** The Surface a Layout draws: the one Signals left for this block, or the one it was given. */
+export function usePhiLayoutSignalSurface(
+// A Layout's props carry its id as the string or number its plugin was handed.
+blockId, surface) {
+    const signalled = useContext(PhiLayoutSignalSurfaceContext);
+    return signalled != null && blockId != null && String(signalled.blockId) === String(blockId)
+        ? signalled.surface : surface;
+}

package/components/layouts/phi-layout-surface-box.d.ts

@@ -0,0 +1,32 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
+import type { PhiCmsInstanceId } from "../../types/cms-instance-id";
+import type { PhiSurface } from "../../types/surface";
+import { type PhiSurfaceGround } from "../../helpers/surface-style";
+export type PhiLayoutSurfaceBoxProps = Omit<HTMLAttributes<HTMLDivElement>, "style" | "children"> & {
+    [attribute: `data-${string}`]: string | undefined;
+    blockId: PhiCmsInstanceId | string | number | null | undefined;
+    /** The Surface the Layout was given, already drawn into `style` and `ground`. */
+    surface: PhiSurface | null | undefined;
+    ground: PhiSurfaceGround | null;
+    style: CSSProperties;
+    children?: ReactNode;
+};
+/**
+ * A Layout's box style with the Surface it was given swapped for the one Signals left: the given
+ * Surface's entries come out, the Layout's own stay, and the signalled Surface goes on top.
+ */
+export declare function resolvePhiLayoutSignalledSurfaceStyle(style: CSSProperties, given: PhiSurface | null | undefined, signalled: PhiSurface | null | undefined): {
+    style: CSSProperties;
+    ground: PhiSurfaceGround | null;
+};
+/**
+ * The root box of a Layout that renders on the server.
+ *
+ * Everything is decided where the Layout renders: the style it receives already carries the Surface, and
+ * the ground layer is the one the Layout resolved. As long as no Signal has changed the Surface, this box
+ * draws exactly that. Once one has (see `usePhiLayoutSignalSurface`), it takes the given Surface's part
+ * out of the style and puts the signalled one in its place -- the Layout's own topology stays as the
+ * server drew it. It is also where the Surface's `tone` lands: the class on the box and the tone scope
+ * around its content.
+ */
+export declare function PhiLayoutSurfaceBox({ blockId, surface, ground, style, children, ...attributes }: PhiLayoutSurfaceBoxProps): import("react").JSX.Element;

package/components/layouts/phi-layout-surface-box.js

@@ -0,0 +1,41 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { resolvePhiSurfaceStyle } from "../../helpers/surface-style";
+import { PhiSurfaceGroundLayer } from "../surface/phi-surface-ground";
+import { PhiSurfaceTone } from "../surface/phi-surface-tone";
+import { resolvePhiSurfaceToneClassName } from "../../types/surface";
+import { PHI_LAYOUT_SURFACE_RADIUS } from "./phi-layout-contract";
+import { usePhiLayoutSignalSurface } from "./phi-layout-signal-surface";
+/*
+ * Kept where a Signal replaces the Surface: the Layout states them for its topology as well, and a box
+ * that lost its own `position` would let its overlays escape it.
+ */
+const PHI_LAYOUT_SURFACE_BOX_KEPT_KEYS = new Set(["position", "isolation"]);
+/**
+ * A Layout's box style with the Surface it was given swapped for the one Signals left: the given
+ * Surface's entries come out, the Layout's own stay, and the signalled Surface goes on top.
+ */
+export function resolvePhiLayoutSignalledSurfaceStyle(style, given, signalled) {
+    const options = { cornerFallback: PHI_LAYOUT_SURFACE_RADIUS };
+    const givenStyle = resolvePhiSurfaceStyle(given, options).style;
+    const next = resolvePhiSurfaceStyle(signalled, options);
+    const rest = Object.fromEntries(Object.entries(style).filter(([key, value]) => PHI_LAYOUT_SURFACE_BOX_KEPT_KEYS.has(key)
+        || givenStyle[key] !== value));
+    return { style: { ...rest, ...next.style }, ground: next.ground };
+}
+/**
+ * The root box of a Layout that renders on the server.
+ *
+ * Everything is decided where the Layout renders: the style it receives already carries the Surface, and
+ * the ground layer is the one the Layout resolved. As long as no Signal has changed the Surface, this box
+ * draws exactly that. Once one has (see `usePhiLayoutSignalSurface`), it takes the given Surface's part
+ * out of the style and puts the signalled one in its place -- the Layout's own topology stays as the
+ * server drew it. It is also where the Surface's `tone` lands: the class on the box and the tone scope
+ * around its content.
+ */
+export function PhiLayoutSurfaceBox({ blockId, surface, ground, style, children, ...attributes }) {
+    const signalled = usePhiLayoutSignalSurface(blockId, surface);
+    const next = signalled === surface ? { style, ground } : resolvePhiLayoutSignalledSurfaceStyle(style, surface, signalled);
+    const toneClassName = resolvePhiSurfaceToneClassName(signalled?.tone);
+    return (_jsxs("div", { ...attributes, className: [attributes.className, toneClassName].filter(Boolean).join(" ") || undefined, style: next.style, children: [_jsx(PhiSurfaceGroundLayer, { ground: next.ground }), toneClassName ? _jsx(PhiSurfaceTone, { tone: signalled?.tone, children: children }) : children] }));
+}

package/components/layouts/phi-layout-view-model.d.ts

@@ -1,6 +1,7 @@
 import type { CSSProperties, ReactNode } from "react";
 import { type PhiBaseLayoutSlotStates, type PhiBaseLayoutSlotState, type PhiLayoutKind, type PhiLayoutProps } from "./phi-layout-contract";
 import type { PhiRenderableBlockCapabilities, PhiRenderableBlockRuntime, PhiRenderableBlockVisibility } from "../../types";
+import { type PhiSurfaceGround } from "../../helpers/surface-style";
 export type PhiBaseLayoutProps = PhiLayoutProps & {
     blockId?: string | number | null;
     visibility?: PhiRenderableBlockVisibility;
@@ -22,11 +23,14 @@ export type PhiBaseLayoutProps = PhiLayoutProps & {
     /** Shared Layout field: the grid line the label column inside this Layout ends at. */
     labelEnd?: number;
     editFrameBackground?: CSSProperties["background"];
+    /** Drawn under the slots and over the Surface: an authoring guide, never part of the Layout's look. */
+    underlay?: ReactNode;
     style?: CSSProperties;
 };
-export declare function resolvePhiBaseLayoutSlotState(initialSlotStates: PhiBaseLayoutSlotStates | undefined, slotIndex: number): PhiBaseLayoutSlotState;
 export declare function resolvePhiBaseLayoutSlotStates(slotCount: number, initialSlotStates?: PhiBaseLayoutSlotStates): PhiBaseLayoutSlotState[];
-export declare function resolvePhiBaseLayoutChrome({ padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, borderSource, border, borderRadius, effect, shadow, labelEnd, }: Pick<PhiBaseLayoutProps, "labelEnd" | "padding" | "paddingTop" | "paddingRight" | "paddingBottom" | "paddingLeft" | "background" | "borderSource" | "border" | "borderRadius" | "effect" | "shadow">): {
+export declare function resolvePhiBaseLayoutChrome({ padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface, labelEnd, }: Pick<PhiBaseLayoutProps, "labelEnd" | "padding" | "paddingTop" | "paddingRight" | "paddingBottom" | "paddingLeft" | "surface">): {
     style: CSSProperties;
+    /** The layer the paint lives on when the box cannot carry it; render it as the box's first child. */
+    ground: PhiSurfaceGround | null;
     hasExplicitLayoutBackground: boolean;
 };

package/components/layouts/phi-layout-view-model.js

@@ -1,7 +1,7 @@
 import { PHI_FORM_GRID_TRACKS } from "../../types/form-descriptor";
-import { resolvePhiLayoutStyle, } from "./phi-layout-contract";
-import { combinePhiBoxShadows, composePhiLayoutEffectStyle, resolvePhiShadow, resolvePhiLayoutEffectStyle, } from "../../helpers/layout-style";
-export function resolvePhiBaseLayoutSlotState(initialSlotStates, slotIndex) {
+import { PHI_LAYOUT_SURFACE_RADIUS, resolvePhiPaddingStyle, } from "./phi-layout-contract";
+import { resolvePhiSurfaceStyle } from "../../helpers/surface-style";
+function resolvePhiBaseLayoutSlotState(initialSlotStates, slotIndex) {
     const candidate = Array.isArray(initialSlotStates)
         ? initialSlotStates[slotIndex]
         : initialSlotStates?.[slotIndex];
@@ -12,26 +12,15 @@ export function resolvePhiBaseLayoutSlotState(initialSlotStates, slotIndex) {
 export function resolvePhiBaseLayoutSlotStates(slotCount, initialSlotStates) {
     return Array.from({ length: slotCount }, (_, slotIndex) => resolvePhiBaseLayoutSlotState(initialSlotStates, slotIndex));
 }
-export function resolvePhiBaseLayoutChrome({ padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, borderSource, border, borderRadius, effect, shadow, labelEnd, }) {
-    const layoutStyle = resolvePhiLayoutStyle({
-        padding,
-        paddingTop,
-        paddingRight,
-        paddingBottom,
-        paddingLeft,
-        background,
-        borderSource,
-        border,
-        borderRadius,
-    });
-    const effectStyle = resolvePhiLayoutEffectStyle({
-        effect,
-        background: layoutStyle.background,
-    });
-    const resolvedBoxShadow = combinePhiBoxShadows(effectStyle?.boxShadow, resolvePhiShadow(shadow));
+export function resolvePhiBaseLayoutChrome({ padding, paddingTop, paddingRight, paddingBottom, paddingLeft, surface, labelEnd, }) {
+    /*
+     * A Layout is a surface, so a corner nobody stated is the Site's to answer -- the same step a Table and
+     * a Tree take. A Layout without a Surface states no corner: there is no box there to round.
+     */
+    const resolvedSurface = resolvePhiSurfaceStyle(surface, { cornerFallback: PHI_LAYOUT_SURFACE_RADIUS });
     const style = {
-        ...composePhiLayoutEffectStyle(layoutStyle, effectStyle),
-        ...(resolvedBoxShadow == null ? {} : { boxShadow: resolvedBoxShadow }),
+        ...resolvedSurface.style,
+        ...resolvePhiPaddingStyle({ padding, paddingTop, paddingRight, paddingBottom, paddingLeft }),
         /*
          * The label column, written the two ways it is read: as the grid line a descriptor form places its
          * labels on, and as the share of the width a labelled Control needs, which knows nothing of the
@@ -48,8 +37,9 @@ export function resolvePhiBaseLayoutChrome({ padding, paddingTop, paddingRight,
             "--phi-labeled-control-width": "100%",
         }),
     };
-    const hasExplicitLayoutBackground = style.background != null ||
-        style.backgroundColor != null ||
-        style.backgroundImage != null;
-    return { style, hasExplicitLayoutBackground };
+    return {
+        style,
+        ground: resolvedSurface.ground,
+        hasExplicitLayoutBackground: resolvedSurface.paintsGround,
+    };
 }

package/components/layouts/phi-masonry-columns.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+/**
+ * A Masonry's column box, packed by height once the browser can measure.
+ *
+ * The server sends the children in a multi-column flow, which balances where the columns end and so
+ * leaves a column empty whenever fewer would end lower: four children of one height in three columns
+ * stood two and two. Here each child is measured and set under the column that ends highest
+ * (`packPhiMasonryItems`), so every column the author asked for is used.
+ *
+ * Nothing is moved in the DOM -- a Widget moved to another parent would mount anew -- the children are
+ * only placed: the column and the top go on each item as custom properties, and
+ * `[data-phi-masonry-packed]` in `styles/layout.css` turns the flow off and places them. The column
+ * count is read from the box, where the container queries chose it, so the thresholds stay in the
+ * stylesheet. One column needs no packing; the flow is the packing then.
+ */
+export declare function PhiMasonryColumns({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/components/layouts/phi-masonry-columns.js

@@ -0,0 +1,77 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLayoutEffect, useRef } from "react";
+import { packPhiMasonryItems } from "./phi-masonry-contract";
+const PHI_MASONRY_ITEM_SELECTOR = ":scope > .phi-masonry-layout__item";
+/** Packs the column box's children, or hands them back to the flow where there is one column. */
+function packPhiMasonryBox(box) {
+    const items = [...box.querySelectorAll(PHI_MASONRY_ITEM_SELECTOR)];
+    const columns = Number.parseInt(getComputedStyle(box).getPropertyValue("--phi-masonry-columns"), 10);
+    if (!Number.isFinite(columns) || columns <= 1 || items.length === 0) {
+        box.removeAttribute("data-phi-masonry-packed");
+        box.style.removeProperty("--phi-masonry-packed-columns");
+        box.style.removeProperty("--phi-masonry-packed-height");
+        for (const item of items) {
+            item.style.removeProperty("--phi-masonry-item-column");
+            item.style.removeProperty("--phi-masonry-item-top");
+        }
+        return;
+    }
+    /*
+     * The count goes on first, so the heights are measured at the width the children have with it -- the
+     * width of a column of the flow, too, so the first pack measures what the flow showed.
+     */
+    box.setAttribute("data-phi-masonry-packed", "");
+    box.style.setProperty("--phi-masonry-packed-columns", String(columns));
+    const heights = items.map((item) => item.getBoundingClientRect().height);
+    const { placements, height } = packPhiMasonryItems(heights, columns);
+    items.forEach((item, index) => {
+        item.style.setProperty("--phi-masonry-item-column", String(placements[index].column));
+        item.style.setProperty("--phi-masonry-item-top", `${placements[index].top}px`);
+    });
+    box.style.setProperty("--phi-masonry-packed-height", `${height}px`);
+}
+/**
+ * A Masonry's column box, packed by height once the browser can measure.
+ *
+ * The server sends the children in a multi-column flow, which balances where the columns end and so
+ * leaves a column empty whenever fewer would end lower: four children of one height in three columns
+ * stood two and two. Here each child is measured and set under the column that ends highest
+ * (`packPhiMasonryItems`), so every column the author asked for is used.
+ *
+ * Nothing is moved in the DOM -- a Widget moved to another parent would mount anew -- the children are
+ * only placed: the column and the top go on each item as custom properties, and
+ * `[data-phi-masonry-packed]` in `styles/layout.css` turns the flow off and places them. The column
+ * count is read from the box, where the container queries chose it, so the thresholds stay in the
+ * stylesheet. One column needs no packing; the flow is the packing then.
+ */
+export function PhiMasonryColumns({ children }) {
+    const boxRef = useRef(null);
+    const observerRef = useRef(null);
+    /* Box width (and with it the count) and every child's height; a pack that changes nothing settles. */
+    useLayoutEffect(() => {
+        const box = boxRef.current;
+        if (!box)
+            return;
+        const observer = new ResizeObserver(() => packPhiMasonryBox(box));
+        observerRef.current = observer;
+        return () => {
+            observer.disconnect();
+            observerRef.current = null;
+        };
+    }, []);
+    /* After every render: the children may have changed, so observe the ones there are and pack. */
+    useLayoutEffect(() => {
+        const box = boxRef.current;
+        const observer = observerRef.current;
+        if (!box || !observer)
+            return;
+        observer.disconnect();
+        observer.observe(box);
+        for (const item of box.querySelectorAll(PHI_MASONRY_ITEM_SELECTOR)) {
+            observer.observe(item);
+        }
+        packPhiMasonryBox(box);
+    });
+    return (_jsx("div", { ref: boxRef, className: "phi-masonry-layout__columns", children: children }));
+}

package/components/layouts/phi-masonry-contract.d.ts

@@ -0,0 +1,45 @@
+import type { PhiResolvedResponsiveValue, PhiResponsiveValue } from "../../types/responsive";
+import { type PhiGridColumnCount } from "./phi-grid-contract";
+/**
+ * How many columns a Masonry has when it was never told: one where there is no room to share, two in
+ * the middle, three where it is at least as wide as the content column.
+ *
+ * One number for every width stood here before, so three columns stood in a sider as in the content
+ * column, only narrower. The other way to answer the room was a minimum column width, and the renderer
+ * then dropped the column count altogether: two fields of which only one ever worked.
+ */
+export declare const PHI_MASONRY_LAYOUT_DEFAULT_COLUMNS: PhiResolvedResponsiveValue<PhiGridColumnCount>;
+/**
+ * Where a Masonry changes its columns, measured on its own box: the Grid's thresholds, so a Masonry and
+ * a Grid of the same room answer the same width. `@container phi-masonry` in `styles/layout.css`
+ * compares against these; `validate-container-breakpoint-contracts.ts` holds the two together.
+ */
+export declare const PHI_MASONRY_RESPONSIVE_MIN_WIDTH: {
+    readonly medium: 144 | 233 | 377 | 610 | 987;
+    readonly wide: 144 | 233 | 377 | 610 | 987;
+};
+/** The Masonry's columns at every width: what was stated where it is a column count, the default elsewhere. */
+export declare function resolvePhiMasonryColumns(columns: PhiResponsiveValue<number> | undefined): PhiResolvedResponsiveValue<PhiGridColumnCount>;
+/**
+ * The custom properties the Masonry's column box reads: its column count at every width and the gap.
+ * `styles/layout.css` (`.phi-masonry-layout__columns`) picks the count by the container queries.
+ */
+export declare function resolvePhiMasonryColumnProperties(columns: PhiResolvedResponsiveValue<PhiGridColumnCount>, gap: string): Record<`--phi-masonry-${string}`, string>;
+/** Where one child stands once packed: its column and its distance from the top of the column box. */
+export type PhiMasonryItemPlacement = {
+    column: number;
+    top: number;
+};
+/**
+ * Packs children by height: each goes under the column that ends highest, in the order they come. Ties
+ * go to the leftmost column; half a pixel counts as a tie, so the fractions a browser measures do not
+ * send a child to the far side.
+ *
+ * The heights include the gap below each child (the item's padding), so the column box is as tall as
+ * the longest column and the gap under it is taken back by the column box's margin, as in the
+ * multi-column flow this replaces in the browser.
+ */
+export declare function packPhiMasonryItems(heights: readonly number[], columns: number): {
+    placements: PhiMasonryItemPlacement[];
+    height: number;
+};