@phis/ui 0.1.0 → 0.2.0

package/components/forms/form-widget-config.js

@@ -0,0 +1,122 @@
+import { readPhiProviderResourceSource, } from "../../types/runtime-data-provider";
+import { isPhiFormId, normalizePhiFormId } from "../../types/form-id";
+import { readPhiSignalRouteSet } from "../../types/signals";
+import { readRenderableBlockConfig, } from "../widgets/config/parser-primitives";
+import { PHI_LAYOUT } from "../../theme/phi-tokens";
+function readRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? { ...value }
+        : {};
+}
+/**
+ * The placement's own cap, or null where it states none.
+ *
+ * Absent -- the key missing, `null`, or a field emptied in the Inspector -- leaves the cap to the house
+ * measure. A cap that is stated but cannot be one is refused rather than replaced: `0` or a negative
+ * number caps the fields at nothing, and a bare `"610"` is not a CSS length, so `min(100%, 610)` is
+ * dropped by the browser and the Form renders uncapped with no error anywhere.
+ */
+function readPhiFormWidgetMaxFormWidth(value) {
+    if (value == null)
+        return null;
+    if (typeof value === "number") {
+        if (Number.isFinite(value) && value > 0)
+            return value;
+        throw new Error(`Invalid Form maxFormWidth ${JSON.stringify(value)}. Expected a positive number.`);
+    }
+    if (typeof value !== "string") {
+        throw new Error(`Invalid Form maxFormWidth ${JSON.stringify(value)}. Expected a number or a length.`);
+    }
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const leadingNumber = /^[+-]?(\d+\.?\d*|\.\d+)/.exec(trimmed);
+    if (leadingNumber && leadingNumber[0] === trimmed) {
+        throw new Error(`Invalid Form maxFormWidth ${JSON.stringify(value)}. A length needs a unit.`);
+    }
+    if (leadingNumber && Number(leadingNumber[0]) <= 0) {
+        throw new Error(`Invalid Form maxFormWidth ${JSON.stringify(value)}. Expected a positive length.`);
+    }
+    return trimmed;
+}
+export function parsePhiFormWidgetConfig(rawConfig) {
+    /*
+     * The block's own geometry, which this Widget used to drop on the floor.
+     *
+     * A parser that returns only its own fields discards everything an author set in the Style tab, and
+     * the Form's parsed config is what the Widget renders from. Where the Form's *cap* comes from is a
+     * different question, answered in `defaultConfig` below rather than here.
+     */
+    const renderableBlockConfig = readRenderableBlockConfig(rawConfig);
+    const normalizedFormId = typeof rawConfig.formId === "string"
+        ? normalizePhiFormId(rawConfig.formId)
+        : "";
+    const execution = readRecord(rawConfig.execution);
+    const card = readRecord(rawConfig.card);
+    const cardPresentation = card.presentation === "card" || card.presentation === "panel" || card.presentation === "wash"
+        ? card.presentation
+        : null;
+    const cardPadding = typeof card.padding === "number" || typeof card.padding === "string"
+        ? card.padding
+        : null;
+    const maxFormWidth = readPhiFormWidgetMaxFormWidth(rawConfig.maxFormWidth);
+    const feedback = readRecord(rawConfig.feedback);
+    const feedbackSuccessText = typeof feedback.successText === "string" && feedback.successText.trim()
+        ? feedback.successText.trim()
+        : null;
+    return {
+        ...renderableBlockConfig,
+        formId: isPhiFormId(normalizedFormId) ? normalizedFormId : null,
+        submit: rawConfig.submit === "inline" ? "inline" : "external",
+        submitOnEnter: rawConfig.submitOnEnter === true,
+        /*
+         * The house measure where the placement names none, and answered HERE as well as declared.
+         *
+         * `defaultConfig` reaches the Builder and the Inspector, but the render path merges only a Widget's
+         * block base under a node (`widgetBlockDefaultsByType`) -- so a Preset placement that says nothing
+         * arrives with no cap at all, which is exactly how every Preset-placed Form once rendered uncapped.
+         * A Widget field has to be answered by its parser. Both sides read the one constant.
+         */
+        maxFormWidth: maxFormWidth ?? PHI_LAYOUT.contentMax,
+        /*
+         * No box unless one is named, and the name is read rather than the block's presence: an author who
+         * takes the box off again leaves an empty `card` behind, and an empty block is not a box.
+         */
+        card: cardPresentation == null ? null : {
+            presentation: cardPresentation,
+            title: typeof card.title === "string" && card.title.trim() ? card.title.trim() : null,
+            padding: cardPadding,
+        },
+        // Absent means silent, so a Form that says nothing about feedback keeps reporting where it stands.
+        feedback: rawConfig.feedback == null ? null : {
+            mode: feedback.mode === "notification" ? "notification" : "message",
+            ...(feedbackSuccessText ? { successText: feedbackSuccessText } : {}),
+        },
+        links: Array.isArray(rawConfig.links)
+            ? rawConfig.links.flatMap((entry) => {
+                const link = readRecord(entry);
+                const key = typeof link.key === "string" ? link.key.trim() : "";
+                const href = typeof link.href === "string" ? link.href.trim() : "";
+                if (!key || !href)
+                    return [];
+                return [{
+                        key,
+                        href,
+                        ...(typeof link.requiresFeature === "string" && link.requiresFeature.trim()
+                            ? { requiresFeature: link.requiresFeature.trim() }
+                            : {}),
+                    }];
+            })
+            : [],
+        formConfig: readRecord(rawConfig.formConfig),
+        execution: {
+            mode: execution.mode === "signal" ? "signal" : "handler",
+            phase: execution.phase === "confirm" ? "confirm" : "submit",
+        },
+        source: readPhiProviderResourceSource(rawConfig.source),
+        openActionKey: typeof rawConfig.openActionKey === "string" && rawConfig.openActionKey.trim()
+            ? rawConfig.openActionKey.trim()
+            : undefined,
+        signalRoutes: readPhiSignalRouteSet(rawConfig.signalRoutes),
+    };
+}

