@phis/ui 0.2.1 → 0.4.0

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

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { isPhiRecord } from "../../helpers/is-record";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { readPhiTableActionSignalValue } from "../../types/table-signal-values";
 import { usePhiSignalListener } from "../runtime/runtime-signal-bus";
@@ -10,6 +11,7 @@ import { readPhiRuntimeConditionStateSignalValue } from "../../types/runtime-con
 import { collectPhiRuntimeValueConditions } from "../../types/runtime-condition";
 import { usePhiTableProvider } from "../widgets/client/shared/phi-table-provider";
 import { PhiFormControl } from "../controls/phi-form-control";
+import { readPhiRuntimeFormValuesSignalValue } from "./runtime-form-state";
 import { resolvePhiFormText } from "./form-descriptor-contract";
 import { PhiFormWidgetSubmitOutlet, usePhiFormWidgetSubmit } from "./phi-form-widget-frame";
 import { usePhiRuntimeFormClient } from "./runtime-form-client";
@@ -17,16 +19,24 @@ import { PhiAlertControl } from "../controls/phi-alert-control";
 import { usePhiRuntimeFormBinding } from "./runtime-form-binding";
 import { usePhiRuntimePageConditionState } from "../runtime/runtime-page-condition-state";
 import { usePhiApplicationFeedback } from "../runtime/use-phi-application-feedback";
-import { requestPhiFormGuard } from "./form-guard-client";
+import { PHI_FORM_GUARD_EXPIRED_CODE, requestPhiFormGuard, } from "./form-guard-client";
 import { usePhiFormRelayArea } from "./form-relay-area";
 import { PhiSkeletonControl } from "../controls/phi-skeleton-control";
+import { usePhiInDialogBody } from "../overlays/phi-dialog-body-context";
+/** How long before its window closes a token is renewed rather than sent: the request takes time too. */
+const PHI_FORM_GUARD_EXPIRY_MARGIN_MS = 60_000;
 const EMPTY_FORM_VALUES = {};
 export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedInitialValues, formId, formControllerAddress, widgetConfig, }) {
     const formClient = usePhiRuntimeFormClient({ controllerAddress: formControllerAddress });
     const formRef = useRef(null);
     const submitCorrelationRef = useRef(null);
     const recordIdentityRef = useRef(null);
+    // Values that arrived through `valuesSet` before the form was there to take them.
+    const pendingValuesRef = useRef(null);
+    const valuesRequestedRef = useRef(false);
     const identity = usePhiSignalIdentity();
+    // Where the placement says nothing about Enter, a dialog's body answers it (FORMS.md, `submitOnEnter`).
+    const inDialogBody = usePhiInDialogBody();
     const emitSignal = usePhiSignalEmitter(identity.sender);
     const source = widgetConfig?.source ?? null;
     const { provider, resource, bindingError } = usePhiTableProvider(source);
@@ -86,6 +96,12 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
      * payload, wrote the mount-time one into the form, and looked as though the save had been undone.
      */
     const [record, setRecord] = useState(null);
+    /*
+     * What the Form starts from: the record over the placement's own values, never instead of them. A record
+     * answers for the fields it carries, and a field it knows nothing about -- a choice the placement makes,
+     * such as whether a reply may be an internal note -- keeps what the placement said.
+     */
+    const startValues = useMemo(() => (record ? { ...configuredInitialValues, ...record } : configuredInitialValues), [configuredInitialValues, record]);
     const [loading, setLoading] = useState(source !== null);
     const [recordKey, setRecordKey] = useState("inline");
     const [conditionControllerStates, setConditionControllerStates] = useState({});
@@ -120,10 +136,10 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
     const requestReset = useCallback((correlationId = createPhiSignalCorrelationId()) => {
         formRef.current?.resetFields();
         formClient.reset({ correlationId });
-        emitCapability("resetValues", { values: record ?? configuredInitialValues }, correlationId);
+        emitCapability("resetValues", { values: startValues }, correlationId);
         emitCapability("stateChange", { dirty: false, valid: true }, correlationId);
         emitCapability("resetComplete", null, correlationId);
-    }, [configuredInitialValues, emitCapability, formClient, record]);
+    }, [emitCapability, formClient, startValues]);
     const readRecord = useCallback(async (rowIdentity, signal) => {
         if (!source) {
             return configuredInitialValues;
@@ -138,10 +154,26 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
             signal,
         });
     }, [bindingError, configuredInitialValues, provider, resource?.recordRead, source]);
