@phis/ui 0.2.0 → 0.3.0

package/components/forms/content-entry-forms.js

@@ -0,0 +1,328 @@
+import { definePhiRuntimeModuleForm } from "./form-registry";
+import { flattenPhiFormLabels } from "./form-labels";
+import { PHI_FORM_FIELD_PROVIDER_KEYS, PHI_FORM_LINK_TARGET_LABEL_KEYS, PHI_FORM_VALIDATION_PROVIDER_KEYS, createPhiSharedFormProviderKey, } from "./form-provider-contract";
+import { readPhiServerApiCredentials } from "../../helpers/phis-server-credentials";
+import { resolvePhiContentEntryEditorApiPaths, } from "../../constants/content-entry-kinds";
+import { PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS } from "../../constants/core-data-provider-keys";
+/** Where the page that places the entry Form names the Site's source language, for the empty "Written in". */
+export const PHI_CONTENT_ENTRY_SOURCE_LOCALE_PLACEHOLDER_CONFIG_KEY = "sourceLocalePlaceholder";
+const label = (key, fallback) => ({ kind: "label", key, fallback });
+const required = (key, fallback) => [{
+        providerKey: PHI_FORM_VALIDATION_PROVIDER_KEYS.required,
+        message: label(key, fallback),
+    }];
+function entryFields(kind) {
+    return [
+        /*
+         * Empty for a new entry, which is how one `PUT` serves both: with an id it is that entry, without one it
+         * is a new entry at the slug below.
+         */
+        { key: "contentId", fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.hidden },
+        /*
+         * The version the row showed, sent back as the base of the save: a save that does not build on the
+         * current version is refused rather than overwriting somebody else's (phis-server CONTENT.md).
+         */
+        { key: "versionId", fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.hidden },
+        {
+            key: "slug",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.text,
+            label: label("slugLabel", "Address"),
+            placeholder: label("slugPlaceholder", "news-entry-address"),
+            /*
+             * Core's own rule (`ENTRY_SLUG_PATTERN` in the entries route), stated here so a space or a capital is
+             * answered at the field rather than by a refused save.
+             */
+            validation: [
+                ...required("slugError", "An address is required."),
+                {
+                    providerKey: PHI_FORM_VALIDATION_PROVIDER_KEYS.pattern,
+                    message: label("slugError", "Lower-case letters, digits and hyphens only."),
+                    config: { source: "^[a-z0-9][a-z0-9-]{0,119}$" },
+                },
+            ],
+        },
+        {
+            key: "title",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.text,
+            label: label("titleLabel", "Title"),
+            validation: required("titleError", "A title is required."),
+        },
+        {
+            key: "subtitle",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.text,
+            label: label("subtitleLabel", "Subtitle"),
+        },
+        {
+            key: "content",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.textarea,
+            label: label("contentLabel", "Body"),
+            placeholder: label("contentPlaceholder", "Markdown"),
+            validation: required("contentError", "A body is required."),
+            config: { rows: 8 },
+        },
+        // A Page of the Public Area, where the list is read, or an address elsewhere -- never a typed path.
+        {
+            key: "link",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.linkTarget,
+            label: label("linkLabel", "Link"),
+            config: { area: "public" },
+        },
+        /*
+         * Offered from what the Site already uses, and typed where a tag is new: a Site with no tagged entry
+         * yet has nothing to pick. The string is a tag's identity, so Core lower-cases and deduplicates what it
+         * is given, and the offer keeps the spellings to the ones already in use.
+         */
+        {
+            key: "tags",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.multiSelect,
+            label: label("tagsLabel", "Tags"),
+            optionsProvider: { providerKey: PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS.contentEntryTags },
+            // `kind` names whose tags are offered; the Options Provider reads it from the field.
+            config: { allowCustom: true, kind },
+        },
+        /*
+         * The Site's languages, handed over by the page that places the Form (`site-locales-config.ts`). Empty
+         * means the Site's own language, which is why the field clears and its placeholder names that language:
+         * the page writes its label into the placement as `sourceLocalePlaceholder`.
+         */
+        {
+            key: "sourceLocale",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.select,
+            label: label("sourceLocaleLabel", "Written in"),
+            placeholder: { kind: "config", key: PHI_CONTENT_ENTRY_SOURCE_LOCALE_PLACEHOLDER_CONFIG_KEY, fallback: "The Site's source language" },
+            optionsProvider: { providerKey: PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS.siteLocales },
+            config: { allowClear: true },
+        },
+        {
+            key: "translate",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.switch,
+            label: label("translateLabel", "May be translated"),
+            initialValue: true,
+        },
+    ];
+}
+const publicationFields = [
+    { key: "contentId", fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.hidden },
+    // The version the Publisher saw in the row is the one that goes live, not whatever was saved since.
+    { key: "versionId", fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.hidden },
+    /*
+     * Both optional, and both meaning something when empty: no publication date keeps the one the entry has
+     * or takes now, no expiry means none. A publish states the whole term, which is why neither carries over
+     * silently from the last one.
+     */
+    {
+        key: "publishedAt",
+        fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.datetime,
+        label: label("publishedAtLabel", "Published from"),
+        // Empty is the moment of publishing, or the date an entry already has: Core takes now where none is.
+        placeholder: label("publishedAtPlaceholder", "Now"),
+    },
+    {
+        key: "expiresAt",
+        fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.datetime,
+        label: label("expiresAtLabel", "Until"),
+        placeholder: label("expiresAtPlaceholder", "No end"),
+    },
+];
+/*
+ * Who an entry is attributed to and what it is filed under: the Publisher's, and not a word of the text,
+ * so its own Form (phis-server CONTENT.md, Curation).
+ *
+ * Both choices are stated on every save, and "none" is a choice of its own -- an empty value, which Core
+ * reads as nobody or no category. A cleared select would send nothing, and Core reads nothing as "leave it".
+ */
+function curationFields(kind) {
+    return [
+        { key: "contentId", fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.hidden },
+        {
+            key: "authorUserId",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.select,
+            label: label("authorLabel", "Author"),
+            optionsProvider: { providerKey: PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS.contentEntryAuthors },
+            config: { kind },
+        },
+        {
+            key: "categoryId",
+            fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.select,
+            label: label("categoryLabel", "Category"),
+            optionsProvider: { providerKey: PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS.contentEntryCategoryOptions },
+            config: { kind },
+        },
+    ];
+}
+/*
+ * One category, stated whole: a new one without an id, a correction with one. The address may be left
+ * empty and is then made from the label, the way Core makes a tag's.
+ */
+const categoryFields = [
+    { key: "id", fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.hidden },
+    {
+        key: "label",
+        fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.text,
+        label: label("categoryNameLabel", "Name"),
+        validation: required("categoryNameError", "A name is required."),
+    },
+    {
+        key: "slug",
+        fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.text,
+        label: label("slugLabel", "Address"),
+        placeholder: label("categorySlugPlaceholder", "Made from the name"),
+    },
+    {
+        key: "sortOrder",
+        fieldProviderKey: PHI_FORM_FIELD_PROVIDER_KEYS.number,
+        label: label("categoryOrderLabel", "Order"),
+    },
+];
+function entryDescriptor(formId, ownerModuleId, fields) {
+    return { schemaVersion: 1, key: formId, labelSetKey: `${ownerModuleId}/labels/forms`, fields };
+}
+async function loadContentEntryFormLabels(context) {
+    const { getPhiContentEntryEditorLabels } = await import("../widgets/label-sets/content-entries");
+    const labels = await getPhiContentEntryEditorLabels({
+        apiBaseUrl: readPhiServerApiCredentials().apiBaseUrl,
+        internalToken: readPhiServerApiCredentials().internalToken,
+        locale: context.runtime.locale.current,
+    });
+    return flattenPhiFormLabels({
+        saveLabel: labels.form.save,
+        savingLabel: labels.form.save,
+        slugLabel: labels.columns.slug,
+        slugPlaceholder: labels.form.slugPlaceholder,
+        slugError: labels.form.slugError,
+        titleLabel: labels.columns.title,
+        titleError: labels.form.titleError,
+        subtitleLabel: labels.form.subtitleLabel,
+        contentLabel: labels.form.contentLabel,
+        contentPlaceholder: labels.form.contentPlaceholder,
+        contentError: labels.form.contentError,
+        linkLabel: labels.form.linkLabel,
+        [PHI_FORM_LINK_TARGET_LABEL_KEYS.none]: labels.form.link.none,
+        [PHI_FORM_LINK_TARGET_LABEL_KEYS.page]: labels.form.link.page,
+        [PHI_FORM_LINK_TARGET_LABEL_KEYS.external]: labels.form.link.external,
+        [PHI_FORM_LINK_TARGET_LABEL_KEYS.pagePlaceholder]: labels.form.link.pagePlaceholder,
+        [PHI_FORM_LINK_TARGET_LABEL_KEYS.externalPlaceholder]: labels.form.link.externalPlaceholder,
+        [PHI_FORM_LINK_TARGET_LABEL_KEYS.newTab]: labels.form.link.newTab,
+        [PHI_FORM_LINK_TARGET_LABEL_KEYS.pagesUnavailable]: labels.form.link.pagesUnavailable,
+        tagsLabel: labels.columns.tags,
+        sourceLocaleLabel: labels.columns.language,
+        translateLabel: labels.form.translateLabel,
+        publishedAtLabel: labels.columns.published,
+        publishedAtPlaceholder: labels.form.publishedAtPlaceholder,
+        expiresAtLabel: labels.columns.expires,
+        expiresAtPlaceholder: labels.form.expiresAtPlaceholder,
+        authorLabel: labels.columns.author,
+        categoryLabel: labels.columns.category,
+        categoryNameLabel: labels.categories.columns.label,
+        categoryNameError: labels.categories.form.labelError,
+        categorySlugPlaceholder: labels.categories.form.slugPlaceholder,
+        categoryOrderLabel: labels.categories.columns.order,
+    });
+}
+/**
+ * A kind's Forms and their handlers, owned by the kind's Module (`CONTENT_ENTRIES.md`).
+ *
+ * One Form per act, because the acts have different authorities. The entry states words: what it says,
+ * where it lives, which language it is written in. The publication states when it is seen. Curation states
+ * who it is by and what it is filed under, and a category is one entry of the Site's order. Core keeps
+ * them apart -- content editing for the first, publishing for the rest -- so one Form covering two would be
+ * reachable by whoever may do the lesser of them.
+ *
+ * Both relay through the Form gateway with the viewer's Site session, because both endpoints are guarded by
+ * a role. Neither takes a CSRF token of its own -- the gateway adds the internal one -- and neither has a
+ * second phase. The ids and handler keys are the Module's, so two kinds never share a Form.
+ */
+export function definePhiContentEntryForms({ kind, ownerModuleId, formIds, titles, }) {
+    const handlerKeys = {
+        entry: `${kind}.entry`,
+        publication: `${kind}.publication`,
+        curation: `${kind}.curation`,
+        category: `${kind}.category`,
+    };
+    const paths = resolvePhiContentEntryEditorApiPaths(kind);
+    const forms = [
+        definePhiRuntimeModuleForm({
+            ownerModuleId,
+            areas: ["editor"],
+            formId: formIds.entry,
+            version: 1,
+            flags: 0,
+            title: titles.entry,
+            description: `The words of one ${kind} entry, stated whole.`,
+            category: "forms",
+            tags: [kind, "content"],
+            descriptor: entryDescriptor(formIds.entry, ownerModuleId, entryFields(kind)),
+            submitHandlerKey: handlerKeys.entry,
+            loadLabels: loadContentEntryFormLabels,
+        }),
+        definePhiRuntimeModuleForm({
+            ownerModuleId,
+            areas: ["editor"],
+            formId: formIds.publication,
+            version: 1,
+            flags: 0,
+            title: titles.publication,
+            description: `When one ${kind} entry is answered, and until when.`,
+            category: "forms",
+            tags: [kind, "publishing"],
+            descriptor: entryDescriptor(formIds.publication, ownerModuleId, publicationFields),
+            submitHandlerKey: handlerKeys.publication,
+            loadLabels: loadContentEntryFormLabels,
+        }),
+        definePhiRuntimeModuleForm({
+            ownerModuleId,
+            areas: ["editor"],
+            formId: formIds.curation,
+            version: 1,
+            flags: 0,
+            title: titles.curation,
+            description: `Who one ${kind} entry is by, and what it is filed under.`,
+            category: "forms",
+            tags: [kind, "publishing"],
+            descriptor: entryDescriptor(formIds.curation, ownerModuleId, curationFields(kind)),
+            submitHandlerKey: handlerKeys.curation,
+            loadLabels: loadContentEntryFormLabels,
+        }),
+        definePhiRuntimeModuleForm({
+            ownerModuleId,
+            areas: ["editor"],
+            formId: formIds.category,
+            version: 1,
+            flags: 0,
+            title: titles.category,
+            description: `One category ${kind} entries are filed under, stated whole.`,
+            category: "forms",
+            tags: [kind, "publishing"],
+            descriptor: entryDescriptor(formIds.category, ownerModuleId, categoryFields),
+            submitHandlerKey: handlerKeys.category,
+            loadLabels: loadContentEntryFormLabels,
+        }),
+    ];
+    /*
+     * A save states the whole entry, and a category whole, so both are a PUT; a publication is an act, so it
+     * is a POST; curation changes two things about an entry and leaves the rest, so it is a PATCH.
+     */
+    const methods = { entry: "PUT", publication: "POST", curation: "PATCH", category: "PUT" };
+    const upstreamPaths = {
+        entry: paths.entries,
+        publication: paths.publish,
+        curation: paths.curation,
+        category: paths.categories,
+    };
+    const handlers = ["entry", "publication", "curation", "category"].map((key) => ({
+        key: createPhiSharedFormProviderKey("handler", `${kind}-${key}`),
+        ownerModuleId,
+        title: `${titles[key]}`,
+        phase: "submit",
+        handlerKey: handlerKeys[key],
+        category: "forms",
+        transport: "relay",
+        method: methods[key],
+        endpointKey: null,
+        upstreamPath: upstreamPaths[key],
+        csrfPath: null,
+        requiresCsrf: false,
+        credentialPolicy: "site-session",
+    }));
+    return { forms, handlers };
+}