package/components/forms/phi-form-widget-frame.d.ts

@@ -1,17 +1,25 @@
 import { type ReactNode } from "react";
-import type { PhiCmsFormWidgetSubmitConfig } from "../../plugins/runtime-modules/core/widgets/form/config";
+import type { PhiCmsFormWidgetCardConfig } from "../../types/core-widget-placements";
+import type { PhiFormLayoutDescriptor, PhiFormLogicalAlignment, PhiFormResponsiveGridRange } from "../../types/form-descriptor";
 /**
  * What a form body offers the Widget above it, so the Widget can draw a submit for it.
  *
- * A form describes fields. Whether there is a button, what it says and which column it stands in are the
- * Widget's to decide -- which is why the body hands up a way to submit rather than a button, and why the
- * label is only what this form would call it if the Widget's config says nothing.
+ * The body hands up a way to submit rather than a button: whether a button is drawn is the Widget's
+ * placement, and what it says and where it stands is the descriptor's -- neither is the body's.
  */
 export type PhiFormWidgetSubmitRegistration = {
     /** Asks the mounted form to submit. The same request the `submit` capability makes. */
     submit: () => void;
-    /** What this form calls submitting, used where the Widget's config names nothing. */
-    label?: string;
+};
+/**
+ * The submit the Widget draws, already resolved: the placement said `inline`, and the descriptor's
+ * `submit` said what it reads and where it stands.
+ */
+export type PhiFormWidgetSubmit = {
+    label: string;
+    align: PhiFormLogicalAlignment;
+    /** The descriptor's own tracks for it, or absent for the layout's control range. */
+    control?: PhiFormResponsiveGridRange;
 };
 type PhiFormWidgetSubmitSlot = {
     register: (registration: PhiFormWidgetSubmitRegistration | null) => void;
@@ -22,7 +30,7 @@ type PhiFormWidgetSubmitSlot = {
  * that a submit is under way. Null where no Widget is listening, which is what a form rendered outside
  * one gets: it simply has no submit of its own to draw instead.
  */
-export declare function usePhiFormWidgetSubmit(submit: () => void, label?: string): PhiFormWidgetSubmitSlot | null;
+export declare function usePhiFormWidgetSubmit(submit: () => void): PhiFormWidgetSubmitSlot | null;
 /**
  * Where in a form body the Widget's submit appears.
  *
@@ -38,10 +46,40 @@ export type PhiFormWidgetLink = {
     href: string;
 };
 export type PhiFormWidgetFrameProps = {
-    /** The submit the Widget carries, or null where it carries none. */
-    submit?: PhiCmsFormWidgetSubmitConfig | null;
+    /** The submit the Widget draws, or null where the placement keeps it external. */
+    submit?: PhiFormWidgetSubmit | null;
+    /**
+     * The box around the whole of it, or null for no box.
+     *
+     * It stands outside the grid rather than around the fields, because the submit and the ways out belong
+     * in it too -- a button outside the box it submits reads as something else's button. Its inset is the
+     * Card's, so the query container is measured inside the padding, which is the width the fields have --
+     * and `wash`, which draws no Card, takes the same inset a Collapsible's body takes, so its ground does
+     * not run flush into the labels. Null draws nothing and insets nothing, which is what a Form in a slot
+     * that already paints a ground wants: there the query container is the block itself, so the width the
+     * fields read is the width the placement capped.
+     */
+    card?: PhiCmsFormWidgetCardConfig | null;
+    /**
+     * How wide the form may get, measured at the fields rather than around the box.
+     *
+     * The cap belongs to the form, so the box grows outwards to carry it: a Form capped at 610 in a `card`
+     * is a 610 form in a 652 card, and its container query reads the 610 it was given. Capping the block
+     * instead -- which is where this number used to live -- put the inset inside the cap, so the fields
+     * read 568 and stood one layout step below the threshold the cap was chosen to land on.
+     *
+     * Null caps nothing. A block `maxSize` still caps the block; that is the other box, and it is drawn
+     * by the slot frame, above everything here.
+     */
+    maxFormWidth?: number | string | null;
     /** The ways out it offers, drawn in the same column as the submit. */
     links?: readonly PhiFormWidgetLink[];
+    /**
+     * The form's own layout, read for one thing only: which tracks its inputs stand on, so the submit
+     * can stand on the same ones. The body is rendered on the Client and cannot tell the frame, and the
+     * frame is the element both are inside, so this is where the answer has to arrive.
+     */
+    layout?: PhiFormLayoutDescriptor;
     children: ReactNode;
 };
 /**
@@ -52,9 +90,9 @@ export type PhiFormWidgetFrameProps = {
  * column ends to line up under the inputs, and only an element above both can tell them.
  *
  * The submit opens its own row of the same twenty-four tracks. Its own grid rather than a row inside the
- * form: the form describes fields, and a submit is not one. Sharing the track count and the label-column
- * property is all it takes for the button to line up under the inputs and move with the column the Layout
- * decides, because that column is a custom property both of them read.
+ * form: the form describes fields, and a submit is not one. Which of those tracks it takes is written
+ * here, from the form's layout, so it lines up under the inputs at each width and still moves with the
+ * column a Form Layout decides -- that column is a custom property both of them read.
  */
-export declare function PhiFormWidgetFrame({ submit, links, children }: PhiFormWidgetFrameProps): import("react").JSX.Element;
+export declare function PhiFormWidgetFrame({ submit, card, maxFormWidth, links, layout, children }: PhiFormWidgetFrameProps): import("react").JSX.Element;
 export {};

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

@@ -2,8 +2,12 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, Fragment, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { PHI_COLOR, PHI_SPACE } from "../../theme/antd-css-var-contract";
+import { PHI_THEME_BORDER_WIDTH } from "../../helpers/border-widget-style";
+import { normalizePhiCssSize, PHI_LAYOUT_SURFACE_RADIUS, PHI_SLOT_INLINE_PLACEMENT_MARGIN_STYLE, } from "../layouts/phi-layout-contract";
 import { PhiButtonControl } from "../controls/phi-button-control";
+import { PhiCardControl } from "../controls/phi-card-control";
 import { PhiLink } from "../navigation/phi-link";
+import { PHI_FORM_ACTIONS_COLUMNS_PROPERTY, PHI_FORM_RESPONSIVE_MODES, phiFormActionsGridColumn, phiFormGridColumn, resolvePhiFormLayout, resolvePhiFormResponsiveGridRange, } from "./form-descriptor-contract";
 /* Two contexts, because they change at different rates: the slot is stable for the life of the frame,
  * while the button is rebuilt whenever a submit starts or ends. A body that only registers must not
  * re-render for that. */
@@ -14,7 +18,7 @@ const PhiFormWidgetSubmitNodeContext = createContext(null);
  * that a submit is under way. Null where no Widget is listening, which is what a form rendered outside
  * one gets: it simply has no submit of its own to draw instead.
  */
-export function usePhiFormWidgetSubmit(submit, label) {
+export function usePhiFormWidgetSubmit(submit) {
     const slot = useContext(PhiFormWidgetSubmitSlotContext);
     // The call is read through a ref so a body may pass a fresh closure every render without
     // re-registering -- the registration is identity, not a value that changes with each keystroke.
@@ -28,9 +32,9 @@ export function usePhiFormWidgetSubmit(submit, label) {
         if (!slot) {
             return;
         }
-        slot.register({ submit: () => submitRef.current(), label });
+        slot.register({ submit: () => submitRef.current() });
         return () => slot.register(null);
-    }, [label, slot]);
+    }, [slot]);
     return slot;
 }
 /**
@@ -46,6 +50,22 @@ export function PhiFormWidgetSubmitOutlet() {
 function resolveSubmitJustification(align) {
     return align === "start" ? "flex-start" : align === "center" ? "center" : "flex-end";
 }
+/**
+ * What one side of a box costs, so the cap can be stated at the fields and the box grown to carry it.
+ *
+ * The inset is the box's own -- the Theme's `padding` for a Card and for a Wash, `paddingSM` for the
+ * chrome-sized Panel, or whatever the placement named instead -- and the two that have a frame pay for
+ * the Theme's line as well. Null where there is no box: then the fields are the outermost thing here and
+ * nothing stands between them and the cap.
+ */
+function resolvePhiFormBoxChrome(card) {
+    if (card == null) {
+        return null;
+    }
+    const inset = normalizePhiCssSize(card.padding ?? undefined)
+        ?? (card.presentation === "panel" ? PHI_SPACE.sm : PHI_SPACE.base);
+    return card.presentation === "wash" ? inset : `(${inset} + ${PHI_THEME_BORDER_WIDTH})`;
+}
 /**
  * The Form Widget's own surface: the query container its form is measured in, and the submit it carries.
  *
@@ -54,15 +74,34 @@ function resolveSubmitJustification(align) {
  * column ends to line up under the inputs, and only an element above both can tell them.
  *
  * The submit opens its own row of the same twenty-four tracks. Its own grid rather than a row inside the
- * form: the form describes fields, and a submit is not one. Sharing the track count and the label-column
- * property is all it takes for the button to line up under the inputs and move with the column the Layout
- * decides, because that column is a custom property both of them read.
+ * form: the form describes fields, and a submit is not one. Which of those tracks it takes is written
+ * here, from the form's layout, so it lines up under the inputs at each width and still moves with the
+ * column a Form Layout decides -- that column is a custom property both of them read.
  */
