@phis/ui 0.4.3 → 0.4.4

package/components/controls/phi-truncated-hover-text.d.ts

@@ -0,0 +1,15 @@
+import { type ReactElement, type ReactNode, type Ref } from "react";
+/**
+ * A hover text that says what an ellipsis cut off, and only then.
+ *
+ * Around one element that cuts its own text short (`text-overflow: ellipsis`): pointed at, the element is
+ * measured, and the whole text shows in the house tooltip when it did not fit. An element whose text fits
+ * shows nothing -- a tooltip repeating the words that stand right there is noise. The child is the element
+ * itself, not a component, so the measuring reaches the box that cuts.
+ */
+export declare function PhiTruncatedHoverText({ title, children, }: {
+    title: ReactNode;
+    children: ReactElement<{
+        ref?: Ref<HTMLElement>;
+    }>;
+}): import("react").JSX.Element;

package/components/controls/phi-truncated-hover-text.js

@@ -0,0 +1,25 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cloneElement, lazy, Suspense, useState } from "react";
+/* The same Tooltip `PhiHoverText` loads, and loaded the same way: only where one is drawn. */
+const PhiLazyTooltip = lazy(() => import("antd/es/tooltip"));
+/** Whether an element shows less than its text: cut off at its end by an ellipsis, or by its height. */
+function isPhiElementTruncated(element) {
+    return element != null
+        && (element.scrollWidth > element.clientWidth + 1 || element.scrollHeight > element.clientHeight + 1);
+}
+/**
+ * A hover text that says what an ellipsis cut off, and only then.
+ *
+ * Around one element that cuts its own text short (`text-overflow: ellipsis`): pointed at, the element is
+ * measured, and the whole text shows in the house tooltip when it did not fit. An element whose text fits
+ * shows nothing -- a tooltip repeating the words that stand right there is noise. The child is the element
+ * itself, not a component, so the measuring reaches the box that cuts.
+ */
+export function PhiTruncatedHoverText({ title, children, }) {
+    // A callback ref held as state: the element is read when it is pointed at, never while rendering.
+    const [element, setElement] = useState(null);
+    const [open, setOpen] = useState(false);
+    const target = cloneElement(children, { ref: setElement });
+    return (_jsx(Suspense, { fallback: children, children: _jsx(PhiLazyTooltip, { title: title, open: open, onOpenChange: (next) => setOpen(next && isPhiElementTruncated(element)), children: target }) }));
+}

