@phis/ui 0.2.1 → 0.4.0

package/components/forms/runtime-form-client.d.ts

@@ -7,28 +7,6 @@ export type PhiRuntimeFormSubmitOptions = {
     phase?: "submit" | "confirm";
     correlationId?: string;
 };
-/**
- * Why a submit failed, which is not the same question as whether the form was accepted.
- *
- * A refusal is not a failure at all: it comes back as a result with `ok: false` and the payload the
- * server sent. These four are the ways the exchange itself did not conclude, and only `transport` is
- * the network. A caller that cannot tell them apart has to guess, and the Login guessed "network" for
- * all of them -- so a submit held by a wiring fault, which ended at the 30s timeout, was reported to
- * the person typing their password as a connection problem.
- */
-export type PhiRuntimeFormSubmitFailure = 
-/** The Controller's own request did not complete. */
-"transport"
-/** No result and no error arrived before the submit gave up waiting. */
- | "timeout"
-/** The caller unmounted while the submit was still in flight. */
- | "cancelled"
-/** The caller has no Controller address to submit to. */
- | "unaddressed";
-export declare class PhiRuntimeFormSubmitError extends Error {
-    readonly failure: PhiRuntimeFormSubmitFailure;
-    constructor(failure: PhiRuntimeFormSubmitFailure, message: string);
-}
 export type PhiRuntimeFormClient = {
     submit(options: PhiRuntimeFormSubmitOptions): Promise<PhiRuntimeFormSubmitResult>;
     setValues(values: Record<string, unknown>): void;

package/components/forms/runtime-form-client.js

@@ -5,7 +5,7 @@ import { createPhiSignalCorrelationId, usePhiSignalDispatcher, usePhiSignalListe
 import { usePhiSignalIdentity } from "../runtime/runtime-signal-identity";
 import { PHI_FORM_SIGNAL_CHANNELS, } from "./runtime-form-controller-signals";
 import { isPhiRecord } from "../../helpers/is-record";
-export class PhiRuntimeFormSubmitError extends Error {
+class PhiRuntimeFormSubmitError extends Error {
     failure;
     constructor(failure, message) {
         super(message);

package/components/forms/runtime-form-controller-mount.js

@@ -39,16 +39,18 @@ function isPhiRuntimeFormSubmitSignalValue(value) {
  * The Area the Form was drawn in, and the browser's CSRF token. The relay used to mint a CSRF pair of
  * its own for each submit, which proved nothing about the page that sent it; now it forwards this one,
  * and a handler that declares CSRF refuses a submit without it. Every submit carries the token, because
- * which handler needs one is the server's catalog, not the page's. A token that cannot be had is left
- * out, and a handler that needs none -- a contact form -- still goes through.
+ * which handler needs one is the server's catalog, not the page's. A token that cannot be had fails the
+ * submit here, with the token's own message (`readPhiCsrfToken` throws rather than returning null):
+ * sent without it, the submit was refused by the handler and the Form showed a generic error that named
+ * nothing.
  */
 async function submitPhiFormToRelay(value, area) {
-    const csrfToken = await readPhiCsrfToken().catch(() => "");
+    const csrfToken = await readPhiCsrfToken();
     return fetch("/api/site/forms", {
         method: "POST",
         headers: {
             "content-type": "application/json",
-            ...(csrfToken ? { "x-csrf-token": csrfToken } : {}),
+            "x-csrf-token": csrfToken,
         },
         body: JSON.stringify({
             formId: value.formId,

package/components/forms/runtime-form-controller-requirement.d.ts

@@ -1,15 +1,5 @@
-import type { PhiCmsWidgetRuntimeControllerRequirementResolver, PhiRuntimeControllerRequirement } from "../../types";
+import type { PhiCmsWidgetRuntimeControllerRequirementResolver } from "../../types";
 import type { PhiCmsFormWidgetConfig } from "./form-widget-config";
-/**
- * How a Widget's Form Controller is named, written once and read back once.
- *
- * A Form Controller mounted for a Widget carries that Widget's id as its instance key. It was a
- * convention four call sites spelled out for themselves; naming it lets the Controller find its way
- * back to the Widget it belongs to, which is what the state it answers with has to be addressed at.
- */
-export declare const PHI_FORM_CONTROLLER_WIDGET_INSTANCE_PREFIX = "widget-";
-export declare function createPhiRuntimeFormWidgetInstanceKey(widgetId: string | number): string;
 /** The Widget a Form Controller was mounted for, or null when it was mounted for something else. */
 export declare function readPhiRuntimeFormControllerWidgetId(instanceKey: string | number | null | undefined): string | null;
-export declare function createPhiRuntimeFormControllerRequirement(instanceKey: string | number): PhiRuntimeControllerRequirement;
 export declare const requirePhiRuntimeFormControllerForWidget: PhiCmsWidgetRuntimeControllerRequirementResolver<PhiCmsFormWidgetConfig>;

package/components/forms/runtime-form-controller-requirement.js

@@ -7,8 +7,8 @@ import { resolvePhiRuntimeConditionControllerRequirements } from "../../types/ru
  * convention four call sites spelled out for themselves; naming it lets the Controller find its way
  * back to the Widget it belongs to, which is what the state it answers with has to be addressed at.
  */
-export const PHI_FORM_CONTROLLER_WIDGET_INSTANCE_PREFIX = "widget-";
-export function createPhiRuntimeFormWidgetInstanceKey(widgetId) {
+const PHI_FORM_CONTROLLER_WIDGET_INSTANCE_PREFIX = "widget-";
+function createPhiRuntimeFormWidgetInstanceKey(widgetId) {
     return `${PHI_FORM_CONTROLLER_WIDGET_INSTANCE_PREFIX}${widgetId}`;
 }
 /** The Widget a Form Controller was mounted for, or null when it was mounted for something else. */
@@ -18,7 +18,7 @@ export function readPhiRuntimeFormControllerWidgetId(instanceKey) {
         ? key.slice(PHI_FORM_CONTROLLER_WIDGET_INSTANCE_PREFIX.length)
         : null;
 }
-export function createPhiRuntimeFormControllerRequirement(instanceKey) {
+function createPhiRuntimeFormControllerRequirement(instanceKey) {
     return {
         type: PHI_FORM_CONTROLLER_TYPE,
         instanceKey: String(instanceKey),

package/components/forms/shared-form-ids.d.ts

@@ -32,4 +32,9 @@ export declare const PHI_SHARED_FORM_IDS: {
      */
     readonly profilePassword: `${string}/forms/${string}`;
     readonly profileEmail: `${string}/forms/${string}`;
+    /**
+     * Answering a conversation, for every Module that runs conversations of its own kind. Core's, because
+     * messaging is: a Module places it, it does not grow a reply of its own (`core/messaging/forms.ts`).
+     */
+    readonly threadReply: `${string}/forms/${string}`;
 };

package/components/forms/shared-form-ids.js

@@ -34,4 +34,9 @@ export const PHI_SHARED_FORM_IDS = {
      */
     profilePassword: createPhiFormId(PHI_SHARED_PACKAGE_NAME, "profile-password"),
     profileEmail: createPhiFormId(PHI_SHARED_PACKAGE_NAME, "profile-email"),
+    /**
+     * Answering a conversation, for every Module that runs conversations of its own kind. Core's, because
+     * messaging is: a Module places it, it does not grow a reply of its own (`core/messaging/forms.ts`).
+     */
+    threadReply: createPhiFormId(PHI_SHARED_PACKAGE_NAME, "thread-reply"),
 };

package/components/forms/shared-form-loaders.d.ts

@@ -1,9 +1,18 @@
 import type { PhiFormInitialValuesLoader, PhiFormLabelSetLoader } from "./form-resolution";
-export declare function createPhiFormLabelSetLoader(load: () => Promise<(options: {
+/**
+ * A Form's labels from a Label Set: the Set is loaded when the Form is rendered, read in the page's
+ * language, and flattened to the keys the descriptor names.
+ *
+ * `select` picks and renames: a Form that calls a field `name` while the Set says `fields.siteName`
+ * states that mapping here. Ten Module forms used to spell the whole loader for themselves to do only
+ * that -- the dynamic import, the credentials, the locale, the flattening -- and the one thing that was
+ * theirs stood in the middle of it.
+ */
+export declare function createPhiFormLabelSetLoader<TLabels>(load: () => Promise<(options: {
     apiBaseUrl: string;
     internalToken: string;
     locale: string;
-}) => Promise<unknown>>): PhiFormLabelSetLoader;
+}) => Promise<TLabels>>, select?: (labels: TLabels) => unknown): PhiFormLabelSetLoader;
 /**
  * The language the form was read in, handed to the handler as one of its values.
  *

package/components/forms/shared-form-loaders.js

@@ -1,4 +1,13 @@
-export function createPhiFormLabelSetLoader(load) {
+/**
+ * A Form's labels from a Label Set: the Set is loaded when the Form is rendered, read in the page's
+ * language, and flattened to the keys the descriptor names.
+ *
+ * `select` picks and renames: a Form that calls a field `name` while the Set says `fields.siteName`
+ * states that mapping here. Ten Module forms used to spell the whole loader for themselves to do only
+ * that -- the dynamic import, the credentials, the locale, the flattening -- and the one thing that was
+ * theirs stood in the middle of it.
+ */
+export function createPhiFormLabelSetLoader(load, select) {
     return async ({ runtime }) => {
         const [{ flattenPhiFormLabels }, { phiRuntime }, loadLabels] = await Promise.all([
             import("./form-labels"),
@@ -6,11 +15,12 @@ export function createPhiFormLabelSetLoader(load) {
             load(),
         ]);
         const rt = phiRuntime(runtime);
-        return flattenPhiFormLabels(await loadLabels({
+        const labels = await loadLabels({
             apiBaseUrl: rt.apiBaseUrl,
             internalToken: rt.internalToken,
             locale: runtime.locale.current,
-        }));
+        });
+        return flattenPhiFormLabels(select ? select(labels) : labels);
     };
 }
 /**

package/components/forms/shared-form-provider-registry.js

@@ -42,6 +42,7 @@ placeholderRows = 1) {
         return (_jsx(Suspense, { fallback: placeholder, children: _jsx(LazyControl, { ...props }) }));
     };
 }
+const PhiLazyLinkTargetFormControl = lazyPhiFormFieldControl(() => import("./link-target-form-control").then((module) => module.PhiLinkTargetFormControl));
 const PhiLazySelectFormControl = lazyPhiFormFieldControl(() => import("./choice-form-field-controls").then((module) => module.PhiSelectFormControl));
 const PhiLazyMultiSelectFormControl = lazyPhiFormFieldControl(() => import("./choice-form-field-controls").then((module) => module.PhiMultiSelectFormControl));
 const PhiLazySegmentedFormControl = lazyPhiFormFieldControl(() => import("./choice-form-field-controls").then((module) => module.PhiSegmentedFormControl));
@@ -155,6 +156,9 @@ export const PHI_SHARED_FORM_PROVIDER_REGISTRY = createPhiFormProviderRegistry({
         phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.storageSize, {
             Control: PhiLazyStorageSizeFormControl,
         }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.linkTarget, {
+            Control: PhiLazyLinkTargetFormControl,
+        }),
     ],
     validationRules: [
         phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.required, {

package/components/forms/storage-size.d.ts

@@ -22,15 +22,6 @@
  */
 export declare const PHI_STORAGE_SIZE_UNIT_BYTES = 1048576;
 export declare const PHI_STORAGE_SIZE_UNIT_LABEL = "MB";
-/**
- * How precisely a size may be stated, in the unit above.
- *
- * Two places is about ten kilobytes, which is finer than any limit anybody sets on purpose and coarse
- * enough that the field does not show a number like 4.76837158203125. A stored size that is not a
- * round count of megabytes therefore displays rounded -- but it is only ever written back when
- * somebody edits the field, so reading the page cannot change what it says.
- */
-export declare const PHI_STORAGE_SIZE_PRECISION = 2;
 export declare function phiBytesToStorageSize(bytes: unknown): number | null;
 /** Bytes are whole, so the product is rounded rather than carried at whatever fraction it lands on. */
 export declare function phiStorageSizeToBytes(size: number | null): number | null;

package/components/forms/storage-size.js

@@ -30,7 +30,7 @@ export const PHI_STORAGE_SIZE_UNIT_LABEL = "MB";
  * round count of megabytes therefore displays rounded -- but it is only ever written back when
  * somebody edits the field, so reading the page cannot change what it says.
  */
-export const PHI_STORAGE_SIZE_PRECISION = 2;
+const PHI_STORAGE_SIZE_PRECISION = 2;
 export function phiBytesToStorageSize(bytes) {
     if (typeof bytes !== "number" || !Number.isFinite(bytes))
         return null;

package/components/forms/upload-form-control.d.ts

@@ -17,6 +17,11 @@ export declare function readPhiFormUploadAssetIds(value: unknown): readonly numb
  * 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.

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";