-export function PhiFormWidgetFrame({ submit, links, children }) {
+export function PhiFormWidgetFrame({ submit, card, maxFormWidth, links, layout, children }) {
     const [registration, setRegistration] = useState(null);
     const [submitting, setSubmitting] = useState(false);
     const slot = useMemo(() => ({ register: setRegistration, setSubmitting }), []);
-    const submitButton = submit && registration ? (_jsx("div", { className: "phi-form-descriptor-actions", children: _jsx("div", { className: "phi-form-cell phi-form-cell--control", style: { display: "flex", justifyContent: resolveSubmitJustification(submit.align) }, children: _jsx(PhiButtonControl, { type: "primary", label: submit.label ?? registration.label ?? "Submit", loading: submitting, onClick: registration.submit }) }) })) : null;
+    const resolvedLayout = useMemo(() => resolvePhiFormLayout(layout), [layout]);
+    const actionsColumns = useMemo(() => Object.fromEntries(PHI_FORM_RESPONSIVE_MODES.map((mode) => [
+        `${PHI_FORM_ACTIONS_COLUMNS_PROPERTY}-${mode}`,
+        phiFormActionsGridColumn(resolvedLayout, mode),
+    ])), [resolvedLayout]);
+    /*
+     * Tracks the descriptor names for its submit replace the actions row's columns for that row alone;
+     * the links keep the layout's control range, which is where they line up with the inputs.
+     */
+    const submitControl = submit?.control;
+    const submitColumns = useMemo(() => {
+        if (!submitControl)
+            return undefined;
+        const ranges = resolvePhiFormResponsiveGridRange(submitControl, resolvedLayout.control, "submit.control");
+        return Object.fromEntries(PHI_FORM_RESPONSIVE_MODES.map((mode) => [
+            `${PHI_FORM_ACTIONS_COLUMNS_PROPERTY}-${mode}`,
+            phiFormGridColumn(ranges[mode]),
+        ]));
+    }, [resolvedLayout, submitControl]);
+    const submitButton = submit && registration ? (_jsx("div", { className: "phi-form-descriptor-actions", style: submitColumns, children: _jsx("div", { className: "phi-form-cell phi-form-cell--control", style: { display: "flex", justifyContent: resolveSubmitJustification(submit.align) }, children: _jsx(PhiButtonControl, { type: "primary", label: submit.label, loading: submitting, onClick: registration.submit }) }) })) : null;
     /*
      * A row of its own on the same tracks, directly under the submit.
      *
@@ -83,12 +122,47 @@ export function PhiFormWidgetFrame({ submit, links, children }) {
      * and anything appended to the end of the frame would sit under those.
      */
     const actionsNode = linksRow || submitButton ? (_jsxs(_Fragment, { children: [linksRow, submitButton] })) : null;
-    return (_jsx(PhiFormWidgetSubmitSlotContext.Provider, { value: slot, children: _jsx(PhiFormWidgetSubmitNodeContext.Provider, { value: actionsNode, children: _jsx("div", { style: {
-                    display: "grid",
-                    gap: PHI_SPACE.sm,
-                    width: "100%",
-                    minWidth: 0,
-                    containerType: "inline-size",
-                    containerName: "phi-form",
-                }, children: children }) }) }));
+    /*
+     * The cap lands on the outermost box this Frame owns, and it lands there grown by that box's chrome.
+     *
+     * One box, one cap: the grid where there is no box, the box where there is, never both -- a cap inside
+     * an inset would take the inset off twice. `min(100%, ...)` because a cap is not a size and must never
+     * push out of the slot: a Form told to take `100%` and then grown by two insets would do exactly that.
+     */
+    const capLength = normalizePhiCssSize(maxFormWidth ?? undefined);
+    const boxChrome = resolvePhiFormBoxChrome(card);
+    const capStyle = capLength == null
+        ? undefined
+        : boxChrome == null
+            ? `min(100%, ${capLength})`
+            : `min(100%, calc(${capLength} + 2 * ${boxChrome}))`;
+    /*
+     * And where the cap leaves room over, the Layout says which side of it the Form stands on.
+     *
+     * The slot's placement margins are handed down as custom properties and the slot child frame reads
+     * them, but the frame around a Form fills the slot: the cap is one box further in, so the frame has no
+     * room left over and its auto margins come to nothing. The box that does have the room is this one,
+     * and it reads the same answer -- centred under a Layout anchored to the centre, at the start edge
+     * under one anchored to the start, which is what it did unasked before.
+     */
+    const placedBoxStyle = {
+        ...(capStyle == null ? {} : { maxWidth: capStyle }),
+        ...PHI_SLOT_INLINE_PLACEMENT_MARGIN_STYLE,
+    };
+    const measured = (_jsx("div", { style: {
+            display: "grid",
+            gap: PHI_SPACE.sm,
+            width: "100%",
+            minWidth: 0,
+            containerType: "inline-size",
+            containerName: "phi-form",
+            ...(card ? {} : placedBoxStyle),
+            ...actionsColumns,
+        }, children: children }));
+    return (_jsx(PhiFormWidgetSubmitSlotContext.Provider, { value: slot, children: _jsx(PhiFormWidgetSubmitNodeContext.Provider, { value: actionsNode, children: card?.presentation === "wash" ? (_jsx("div", { style: {
+                    background: PHI_COLOR.fillQuaternary,
+                    borderRadius: PHI_LAYOUT_SURFACE_RADIUS,
+                    padding: card.padding ?? PHI_SPACE.base,
+                    ...placedBoxStyle,
+                }, children: measured })) : card ? (_jsx(PhiCardControl, { size: card.presentation === "panel" ? "small" : "medium", ...(card.title ? { title: card.title } : {}), ...(card.padding == null ? {} : { padding: card.padding }), style: placedBoxStyle, children: measured })) : measured }) }));
 }

package/components/forms/phi-form-widget.d.ts

@@ -0,0 +1,15 @@
+import type { PhiBlockRuntime } from "../../types";
+import type { PhiCmsRuntimeRenderRegistry } from "../../types/cms-plugins";
+import type { PhiFormId } from "../../types/form-id";
+import type { PhiCmsFormWidgetConfig } from "./form-widget-config";
+import { type PhiRuntimeFeatureState } from "../../types/runtime-condition";
+export type PhiFormWidgetProps = {
+    runtime: Pick<PhiBlockRuntime, "site" | "locale"> & Partial<Pick<PhiBlockRuntime, "area">>;
+    registry: Pick<PhiCmsRuntimeRenderRegistry, "formDefinitionsById" | "uiProviderModuleIds">;
+    formId: PhiFormId;
+    formInstanceKey?: string | number | null;
+    config?: PhiCmsFormWidgetConfig;
+    /** What the active Modules published about this Site, as the renderer already resolved it. */
+    features?: PhiRuntimeFeatureState | null;
+};
+export declare function PhiFormWidget({ runtime, registry, formId, formInstanceKey, config, features, }: PhiFormWidgetProps): Promise<import("react").JSX.Element | null>;

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

@@ -0,0 +1,95 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { phiRuntime } from "../../server-helpers/phi-runtime";
+import { getResolvedFormDefinition } from "../../gateway/form-registry";
+import { resolvePhiFormLabels } from "./form-resolution";
+import { createPhiRuntimeFormControllerAddress } from "./runtime-form-controller-address";
+import { PhiRuntimeModuleRenderClientHost } from "../runtime/runtime-module-render-client-manifest";
+import { PhiRuntimeRenderClientType } from "../../constants/runtime-render-client-types";
+import { resolvePhiFormText } from "./form-descriptor-contract";
+import { PHI_FORM_DEFAULT_SUBMIT_LABEL } from "../../types/form-descriptor";
+import { readPhiRuntimeConditionValue, } from "../../types/runtime-condition";
+import { PhiRuntimeModuleUiProviderHost } from "../runtime/runtime-module-ui-provider-client-manifest";
+function normalizeFormId(value) {
+    return value.trim().toLowerCase();
+}
+export async function PhiFormWidget({ runtime, registry, formId, formInstanceKey, config, features = null, }) {
+    const normalizedFormId = normalizeFormId(formId);
+    if (!normalizedFormId) {
+        return null;
+    }
+    const rt = phiRuntime(runtime);
+    const resolvedForm = await getResolvedFormDefinition({
+        apiBaseUrl: rt.apiBaseUrl,
+        internalToken: rt.internalToken,
+        siteKey: runtime.site.key,
+        formId: normalizedFormId,
+        presetDefinitions: [...registry.formDefinitionsById.values()],
+    });
+    if (!resolvedForm) {
+        throw new Error(`Form "${normalizedFormId}" is not available from the active runtime modules.`);
+    }
+    const renderOptions = {
+        config: config?.formConfig,
+        formControllerAddress: createPhiRuntimeFormControllerAddress(formInstanceKey ?? `form-${normalizedFormId}`),
+        formInstanceKey: String(formInstanceKey ?? `form-${normalizedFormId}`),
+    };
+    const ownerModuleId = resolvedForm.definition.ownerModuleId;
+    const hasUiProvider = registry.uiProviderModuleIds.has(ownerModuleId);
+    /*
+     * Both reads happen here, on the server, and both are the form's own: what it is called, and what it
+     * already knows. Asking for either after hydration is a blank card for as long as the page takes to
+     * become interactive, which is the wait a visitor reads as a slow site.
+     */
+    const renderContext = { runtime, resolvedForm, options: renderOptions };
+    const [labels, loadedInitialValues] = await Promise.all([
+        resolvePhiFormLabels(renderContext),
+        resolvedForm.definition.loadInitialValues?.(renderContext) ?? null,
+    ]);
+    /*
+     * A link is offered only where it leads somewhere that exists: a Site with registration switched off
+     * has no account to create. The fact is read from the same published Module state a node condition
+     * reads, so the two cannot disagree about what this Site offers.
+     */
+    const resolvedLinks = (config?.links ?? []).flatMap((link) => {
+        if (link.requiresFeature && !readPhiRuntimeConditionValue(features, link.requiresFeature)) {
+            return [];
+        }
+        const label = labels[`actions.${link.key}Label`];
+        return label ? [{ key: link.key, label, href: link.href }] : [];
+    });
+    /*
+     * Every form body is wrapped the same way, and no body carries a submit or a way out: a body offers
+     * a way to submit. Whether a button is drawn is this placement's `submit`; what it says and which
+     * tracks it stands on are the descriptor's, resolved here where the form's labels already are.
+     */
+    const submitDescriptor = resolvedForm.definition.descriptor.submit;
+    const submit = config?.submit === "inline"
+        ? {
+            label: resolvePhiFormText(submitDescriptor?.label ?? PHI_FORM_DEFAULT_SUBMIT_LABEL, labels, config.formConfig),
+            align: submitDescriptor?.align ?? "start",
+            ...(submitDescriptor?.control ? { control: submitDescriptor.control } : {}),
+        }
+        : null;
+    const wrapFormUiProvider = (node) => {
+        const frameProps = {
+            submit,
+            card: config?.card ?? null,
+            maxFormWidth: config?.maxFormWidth ?? null,
+            links: resolvedLinks,
+            layout: resolvedForm.definition.descriptor.layout,
+            children: node,
+        };
+        const framed = (_jsx(PhiRuntimeModuleRenderClientHost, { type: PhiRuntimeRenderClientType.FormWidgetFrame, componentProps: frameProps }));
+        return hasUiProvider
+            ? (_jsx(PhiRuntimeModuleUiProviderHost, { moduleId: ownerModuleId, children: framed }))
+            : framed;
+    };
+    return wrapFormUiProvider(_jsx(PhiRuntimeModuleRenderClientHost, { type: PhiRuntimeRenderClientType.FormDescriptor, componentProps: {
+            descriptor: resolvedForm.definition.descriptor,
+            labels,
+            loadedInitialValues,
+            formId: resolvedForm.definition.formId,
+            formControllerAddress: renderOptions.formControllerAddress,
+            widgetConfig: config,
+        } }));
+}

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

@@ -4,6 +4,7 @@ import { PHI_SIGNAL_VALUE_SCHEMAS, } from "../../types/signals";
 import { createPhiSignalCorrelationId, usePhiSignalDispatcher, usePhiSignalListener, } from "../runtime/runtime-signal-bus";
 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 {
     failure;
     constructor(failure, message) {
@@ -12,21 +13,18 @@ export class PhiRuntimeFormSubmitError extends Error {
         this.failure = failure;
     }
 }
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 function readRuntimeFormResult(value) {
-    if (!isRecord(value) || typeof value.ok !== "boolean" || typeof value.status !== "number") {
+    if (!isPhiRecord(value) || typeof value.ok !== "boolean" || typeof value.status !== "number") {
         return null;
     }
     return {
         ok: value.ok,
         status: value.status,
-        payload: isRecord(value.payload) ? value.payload : null,
+        payload: isPhiRecord(value.payload) ? value.payload : null,
     };
 }
 function readRuntimeFormError(value) {
-    return isRecord(value) && typeof value.message === "string"
+    return isPhiRecord(value) && typeof value.message === "string"
         ? { message: value.message }
         : null;
 }

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

@@ -8,7 +8,7 @@ export declare const PHI_RUNTIME_FORM_CONTROLLER_DEFINITION: {
     description: string;
     iconFamily: string;
     flags: "multiInstance"[];
-    allowedMountScopes: ("area" | "site" | "page")[];
+    allowedMountScopes: ("area" | "page" | "site")[];
     runtimeSignals: {
         emits: ({
             readonly id: "values";

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

@@ -7,6 +7,9 @@ import { usePhiSignalRuntimePartition } from "../runtime/runtime-signal-partitio
 import { PHI_FORM_SIGNAL_CHANNELS, createPhiRuntimeFormControllerAddress, } from "./runtime-form-controller-signals";
 import { readPhiRuntimeFormControllerWidgetId } from "./runtime-form-controller-requirement";
 import { readPhiRuntimeFormFieldSignalValue, readPhiRuntimeFormTouchedSignalValue, readPhiRuntimeFormValiditySignalValue, readPhiRuntimeFormValuesSignalValue, } from "./runtime-form-state";
+import { isPhiRecord } from "../../helpers/is-record";
+import { readPhiCsrfToken } from "../../helpers/csrf-token";
+import { resolvePhiFormRelayArea } from "./form-relay-area";
 /**
  * Who the Controller's answer is for.
  *
@@ -23,16 +26,38 @@ function resolveFormOwnerReceiver(instanceKey) {
     const widgetId = readPhiRuntimeFormControllerWidgetId(instanceKey);
     return widgetId ? createPhiSignalAddress("cms", widgetId) : "broadcast";
 }
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 function isPhiRuntimeFormSubmitSignalValue(value) {
-    if (!isRecord(value) || !isRecord(value.values)) {
+    if (!isPhiRecord(value) || !isPhiRecord(value.values)) {
         return false;
     }
     return (typeof value.formId === "string" &&
         (value.phase === "submit" || value.phase === "confirm"));
 }
+/**
+ * One submit to the Site's form relay, carrying what the relay may not work out for itself.
+ *
+ * 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.
+ */
+async function submitPhiFormToRelay(value, area) {
+    const csrfToken = await readPhiCsrfToken().catch(() => "");
+    return fetch("/api/site/forms", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            ...(csrfToken ? { "x-csrf-token": csrfToken } : {}),
+        },
+        body: JSON.stringify({
+            formId: value.formId,
+            phase: value.phase,
+            area,
+            values: value.values,
+        }),
+    });
+}
 function emitControllerFeedback(dispatchSignal, baseSignal, input) {
     dispatchSignal({
         ...baseSignal,
@@ -101,17 +126,7 @@ export function PhiRuntimeFormControllerMount({ address, instanceKey, context, r
             value: true,
             valueType: "boolean",
         });
-        void fetch("/api/site/forms", {
-            method: "POST",
-            headers: {
-                "content-type": "application/json",
-            },
-            body: JSON.stringify({
-                formId: signal.value.formId,
-                phase: signal.value.phase,
-                values: signal.value.values,
-            }),
-        })
+        void submitPhiFormToRelay(signal.value, resolvePhiFormRelayArea(signalPartition))
             .then(async (response) => {
             const payload = (await response.json().catch(() => null));
             return {

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

@@ -8,7 +8,7 @@ export declare const PHI_RUNTIME_FORM_CONTROLLER_PLUGIN: {
     description: string;
     iconFamily: string;
     flags: "multiInstance"[];
-    allowedMountScopes: ("area" | "site" | "page")[];
+    allowedMountScopes: ("area" | "page" | "site")[];
     runtimeSignals: {
         emits: ({
             readonly id: "values";

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

@@ -1,5 +1,5 @@
 import type { PhiCmsWidgetRuntimeControllerRequirementResolver, PhiRuntimeControllerRequirement } from "../../types";
-import type { PhiCmsFormWidgetConfig } from "../../plugins/runtime-modules/core/widgets/form/config";
+import type { PhiCmsFormWidgetConfig } from "./form-widget-config";
 /**
  * How a Widget's Form Controller is named, written once and read back once.
  *