package/components/forms/extended-form-field-controls.js

@@ -3,7 +3,24 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { PhiCascaderControl } from "../controls/phi-cascader-control";
 import { PhiNumberControl } from "../controls/phi-number-control";
 import { PhiSliderControl } from "../controls/phi-slider-control";
+import { resolvePhiFormText } from "./form-descriptor-contract";
 import { PHI_STORAGE_SIZE_UNIT_LABEL, phiBytesToStorageSize, phiStorageSizeToBytes, } from "./storage-size";
+/**
+ * The unit beside a number, which is the value's and not the field's name ("days", not "Window (days)").
+ *
+ * A symbol nobody translates -- `ms`, `px` -- is written as a string. A word is a label reference
+ * (`{ kind: "label", key, fallback }`) and is read from the Form's labels like the field's own label,
+ * so "days" is "Tage" where the Form is German.
+ */
+function readPhiNumberFieldPrefix(prefix, labels) {
+    if (typeof prefix === "string")
+        return prefix;
+    const text = prefix;
+    if (text?.kind === "label" && typeof text.key === "string" && typeof text.fallback === "string") {
+        return resolvePhiFormText({ kind: "label", key: text.key, fallback: text.fallback }, labels);
+    }
+    return undefined;
+}
 /*
  * Field kinds most forms never have, loaded only where one is rendered: the slider, the cascader and
  * the number fields.
@@ -23,7 +40,7 @@ export const PhiSliderFormControl = ({ field, value, onChange, disabled, readOnl
     return field.config?.showInput === true ? (_jsxs("div", { style: { display: "grid", gridTemplateColumns: "minmax(96px, 1fr) minmax(0, 2fr)", gap: "var(--ant-padding-sm)", alignItems: "center", minWidth: 0 }, children: [_jsx(PhiNumberControl, { value: numericValue ?? null, min: min, max: max, step: step, precision: typeof field.config?.precision === "number" ? field.config.precision : undefined, disabled: disabled, readOnly: readOnly, style: { width: "100%" }, onChange: (nextValue) => onChange?.(nextValue) }), slider] })) : slider;
 };
 export const PhiCascaderFormControl = ({ field, value, onChange, options, placeholder, disabled, readOnly }) => (_jsx(PhiCascaderControl, { value: typeof value === "string" ? value : undefined, placeholder: placeholder, disabled: disabled, readOnly: readOnly, options: options ?? [], allowRoot: field.config?.allowRoot !== false, allowClear: field.config?.allowClear === true, separator: typeof field.config?.separator === "string" ? field.config.separator : "/", rootValue: typeof field.config?.rootValue === "string" ? field.config.rootValue : "/", normalize: field.config?.normalize === "path" ? "path" : "raw", onChange: (nextValue) => onChange?.(nextValue) }));
-export const PhiNumberFormControl = ({ id, field, value, onChange, placeholder, disabled, readOnly, }) => (_jsx(PhiNumberControl, { id: id, value: typeof value === "number" ? value : null, disabled: disabled, readOnly: readOnly, placeholder: placeholder, min: typeof field.config?.min === "number" ? field.config.min : undefined, max: typeof field.config?.max === "number" ? field.config.max : undefined, step: typeof field.config?.step === "number" ? field.config.step : undefined, precision: typeof field.config?.precision === "number" ? field.config.precision : undefined, prefix: typeof field.config?.prefix === "string" ? field.config.prefix : undefined, style: { width: "100%" }, onChange: (nextValue) => onChange?.(nextValue) }));
+export const PhiNumberFormControl = ({ id, field, value, onChange, placeholder, disabled, readOnly, labels, }) => (_jsx(PhiNumberControl, { id: id, value: typeof value === "number" ? value : null, disabled: disabled, readOnly: readOnly, placeholder: placeholder, min: typeof field.config?.min === "number" ? field.config.min : undefined, max: typeof field.config?.max === "number" ? field.config.max : undefined, step: typeof field.config?.step === "number" ? field.config.step : undefined, precision: typeof field.config?.precision === "number" ? field.config.precision : undefined, prefix: readPhiNumberFieldPrefix(field.config?.prefix, labels), style: { width: "100%" }, onChange: (nextValue) => onChange?.(nextValue) }));
 /*
  * The field holds bytes and shows megabytes, so both conversions sit on this one Control: the value a
  * form carries is bytes before it reaches here and bytes again the moment it leaves, and no submit

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

@@ -150,15 +150,6 @@ export declare function phiFormFieldFollowsLayoutColumns(input: {
  * in, and moving the first column would take the form off its own left edge.
  */
 export declare function phiFormCellOpensColumn(range: PhiFormGridRange, sibling: PhiFormGridRange): boolean;
