@phis/ui 0.2.1 → 0.4.0

package/components/motion/use-phi-sequence-gestures.js

@@ -0,0 +1,59 @@
+"use client";
+import { useCallback, useRef } from "react";
+/*
+ * The two ways to move a sequence that are not a button: a swipe, and the arrow keys.
+ *
+ * A slideshow on a phone that only moves on its arrows is a foreign body, and one on a keyboard that
+ * only moves on Tab-Tab-Enter is slower than reading. Neither needs the viewport to know: both say
+ * "one step" to whoever owns the index.
+ */
+/** How far a finger has to travel sideways, and more sideways than up or down, to count as a swipe. */
+const PHI_SEQUENCE_SWIPE_THRESHOLD_PX = 40;
+/**
+ * Which way a swipe moves the sequence, or `null` where it was a tap, a scroll or too short.
+ *
+ * A finger going left pulls the next item in, so left is forward. Vertical travel that outweighs the
+ * sideways travel is the page scrolling, and is left to it.
+ */
+export function resolvePhiSwipeStep(deltaX, deltaY, threshold = PHI_SEQUENCE_SWIPE_THRESHOLD_PX) {
+    if (Math.abs(deltaX) < threshold || Math.abs(deltaX) <= Math.abs(deltaY))
+        return null;
+    return deltaX < 0 ? 1 : -1;
+}
+export function usePhiSequenceGestures({ step }) {
+    const origin = useRef(null);
+    const onPointerDown = useCallback((event) => {
+        // The primary button only: a right click or a second finger is not the start of a swipe.
+        if (!event.isPrimary || (event.pointerType === "mouse" && event.button !== 0))
+            return;
+        origin.current = { x: event.clientX, y: event.clientY };
+    }, []);
+    const onPointerUp = useCallback((event) => {
+        const start = origin.current;
+        origin.current = null;
+        if (!start)
+            return;
+        const direction = resolvePhiSwipeStep(event.clientX - start.x, event.clientY - start.y);
+        if (direction)
+            step(direction);
+    }, [step]);
+    const onPointerCancel = useCallback(() => {
+        origin.current = null;
+    }, []);
+    const onDragStart = useCallback((event) => {
+        event.preventDefault();
+    }, []);
+    const onKeyDown = useCallback((event) => {
+        // Only the keys that mean a step; a Tab or an Enter on a button is the button's.
+        if (event.key !== "ArrowLeft" && event.key !== "ArrowRight")
+            return;
+        if (event.defaultPrevented)
+            return;
+        event.preventDefault();
+        step(event.key === "ArrowRight" ? 1 : -1);
+    }, [step]);
+    return {
+        handlers: { onPointerDown, onPointerUp, onPointerCancel, onDragStart, onKeyDown },
+        style: { touchAction: "pan-y" },
+    };
+}

package/components/overlays/phi-dialog-body-context.d.ts

@@ -0,0 +1,5 @@
+import { type ReactNode } from "react";
+export declare function PhiDialogBodyProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function usePhiInDialogBody(): boolean;

package/components/overlays/phi-dialog-body-context.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+/*
+ * Whether what renders here stands in a dialog's body -- a Modal Overlay, not a Drawer.
+ *
+ * A dialog asks one question, so a key there has one meaning: Enter in a Form is what the footer's
+ * primary button does (FORMS.md, `submitOnEnter`). A page or a Drawer can hold several Forms and a
+ * search, which is why Enter stays off there unless a placement says otherwise.
+ */
+const PhiDialogBodyContext = createContext(false);
+export function PhiDialogBodyProvider({ children }) {
+    return _jsx(PhiDialogBodyContext.Provider, { value: true, children: children });
+}
+export function usePhiInDialogBody() {
+    return useContext(PhiDialogBodyContext);
+}

package/components/overlays/phi-overlay-container-client.js

@@ -1,21 +1,27 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { usePathname } from "next/navigation";
 import { shouldPhiCmsContentStayMounted } from "../../types/cms-mount-policy";
-import { parsePhiCmsOverlayConfig, } from "../../types/cms-overlay";
+import { parsePhiCmsOverlayConfig, resolvePhiCmsOverlayBehaviour, } from "../../types/cms-overlay";
 import { readPhiControlSize } from "../../types/control";
 import { readPhiDimensionValue } from "../../types/dimension";