+    /*
+     * The one record read in flight. Every new read aborts the one before it, and unmount aborts the
+     * last: two reads racing meant the slower one wrote `record` and `recordIdentityRef` last, so a Form
+     * opened on row B could show row A and save into it.
+     */
+    const recordLoadRef = useRef(null);
+    const beginRecordLoad = useCallback(() => {
+        recordLoadRef.current?.abort();
+        const abortController = new AbortController();
+        recordLoadRef.current = abortController;
+        return abortController;
+    }, []);
+    useEffect(() => () => {
+        recordLoadRef.current?.abort();
+        recordLoadRef.current = null;
+    }, []);
     const loadRecord = useCallback(async (rowIdentity) => {
         setLoading(true);
         setError(null);
-        const abortController = new AbortController();
+        const abortController = beginRecordLoad();
         const signal = abortController.signal;
         try {
             const values = await readRecord(rowIdentity, signal);
@@ -160,11 +192,11 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
             if (!signal.aborted)
                 setLoading(false);
         }
-    }, [readRecord]);
+    }, [beginRecordLoad, readRecord]);
     useEffect(() => {
         if (!source || widgetConfig?.openActionKey)
             return;
-        const abortController = new AbortController();
+        const abortController = beginRecordLoad();
         void readRecord(null, abortController.signal).then((values) => {
             if (abortController.signal.aborted)
                 return;
@@ -181,7 +213,7 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
                 setLoading(false);
         });
         return () => abortController.abort();
-    }, [readRecord, source, widgetConfig?.openActionKey]);
+    }, [beginRecordLoad, readRecord, source, widgetConfig?.openActionKey]);
     usePhiSignalListener(useCallback((signal) => {
         if (signal.receiver !== identity.receiver && signal.receiver !== "broadcast")
             return;
@@ -232,6 +264,17 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
         else if (route.capabilityId === "reset") {
             requestReset(signal.correlationId);
         }
+        else if (route.capabilityId === "valuesSet") {
+            const payload = readPhiRuntimeFormValuesSignalValue(signal.value);
+            if (!payload)
+                return;
+            if (formRef.current) {
+                formRef.current.setFieldsValue(payload.values);
+            }
+            else {
+                pendingValuesRef.current = { ...pendingValuesRef.current, ...payload.values };
+            }
+        }
         else if (route.capabilityId === "conditionStateChange" &&
             isPhiControllerSignalAddress(signal.sender) &&
             conditionControllerAddresses.has(signal.sender)) {
@@ -253,6 +296,13 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
             emitCapability("conditionStateRequest");
         }
     }, [conditionControllerAddresses, emitCapability]);
+    // Once per mount: asked again later, the answer would overwrite what was chosen in the meantime.
+    useEffect(() => {
+        if (valuesRequestedRef.current)
+            return;
+        valuesRequestedRef.current = true;
+        emitCapability("valuesRequest");
+    }, [emitCapability]);
     /*
      * The guard token of a form that declares one, asked for as soon as the form is in the browser.
      *
@@ -260,6 +310,11 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
      * submit against: too fast is a bot, too late is expired. It is added to the values when they are
      * submitted rather than kept in hidden fields, so resetting the form after a success cannot empty it.
      * A request that failed is forgotten, and the next submit asks again.
+     *
+     * The answer names the window the token is good for. A submit after it has closed -- a form left open
+     * past `maxSubmitMs` -- asks for a fresh token first, and a submit before a token is ready waits for
+     * it, so neither is refused. A token the server still refused as expired (`form_expired`) is forgotten
+     * and a fresh one asked for at once; that refused submit is not sent again by itself.
      */
     const guardRef = useRef(null);
     const relayArea = usePhiFormRelayArea();
@@ -276,6 +331,21 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
         if (descriptor.guard && formId)
             void readGuard().catch(() => undefined);
     }, [descriptor.guard, formId, readGuard]);
