@phis/ui 0.2.0 → 0.3.0

package/components/forms/upload-form-control.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { PhiMediaKind } from "../../constants/media";
 import { PhiButtonControl } from "../controls/phi-button-control";
 import { PhiFileDropControl } from "../controls/phi-file-drop-control";
@@ -8,10 +8,13 @@ import { PhiFlexControl } from "../controls/phi-flex-control";
 import { PhiProgressControl } from "../controls/phi-progress-control";
 import { PhiTagControl } from "../controls/phi-tag-control";
 import { PhiTypographyControl } from "../controls/phi-typography-control";
+import { PhiIcon } from "../shell/phi-icon";
 import { PHI_MEDIA_UPLOAD_DEFAULT_LABELS, usePhiMediaUpload, } from "../media/phi-media-upload";
 import { PHI_FORM_UPLOAD_LABEL_KEYS } from "./form-provider-contract";
 const DEFAULT_TRIGGER_LABEL = "Choose a file";
+const DEFAULT_DROP_HINT_LABEL = "or drop it here";
 const DEFAULT_TOO_MANY_LABEL = "No more files fit here.";
+const DEFAULT_PENDING_LABEL = "Wait until the file has arrived.";
 const MEDIA_KINDS = new Set(Object.values(PhiMediaKind));
 /**
  * What the Form value is: the Media Asset ids the finished uploads left behind.
@@ -43,7 +46,13 @@ function readUploadSettings(config) {
         ? Math.trunc(config.maxBytes)
         : undefined;
     const space = typeof config?.space === "string" && config.space.trim() ? config.space.trim() : null;
-    return { kinds: declaredKinds.length === 0 ? undefined : declaredKinds, maxFiles, maxBytes, space };
+    return {
+        kinds: declaredKinds.length === 0 ? undefined : declaredKinds,
+        maxFiles,
+        maxBytes,
+        space,
+        area: config?.presentation === "area",
+    };
 }
 function resolveUploadLabels(labels) {
     const read = (key, fallback) => labels?.[key]?.trim() || fallback;
@@ -69,6 +78,11 @@ function resolveUploadLabels(labels) {
  * Emptiness is `undefined` rather than `[]`. Ant Design's required rule accepts an empty array, so a
  * Form asking for a mandatory attachment would submit without one.
  *
+ * While a file is on its way the Form's submit is held (`formContext.holdSubmit`): the Asset id only
+ * enters the value once the upload settled, so a submit in between would send the Form without the
+ * attachment somebody can see arriving -- and the id would land in the next draft after the reset.
+ * Leaving the Form stops the upload, so no Asset is finalized that the Form never names.
+ *
  * The file name comes from the upload that is still in this Control's hands. An id that arrived as an
  * initial value has no name here, and inventing one would mean reading the Media Asset -- a second
  * contract inside a field provider, which is not this Control's to open.
@@ -92,7 +106,7 @@ export function PhiUploadFormControl({ field, value, onChange, placeholder, labe
     const commit = (next) => onChange?.(next.length === 0 ? undefined : [...next]);
     const acceptance = useMemo(() => ({ kinds: settings.kinds, maxBytes: settings.maxBytes, multiple: settings.maxFiles !== 1 }), [settings]);
     const initOptions = useMemo(() => ({ spaceAddress: settings.space }), [settings]);
-    const { accept, items, upload } = usePhiMediaUpload({
+    const { accept, items, uploading, upload } = usePhiMediaUpload({
         labels: uploadLabels,
         acceptance,
         initOptions,
@@ -102,12 +116,20 @@ export function PhiUploadFormControl({ field, value, onChange, placeholder, labe
         },
         onRejected: (message) => setRefusal(message),
     });
+    const pendingLabel = labels?.[PHI_FORM_UPLOAD_LABEL_KEYS.pending]?.trim() || DEFAULT_PENDING_LABEL;
+    const triggerLabel = placeholder?.trim() || labels?.[PHI_FORM_UPLOAD_LABEL_KEYS.trigger]?.trim() || DEFAULT_TRIGGER_LABEL;
+    useEffect(() => {
+        if (!formContext || !uploading)
+            return;
+        formContext.holdSubmit(field.key, pendingLabel);
+        return () => formContext.holdSubmit(field.key, null);
+    }, [field.key, formContext, pendingLabel, uploading]);
     const nameByAssetId = new Map(items
         .filter((item) => item.assetId != null)
         .map((item) => [item.assetId, item.file.name]));
     const transferring = items.filter((item) => item.status === "uploading");
     const full = settings.maxFiles != null && assetIds.length >= settings.maxFiles;
-    return (_jsxs(PhiFlexControl, { vertical: true, gap: "small", children: [assetIds.length === 0 ? null : (_jsx(PhiFlexControl, { wrap: true, gap: "small", children: assetIds.map((assetId) => (_jsx(PhiTagControl, { closable: !disabled && !readOnly, onClose: () => commit(readAssetIdsNow().filter((entry) => entry !== assetId)), children: nameByAssetId.get(assetId) ?? `#${assetId}` }, assetId))) })), transferring.map((item) => (_jsx(PhiProgressControl, { percent: Math.round(item.progress), size: "small" }, item.localId))), readOnly ? null : (_jsx(PhiFileDropControl, { accept: accept, multiple: settings.maxFiles !== 1, disabled: disabled || full, onFile: (file) => {
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: "small", children: [assetIds.length === 0 ? null : (_jsx(PhiFlexControl, { wrap: true, gap: "small", children: assetIds.map((assetId) => (_jsx(PhiTagControl, { closable: !disabled && !readOnly, onClose: () => commit(readAssetIdsNow().filter((entry) => entry !== assetId)), children: nameByAssetId.get(assetId) ?? `#${assetId}` }, assetId))) })), transferring.map((item) => (_jsx(PhiProgressControl, { percent: Math.round(item.progress), size: "small" }, item.localId))), readOnly ? null : (_jsx(PhiFileDropControl, { dropZone: settings.area, accept: accept, multiple: settings.maxFiles !== 1, disabled: disabled || full, onFile: (file) => {
                     /*
                      * Counted rather than read off the items, because a multiple selection arrives file by file
                      * within one tick and no state has moved yet when the second one is offered.
@@ -120,7 +142,5 @@ export function PhiUploadFormControl({ field, value, onChange, placeholder, labe
                     void upload(file).finally(() => {
                         inFlight.current -= 1;
                     });
-                }, children: _jsx(PhiButtonControl, { label: placeholder?.trim()
-                        || labels?.[PHI_FORM_UPLOAD_LABEL_KEYS.trigger]?.trim()
-                        || DEFAULT_TRIGGER_LABEL, disabled: disabled || full, onClick: () => { } }) })), refusal ? _jsx(PhiTypographyControl, { type: "danger", children: refusal }) : null] }));
+                }, children: settings.area ? (_jsxs(PhiFlexControl, { vertical: true, align: "center", gap: 4, style: { width: "100%", paddingBlock: 8 }, children: [_jsx(PhiIcon, { name: "upload", size: 20 }), _jsx(PhiTypographyControl, { children: triggerLabel }), _jsx(PhiTypographyControl, { type: "secondary", children: labels?.[PHI_FORM_UPLOAD_LABEL_KEYS.dropHint]?.trim() || DEFAULT_DROP_HINT_LABEL })] })) : (_jsx(PhiButtonControl, { label: triggerLabel, disabled: disabled || full, onClick: () => { } })) })), refusal ? _jsx(PhiTypographyControl, { type: "danger", children: refusal }) : null] }));
 }

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

@@ -1,7 +1,5 @@
-import type { CSSProperties, ReactNode } from "react";
 import type { PhiMotionEasing, PhiSequenceAnchor, PhiSequenceTransition } from "../../../helpers/motion";
-import { type PhiBaseLayoutProps } from "../phi-layout-view-model";
-import type { PhiAnchorWidgetPlacement } from "../../controls/phi-anchor-control-contract";
+import { type PhiSequenceLayoutProps } from "./use-phi-sequence-layout";
 /**
  * A Stack with a wider window.
  *
@@ -23,17 +21,7 @@ import type { PhiAnchorWidgetPlacement } from "../../controls/phi-anchor-control
  * back. It is fixed to `lazy-keep`: nothing mounts before it is first needed, nothing unmounts until
  * the page goes.
  */