package/components/forms/link-target-form-control.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentType } from "react";
+import type { ComponentType } from "react";
 import type { PhiFormFieldProviderProps } from "./form-provider-registry";
 /**
  * The `link-target` field: one link, to a Page of an Area or to an address elsewhere (`FORMS.md`).

package/components/forms/link-target-form-control.js

@@ -1,8 +1,8 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
 import { isPhiCmsAreaKey } from "../../constants/cms-areas";
 import { PhiLinkTargetControl } from "../widgets/client/shared/phi-link-target-control";
+import { usePhiPageReferenceOptions } from "../widgets/client/shared/use-page-reference-options";
 import { PHI_FORM_LINK_TARGET_LABEL_KEYS } from "./form-provider-contract";
 const DEFAULT_LABELS = {
     none: "None",
@@ -13,32 +13,6 @@ const DEFAULT_LABELS = {
     newTab: "Open in a new tab",
     pagesUnavailable: "The Pages could not be loaded.",
 };
-/*
- * One request per Area for as long as the page lives: the create and the edit dialog offer the same
- * Pages, and a list that changed meanwhile is a Page somebody published while this one was being written.
- * A failed request is forgotten, so the next dialog asks again.
- */
-const pageOptionsByArea = new Map();
-function loadPageOptions(area) {
-    const cached = pageOptionsByArea.get(area);
-    if (cached)
-        return cached;
-    const request = (async () => {
-        const response = await fetch(`/api/site/page-references?area=${encodeURIComponent(area)}`, {
-            cache: "no-store",
-            credentials: "same-origin",
-            headers: { accept: "application/json" },
-        });
-        const payload = (await response.json().catch(() => null));
-        if (!response.ok || !Array.isArray(payload?.options)) {
-            throw new Error(`Page references for "${area}" answered ${response.status}.`);
-        }
-        return payload.options;
-    })();
-    pageOptionsByArea.set(area, request);
-    request.catch(() => pageOptionsByArea.delete(area));
-    return request;
-}
 /**
  * The `link-target` field: one link, to a Page of an Area or to an address elsewhere (`FORMS.md`).
  *
@@ -48,24 +22,7 @@ function loadPageOptions(area) {
  */
 export const PhiLinkTargetFormControl = ({ field, value, labels, disabled, readOnly, onChange, }) => {
     const area = isPhiCmsAreaKey(field.config?.area) ? field.config.area : "public";
-    const [options, setOptions] = useState([]);
-    const [failed, setFailed] = useState(false);
-    useEffect(() => {
-        let current = true;
-        loadPageOptions(area).then((next) => {
-            if (current) {
-                setOptions(next);
-                setFailed(false);
-            }
-        }, (error) => {
-            console.warn("[phi-form] Page references could not be loaded.", { area, error });
-            if (current)
-                setFailed(true);
-        });
-        return () => {
-            current = false;
-        };
-    }, [area]);
+    const { options, failed } = usePhiPageReferenceOptions(area, "phi-form");
     const read = (key, fallback) => labels?.[key]?.trim() || fallback;
     const controlLabels = {
         none: read(PHI_FORM_LINK_TARGET_LABEL_KEYS.none, DEFAULT_LABELS.none),

package/components/forms/phi-form-widget-frame.js

@@ -1,7 +1,7 @@
 "use client";
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, Fragment, useContext, useEffect, useMemo, useRef, useState, } from "react";
-import { PHI_COLOR, PHI_SPACE } from "../../theme/antd-css-var-contract";
+import { PHI_FONT_SIZE, PHI_COLOR, PHI_SPACE } from "../../theme/antd-css-var-contract";
 import { PHI_THEME_BORDER_WIDTH } from "../../helpers/border-widget-style";
 import { normalizePhiCssSize, PHI_LAYOUT_SURFACE_RADIUS, PHI_SLOT_INLINE_PLACEMENT_MARGIN_STYLE, } from "../layouts/phi-layout-contract";
 import { PhiButtonControl } from "../controls/phi-button-control";
@@ -109,7 +109,9 @@ export function PhiFormWidgetFrame({ submit, card, maxFormWidth, links, layout,
      * Widget rather than beside it: a Widget in the next slot stands in the Layout's box, not on the
      * form's grid, and no percentage of the outer width lands on that column once the grid has gaps.
      */
-    const linksRow = links && links.length > 0 ? (_jsx("div", { className: "phi-form-descriptor-actions", children: _jsx("div", { className: "phi-form-cell phi-form-cell--control", style: { display: "flex", flexWrap: "wrap", alignItems: "center", gap: PHI_SPACE.sm }, children: links.map((link, index) => (_jsxs(Fragment, { children: [index > 0 ? _jsx("span", { "aria-hidden": true, style: { color: PHI_COLOR.textTertiary }, children: "|" }) : null, _jsx(PhiLink, { href: link.href, children: link.label })] }, link.key))) }) })) : null;
+    const linksRow = links && links.length > 0 ? (_jsx("div", { className: "phi-form-descriptor-actions", children: _jsx("div", { className: "phi-form-cell phi-form-cell--control", 
+            // The ways out are asides to the form, taken now and then, so they write small (`sm`).
+            style: { display: "flex", flexWrap: "wrap", alignItems: "center", gap: PHI_SPACE.sm, fontSize: PHI_FONT_SIZE.sm }, children: links.map((link, index) => (_jsxs(Fragment, { children: [index > 0 ? _jsx("span", { "aria-hidden": true, style: { color: PHI_COLOR.textTertiary }, children: "|" }) : null, _jsx(PhiLink, { href: link.href, children: link.label })] }, link.key))) }) })) : null;
     /*
      * The ways out come first, then the button.
      *

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

@@ -75,6 +75,8 @@ function renderColumn(isAuthoringRender, key, child, width, flex, anchor, slotRo
                     width: "100%",
                 } })) : null] }, key));
 }
+/** How much faster the middle slot grows than each balanced side. */
+const PHI_THREE_COLUMN_MIDDLE_GROW = 2;
 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, surface, labelEnd, size, minSize, maxSize, collapsedSizeHint, } = layoutProps;
@@ -83,7 +85,14 @@ export function PhiThreeColumnLayout({ blockId, slots, balancedSides = true, gap
     const resolvedMiddleWidth = normalizePhiCssSize(middleWidth);
     const resolvedRightWidth = normalizePhiCssSize(rightWidth);
     const leftFlex = resolvedLeftWidth ? `0 0 ${resolvedLeftWidth}` : balancedSides ? "1 1 0" : "0 1 auto";
-    const middleFlex = resolvedMiddleWidth ? `0 0 ${resolvedMiddleWidth}` : "1 1 0";
+    /*
+     * The middle is the main thing and takes the larger share: with balanced sides it grows twice as fast as
+     * each side, so the sides stay equal to each other and the middle stays centred; without, it takes what
+     * the sides' content leaves.
+     */
+    const middleFlex = resolvedMiddleWidth
+        ? `0 0 ${resolvedMiddleWidth}`
+        : `${PHI_THREE_COLUMN_MIDDLE_GROW} 1 0`;
     const rightFlex = resolvedRightWidth ? `0 0 ${resolvedRightWidth}` : balancedSides ? "1 1 0" : "0 1 auto";
     const showInsertButton = resolvedRenderMode === "editor";
     const { style: resolvedLayoutStyle, ground, hasExplicitLayoutBackground, } = resolvePhiBaseLayoutChrome({

package/components/navigation/phi-link.js

@@ -10,10 +10,15 @@ export function PhiLink({ href, children, external, newTab, prefetch, className,
     const [active, setActive] = useState(false);
     const useAnchor = external ?? isPhiExternalHref(href);
     const linkStyle = useMemo(() => ({
-        color: active ? token.colorLinkActive : hovered ? token.colorLinkHover : token.colorLink,
         textDecoration: "none",
         cursor: "pointer",
         ...style,
+        /*
+         * A colour the caller states is the link at rest -- a Header's text colour, a list's inherited one --
+         * and never more: pointed at and pressed, a link answers in the Theme's link colours whatever it
+         * rests in. Spread after `style`, a stated colour had silenced the hover of every link that set one.
+         */
+        color: active ? token.colorLinkActive : hovered ? token.colorLinkHover : style?.color ?? token.colorLink,
     }), [active, hovered, style, token.colorLink, token.colorLinkActive, token.colorLinkHover]);
     const interactionProps = {
         onMouseEnter: () => setHovered(true),

package/components/regions/clients/cms-region-container-client.js

@@ -17,7 +17,8 @@ import { PhiEffectsReadyTrigger } from "../../../plugins/runtime/phi-effects-rea
 import { PhiSlotChildEffectsVisibilityObserver } from "../../../plugins/runtime/phi-slot-child-effects-visibility-observer";
 import { PhiSlotChildViewportEffectsObserver } from "../../../plugins/runtime/phi-slot-child-viewport-effects-observer";
 import { PhiFlexControl } from "../../controls/phi-flex-control";
-import { resolvePhiCmsRegionShell } from "../phi-cms-region-shell";
+import { phiCmsRegionSiderSticks, resolvePhiCmsRegionShell, } from "../phi-cms-region-shell";
+import { usePhiShellStickyTop } from "../../shell/use-phi-shell-sticky-top";
 import { usePhiVisualAnchor } from "../../runtime/runtime-visual-anchors";
 import { usePhiPathname } from "../../runtime/use-phi-pathname";
 import { stripLocaleAndAreaFromPathname } from "../../../helpers/locale";
@@ -100,6 +101,10 @@ export function PhiCmsRegionContainerClient({ children, className, regionKey, co
         elementRef,
         placeholderRef,
     });
+    usePhiShellStickyTop({
+        active: !previewMode && inScope && phiCmsRegionSiderSticks(regionKey, initialConfig),
+        elementRef,
+    });
     /*
      * Off this Page, the Region leaves a hidden marker rather than nothing: `header_top` still has to tell
      * the Shell it holds no room, and it finds the Shell from here.

package/components/regions/phi-cms-region-container.js

@@ -3,6 +3,7 @@ import { isPhiCmsPageOwnedRegion } from "../../helpers/cms-region-keys";
 import { hasPhiFlag } from "../../helpers/flags";
 import { PhiCmsFlags } from "../../constants/phi-cms";
 import { PhiCmsRegionStatic } from "./phi-cms-region-static";
+import { phiCmsRegionSiderSticks } from "./phi-cms-region-shell";
 import { resolveRenderableBlockEffectsAttributes, resolveRenderableBlockViewportEffects, } from "../../helpers/renderable-block-effects";
 import { PhiRuntimeModuleRenderClientHost } from "../runtime/runtime-module-render-client-manifest";
 import { PhiRuntimeRenderClientType } from "../../constants/runtime-render-client-types";
@@ -21,6 +22,8 @@ export function PhiCmsRegionContainer({ children, className, regionKey, config,
     const requiresClientEnhancement = signalParticipant ||
         pageScoped ||
         (!previewMode && readPhiCmsRegionReveal(regionKey, config) !== "always") ||
+        // A stuck Sider stands under the Header as measured, and only the browser can measure it.
+        (!previewMode && phiCmsRegionSiderSticks(regionKey, config)) ||
         hasPhiFlag(config?.flags, PhiCmsFlags.Collapsible) ||
         requiresEffectsObserver ||
         resolvePhiBackgroundMotion(config?.surface?.background) != null;

package/components/regions/phi-cms-region-shell.d.ts

@@ -3,7 +3,7 @@ import type { CSSProperties } from "react";
 import { type PhiRenderableBlockEffectsAttributes } from "../../helpers/renderable-block-effects";
 import { resolvePhiShellRegionChrome } from "../../helpers/shell-region-style";
 import type { PhiBlockRuntime, PhiCmsRegionConfig, PhiCmsRegionKey, PhiRenderableBlock } from "../../types";
-import type { PhiSurfaceGround } from "../../helpers/surface-style";
+import { type PhiSurfaceGround } from "../../helpers/surface-style";
 import type { PhiCmsRegionReveal } from "../../types/cms-presets";
 import { type PhiCmsBackgroundWidgetConfig } from "../widgets/config/background";
 /**
@@ -92,6 +92,17 @@ export type PhiCmsRegionShell = {
     /** The content wrapper's style, which is where Region padding lives (LAYOUTING.md "Regions"). */
     contentStyle: CSSProperties;
 };
+/**
+ * Whether a Region is a Sider that sticks under the Header, and so needs the Header's measured bottom.
+ *
+ * Two kinds of Sider stick, and only one of them under the Header. A `FullHeight` Sider is a column of the
+ * Shell from the viewport's top to its bottom -- an Admin or Builder navigation beside the Header, not
+ * below it -- and stands at its configured `offsetTop`. A `Sticky` Sider without it stands in the page
+ * below the Header -- a contents beside a text -- and sticks under the line the Shell publishes as
+ * `--phi-shell-sticky-top` (`usePhiShellStickyTop`), with its offset added. The Region renderer runs that
+ * measurement for such a Sider, which is why this is asked before the Region renders.
+ */
+export declare function phiCmsRegionSiderSticks(regionKey: PhiCmsRegionKey, config: Pick<PhiCmsRegionConfig, "flags"> | null | undefined): boolean;
 /**
  * The Region's shell, or null where the Region renders nothing: hidden, or collapsed in a preview.
  * `header_bottom` is exempt from the preview collapse because the Page, not the Area, owns its content.

package/components/regions/phi-cms-region-shell.js

@@ -6,11 +6,12 @@ import { resolveRenderableBlockEffectsAttributes, resolveRenderableBlockEffectsS
 import { resolvePhiShellRegionChrome, resolvePhiShellRegionGroundStyle, resolvePhiShellRegionTypography, resolvePhiShellRegionZIndex, resolvePhiShellSiderCollapsedWidth, resolvePhiShellSiderWidth, } from "../../helpers/shell-region-style";
 import { PhiCmsFlags } from "../../constants/phi-cms";
 import { resolvePhiCmsBorderSource } from "../../types/cms-border-source";
+import { PHI_SURFACE_TONE_GROUND, phiSurfaceTakesToneGround, } from "../../helpers/surface-style";
 import { resolvePhiRenderableBlockGeometry } from "../../types/renderable-block-geometry";
 import { createPhiSignalAddress } from "../../types/signals";
 import { readPhiCmsRegionReveal } from "../../helpers/region-page-scope";
 import { resolvePhiPaddingStyle } from "../layouts/phi-layout-contract";
-import { phiRegionUsesShellChromeOverlay } from "../root/phi-shell-chrome-overlay";
+import { PHI_SHELL_STICKY_TOP_PROPERTY, phiRegionUsesShellChromeOverlay } from "../root/phi-shell-chrome-overlay";
 import { normalizePhiBackgroundWidgetConfig, phiBackgroundWidgetConfigPaintsGround, resolvePhiBackgroundGroundFilter, resolvePhiBackgroundMotion, resolvePhiBackgroundMotionHostStyle, resolvePhiBackgroundPane, resolvePhiBackgroundWidgetStyle, } from "../widgets/config/background";
 /*
  * The longhands every Region that paints the Shell Chrome Overlay (SHELL.md) carries, read from the
@@ -45,6 +46,25 @@ function resolvePhiCmsRegionShellFamily(regionKey) {
     }
     return "other";
 }
+/**
+ * Whether a Region is a Sider that sticks under the Header, and so needs the Header's measured bottom.
+ *
+ * Two kinds of Sider stick, and only one of them under the Header. A `FullHeight` Sider is a column of the
+ * Shell from the viewport's top to its bottom -- an Admin or Builder navigation beside the Header, not
+ * below it -- and stands at its configured `offsetTop`. A `Sticky` Sider without it stands in the page
+ * below the Header -- a contents beside a text -- and sticks under the line the Shell publishes as
+ * `--phi-shell-sticky-top` (`usePhiShellStickyTop`), with its offset added. The Region renderer runs that
+ * measurement for such a Sider, which is why this is asked before the Region renders.
+ */
+export function phiCmsRegionSiderSticks(regionKey, config) {
+    return resolvePhiCmsRegionShellFamily(regionKey) === "sider"
+        && hasPhiFlag(config?.flags, PhiCmsFlags.Sticky)
+        && !hasPhiFlag(config?.flags, PhiCmsFlags.FullHeight);
+}
+/** The line a stuck Sider stands at: under the Header as measured, plus its own offset. */
+function resolvePhiCmsRegionSiderStuckTop(topCss) {
+    return `calc(var(${PHI_SHELL_STICKY_TOP_PROPERTY}, 0px) + ${topCss})`;
+}
 /*
  * A Region's edge, from its Surface.
  *
@@ -123,15 +143,24 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
      * `scroll-up` band ever publishes it (SHELL.md "Region visibility per Page"), so for every other Shell
      * it is unset and the offset is the one configured.
      */
+    /*
+     * A full-height Sider is a Shell column from the viewport's top and stands at its own offset; a sticky
+     * one stands under the Header as it is measured right now (`phiCmsRegionSiderSticks`) and is at most as
+     * tall as what is left of the viewport below that line.
+     */
+    const siderUnderHeader = isSider && sticky && !fullHeight;
     const stuckTop = !stuck
         ? undefined
         : isHeader && regionKey !== "header_top"
             ? `calc(${topCss} + var(--phi-shell-header-top-stack, 0px))`
-            : top;
+            : siderUnderHeader
+                ? resolvePhiCmsRegionSiderStuckTop(topCss)
+                : top;
     const blockSize = geometry.block.size?.css;
     const fullHeightSize = fullHeight && !blockSize
         ? `calc(100dvh - ${topCss})`
         : blockSize;
+    const underHeaderMaxSize = siderUnderHeader ? `calc(100dvh - ${resolvePhiCmsRegionSiderStuckTop(topCss)})` : undefined;
     const zIndex = config.zIndex ?? resolvePhiShellRegionZIndex(regionKey, hasPhiFlag(config.flags, PhiCmsFlags.FullHeight));
     /*
      * A Background config that paints nothing is not an authored ground. The Builder writes one onto every
@@ -143,12 +172,31 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
         ? normalizePhiBackgroundWidgetConfig(surface.background)
         : null;
     const backgroundConfig = phiBackgroundWidgetConfigPaintsGround(surfaceBackground) ? surfaceBackground : null;
+    /*
+     * A tone turns the ground as well, by the rule every Surface follows (LAYOUTING.md "Surface tone"):
+     * where the Background paints nothing, the Region takes its tone's container ground, which resolves
+     * under the tone class the root element carries. That is a ground of the Region's own, so the Shell's
+     * -- the Theme's record, the Chrome Overlay, a pane frosting either -- does not show beneath it.
+     */
+    const toneGround = phiSurfaceTakesToneGround(surface?.tone, backgroundConfig != null);
+    /*
+     * The Theme's Overlay as the ground (`base.kind: "theme"`). Without a tone a Chrome Region takes it the
+     * way a Region without a Background does -- the `data-phi-shell-chrome` marker, so that where the Shell
+     * draws its panes the pane behind shows through instead of a second frosting -- but over any ground the
+     * Shell record sets. Every other Region, and a toned one, paints it itself, which under a tone's class
+     * is the Overlay of the tone's mode.
+     */
+    const themeGround = backgroundConfig?.base.kind === "theme";
+    const themeGroundIsShellChrome = themeGround
+        && resolvePhiSurfaceToneClassName(surface?.tone) == null
+        && phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, grounds: [] });
     /*
      * A pane on a Region without a ground of its own frosts the Shell's ground for this Region -- the
      * Theme's record, or the family's fallback -- which is what glass on a bare Header has always meant.
-     * A Region that paints its own ground carries its pane inside that Background, as every Surface does.
+     * A Region that paints its own ground carries its pane inside that Background, as every Surface does;
+     * the tone's ground is one, so its pane stays on the box under that ground, as on a toned Layout.
      */
-    const shellPane = backgroundConfig == null ? resolvePhiBackgroundPane(surfaceBackground) : null;
+    const shellPane = backgroundConfig == null && !toneGround ? resolvePhiBackgroundPane(surfaceBackground) : null;
     const backgroundMoves = animatesBackground &&
         backgroundConfig != null &&
         resolvePhiBackgroundMotion(backgroundConfig) != null;
@@ -160,11 +208,18 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
             motion: null,
         }
         : null;
-    const backgroundStyle = backgroundConfig == null || ground != null
+    const backgroundStyle = themeGroundIsShellChrome
         ? null
-        : backgroundMoves
-            ? resolvePhiBackgroundMotionHostStyle(backgroundConfig)
-            : resolvePhiBackgroundWidgetStyle(backgroundConfig);
+        : toneGround
+            ? {
+                ...(surfaceBackground ? resolvePhiBackgroundWidgetStyle(surfaceBackground) : {}),
+                backgroundColor: PHI_SURFACE_TONE_GROUND,
+            }
+            : backgroundConfig == null || ground != null
+                ? null
+                : backgroundMoves
+                    ? resolvePhiBackgroundMotionHostStyle(backgroundConfig)
+                    : resolvePhiBackgroundWidgetStyle(backgroundConfig);
     const chromeInput = {
         shadow: surface?.shadow ?? undefined,
         effect: shellPane ?? undefined,
@@ -184,12 +239,14 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
      * the stored one: the Builder persists an empty Background record for every Region an author has ever
      * opened, and the raw value is never null for those.
      */
-    const usesShellChromeOverlay = phiRegionUsesShellChromeOverlay({
-        regionKey,
-        backgroundConfig,
-        pane: shellPane,
-        grounds: [chrome.light.background, chrome.dark.background],
-    });
+    const usesShellChromeOverlay = themeGround
+        ? themeGroundIsShellChrome
+        : !toneGround && phiRegionUsesShellChromeOverlay({
+            regionKey,
+            backgroundConfig,
+            pane: shellPane,
+            grounds: [chrome.light.background, chrome.dark.background],
+        });
     /*
      * The ground. Published, it is the pair of custom properties `shell.css` paints from, because it may
      * be a colour or a gradient and only CSS can tell which without guessing; nothing inline may name a
@@ -203,13 +260,18 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
      * drop one of those from an element whose `background` shorthand is still set.
      */
     const liveChrome = paint.kind === "live" ? chrome[paint.mode] : null;
+    /*
+     * A toned Region publishes no Shell ground: `shell.css` would paint a gradient one beneath its own. Nor
+     * does one whose ground is the Theme's: the Overlay stands where the Shell record's ground would.
+     */
+    const withoutShellGround = toneGround || themeGround;
     const modeStyle = liveChrome
         ? {}
         : {
-            ...(chrome.light.background == null
+            ...(chrome.light.background == null || withoutShellGround
                 ? {}
                 : { "--phi-region-background-light": String(chrome.light.background) }),
-            ...(chrome.dark.background == null
+            ...(chrome.dark.background == null || withoutShellGround
                 ? {}
                 : { "--phi-region-background-dark": String(chrome.dark.background) }),
             "--phi-region-color-light": String(chrome.light.color),
@@ -219,7 +281,7 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
     const effectStyle = liveChrome || paintedChrome.effectStyle?.backgroundColor == null
         ? paintedChrome.effectStyle
         : { ...paintedChrome.effectStyle, backgroundColor: "var(--phi-region-background)" };
-    const groundStyle = liveChrome && backgroundStyle == null
+    const groundStyle = liveChrome && backgroundStyle == null && !themeGround
         ? resolvePhiShellRegionGroundStyle(liveChrome.background)
         : {};
     const typography = resolvePhiShellRegionTypography(regionKey, shellTheme, {
@@ -258,11 +320,11 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
             maxWidth: geometry.inline.max?.css ?? siderWidth,
             height: fullHeightSize,
             minHeight: geometry.block.min?.css ?? (fullHeight ? fullHeightSize : undefined),
-            maxHeight: geometry.block.max?.css,
+            maxHeight: geometry.block.max?.css ?? underHeaderMaxSize,
             alignSelf: fullHeight ? "stretch" : "start",
             flex: fullHeight ? "1 1 auto" : undefined,
             overflowX: "visible",
-            overflowY: fullHeight ? "auto" : "visible",
+            overflowY: fullHeight || siderUnderHeader ? "auto" : "visible",
         }
         : {
             width: geometry.inline.size?.css ?? "100%",

package/components/root/phi-config-provider.d.ts

@@ -30,6 +30,11 @@ export type PhiConfig = {
      * the reader rather than quietly working until the day the Theme is computed by something else.
      */
     token: PhiThemeTokens;
+    /**
+     * The page's Theme where `token` is a Surface tone's (`PhiNestedModeConfigProvider`): set only inside
+     * a tone scope, so outside one the page's Theme is `token` itself. Read through `usePhiPageModeToken`.
+     */
+    pageToken?: PhiThemeTokens;
 };
 export type PhiFontCatalogueFamily = {
     family: string;
@@ -49,6 +54,14 @@ export declare function PhiConfigProvider({ children, locale, fonts, fontFamilie
     controlShape: PhiControlShape;
 }): import("react").JSX.Element;
 export declare function usePhiConfig(): PhiConfig;
+/**
+ * The Theme of the page's own mode, wherever this is asked -- inside a Surface tone too.
+ *
+ * What draws the page's tools rather than its content takes its colours from here: the Builder's scaffolds
+ * mark Layouts and Widgets in the editor's mode, and a Region turned inverse leaves them as they were
+ * instead of turning them with the content they stand around.
+ */
+export declare function usePhiPageModeToken(): PhiThemeTokens;
 /** The locale the root adapter configures Ant Design with, for whoever hands it on. */
 export type PhiConfigLocale = ConfigProviderProps["locale"];
 /**

package/components/root/phi-config-provider.js

@@ -70,6 +70,17 @@ export function usePhiConfig() {
     }
     return config;
 }
+/**
+ * The Theme of the page's own mode, wherever this is asked -- inside a Surface tone too.
+ *
+ * What draws the page's tools rather than its content takes its colours from here: the Builder's scaffolds
+ * mark Layouts and Widgets in the editor's mode, and a Region turned inverse leaves them as they were
+ * instead of turning them with the content they stand around.
+ */
+export function usePhiPageModeToken() {
+    const config = usePhiConfig();
+    return config.pageToken ?? config.token;
+}
 /**
  * The page's config in another mode: Ant Design's Theme for `mode` and the house config with that mode's
  * colours and tokens.
@@ -89,6 +100,6 @@ export function PhiNestedModeConfigProvider({ mode, theme, cssVarKey, locale, cu
 function PhiNestedModeConfigValue({ mode, customColors, children, }) {
     const outer = usePhiConfig();
     const { token } = antdTheme.useToken();
-    const value = useMemo(() => ({ ...outer, mode, customColors, token }), [customColors, mode, outer, token]);
+    const value = useMemo(() => ({ ...outer, mode, customColors, token, pageToken: outer.pageToken ?? outer.token }), [customColors, mode, outer, token]);
     return _jsx(PhiConfigContext.Provider, { value: value, children: children });
 }

package/components/root/phi-root-background.d.ts

@@ -53,6 +53,13 @@ export declare const PHI_ROOT_BACKGROUND_IMAGE_SOURCE_KINDS: readonly PhiBackgro
  * simply resolves away.
  */
 export declare const PHI_ROOT_BACKGROUND_FILTERS: readonly PhiBackgroundFilter[];
+/**
+ * The Base kinds the Theme Root Background offers and honours: every one but `theme`.
+ *
+ * `theme` is the Chrome Overlay standing in for a box's ground, and the Root Background is no box on the
+ * page but the ground beneath all of them. A stored value outside the offer resolves to `none`.
+ */
+export declare const PHI_ROOT_BACKGROUND_BASE_KINDS: readonly PhiCmsBackgroundWidgetConfig["base"]["kind"][];
 /**
  * What the ground paints, without the geometry of the layer that paints it.
  *

package/components/root/phi-root-background.js

@@ -59,8 +59,27 @@ export const PHI_ROOT_BACKGROUND_FILTERS = [];
 function withoutPhiRootBackgroundFilter(config) {
     return config ? { ...normalizePhiBackgroundWidgetConfig(config), filter: null } : null;
 }
+/**
+ * The Base kinds the Theme Root Background offers and honours: every one but `theme`.
+ *
+ * `theme` is the Chrome Overlay standing in for a box's ground, and the Root Background is no box on the
+ * page but the ground beneath all of them. A stored value outside the offer resolves to `none`.
+ */
+export const PHI_ROOT_BACKGROUND_BASE_KINDS = [
+    "none",
+    "color",
+    "gradient",
+    "image",
+];
 function readPhiRootBackgroundConfig(root, mode) {
-    return (mode === "dark" ? root?.background?.dark : root?.background?.light) ?? null;
+    const configured = (mode === "dark" ? root?.background?.dark : root?.background?.light) ?? null;
+    if (configured == null) {
+        return null;
+    }
+    const normalized = normalizePhiBackgroundWidgetConfig(configured);
+    return PHI_ROOT_BACKGROUND_BASE_KINDS.includes(normalized.base.kind)
+        ? configured
+        : { ...normalized, base: { kind: "none" } };
 }
 /**
  * What the ground paints, without the geometry of the layer that paints it.

package/components/root/phi-root-theme-resolver.js

@@ -53,6 +53,9 @@ export function resolvePhiRootTheme({ siteTheme, mode, fonts, presets, }) {
     const resolvedShellHeaderMainBackground = resolvePhiShellRegionBackground(siteTheme?.shell, mode, { family: "header", region: "main" }) ??
         (mode === "dark" ? PHI_DEFAULT_DARK_NAV_BACKGROUND : undefined);
     const sharedComponentDefaults = buildPhiComponentTokens({
+        ...(typeof effectiveThemeTokens.fontSizeSM === "number" ? { fontSizeSM: effectiveThemeTokens.fontSizeSM } : {}),
+        ...(typeof effectiveThemeTokens.fontSize === "number" ? { fontSize: effectiveThemeTokens.fontSize } : {}),
+        ...(typeof effectiveThemeTokens.lineHeight === "number" ? { lineHeight: effectiveThemeTokens.lineHeight } : {}),
         layout: {
             ...(resolvedShellSiderBackground ? { siderBg: resolvedShellSiderBackground } : {}),
             ...(resolvedShellHeaderMainBackground ? { headerBg: resolvedShellHeaderMainBackground } : {}),

package/components/root/phi-shell-chrome-overlay.d.ts

@@ -58,13 +58,18 @@ export declare const PHI_SHELL_CHROME_OVERLAY_IMAGE_SOURCE_KINDS: readonly PhiBa
 export declare const PHI_SHELL_CHROME_OVERLAY_MOTION_MODES: readonly PhiBackgroundMotionMode[];
 export type PhiShellChromeOverlayVariables = Record<`--phi-shell-chrome-${string}`, string>;
 /**
- * Whether this Region paints the shared overlay, which it does only while it authored nothing itself.
+ * Whether this Region paints the shared overlay, which it does while it authored nothing itself -- or
+ * while what it authored is the overlay.
  *
  * A Region that authored its own chrome paints over the Theme, and that is how an Area keeps a look of
  * its own. Authored means every carrier, not just one: the Region Surface's Background, the ground the
  * Shell record sets, and a glass pane the Region asks for over that ground. Reading only the
  * first let the Builder's Sider take the Site's overlay on top of the container ground it paints on
  * purpose, which is what this exists to prevent.
+ *
+ * A Background whose Base is `theme` states the overlay, so a Chrome Region takes it whatever the Shell
+ * record says. The caller asks this only for a Region without a tone: a toned one wants the overlay of
+ * its tone's mode, which it paints itself (`PHI_BACKGROUND_THEME_STYLE`).
  */
 export declare function phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, pane, grounds, }: {
     regionKey: string;
@@ -125,6 +130,12 @@ export declare function resolvePhiShellChromePaneStickyTop(bands: readonly PhiSh
  */
 export declare const PHI_SHELL_HEADER_TOP_EXTENT_PROPERTY = "--phi-shell-header-top-extent";
 export declare const PHI_SHELL_HEADER_TOP_STACK_PROPERTY = "--phi-shell-header-top-stack";
+/**
+ * The Header's measured bottom: the lowest bottom of every Header band stuck right now, written on the
+ * Shell by `usePhiShellStickyTop` (components/shell/use-phi-shell-sticky-top.ts). A sticky Table header
+ * and a stuck Sider stand under it; unset, it reads `0px`.
+ */
+export declare const PHI_SHELL_STICKY_TOP_PROPERTY = "--phi-shell-sticky-top";
 /**
  * How `header_top` behaves where the browser decides it, as far as the Header pane is concerned.
  */

package/components/root/phi-shell-chrome-overlay.js

@@ -76,17 +76,27 @@ const PHI_SHELL_CHROME_OVERLAY_REGION_KEYS = [
     "footer_bottom",
 ];
 /**
- * Whether this Region paints the shared overlay, which it does only while it authored nothing itself.
+ * Whether this Region paints the shared overlay, which it does while it authored nothing itself -- or
+ * while what it authored is the overlay.
  *
  * A Region that authored its own chrome paints over the Theme, and that is how an Area keeps a look of
  * its own. Authored means every carrier, not just one: the Region Surface's Background, the ground the
  * Shell record sets, and a glass pane the Region asks for over that ground. Reading only the
  * first let the Builder's Sider take the Site's overlay on top of the container ground it paints on
  * purpose, which is what this exists to prevent.
+ *
+ * A Background whose Base is `theme` states the overlay, so a Chrome Region takes it whatever the Shell
+ * record says. The caller asks this only for a Region without a tone: a toned one wants the overlay of
+ * its tone's mode, which it paints itself (`PHI_BACKGROUND_THEME_STYLE`).
  */
 export function phiRegionUsesShellChromeOverlay({ regionKey, backgroundConfig, pane, grounds, }) {
-    return (PHI_SHELL_CHROME_OVERLAY_REGION_KEYS.includes(regionKey) &&
-        backgroundConfig == null &&
+    if (!PHI_SHELL_CHROME_OVERLAY_REGION_KEYS.includes(regionKey)) {
+        return false;
+    }
+    if (backgroundConfig != null && normalizePhiBackgroundWidgetConfig(backgroundConfig).base.kind === "theme") {
+        return true;
+    }
+    return (backgroundConfig == null &&
         pane == null &&
         grounds.every((ground) => ground == null));
 }
@@ -223,6 +233,12 @@ export function resolvePhiShellChromePaneStickyTop(bands) {
  */
 export const PHI_SHELL_HEADER_TOP_EXTENT_PROPERTY = "--phi-shell-header-top-extent";
 export const PHI_SHELL_HEADER_TOP_STACK_PROPERTY = "--phi-shell-header-top-stack";
+/**
+ * The Header's measured bottom: the lowest bottom of every Header band stuck right now, written on the
+ * Shell by `usePhiShellStickyTop` (components/shell/use-phi-shell-sticky-top.ts). A sticky Table header
+ * and a stuck Sider stand under it; unset, it reads `0px`.
+ */
+export const PHI_SHELL_STICKY_TOP_PROPERTY = "--phi-shell-sticky-top";
 /**
  * Where the Header pane sticks when `header_top` may come and go.
  *

package/components/shell/phi-antd-icon.d.ts

@@ -17,6 +17,7 @@ declare const PHI_ANTD_ICON_LOADERS: {
     readonly CalendarOutlined: () => Promise<typeof import("@ant-design/icons-svg/es/asn/CalendarOutlined")>;
     readonly CheckOutlined: () => Promise<typeof import("@ant-design/icons-svg/es/asn/CheckOutlined")>;
     readonly CloseOutlined: () => Promise<typeof import("@ant-design/icons-svg/es/asn/CloseOutlined")>;
+    readonly CloudDownloadOutlined: () => Promise<typeof import("@ant-design/icons-svg/es/asn/CloudDownloadOutlined")>;
     readonly CloudUploadOutlined: () => Promise<typeof import("@ant-design/icons-svg/es/asn/CloudUploadOutlined")>;
     readonly ClusterOutlined: () => Promise<typeof import("@ant-design/icons-svg/es/asn/ClusterOutlined")>;
     readonly CodeOutlined: () => Promise<typeof import("@ant-design/icons-svg/es/asn/CodeOutlined")>;