+    const renewGuard = useCallback(() => {
+        guardRef.current = null;
+        void readGuard().catch(() => undefined);
+    }, [readGuard]);
+    const readSubmittableGuard = useCallback(async () => {
+        let lease = await readGuard();
+        if (Date.now() >= lease.expiresAt - PHI_FORM_GUARD_EXPIRY_MARGIN_MS) {
+            guardRef.current = null;
+            lease = await readGuard();
+        }
+        const waitMs = lease.readyAt - Date.now();
+        if (waitMs > 0)
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+        return lease.props;
+    }, [readGuard]);
     /*
      * What the Widget presses when it draws a submit: `requestSubmit`, the same call the `submit`
      * capability makes when a Button Widget outside asks for one. One path, so the two cannot disagree
@@ -314,7 +384,7 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
             if (!raw)
                 return;
             const parsed = JSON.parse(raw);
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            if (isPhiRecord(parsed)) {
                 formRef.current?.setFieldsValue(parsed);
             }
         }
@@ -377,8 +447,12 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
         if (completed)
             submitSlot?.register(null);
     }, [completed, submitSlot]);
-    const content = loading ? _jsx(PhiSkeletonControl, { lines: 4, withTitle: true }) : (_jsxs(_Fragment, { children: [answersInPlace && error ? _jsx(PhiAlertControl, { level: "error", showIcon: true, title: error }) : null, answersInPlace && succeeded && success ? (_jsx(PhiAlertControl, { level: "success", showIcon: true, title: resolvePhiFormText(success.title, labels), description: success.text ? resolvePhiFormText(success.text, labels) : undefined })) : null, completed ? null : (_jsxs(_Fragment, { children: [_jsx(PhiFormControl, { descriptor: descriptor, labels: labels, formConfig: widgetConfig?.formConfig, initialValues: record ?? configuredInitialValues, submitOnEnter: widgetConfig?.submitOnEnter ?? false, onFormReady: (activeForm) => {
+    const content = loading ? _jsx(PhiSkeletonControl, { lines: 4, withTitle: true }) : (_jsxs(_Fragment, { children: [answersInPlace && error ? _jsx(PhiAlertControl, { level: "error", showIcon: true, title: error }) : null, answersInPlace && succeeded && success ? (_jsx(PhiAlertControl, { level: "success", showIcon: true, title: resolvePhiFormText(success.title, labels), description: success.text ? resolvePhiFormText(success.text, labels) : undefined })) : null, completed ? null : (_jsxs(_Fragment, { children: [_jsx(PhiFormControl, { descriptor: descriptor, labels: labels, formConfig: widgetConfig?.formConfig, initialValues: startValues, submitOnEnter: widgetConfig?.submitOnEnter ?? inDialogBody, onFormReady: (activeForm) => {
                             formRef.current = activeForm;
+                            if (pendingValuesRef.current) {
+                                activeForm.setFieldsValue(pendingValuesRef.current);
+                                pendingValuesRef.current = null;
+                            }
                         }, conditionControllerStates: conditionControllerStates, onValuesChange: (changed, all) => {
                             // A value moved, so whatever validation refused before is no longer what is being asked.
                             rejectedRef.current = false;
@@ -424,7 +498,7 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
                                 return;
                             }
                             try {
-                                const guard = descriptor.guard ? await readGuard() : null;
+                                const guard = descriptor.guard ? await readSubmittableGuard() : null;
                                 const result = await formClient.submit({
                                     formId,
                                     values: guard ? { ...values, ...guard } : values,
@@ -438,6 +512,8 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
                                      * for a log, and it stands in only where the code is absent or nothing maps it.
                                      */
                                     const code = typeof result.payload?.code === "string" ? result.payload.code : null;