-import { resolvePhiCmsContainerChromeStyle } from "../../helpers/cms-container-chrome";
+import { resolvePhiCmsContainerSurface } from "../../helpers/cms-container-chrome";
 import { PHI_SIGNAL_VALUE_SCHEMAS, createPhiSignalAddress, findPhiSignalRoutesByCapabilityId, } from "../../types/signals";
 import { readPhiTableActionSignalValue } from "../../types/table-signal-values";
 import { emitPhiSignalCapability, usePhiSignalEmitter, PhiSignalIdentityProvider, } from "../runtime/runtime-signal-identity";
 import { usePhiSignalListener } from "../runtime/runtime-signal-bus";
 import { registerPhiSignalInstance } from "../runtime/runtime-signal-registry";
 import { usePhiSignalRuntimePartition } from "../runtime/runtime-signal-partition";
+import { usePhiVisualAnchor } from "../runtime/runtime-visual-anchors";
 import { PhiModalControl } from "../controls/phi-modal-control";
 import { PhiDrawerControl } from "../controls/phi-drawer-control";
+import { PhiAlertControl } from "../controls/phi-alert-control";
 import { usePhiOverlayZonesLoaderIfAny } from "./phi-overlay-zones-loader";
+import { PhiDialogBodyProvider } from "./phi-dialog-body-context";
+import { usePhiPathname } from "../runtime/use-phi-pathname";
+function renderOverlayZonesFailure(failure) {
+    return (_jsx(PhiAlertControl, { level: "error", title: "This content could not be shown.", description: failure }));
+}
 /** Stands where the body will be while the zones are on their way, so the shell opens at once. */
 const PHI_OVERLAY_ZONES_PENDING = (_jsx("div", { "aria-busy": "true", style: { minBlockSize: "calc(var(--ant-control-height) * 3)" } }));
 /**
@@ -46,6 +52,7 @@ function matchesRoute(signal, route) {
 export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawConfig, signalScope, header, body, footer, deferredZones, }) {
     const configKey = JSON.stringify(rawConfig);
     const config = useMemo(() => parsePhiCmsOverlayConfig(JSON.parse(configKey), overlayType), [configKey, overlayType]);
+    const behaviour = useMemo(() => resolvePhiCmsOverlayBehaviour(config), [config]);
     const receiver = useMemo(() => createPhiSignalAddress("cms", overlayId), [overlayId]);
     const signalPartition = usePhiSignalRuntimePartition();
     const [open, setOpen] = useState(false);
@@ -64,8 +71,10 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
         : config.title;
     const emittedOpenRef = useRef(false);
     const openedAtPathname = useRef(null);
-    const pathname = usePathname() ?? "/";
+    const pathname = usePhiPathname();
     const emitSignal = usePhiSignalEmitter(receiver);
+    // The Overlay's panel, found by a Tour under the Overlay's own address while it is drawn.
+    const panelRef = usePhiVisualAnchor(receiver);
     const loadZones = usePhiOverlayZonesLoaderIfAny();
     const [loadedZones, setLoadedZones] = useState(null);
     const listenRoutes = useMemo(() => config.signalRoutes?.listens ?? [], [config.signalRoutes?.listens]);
@@ -94,6 +103,9 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
     const updateOpen = useCallback((nextOpen) => {
         if (nextOpen)
             setHasOpened(true);
+        // A failed load is forgotten on close, so the next open asks the server again.
+        if (!nextOpen)
+            setLoadedZones((current) => current && "failure" in current ? null : current);
         setOpen(nextOpen);
     }, []);
     /*
@@ -101,8 +113,8 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
      *
      * Kept per request and address: an Area Overlay outlives client navigations, and its zones were
      * rendered for the page under it -- a link target resolves against it -- so another address asks again
-     * the next time it opens. Asking fails into a closed Overlay and a logged error; the next open asks
-     * again rather than showing an empty shell.
+     * the next time it opens. Asking fails into the open shell, which shows the failure in its body; the
+     * next open asks again (`PhiFailedOverlayZones`).
      */
     const deferredZonesKey = deferredZones ? `${JSON.stringify(deferredZones)}@${pathname}` : null;
     useEffect(() => {
@@ -116,8 +128,12 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
             if (cancelled)
                 return;
             if (!zones) {
+                // The server answered, and the answer is that this viewer has no such Overlay to see here.
                 console.error(`Overlay ${overlayId} could not be rendered for this viewer.`);
-                updateOpen(false);
+                setLoadedZones({
+                    key: deferredZonesKey,
+                    failure: "It is not available to you on this page.",
+                });
                 return;
             }
             setLoadedZones({ key: deferredZonesKey, zones });
@@ -125,12 +141,15 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
             if (cancelled)
                 return;
             console.error(`Overlay ${overlayId} could not be loaded.`, error);
-            updateOpen(false);
+            setLoadedZones({
+                key: deferredZonesKey,
+                failure: error instanceof Error && error.message ? error.message : "The request failed.",
+            });
         });
         return () => {
             cancelled = true;
         };