-export type PhiCarouselLayoutSlotMeta = {
-    key: string;
-    label: string;
-    slotIndex: number;
-    hasContent?: boolean;
-};
-export type PhiCarouselLayoutProps = Omit<PhiBaseLayoutProps, "slots"> & {
-    slots: ReactNode[];
-    slotKeys: string[];
-    slotMeta?: PhiCarouselLayoutSlotMeta[];
-    defaultActiveSlotKey?: string;
+export type PhiCarouselLayoutProps = PhiSequenceLayoutProps & {
     visibleSlots?: number;
     windowAnchor?: PhiSequenceAnchor;
     transition?: PhiSequenceTransition;
@@ -52,12 +40,12 @@ export type PhiCarouselLayoutProps = Omit<PhiBaseLayoutProps, "slots"> & {
     controlLabels?: {
         previous?: string;
         next?: string;
+        pause?: string;
+        play?: string;
+        region?: string;
     };
     /** Absent or zero means it does not move on its own. */
     autoplayMs?: number;
     lookahead?: number;
-    slotAnchor?: PhiAnchorWidgetPlacement | null;
-    editSlotAnchor?: PhiAnchorWidgetPlacement | null;
-    style?: CSSProperties;
 };
 export declare function PhiCarouselLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey, visibleSlots, windowAnchor, transition, transitionDurationMs, transitionEasing, slotGap, loop, controls, controlLabels, autoplayMs, lookahead, slotAnchor, ...layoutProps }: PhiCarouselLayoutProps): import("react").JSX.Element;

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