-/**
- * `grid-column` for the two halves of a row a Form Layout may move the boundary of.
- *
- * The line is substituted by CSS rather than by us, through the custom property the Form Layout writes.
- * It has to be CSS: the Layout renders on the server and hands this form in as an already-rendered
- * child, so nothing React carries can reach from one to the other. The descriptor's own line stands as
- * the fallback, which is what a form outside any Form Layout uses.
- */
-export declare const PHI_FORM_LABEL_END_PROPERTY = "--phi-form-label-end";
 export declare function phiFormLabelGridColumn(range: PhiFormGridRange, followsLayout: boolean): string;
 export declare function phiFormControlGridColumn(range: PhiFormGridRange, followsLayout: boolean): string;
 /** The `grid-column` shorthand for a range, which is the only form CSS accepts. */

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

@@ -174,7 +174,7 @@ export function phiFormCellOpensColumn(range, sibling) {
  * child, so nothing React carries can reach from one to the other. The descriptor's own line stands as
  * the fallback, which is what a form outside any Form Layout uses.
  */
-export const PHI_FORM_LABEL_END_PROPERTY = "--phi-form-label-end";
+const PHI_FORM_LABEL_END_PROPERTY = "--phi-form-label-end";
 export function phiFormLabelGridColumn(range, followsLayout) {
     return followsLayout
         ? `1 / var(${PHI_FORM_LABEL_END_PROPERTY}, ${range.end})`

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