-    }, [deferredZones, deferredZonesKey, loadZones, loadedZones?.key, open, overlayId, updateOpen]);
+    }, [deferredZones, deferredZonesKey, loadZones, loadedZones?.key, open, overlayId]);
     useEffect(() => {
         if (emittedOpenRef.current === open)
             return;
@@ -227,7 +246,9 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
     const zones = !deferredZones
         ? { header, body, footer }
         : loadedZones && loadedZones.key === deferredZonesKey
-            ? loadedZones.zones
+            ? "failure" in loadedZones
+                ? { header: null, body: renderOverlayZonesFailure(loadedZones.failure), footer: null }
+                : loadedZones.zones
             : open ? { header: null, body: PHI_OVERLAY_ZONES_PENDING, footer: null } : null;
     /*
      * The Controllers that came with the zones, mounted for as long as this Overlay is, open or not.
@@ -235,11 +256,15 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
      * Taken from the last load even after a navigation made its zones stale: the next open asks again and
      * the new answer takes their place, while a Controller in the middle of something keeps its state.
      */
-    const zoneControllers = loadedZones?.zones.controllers ?? null;
-    const containerChromeStyle = resolvePhiCmsContainerChromeStyle(config);
-    const surfaceStyle = { ...containerChromeStyle, padding: 0 };
+    const zoneControllers = loadedZones && "zones" in loadedZones ? loadedZones.zones.controllers : null;
+    /*
+     * The container draws its Surface through the Drawer or Modal primitive's own box, which has no layer
+     * beneath its content to give a softened paint: a `blur` Filter there paints unsoftened, the way every
+     * Surface without a ground layer does (LAYOUTING.md, "Background filter").
+     */
+    const surfaceStyle = { ...resolvePhiCmsContainerSurface(config).style, padding: 0 };
     if (overlayType === "drawer") {
-        return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiDrawerControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body), footer: renderZone(zones?.footer), closable: config.closable, keyboard: config.keyboard, mask: config.mask, mountPolicy: config.mountPolicy, placement: config.placement, size: config.size, maxSize: config.maxSize, resizable: config.resizable, push: config.push, containerStyle: surfaceStyle, onDismiss: requestClose })] }));
+        return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiDrawerControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, placement: config.placement, size: config.size, maxSize: config.maxSize, resizable: behaviour.resizable, push: behaviour.push, containerStyle: surfaceStyle, onDismiss: requestClose, panelRef: panelRef })] }));
     }
-    return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiModalControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body), footer: renderZone(zones?.footer), closable: config.closable, keyboard: config.keyboard, mask: config.mask, mountPolicy: config.mountPolicy, centered: config.centered, controlSize: runtimeControlSize ?? config.controlSize, size: runtimeSize, width: config.width, containerStyle: surfaceStyle, onDismiss: requestClose })] }));
+    return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiModalControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body == null ? null : _jsx(PhiDialogBodyProvider, { children: zones.body })), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, centered: behaviour.centered, controlSize: runtimeControlSize ?? config.controlSize, size: runtimeSize, width: config.width, containerStyle: surfaceStyle, onDismiss: requestClose, panelRef: panelRef })] }));
 }

package/components/regions/clients/cms-region-container-client.d.ts

@@ -2,6 +2,7 @@ import type { CSSProperties, ReactNode } from "react";
 import type { PhiCmsRegionConfig, PhiCmsRegionKey } from "../../../types";
 import type { PhiRenderableBlockRuntimeContext, PhiSignalScope } from "../../../types";
 import { type PhiCmsRegionShellTheme } from "../phi-cms-region-shell";