@@ -1,38 +1,29 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { LeftOutlined, RightOutlined } from "@ant-design/icons";
-import { theme } from "antd";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { usePhiConfig } from "../../root/phi-config-provider";
+import { useCallback, useMemo } from "react";
 import { PhiButtonControl } from "../../controls/phi-button-control";
 import { PhiSequenceViewport } from "../../motion/phi-sequence-viewport";
+import { usePhiSequenceAutoplay } from "../../motion/use-phi-sequence-autoplay";
+import { usePhiSequenceGestures } from "../../motion/use-phi-sequence-gestures";
 import { resolvePhiLayoutInset } from "../phi-layout-contract";
-import { resolvePhiBaseLayoutChrome, } from "../phi-layout-view-model";
+import { resolvePhiBaseLayoutChrome } from "../phi-layout-view-model";
 import { isRenderablePhiNode } from "../phi-layout-scaffold-utils";
+import { PhiLayoutSurfaceBox } from "../phi-layout-surface-box";
 import { PhiLayoutAnchoredOverlay } from "./phi-layout-anchored-overlay";
 import { PhiSequenceSlotEditor } from "./phi-sequence-slot-editor";
-import { resolvePhiSequenceEditableSlotCount, usePhiSlotSequence } from "../use-phi-slot-sequence";
+import { usePhiSequenceLayout } from "./use-phi-sequence-layout";
 import { resolvePhiCarouselCurrentPage, resolvePhiCarouselPageStarts, resolvePhiCarouselStep, } from "../phi-carousel-pages";