+                                    if (code === PHI_FORM_GUARD_EXPIRED_CODE && descriptor.guard)
+                                        renewGuard();
                                     const declared = code ? descriptor.errors?.[code] : undefined;
                                     const message = declared
                                         ? resolvePhiFormText(declared, labels)

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

@@ -1,8 +1,21 @@
 import type { PhiFormGuardProps } from "./contracts";
+/** The code a submit handler answers with when the guard token is older than the Site allows. */
+export declare const PHI_FORM_GUARD_EXPIRED_CODE = "form_expired";
+/**
+ * A guard token and the window it is good for, measured on this browser's clock: `readyAt` is the
+ * first moment the handler accepts it, `expiresAt` the last. Both are taken on the safe side -- ready
+ * from when the answer arrived, expiring from when it was asked for -- so neither clock skew nor the
+ * request's own duration can put a submit outside the window the server measures.
+ */
+export type PhiFormGuardLease = {
+    props: PhiFormGuardProps;
+    readyAt: number;
+    expiresAt: number;
+};
 /**
  * Asks the Site's form relay for a guard token, for a form whose descriptor declares `guard`.
  *
  * The relay issues one only for a form whose submit handler is active in the Area the page names
  * (`usePhiFormRelayArea`), so a refusal is a wiring fault to show, not something to retry.
  */
-export declare function requestPhiFormGuard(formId: string, area: string | null): Promise<PhiFormGuardProps>;
+export declare function requestPhiFormGuard(formId: string, area: string | null): Promise<PhiFormGuardLease>;

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