+import type { PhiCmsResolvedRegionPageScope } from "../../../types/cms-presets";
 type PhiCmsRegionContainerClientProps = {
     children: ReactNode;
     className?: string;
@@ -13,6 +14,10 @@ type PhiCmsRegionContainerClientProps = {
     previewMode?: boolean;
     runtime: Pick<PhiRenderableBlockRuntimeContext, "siteKey" | "publicUrl" | "defaultLang" | "area" | "pageKey">;
     routeScope: Extract<PhiSignalScope, "area" | "page">;
+    /** The Pages this Region stands on, as the server resolved them for this render. */
+    pageScope?: PhiCmsResolvedRegionPageScope | null;
+    /** The Site's locales, handed over only where the Region has a Page scope to ask. */
+    availableLocales?: string[];
 };
 /**
  * A Region that stays alive after it has rendered: it takes signals, runs effects, collapses, or moves
@@ -20,5 +25,5 @@ type PhiCmsRegionContainerClientProps = {
  * fed with the config merged with the live runtime state and painted in the live colour mode. What is
  * left here is what only a live Region has.
  */
-export declare function PhiCmsRegionContainerClient({ children, className, regionKey, config: initialConfig, shellTheme, style, regionType, previewMode, runtime, routeScope, }: PhiCmsRegionContainerClientProps): import("react").JSX.Element | null;
+export declare function PhiCmsRegionContainerClient({ children, className, regionKey, config: initialConfig, shellTheme, style, regionType, previewMode, runtime, routeScope, pageScope: resolvedPageScope, availableLocales, }: PhiCmsRegionContainerClientProps): import("react").JSX.Element | null;
 export {};

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

@@ -1,10 +1,12 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from "react";
+import { useCallback, useRef, useState } from "react";
 import { PhiButtonControl } from "../../controls/phi-button-control";
-import { MenuFoldOutlined, MenuUnfoldOutlined } from "@ant-design/icons";
-import {} from "../../widgets/config/background";
+import { PhiSurfaceGroundLayer } from "../../surface/phi-surface-ground";
+import { PhiSurfaceTone } from "../../surface/phi-surface-tone";
 import { resolvePhiShellRegionZIndex } from "../../../helpers/shell-region-style";
+import { hasPhiFlag } from "../../../helpers/flags";
+import { PhiCmsFlags } from "../../../constants/phi-cms";
 import { PhiBackgroundMotionLayer } from "../../cms/clients/phi-background-motion-layer-lazy";
 import { PhiIcon } from "../../shell/phi-icon";
 import { PhiSiderContextProvider } from "../presets/clients/sider-context";
@@ -16,15 +18,36 @@ import { PhiSlotChildEffectsVisibilityObserver } from "../../../plugins/runtime/
 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 { usePhiVisualAnchor } from "../../runtime/runtime-visual-anchors";
+import { usePhiPathname } from "../../runtime/use-phi-pathname";
+import { stripLocaleAndAreaFromPathname } from "../../../helpers/locale";
+import { phiCmsRegionPageScopeIncludes, readPhiCmsRegionReveal } from "../../../helpers/region-page-scope";
+import { usePhiRegionRevealed, usePhiShellHeaderTopRoom } from "./use-phi-region-reveal";
 /**
  * A Region that stays alive after it has rendered: it takes signals, runs effects, collapses, or moves
  * its Background. What it draws comes from the Region-shell resolver it shares with the static renderer,
  * fed with the config merged with the live runtime state and painted in the live colour mode. What is
  * left here is what only a live Region has.
  */
-export function PhiCmsRegionContainerClient({ children, className, regionKey, config: initialConfig, shellTheme, style, regionType, previewMode = false, runtime, routeScope, }) {
+export function PhiCmsRegionContainerClient({ children, className, regionKey, config: initialConfig, shellTheme, style, regionType, previewMode = false, runtime, routeScope, pageScope: resolvedPageScope = null, availableLocales, }) {
     const { mode: liveThemeMode, token } = usePhiConfig();
     const receiver = createPhiRenderableBlockReceiver("region", regionKey);
+    const anchorRef = usePhiVisualAnchor(receiver);
+    const elementRef = useRef(null);
+    const placeholderRef = useRef(null);
+    const setElementRef = useCallback((element) => {
+        elementRef.current = element;
+        anchorRef(element);
+    }, [anchorRef]);
+    /*
+     * The Page scope and the reveal (SHELL.md "Region visibility per Page"), both asked here because the
+     * Shell Layout is not rendered again when the visitor follows a link inside a dynamic Area.
+     */
+    const pathname = usePhiPathname();
+    const pageScope = previewMode ? null : resolvedPageScope;
+    const inScope = phiCmsRegionPageScopeIncludes(pageScope, pageScope == null ? "/" : stripLocaleAndAreaFromPathname(pathname, { availableLocales }));
+    const reveal = previewMode ? "always" : readPhiCmsRegionReveal(regionKey, initialConfig);
+    const revealed = usePhiRegionRevealed(reveal);
     const blockRuntime = usePhiRenderableBlockRuntime({
         blockId: null,
         receiver,
@@ -32,18 +55,13 @@ export function PhiCmsRegionContainerClient({ children, className, regionKey, co
         visibility: initialConfig?.visibility,
         enabled: initialConfig?.enabled,
         zIndex: initialConfig?.zIndex ??
-            resolvePhiShellRegionZIndex(regionKey, initialConfig?.fullHeight === true),
+            resolvePhiShellRegionZIndex(regionKey, hasPhiFlag(initialConfig?.flags, PhiCmsFlags.FullHeight)),
         opacity: initialConfig?.opacity,
         size: initialConfig?.size,
         minSize: initialConfig?.minSize,
         maxSize: initialConfig?.maxSize,
         collapsedSizeHint: initialConfig?.collapsedSizeHint,
-        background: initialConfig?.backgroundConfig ?? initialConfig?.background,
-        border: initialConfig?.border && typeof initialConfig.border !== "boolean"
-            ? initialConfig.border
-            : undefined,
-        effect: initialConfig?.effect,
-        shadow: initialConfig?.shadow,
+        surface: initialConfig?.surface ?? undefined,
         effects: initialConfig?.effects,
         runtime: {
             ...runtime,
@@ -52,11 +70,14 @@ export function PhiCmsRegionContainerClient({ children, className, regionKey, co
         },
     });
     const resolvedVisibility = blockRuntime.state.visibility ?? "visible";
-    const runtimeBackground = blockRuntime.state.background;
     const config = {
         ...(initialConfig ?? {}),
         visibility: resolvedVisibility,
-        viewportFlags: blockRuntime.state.viewportFlags,
+        /*
+         * The stored widths unless a Signal has said otherwise. The block runtime does not carry them, so
+         * taking its answer alone dropped them for every Region that renders here.
+         */
+        viewportFlags: blockRuntime.state.viewportFlags ?? initialConfig?.viewportFlags,
         enabled: blockRuntime.state.enabled ?? true,
         size: resolvedVisibility === "collapsed"
             ? blockRuntime.state.collapsedSizeHint ?? blockRuntime.state.size
@@ -67,17 +88,25 @@ export function PhiCmsRegionContainerClient({ children, className, regionKey, co
         zIndex: blockRuntime.state.zIndex,
         opacity: blockRuntime.state.opacity,
         effects: blockRuntime.state.effects,
-        background: typeof runtimeBackground === "string"
-            ? runtimeBackground
-            : initialConfig?.background,
-        backgroundConfig: runtimeBackground && typeof runtimeBackground === "object" && !Array.isArray(runtimeBackground)
-            ? runtimeBackground
-            : null,
-        border: (blockRuntime.state.border ?? initialConfig?.border),
-        shadow: blockRuntime.state.shadow ?? initialConfig?.shadow,
-        effect: blockRuntime.state.effect ?? initialConfig?.effect,
+        // The Surface as it stands now: the stored one with whatever Signals have set for its parts.
+        surface: blockRuntime.state.surface ?? null,
     };
     const [collapsed, setCollapsed] = useState(false);
+    usePhiShellHeaderTopRoom({
+        active: regionKey === "header_top" && (pageScope != null || reveal !== "always"),
+        present: inScope && resolvedVisibility !== "hidden",
+        reveal,
+        revealed,
+        elementRef,
+        placeholderRef,
+    });
+    /*
+     * 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.
+     */
+    if (!inScope) {
+        return _jsx("span", { ref: placeholderRef, hidden: true, "data-phi-region-key": regionKey, "data-phi-region-out-of-scope": "true" });
+    }
     const shell = resolvePhiCmsRegionShell({
         regionKey,
         config,
@@ -107,25 +136,34 @@ export function PhiCmsRegionContainerClient({ children, className, regionKey, co
     const attributes = {
         ...shell.attributes,
         "data-phi-effects-state": blockRuntime.state.effectsState ?? shell.attributes["data-phi-effects-state"],
+        "data-phi-region-revealed": revealed == null || reveal === "always" ? undefined : String(revealed),
     };
+    /*
+     * The strip along the top edge a `hover` band is found by. It hangs below the band, so while the band
+     * is away it lies along the top of the viewport, and the pointer on it is the pointer on the band.
+     */
+    const revealZone = reveal === "hover"
+        ? _jsx("span", { "aria-hidden": true, className: "phi-cms-region-reveal-zone" })
+        : null;
     const backgroundMotionLayer = shell.animatesBackground && shell.backgroundConfig != null
         ? _jsx(PhiBackgroundMotionLayer, { config: shell.backgroundConfig })
-        : null;
+        : _jsx(PhiSurfaceGroundLayer, { ground: shell.ground });
     const effectObservers = (_jsxs(_Fragment, { children: [effectsTrigger === "on_visible" ? (_jsx(PhiSlotChildEffectsVisibilityObserver, { once: shell.attributes["data-phi-effects-once"] !== "false" })) : null, effectsTrigger === "on_ready" ? _jsx(PhiEffectsReadyTrigger, {}) : null, viewportEffects.length > 0 ? (_jsx(PhiSlotChildViewportEffectsObserver, { effects: viewportEffects })) : null] }));
+    const withTone = (element) => shell.tone ? _jsx(PhiSurfaceTone, { tone: shell.tone, children: element }) : element;
     if (shell.family !== "sider") {
         const Element = shell.element;
-        return (_jsxs(Element, { ...attributes, style: shell.style, children: [backgroundMotionLayer, _jsx("div", { className: "phi-cms-region-shell__content", style: shell.contentStyle, children: children }), effectObservers] }));
+        return withTone(_jsxs(Element, { ...attributes, ref: setElementRef, style: shell.style, children: [backgroundMotionLayer, _jsx("div", { className: "phi-cms-region-shell__content", style: shell.contentStyle, children: children }), revealZone, effectObservers] }));
     }
     const isRightSider = regionKey === "sider_right";
-    const collapsible = config.collapsible === true;
-    const isFullHeight = config.fullHeight === true;
+    const collapsible = hasPhiFlag(config.flags, PhiCmsFlags.Collapsible);
+    const isFullHeight = hasPhiFlag(config.flags, PhiCmsFlags.FullHeight);
     const isCollapsed = collapsible && collapsed;
     const collapsedWidth = shell.siderCollapsedWidth;
     const collapseIcon = typeof config.collapseIcon === "string" ? config.collapseIcon : undefined;
     const contentTransform = isCollapsed
         ? `translate3d(${isRightSider ? "6px" : "-6px"}, 0, 0) scale(0.995)`
         : "translate3d(0, 0, 0) scale(1)";
-    return (_jsxs("aside", { ...attributes, "data-phi-sider-collapsed": isCollapsed ? "true" : undefined, style: {
+    return withTone(_jsxs("aside", { ...attributes, ref: setElementRef, "data-phi-sider-collapsed": isCollapsed ? "true" : undefined, style: {
             transition: "width 180ms ease, min-width 180ms ease, max-width 180ms ease, flex-basis 180ms ease",
             ...shell.style,
             /*
@@ -153,7 +191,7 @@ export function PhiCmsRegionContainerClient({ children, className, regionKey, co
                                 paddingBottom: 0,
                                 borderBottom: shell.borderLine,
                                 zIndex: 1,
-                            }, children: _jsx(PhiButtonControl, { type: "text", ariaLabel: collapsed ? "Expand sidebar" : "Collapse sidebar", icon: collapseIcon ? (_jsx(PhiIcon, { name: collapseIcon })) : isRightSider ? (collapsed ? _jsx(MenuFoldOutlined, {}) : _jsx(MenuUnfoldOutlined, {})) : collapsed ? (_jsx(MenuUnfoldOutlined, {})) : (_jsx(MenuFoldOutlined, {})), style: {
+                            }, children: _jsx(PhiButtonControl, { type: "text", ariaLabel: collapsed ? "Expand sidebar" : "Collapse sidebar", icon: collapseIcon ? (_jsx(PhiIcon, { name: collapseIcon })) : isRightSider ? (collapsed ? _jsx(PhiIcon, { name: "menu-fold", size: "inherit" }) : _jsx(PhiIcon, { name: "menu-unfold", size: "inherit" })) : collapsed ? (_jsx(PhiIcon, { name: "menu-unfold", size: "inherit" })) : (_jsx(PhiIcon, { name: "menu-fold", size: "inherit" })), style: {
                                     minWidth: collapsedWidth,
                                     height: collapsedWidth,
                                     paddingInline: 0,

package/components/regions/clients/use-phi-region-reveal.d.ts

@@ -0,0 +1,28 @@
+import { type RefObject } from "react";
+import type { PhiCmsRegionReveal } from "../../../types/cms-presets";
+/**
+ * Whether the scroll position has the band in view, or `null` where the pointer decides instead.
+ *
+ * `scroll-up` follows the page: in view at the top, away while the visitor reads down, back the moment
+ * they scroll up. `hover` is the pointer's, and CSS answers it (`shell.css`); a device that has no
+ * hover gets the scroll rule, because a band that waits for a pointer it will never see is a band
+ * nobody reaches.
+ */
+export declare function usePhiRegionRevealed(reveal: PhiCmsRegionReveal): boolean | null;
+/**
+ * What `header_top` tells the Shell about the room it takes, while the browser decides it.
+ *
+ * The Header pane and the sticky bands below are its siblings, so it publishes on the Shell element
+ * they share (SHELL.md "Region visibility per Page"): `extent` is the height its track holds, `stack`
+ * the part of the viewport's top a `scroll-up` band holds right now. The server writes both for the
+ * first Page; this keeps them true after every link and every scroll. A band that is gone leaves zeros
+ * behind, never nothing, because nothing would fall back to the server's first answer.
+ */
+export declare function usePhiShellHeaderTopRoom({ active, present, reveal, revealed, elementRef, placeholderRef, }: {
+    active: boolean;
+    present: boolean;
+    reveal: PhiCmsRegionReveal;
+    revealed: boolean | null;
+    elementRef: RefObject<HTMLElement | null>;
+    placeholderRef: RefObject<HTMLElement | null>;
+}): void;

package/components/regions/clients/use-phi-region-reveal.js

@@ -0,0 +1,104 @@
+"use client";
+import { useEffect, useLayoutEffect, useState, useSyncExternalStore } from "react";
+import { PHI_SHELL_HEADER_TOP_EXTENT_PROPERTY, PHI_SHELL_HEADER_TOP_STACK_PROPERTY, } from "../../root/phi-shell-chrome-overlay";
+/** How far the page has to move before its direction counts, so a trembling wheel does not flicker. */
+const PHI_REGION_REVEAL_SCROLL_SLACK = 4;
+const PHI_NO_HOVER_QUERY = "(hover: none)";
+function subscribePhiNoHover(onChange) {
+    const query = window.matchMedia(PHI_NO_HOVER_QUERY);
+    query.addEventListener("change", onChange);
+    return () => query.removeEventListener("change", onChange);
+}
+function readPhiNoHover() {
+    return window.matchMedia(PHI_NO_HOVER_QUERY).matches;
+}
+/**
+ * Whether the scroll position has the band in view, or `null` where the pointer decides instead.
+ *
+ * `scroll-up` follows the page: in view at the top, away while the visitor reads down, back the moment
+ * they scroll up. `hover` is the pointer's, and CSS answers it (`shell.css`); a device that has no
+ * hover gets the scroll rule, because a band that waits for a pointer it will never see is a band
+ * nobody reaches.
+ */
+export function usePhiRegionRevealed(reveal) {
+    const [revealed, setRevealed] = useState(true);
+    const noHover = useSyncExternalStore(subscribePhiNoHover, readPhiNoHover, () => false);
+    const followsScroll = reveal === "scroll-up" || (reveal === "hover" && noHover);
+    useEffect(() => {
+        if (!followsScroll) {
+            return undefined;
+        }
+        let last = window.scrollY;
+        let frame = 0;
+        const read = () => {
+            frame = 0;
+            const current = window.scrollY;
+            if (current <= 0) {
+                setRevealed(true);
+            }
+            else if (current > last + PHI_REGION_REVEAL_SCROLL_SLACK) {
+                setRevealed(false);
+            }
+            else if (current < last - PHI_REGION_REVEAL_SCROLL_SLACK) {
+                setRevealed(true);
+            }
+            else {
+                return;
+            }
+            last = current;
+        };
+        const onScroll = () => {
+            if (frame === 0) {
+                frame = window.requestAnimationFrame(read);
+            }
+        };
+        window.addEventListener("scroll", onScroll, { passive: true });
+        return () => {
+            window.removeEventListener("scroll", onScroll);
+            if (frame !== 0) {
+                window.cancelAnimationFrame(frame);
+            }
+        };
+    }, [followsScroll]);
+    if (reveal === "always") {
+        return true;
+    }
+    return followsScroll ? revealed : null;
+}
+/**
+ * What `header_top` tells the Shell about the room it takes, while the browser decides it.
+ *
+ * The Header pane and the sticky bands below are its siblings, so it publishes on the Shell element
+ * they share (SHELL.md "Region visibility per Page"): `extent` is the height its track holds, `stack`
+ * the part of the viewport's top a `scroll-up` band holds right now. The server writes both for the
+ * first Page; this keeps them true after every link and every scroll. A band that is gone leaves zeros
+ * behind, never nothing, because nothing would fall back to the server's first answer.
+ */
+export function usePhiShellHeaderTopRoom({ active, present, reveal, revealed, elementRef, placeholderRef, }) {
+    useLayoutEffect(() => {
+        if (!active) {
+            return undefined;
+        }
+        const element = elementRef.current;
+        const shell = (element ?? placeholderRef.current)?.closest("[data-phi-shell-layout]");
+        if (!shell) {
+            return undefined;
+        }
+        const publish = () => {
+            const extent = present && element && reveal !== "hover" ? element.offsetHeight : 0;
+            element?.style.setProperty("--phi-region-reveal-extent", `${element.offsetHeight}px`);
+            shell.style.setProperty(PHI_SHELL_HEADER_TOP_EXTENT_PROPERTY, `${extent}px`);
+            shell.style.setProperty(PHI_SHELL_HEADER_TOP_STACK_PROPERTY, `${reveal === "scroll-up" && revealed !== false ? extent : 0}px`);
+        };
+        publish();
+        const observer = present && element ? new ResizeObserver(publish) : null;
+        if (observer && element) {
+            observer.observe(element);
+        }
+        return () => {
+            observer?.disconnect();
+            shell.style.setProperty(PHI_SHELL_HEADER_TOP_EXTENT_PROPERTY, "0px");
+            shell.style.setProperty(PHI_SHELL_HEADER_TOP_STACK_PROPERTY, "0px");
+        };
+    }, [active, present, reveal, revealed, elementRef, placeholderRef]);
+}

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

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { PhiBlockRuntime, PhiCmsRegionConfig, PhiCmsRegionKey } from "../../types";
+import type { PhiCmsResolvedRegionPageScope } from "../../types/cms-presets";
 type PhiRuntimeShellTheme = NonNullable<NonNullable<PhiBlockRuntime["site"]["theme"]>["shell"]>;
 export type PhiCmsRegionContainerProps = {
     children: ReactNode;
@@ -12,6 +13,8 @@ export type PhiCmsRegionContainerProps = {
     previewMode?: boolean;
     runtime: Pick<PhiBlockRuntime, "site" | "locale" | "area" | "page">;
     signalParticipant?: boolean;
+    /** The Pages this Region stands on, resolved for this render; null where it stands on every Page. */
+    pageScope?: PhiCmsResolvedRegionPageScope | null;
 };
-export declare function PhiCmsRegionContainer({ children, className, regionKey, config, shellTheme, style, regionType, previewMode, runtime, signalParticipant, }: PhiCmsRegionContainerProps): import("react").JSX.Element;
+export declare function PhiCmsRegionContainer({ children, className, regionKey, config, shellTheme, style, regionType, previewMode, runtime, signalParticipant, pageScope, }: PhiCmsRegionContainerProps): import("react").JSX.Element;
 export {};

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

@@ -1,11 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 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 { resolveRenderableBlockEffectsAttributes, resolveRenderableBlockViewportEffects, } from "../../helpers/renderable-block-effects";
 import { PhiRuntimeModuleRenderClientHost } from "../runtime/runtime-module-render-client-manifest";
 import { PhiRuntimeRenderClientType } from "../../constants/runtime-render-client-types";
 import { resolvePhiBackgroundMotion } from "../widgets/config/background";
-export function PhiCmsRegionContainer({ children, className, regionKey, config, shellTheme, style, regionType, previewMode = false, runtime, signalParticipant = false, }) {
+import { readPhiCmsRegionReveal } from "../../helpers/region-page-scope";
+export function PhiCmsRegionContainer({ children, className, regionKey, config, shellTheme, style, regionType, previewMode = false, runtime, signalParticipant = false, pageScope = null, }) {
     const routeScope = isPhiCmsPageOwnedRegion(regionKey) ? "page" : "area";
     const effectsConfig = config?.effects == null ? undefined : { effects: config.effects };
     const effectsAttributes = resolveRenderableBlockEffectsAttributes(effectsConfig);
@@ -13,10 +16,14 @@ export function PhiCmsRegionContainer({ children, className, regionKey, config,
     const requiresEffectsObserver = effectsTrigger === "on_visible" ||
         effectsTrigger === "on_ready" ||
         resolveRenderableBlockViewportEffects(effectsConfig).length > 0;
+    // Which Page the visitor is on is a question only the browser can answer after a link was followed.
+    const pageScoped = !previewMode && pageScope != null;
     const requiresClientEnhancement = signalParticipant ||
-        config?.collapsible === true ||
+        pageScoped ||
+        (!previewMode && readPhiCmsRegionReveal(regionKey, config) !== "always") ||
+        hasPhiFlag(config?.flags, PhiCmsFlags.Collapsible) ||
         requiresEffectsObserver ||
-        resolvePhiBackgroundMotion(config?.backgroundConfig) != null;
+        resolvePhiBackgroundMotion(config?.surface?.background) != null;
     if (!requiresClientEnhancement) {
         return (_jsx(PhiCmsRegionStatic, { className: className, regionKey: regionKey, config: config, shellTheme: shellTheme, style: style, regionType: regionType, previewMode: previewMode, children: children }));
     }
@@ -37,5 +44,8 @@ export function PhiCmsRegionContainer({ children, className, regionKey, config,
                 pageKey: runtime.page?.path ?? null,
             },
             routeScope,
+            pageScope: pageScoped ? pageScope : null,
+            // The prefixes the browser strips before it asks the Page scope, which are the Site's locales.
+            availableLocales: pageScoped ? runtime.site.availableLocales.map((option) => option.code) : undefined,
         } }));
 }