+import { PhiIcon } from "../../shell/phi-icon";
 export function PhiCarouselLayout({ slots, slotKeys, slotMeta, defaultActiveSlotKey, visibleSlots = 1, windowAnchor = "start", transition = "slide", transitionDurationMs, transitionEasing, slotGap = 0, loop = false, controls = "arrows", controlLabels, autoplayMs = 0, lookahead = 1, slotAnchor = "center", ...layoutProps }) {
-    // Named fields rather than the rest object: handing the compiler a whole rest object makes every
-    // value later destructured out of it look like it may change, which costs the component its memoization.
-    const authoring = {
-        editSlotAction: layoutProps.editSlotAction,
-        editSlotLabels: layoutProps.editSlotLabels,
-        capabilities: layoutProps.capabilities,
-    };
-    const { blockId, renderMode, style, layoutKind = "carousel", padding, paddingTop, paddingRight, paddingBottom, paddingLeft, background, backgroundLayer, borderSource, border, borderRadius, effect, shadow, editSlotAction, editRenderInsertControl, editSlotAnchor = "center", } = layoutProps;
-    const isEditMode = renderMode === "editor";
-    const editableSlotCount = resolvePhiSequenceEditableSlotCount(slots, slotKeys);
-    const { token } = theme.useToken();
-    const { activeIndex, slotMeta: resolvedSlotMeta, setActiveIndex, } = usePhiSlotSequence({
-        blockId,
+    const { token } = usePhiConfig();
+    const { blockId, layoutKind, style, isEditMode, storedChrome, activeIndex, setActiveIndex, slotMeta: resolvedSlotMeta, editor, } = usePhiSequenceLayout({
         slots,
         slotKeys,
-        // While authoring, the sequence reaches one slot past the last filled one -- the empty slot the
-        // next child goes into. A page has no such slot and steps through what it holds.
-        ...(isEditMode ? { slotCount: editableSlotCount } : {}),
-        ...(slotMeta ? { slotLabels: slotMeta } : {}),
-        ...(defaultActiveSlotKey === undefined ? {} : { defaultActiveSlotKey }),
+        slotMeta,
+        defaultActiveSlotKey,
+        defaultLayoutKind: "carousel",
+        layoutProps,
     });
     /*
      * The filled slots, in order, and the slot index each of them came from.
@@ -60,43 +51,23 @@ export function PhiCarouselLayout({ slots, slotKeys, slotMeta, defaultActiveSlot
     }, [setActiveIndex, track]);
     const step = useCallback((direction) => stepTo(resolvePhiCarouselStep(pageStarts, trackIndex, direction, loop)), [loop, pageStarts, stepTo, trackIndex]);
     const advance = useCallback(() => step(1), [step]);
-    /*
-     * Movement nobody asked for, and the two ways to decline it.
-     *
-     * Reduced motion means it never starts -- read in an effect rather than during render, so the
-     * server's markup and the browser's first pass agree. Pointing at it or tabbing into it pauses it:
-     * a slide that moves out from under the cursor is the reason carousels have a bad name.
-     */
-    const [paused, setPaused] = useState(false);
-    const reducedMotion = useRef(false);
-    useEffect(() => {
-        reducedMotion.current = typeof window.matchMedia === "function" &&
-            window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-    }, []);
-    useEffect(() => {
-        if (isEditMode || autoplayMs <= 0 || paused || track.length <= span || reducedMotion.current) {
-            return undefined;
-        }
-        const timer = window.setInterval(advance, autoplayMs);
-        return () => window.clearInterval(timer);
-    }, [advance, autoplayMs, isEditMode, paused, span, track.length]);
-    const chrome = {
-        padding,
-        paddingTop,
-        paddingRight,
-        paddingBottom,
-        paddingLeft,
-        background,
-        borderSource,
-        border,
-        borderRadius,
-        effect,
-        shadow,
-    };
+    // Movement nobody asked for, and every way to decline it, shared with the Gallery (`components/motion`).
+    const autoplay = usePhiSequenceAutoplay({
+        intervalMs: autoplayMs,
+        active: !isEditMode && track.length > span,
+        advance,
+    });
+    // A step somebody took: the next automatic one is a whole interval away again.
+    const stepByHand = useCallback((direction) => {
+        step(direction);
+        autoplay.restart();
+    }, [autoplay, step]);
+    const gestures = usePhiSequenceGestures({ step: stepByHand });
     if (isEditMode) {
-        return (_jsx(PhiSequenceSlotEditor, { slots: slots, slotKeys: slotKeys, slotLabels: resolvedSlotMeta, slotCount: editableSlotCount, activeIndex: activeIndex, onActiveIndexChange: setActiveIndex, slotNoun: "carousel slot", layoutKind: layoutKind, renderMode: renderMode, authoring: authoring, chrome: chrome, backgroundLayer: backgroundLayer, editSlotAction: editSlotAction, editRenderInsertControl: editRenderInsertControl, editSlotAnchor: editSlotAnchor, style: style }));
+        return _jsx(PhiSequenceSlotEditor, { ...editor, slotNoun: "carousel slot" });
     }
-    const resolvedLayoutInset = resolvePhiLayoutInset(chrome);
+    const resolvedLayoutInset = resolvePhiLayoutInset(storedChrome);
+    const resolvedChrome = resolvePhiBaseLayoutChrome(storedChrome);
     /*
      * One dot per window, not per slot: with a wide window the slots move a window at a time, so a dot
      * per slot would offer positions the Carousel never stops at. Each is named after the first slot it
@@ -114,7 +85,7 @@ export function PhiCarouselLayout({ slots, slotKeys, slotMeta, defaultActiveSlot
     const showDots = (controls === "dots" || controls === "both") && pageCount > 1;
     const atStart = trackIndex <= 0;
     const atEnd = trackIndex >= lastTrackStart;
-    return (_jsxs("div", { "data-layout-kind": layoutKind, "data-phi-carousel-transition": transition, "data-phi-carousel-controls": controls, onMouseEnter: () => setPaused(true), onMouseLeave: () => setPaused(false), onFocusCapture: () => setPaused(true), onBlurCapture: () => setPaused(false), 
+    return (_jsxs(PhiLayoutSurfaceBox, { blockId: blockId, surface: storedChrome.surface, ground: resolvedChrome.ground, "data-layout-kind": layoutKind, "data-phi-carousel-transition": transition, "data-phi-carousel-controls": controls, role: "region", "aria-roledescription": "carousel", "aria-label": controlLabels?.region ?? "Carousel", ...autoplay.holdHandlers, ...gestures.handlers, 
         /*
          * The Layout's own box, named as one: the fill rules address `.phi-layout`
          * (`.phi-slot-child--block-fill > .phi-layout`, styles/layout.css), and this box carried a
@@ -128,9 +99,13 @@ export function PhiCarouselLayout({ slots, slotKeys, slotMeta, defaultActiveSlot
             minWidth: 0,
             minHeight: 0,
             boxSizing: "border-box",
-            ...resolvePhiBaseLayoutChrome(chrome).style,
+            ...gestures.style,
+            ...resolvedChrome.style,
             ...style,
-        }, children: [backgroundLayer, _jsxs("div", { style: { position: "relative", flex: "1 1 auto", minWidth: 0, minHeight: 0 }, children: [_jsx(PhiSequenceViewport, { items: track.map((entry) => entry.slot), activeIndex: trackIndex, visibleCount: span, anchor: windowAnchor, transition: transition, ...(transitionDurationMs === undefined ? {} : { durationMs: transitionDurationMs }), ...(transitionEasing === undefined ? {} : { easing: transitionEasing }), lookahead: lookahead, gap: slotGap, style: { width: "100%", height: "100%", minHeight: 0 }, renderItem: (slot) => (_jsx(PhiLayoutAnchoredOverlay, { anchor: slotAnchor, positionMode: "flow", fillAvailableInline: true, fillAvailableBlock: true, inset: resolvedLayoutInset, children: slot })) }), showArrows ? (_jsxs(_Fragment, { children: [_jsx("div", { style: { position: "absolute", insetBlockStart: "50%", insetInlineStart: token.marginXS, transform: "translateY(-50%)", zIndex: 1 }, children: _jsx(PhiButtonControl, { icon: _jsx(LeftOutlined, {}), ariaLabel: controlLabels?.previous ?? "Previous", shape: "circle", disabled: atStart && !loop, onClick: () => step(-1) }) }), _jsx("div", { style: { position: "absolute", insetBlockStart: "50%", insetInlineEnd: token.marginXS, transform: "translateY(-50%)", zIndex: 1 }, children: _jsx(PhiButtonControl, { icon: _jsx(RightOutlined, {}), ariaLabel: controlLabels?.next ?? "Next", shape: "circle", disabled: atEnd && !loop, onClick: () => step(1) }) })] })) : null] }), showDots ? (_jsx("div", { style: { display: "flex", flex: "0 0 auto", justifyContent: "center", gap: token.marginXXS, paddingBlockStart: token.marginXS }, children: Array.from({ length: pageCount }, (_, page) => (_jsx("button", { type: "button", "aria-label": slotLabelAt(pageStarts[page] ?? 0), "aria-current": page === currentPage || undefined, onClick: () => stepTo(pageStarts[page] ?? 0), style: {
+        }, children: [_jsxs("div", { style: { position: "relative", flex: "1 1 auto", minWidth: 0, minHeight: 0 }, "aria-live": autoplay.running ? "off" : "polite", children: [_jsx(PhiSequenceViewport, { items: track.map((entry) => entry.slot), activeIndex: trackIndex, visibleCount: span, anchor: windowAnchor, transition: transition, ...(transitionDurationMs === undefined ? {} : { durationMs: transitionDurationMs }), ...(transitionEasing === undefined ? {} : { easing: transitionEasing }), lookahead: lookahead, gap: slotGap, style: { width: "100%", height: "100%", minHeight: 0 }, renderItem: (slot) => (_jsx(PhiLayoutAnchoredOverlay, { anchor: slotAnchor, positionMode: "flow", fillAvailableInline: true, fillAvailableBlock: true, inset: resolvedLayoutInset, children: slot })) }), showArrows ? (_jsxs(_Fragment, { children: [_jsx("div", { style: { position: "absolute", insetBlockStart: "50%", insetInlineStart: token.marginXS, transform: "translateY(-50%)", zIndex: 1 }, children: _jsx(PhiButtonControl, { icon: _jsx(PhiIcon, { name: "left", size: "inherit" }), ariaLabel: controlLabels?.previous ?? "Previous", shape: "circle", disabled: atStart && !loop, onClick: () => stepByHand(-1) }) }), _jsx("div", { style: { position: "absolute", insetBlockStart: "50%", insetInlineEnd: token.marginXS, transform: "translateY(-50%)", zIndex: 1 }, children: _jsx(PhiButtonControl, { icon: _jsx(PhiIcon, { name: "right", size: "inherit" }), ariaLabel: controlLabels?.next ?? "Next", shape: "circle", disabled: atEnd && !loop, onClick: () => stepByHand(1) }) })] })) : null, autoplay.offered ? (_jsx("div", { style: { position: "absolute", insetBlockEnd: token.marginXS, insetInlineEnd: token.marginXS, zIndex: 1 }, children: _jsx(PhiButtonControl, { icon: _jsx(PhiIcon, { name: autoplay.stopped ? "play-circle" : "pause-circle", size: "inherit" }), ariaLabel: autoplay.stopped ? (controlLabels?.play ?? "Play") : (controlLabels?.pause ?? "Pause"), ariaPressed: autoplay.stopped, shape: "circle", onClick: autoplay.toggleStopped }) })) : null] }), showDots ? (_jsx("div", { role: "group", style: { display: "flex", flex: "0 0 auto", justifyContent: "center", gap: token.marginXXS, paddingBlockStart: token.marginXS }, children: Array.from({ length: pageCount }, (_, page) => (_jsx("button", { type: "button", "aria-label": slotLabelAt(pageStarts[page] ?? 0), "aria-current": page === currentPage || undefined, onClick: () => {
+                        stepTo(pageStarts[page] ?? 0);
+                        autoplay.restart();
+                    }, style: {
                         width: page === currentPage ? token.controlHeightXS : token.marginXS,
                         height: token.marginXS,
                         padding: 0,

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

@@ -20,7 +20,9 @@ export type PhiCollapsibleLayoutProps = Omit<PhiBaseLayoutProps, "slots"> & {
     panelMinHeight?: CSSProperties["minHeight"];
     accordion?: boolean;
     slotTitles?: string[];
-    translateSlotTitles?: boolean;
+    /** The hint behind each panel's title, in slot order; an empty one draws none. */
+    slotDescriptions?: string[];
+    /** Every change of the open panels after the first render, whoever made it: a click or a signal. */
     onOpenSlotKeysChange?: (next: string[]) => void;
     defaultOpenSlotKeys?: string[];
     collapsible?: "header" | "icon" | "disabled";

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

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

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

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