@@ -1,3 +1,5 @@
+/** The code a submit handler answers with when the guard token is older than the Site allows. */
+export const PHI_FORM_GUARD_EXPIRED_CODE = "form_expired";
 /**
  * Asks the Site's form relay for a guard token, for a form whose descriptor declares `guard`.
  *
@@ -5,13 +7,22 @@
  * (`usePhiFormRelayArea`), so a refusal is a wiring fault to show, not something to retry.
  */
 export async function requestPhiFormGuard(formId, area) {
+    const requestedAt = Date.now();
     const search = new URLSearchParams({ phase: "guard", formId, ...(area ? { area } : {}) });
     const response = await fetch(`/api/site/forms?${search.toString()}`, {
         cache: "no-store",
     });
     const payload = (await response.json().catch(() => null));
-    if (!response.ok || typeof payload?.issuedAt !== "string" || typeof payload.formToken !== "string") {
+    if (!response.ok ||
+        typeof payload?.issuedAt !== "string" ||
+        typeof payload.formToken !== "string" ||
+        typeof payload.minSubmitMs !== "number" ||
+        typeof payload.maxSubmitMs !== "number") {
         throw new Error(typeof payload?.error === "string" ? payload.error : "The form could not be prepared.");
     }
-    return { issuedAt: payload.issuedAt, formToken: payload.formToken };
+    return {
+        props: { issuedAt: payload.issuedAt, formToken: payload.formToken },
+        readyAt: Date.now() + payload.minSubmitMs,
+        expiresAt: requestedAt + payload.maxSubmitMs,
+    };
 }

package/components/forms/form-labels.js

@@ -1,3 +1,4 @@
+import { isPhiRecord } from "../../helpers/is-record";
 export function flattenPhiFormLabels(value, prefix = "") {
     const labels = {};
     function visit(entry, path) {
@@ -7,7 +8,7 @@ export function flattenPhiFormLabels(value, prefix = "") {
             }
             return;
         }
-        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        if (!isPhiRecord(entry)) {
             return;
         }
         for (const [key, child] of Object.entries(entry)) {

package/components/forms/form-provider-contract.d.ts

@@ -23,6 +23,7 @@ export declare const PHI_FORM_FIELD_PROVIDER_KEYS: {
     readonly table: `${string}/${string}`;
     readonly tree: `${string}/${string}`;
     readonly upload: `${string}/${string}`;
+    readonly linkTarget: `${string}/${string}`;
 };
 export declare const PHI_AUTH_FORM_FIELD_PROVIDER_KEYS: {
     readonly termsConsent: `${string}/${string}`;
@@ -70,9 +71,24 @@ export declare const PHI_FORM_HANDLER_PROVIDER_KEYS: {
  * They live with the descriptors rather than with the Control, because a Server label loader writes them
  * and a Server module must not reach into a client component to learn their names.
  */
+/** The `link-target` field's wording, read from the Form's Label Set and falling back to English. */
+export declare const PHI_FORM_LINK_TARGET_LABEL_KEYS: {
+    readonly none: "linkTargetNone";
+    readonly page: "linkTargetPage";
+    readonly external: "linkTargetExternal";
+    readonly pagePlaceholder: "linkTargetPagePlaceholder";
+    readonly externalPlaceholder: "linkTargetExternalPlaceholder";
+    readonly newTab: "linkTargetNewTab";
+    /** Where the Pages would be, when the Site could not list them. */
+    readonly pagesUnavailable: "linkTargetPagesUnavailable";
+};
 export declare const PHI_FORM_UPLOAD_LABEL_KEYS: {
     readonly trigger: "uploadTrigger";
+    /** Beneath the trigger in an upload area (`config.presentation: "area"`): that a drop works too. */
+    readonly dropHint: "uploadDropHint";
     readonly tooMany: "uploadErrorTooMany";
+    /** Shown on the field when the Form is submitted while a file is still on its way. */
+    readonly pending: "uploadPending";
     readonly errorGeneric: "uploadErrorGeneric";
     readonly errorNetwork: "uploadErrorNetwork";
     readonly errorTooLarge: "uploadErrorTooLarge";
@@ -363,6 +379,28 @@ export declare const PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS: readonly [
         readonly type: "string";
         readonly label: "Space";
         readonly description: "`user` for the viewer's own Space.";
+    }, {
+        readonly key: "presentation";
+        readonly type: "choice";
+        readonly mode: "single";
+        readonly valueType: "string";
+        readonly label: "Presentation";
+        readonly description: "A button, or an area that also takes a drop.";
+        readonly options: {
+            value: string;
+            label: string;
+        }[];
+    }];
+}, {
+    readonly key: `${string}/${string}`;
+    readonly title: "Link";
+    readonly valueType: "json";
+    readonly presentation: "control";
+    readonly settingsFields: readonly [{
+        readonly key: "area";
+        readonly type: "string";
+        readonly label: "Area";
+        readonly description: "Whose Pages are offered; Public when empty.";
     }];
 }];
 export declare const PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS: readonly [{

package/components/forms/form-provider-contract.js

@@ -30,6 +30,7 @@ export const PHI_FORM_FIELD_PROVIDER_KEYS = {
     table: createPhiSharedFormProviderKey("field", "table"),
     tree: createPhiSharedFormProviderKey("field", "tree"),
     upload: createPhiSharedFormProviderKey("field", "upload"),
+    linkTarget: createPhiSharedFormProviderKey("field", "link-target"),
 };
 export const PHI_AUTH_FORM_FIELD_PROVIDER_KEYS = {
     termsConsent: createPhiSharedFormProviderKey("field", "auth-terms-consent"),
@@ -77,9 +78,24 @@ export const PHI_FORM_HANDLER_PROVIDER_KEYS = {
  * They live with the descriptors rather than with the Control, because a Server label loader writes them
  * and a Server module must not reach into a client component to learn their names.
  */
+/** The `link-target` field's wording, read from the Form's Label Set and falling back to English. */
+export const PHI_FORM_LINK_TARGET_LABEL_KEYS = {
+    none: "linkTargetNone",
+    page: "linkTargetPage",
+    external: "linkTargetExternal",
+    pagePlaceholder: "linkTargetPagePlaceholder",
+    externalPlaceholder: "linkTargetExternalPlaceholder",
+    newTab: "linkTargetNewTab",
+    /** Where the Pages would be, when the Site could not list them. */
+    pagesUnavailable: "linkTargetPagesUnavailable",
+};
 export const PHI_FORM_UPLOAD_LABEL_KEYS = {
     trigger: "uploadTrigger",
+    /** Beneath the trigger in an upload area (`config.presentation: "area"`): that a drop works too. */
+    dropHint: "uploadDropHint",
     tooMany: "uploadErrorTooMany",
+    /** Shown on the field when the Form is submitted while a file is still on its way. */
+    pending: "uploadPending",
     errorGeneric: "uploadErrorGeneric",
     errorNetwork: "uploadErrorNetwork",
     errorTooLarge: "uploadErrorTooLarge",
@@ -226,6 +242,31 @@ export const PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS = [
             { key: "maxFiles", type: "number", label: "Most files", min: 1, precision: 0 },
             { key: "maxBytes", type: "number", label: "Largest file", min: 1, precision: 0, prefix: "bytes" },
             { key: "space", type: "string", label: "Space", description: "`user` for the viewer's own Space." },
+            {
+                key: "presentation",
+                type: "choice",
+                mode: "single",
+                valueType: "string",
+                label: "Presentation",
+                description: "A button, or an area that also takes a drop.",
+                options: [
+                    { value: "button", label: "Button" },
+                    { value: "area", label: "Area" },
+                ],
+            },
+        ],
+    },
+    /*
+     * One link: a Page of an Area, or an address elsewhere (`REFERENCES.md`, stable internal targets). The
+     * value is the `PhiLinkTarget` itself, `null` for none. `area` names the Area whose Pages are offered.
+     */
+    {
+        key: PHI_FORM_FIELD_PROVIDER_KEYS.linkTarget,
+        title: "Link",
+        valueType: "json",
+        presentation: "control",
+        settingsFields: [
+            { key: "area", type: "string", label: "Area", description: "Whose Pages are offered; Public when empty." },
         ],
     },
 ];

package/components/forms/form-provider-registry.d.ts

@@ -1,5 +1,5 @@
 import { type ComponentType, type ReactNode } from "react";
-import type { Rule } from "antd/es/form";
+import type { PhiFormControlRule } from "../controls/phi-form-control-contract";
 import type { PhiFormFieldDescriptor, PhiFormFieldTypeProviderDescriptor, PhiFormProviderKey, PhiFormValidationProviderDescriptor, PhiFormValidationRuleDescriptor } from "../../types/form-descriptor";
 import type { PhiControlOption } from "../controls/phi-control-options";
 export type PhiFormFieldProviderProps = {
@@ -27,6 +27,13 @@ export type PhiFormFieldProviderProps = {
     formContext?: {
         getValues(): Record<string, unknown>;
         setValues(values: Record<string, unknown>): void;
+        /**
+         * Holds the Form's submit while this field's value is not complete yet, with the sentence the field
+         * shows if somebody submits anyway; `null` releases it. For a value that only arrives later -- an
+         * upload whose Asset id comes once the body is there. A submit while a hold stands does not reach
+         * the handler: it fails the way a rule fails, on this field and through `onValidationFailed`.
+         */
+        holdSubmit(fieldKey: string, reason: string | null): void;
     };
     /** What the Widget was placed with, for text a field takes from its placement rather than its form. */
     formConfig?: Readonly<Record<string, unknown>>;
@@ -41,7 +48,7 @@ export type PhiFormValidationContext = {
     message?: string;
 };
 export type PhiFormValidationProvider = Omit<PhiFormValidationProviderDescriptor, "ownerModuleId"> & {
-    createRule: (context: PhiFormValidationContext) => Rule;
+    createRule: (context: PhiFormValidationContext) => PhiFormControlRule;
 };
 export type PhiFormProviderRegistry = {
     fieldTypesByKey: ReadonlyMap<PhiFormProviderKey, PhiFormFieldTypeProvider>;

package/components/forms/form-resolution.js

@@ -1,3 +1,4 @@
+import { normalizePhiFormKey } from "../../helpers/form-id";
 import "server-only";
 import { isPhiRecord } from "../../helpers/is-record";
 export async function resolvePhiFormLabels(context) {
@@ -22,15 +23,12 @@ function deepMergeRecords(base, override) {
     }
     return result;
 }
-function normalizeFormId(value) {
-    return value.trim().toLowerCase();
-}
 export function buildPhiFormRenderTarget(definition, source) {
     return {
         key: definition.formId,
         id: definition.id ?? null,
         ownerModuleId: definition.ownerModuleId,
-        formId: normalizeFormId(definition.formId),
+        formId: normalizePhiFormKey(definition.formId),
         version: definition.version,
         source,
     };
@@ -50,7 +48,7 @@ export function resolvePhiFormDefinition({ presetDefinition, overrideDefinition,
             ...overrideDefinition,
             id: overrideDefinition.id,
             ownerModuleId: overrideDefinition.ownerModuleId,
-            formId: normalizeFormId(overrideDefinition.formId || presetDefinition.formId),
+            formId: normalizePhiFormKey(overrideDefinition.formId || presetDefinition.formId),
             title: overrideDefinition.title || presetDefinition.title,
             description: overrideDefinition.description ?? presetDefinition.description,
             category: overrideDefinition.category ?? presetDefinition.category,

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

@@ -7,11 +7,12 @@ export type PhiCmsFormWidgetConfig = PhiCmsWidgetConfigBase & {
     formId: PhiFormId | null;
     submit: PhiCmsFormWidgetSubmitPlacement;
     /**
-     * Whether Enter in a single-line field submits. Off unless the placement says so: with a second form
-     * or a search on the same page, Enter has more than one thing it could mean, and only whoever put
-     * them there knows which one it should.
+     * Whether Enter in a single-line field submits; `null` where the placement says nothing. Then it is on
+     * in a dialog's body, which asks one question, and off anywhere else: with a second form or a search
+     * on the same page, Enter has more than one thing it could mean, and only whoever put them there
+     * knows which one it should.
      */
-    submitOnEnter: boolean;
+    submitOnEnter: boolean | null;
     card: PhiCmsFormWidgetCardConfig | null;
     /**
      * How wide the form may get, measured where its fields stand rather than around the box.

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

@@ -1,10 +1,11 @@
+import { isPhiRecord } from "../../helpers/is-record";
 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)
+    return isPhiRecord(value)
         ? { ...value }
         : {};
 }
@@ -68,7 +69,7 @@ export function parsePhiFormWidgetConfig(rawConfig) {
         ...renderableBlockConfig,
         formId: isPhiFormId(normalizedFormId) ? normalizedFormId : null,
         submit: rawConfig.submit === "inline" ? "inline" : "external",
-        submitOnEnter: rawConfig.submitOnEnter === true,
+        submitOnEnter: typeof rawConfig.submitOnEnter === "boolean" ? rawConfig.submitOnEnter : null,
         /*
          * The house measure where the placement names none, and answered HERE as well as declared.
          *

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

@@ -0,0 +1,10 @@
+import { type ComponentType } from "react";
+import type { PhiFormFieldProviderProps } from "./form-provider-registry";
+/**
+ * The `link-target` field: one link, to a Page of an Area or to an address elsewhere (`FORMS.md`).
+ *
+ * `config.area` names the Area whose Pages are offered and is written into every Page target, because a
+ * Form usually stands somewhere else than the link leads -- an Editor Form linking a Public Page. The
+ * value is the `PhiLinkTarget` itself, or `null` for no link, so a save that removes one says so.
+ */
+export declare const PhiLinkTargetFormControl: ComponentType<PhiFormFieldProviderProps>;

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

@@ -0,0 +1,82 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { isPhiCmsAreaKey } from "../../constants/cms-areas";
+import { PhiLinkTargetControl } from "../widgets/client/shared/phi-link-target-control";
+import { PHI_FORM_LINK_TARGET_LABEL_KEYS } from "./form-provider-contract";
+const DEFAULT_LABELS = {
+    none: "None",
+    page: "Page",
+    external: "Address",
+    pagePlaceholder: "Select a Page",
+    externalPlaceholder: "https://example.com",
+    newTab: "Open in a new tab",
+    pagesUnavailable: "The Pages could not be loaded.",
+};
+/*
+ * One request per Area for as long as the page lives: the create and the edit dialog offer the same
+ * Pages, and a list that changed meanwhile is a Page somebody published while this one was being written.
+ * A failed request is forgotten, so the next dialog asks again.
+ */
+const pageOptionsByArea = new Map();
+function loadPageOptions(area) {
+    const cached = pageOptionsByArea.get(area);
+    if (cached)
+        return cached;
+    const request = (async () => {
+        const response = await fetch(`/api/site/page-references?area=${encodeURIComponent(area)}`, {
+            cache: "no-store",
+            credentials: "same-origin",
+            headers: { accept: "application/json" },
+        });
+        const payload = (await response.json().catch(() => null));
+        if (!response.ok || !Array.isArray(payload?.options)) {
+            throw new Error(`Page references for "${area}" answered ${response.status}.`);
+        }
+        return payload.options;
+    })();
+    pageOptionsByArea.set(area, request);
+    request.catch(() => pageOptionsByArea.delete(area));
+    return request;
+}
+/**
+ * The `link-target` field: one link, to a Page of an Area or to an address elsewhere (`FORMS.md`).
+ *
+ * `config.area` names the Area whose Pages are offered and is written into every Page target, because a
+ * Form usually stands somewhere else than the link leads -- an Editor Form linking a Public Page. The
+ * value is the `PhiLinkTarget` itself, or `null` for no link, so a save that removes one says so.
+ */
+export const PhiLinkTargetFormControl = ({ field, value, labels, disabled, readOnly, onChange, }) => {
+    const area = isPhiCmsAreaKey(field.config?.area) ? field.config.area : "public";
+    const [options, setOptions] = useState([]);
+    const [failed, setFailed] = useState(false);
+    useEffect(() => {
+        let current = true;
+        loadPageOptions(area).then((next) => {
+            if (current) {
+                setOptions(next);
+                setFailed(false);
+            }
+        }, (error) => {
+            console.warn("[phi-form] Page references could not be loaded.", { area, error });
+            if (current)
+                setFailed(true);
+        });
+        return () => {
+            current = false;
+        };
+    }, [area]);
+    const read = (key, fallback) => labels?.[key]?.trim() || fallback;
+    const controlLabels = {
+        none: read(PHI_FORM_LINK_TARGET_LABEL_KEYS.none, DEFAULT_LABELS.none),
+        page: read(PHI_FORM_LINK_TARGET_LABEL_KEYS.page, DEFAULT_LABELS.page),
+        external: read(PHI_FORM_LINK_TARGET_LABEL_KEYS.external, DEFAULT_LABELS.external),
+        // The refusal stands where the Pages would, rather than an empty list that looks like a Site without any.
+        pagePlaceholder: failed
+            ? read(PHI_FORM_LINK_TARGET_LABEL_KEYS.pagesUnavailable, DEFAULT_LABELS.pagesUnavailable)
+            : read(PHI_FORM_LINK_TARGET_LABEL_KEYS.pagePlaceholder, DEFAULT_LABELS.pagePlaceholder),
+        externalPlaceholder: read(PHI_FORM_LINK_TARGET_LABEL_KEYS.externalPlaceholder, DEFAULT_LABELS.externalPlaceholder),
+        newTab: read(PHI_FORM_LINK_TARGET_LABEL_KEYS.newTab, DEFAULT_LABELS.newTab),
+    };
+    return (_jsx(PhiLinkTargetControl, { value: value, options: options, labels: controlLabels, area: area, disabled: disabled || readOnly, onChange: onChange ? (next) => onChange(next ?? null) : undefined }));
+};

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

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { normalizePhiFormKey } from "../../helpers/form-id";
 import { phiRuntime } from "../../server-helpers/phi-runtime";
 import { getResolvedFormDefinition } from "../../gateway/form-registry";
 import { resolvePhiFormLabels } from "./form-resolution";
@@ -9,11 +10,8 @@ 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);
+    const normalizedFormId = normalizePhiFormKey(formId);
     if (!normalizedFormId) {
         return null;
     }