@phis/ui 0.1.0 → 0.2.1

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

@@ -1,12 +1,10 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { Skeleton } from "antd";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { readPhiTableActionSignalValue, } from "../../types/table-widget";
+import { readPhiTableActionSignalValue } from "../../types/table-signal-values";
 import { usePhiSignalListener } from "../runtime/runtime-signal-bus";
 import { createPhiSignalCorrelationId } from "../runtime/runtime-signal-bus";
-import { usePhiSignalEmitter, usePhiSignalIdentity } from "../runtime/runtime-signal-identity";
-import { findPhiSignalRoutesByCapabilityId } from "../../types/signals";
+import { emitPhiSignalCapability, usePhiSignalEmitter, usePhiSignalIdentity, } from "../runtime/runtime-signal-identity";
 import { isPhiControllerSignalAddress } from "../../types/signals";
 import { readPhiRuntimeConditionStateSignalValue } from "../../types/runtime-condition";
 import { collectPhiRuntimeValueConditions } from "../../types/runtime-condition";
@@ -18,7 +16,10 @@ import { usePhiRuntimeFormClient } from "./runtime-form-client";
 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 { usePhiFormRelayArea } from "./form-relay-area";
+import { PhiSkeletonControl } from "../controls/phi-skeleton-control";
 const EMPTY_FORM_VALUES = {};
 export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedInitialValues, formId, formControllerAddress, widgetConfig, }) {
     const formClient = usePhiRuntimeFormClient({ controllerAddress: formControllerAddress });
@@ -74,7 +75,17 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
     }, [initialValuesInput, loadedInitialValues, queryInitialValues]);
     const [error, setError] = useState(null);
     const [succeeded, setSucceeded] = useState(false);
-    const [record, setRecord] = useState(configuredInitialValues);
+    /*
+     * What a source read brought back, and nothing until one has. The placement's own values are not
+     * state and must not be seeded into any.
+     *
+     * They were: this started as `useState(configuredInitialValues)`, and a `useState` initializer runs
+     * once. From then on the Form was handed the values the page had been rendered with at mount, for
+     * the rest of the tab's life -- while the Widget's props went on carrying whatever the Server last
+     * said. A Settings panel that saves and then asks for its Page again got the new value in the
+     * payload, wrote the mount-time one into the form, and looked as though the save had been undone.
+     */
+    const [record, setRecord] = useState(null);
     const [loading, setLoading] = useState(source !== null);
     const [recordKey, setRecordKey] = useState("inline");
     const [conditionControllerStates, setConditionControllerStates] = useState({});
@@ -91,21 +102,17 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
         scope: identity.scope ?? "page",
     });
     const emitCapability = useCallback((capabilityId, value = null, correlationId) => {
-        for (const route of findPhiSignalRoutesByCapabilityId(widgetConfig?.signalRoutes?.emits, capabilityId)) {
-            if (route.receiver == null || (route.valueType === "json" && !route.valueSchema))
-                continue;
-            emitSignal({
-                scope: route.scope,
-                channel: route.channel,
-                action: route.action,
-                value: route.valueType === "none" ? null : value,
-                valueType: route.valueType,
-                valueSchema: route.valueSchema ?? null,
-                receiver: route.receiver,
-                ...(correlationId ? { correlationId } : {}),
-            });
-        }
+        emitPhiSignalCapability(emitSignal, widgetConfig?.signalRoutes?.emits, capabilityId, value, correlationId);
     }, [emitSignal, widgetConfig]);
+    /*
+     * That the values now in the form have already been rejected, and nothing has changed since.
+     *
+     * It exists because a submit changes the state it is triggered by: validation writes its errors onto
+     * the fields, Ant Design reports that as a field change, and a placement that reads "the state
+     * changed" as "save this" asks for the same submit again -- which fails again, for the same reason,
+     * as fast as the browser can manage. Set when validation refuses, cleared as soon as a value moves.
+     */
+    const rejectedRef = useRef(false);
     const requestSubmit = useCallback((correlationId = createPhiSignalCorrelationId()) => {
         submitCorrelationRef.current = correlationId;
         formRef.current?.submit();
@@ -178,6 +185,18 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
     usePhiSignalListener(useCallback((signal) => {
         if (signal.receiver !== identity.receiver && signal.receiver !== "broadcast")
             return;
+        /*
+         * What this form's own Controller says back is not an instruction to this form.
+         *
+         * Every form is bound to a Form Controller, and that Controller answers a command by sending it on
+         * to the form it belongs to -- same channel, same action, addressed here. The binding applies those
+         * answers; this listener is for what a Preset wired. Reading them as Preset signals made `reset`
+         * into a loop with no end: the route called `requestReset`, which tells the Controller, which sent
+         * the reset back here, which called `requestReset` again. Thousands of deliveries a second, one
+         * blocked main thread -- the Users Page froze on Cancel and its edit form never left its skeleton.
+         */
+        if (signal.sender === formControllerAddress)
+            return;
         const route = widgetConfig?.signalRoutes?.listens?.find((candidate) => candidate.channel === signal.channel &&
             candidate.action === signal.action &&
             candidate.valueType === signal.valueType &&
@@ -201,7 +220,14 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
                 void loadRecord(rowIdentity);
         }
         else if (route.capabilityId === "submit") {
-            requestSubmit(signal.correlationId);
+            /*
+             * Asked again for values already refused, with nothing changed since, this is not a second
+             * submit -- it is the first one arriving twice, and answering it is how the loop above spins. A
+             * person pressing Save is not filtered here: they are asking to be shown the reason again, and
+             * `requestSubmit` runs for them either way.
+             */
+            if (!rejectedRef.current)
+                requestSubmit(signal.correlationId);
         }
         else if (route.capabilityId === "reset") {
             requestReset(signal.correlationId);
@@ -214,7 +240,7 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
                 setConditionControllerStates((current) => ({ ...current, [signal.sender]: next.state }));
             }
         }
-    }, [conditionControllerAddresses, emitCapability, identity.receiver, loadRecord, requestReset, requestSubmit, widgetConfig]), useMemo(() => {
+    }, [conditionControllerAddresses, emitCapability, formControllerAddress, identity.receiver, loadRecord, requestReset, requestSubmit, widgetConfig]), useMemo(() => {
         const listenRoutes = widgetConfig?.signalRoutes?.listens ?? [];
         return listenRoutes.length === 0 ? null : {
             scopes: Array.from(new Set(listenRoutes.map((route) => route.scope))),
@@ -236,15 +262,16 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
      * A request that failed is forgotten, and the next submit asks again.
      */
     const guardRef = useRef(null);
+    const relayArea = usePhiFormRelayArea();
     const readGuard = useCallback(() => {
-        const pending = guardRef.current ?? requestPhiFormGuard(formId);
+        const pending = guardRef.current ?? requestPhiFormGuard(formId, relayArea);
         guardRef.current = pending;
         pending.catch(() => {
             if (guardRef.current === pending)
                 guardRef.current = null;
         });
         return pending;
-    }, [formId]);
+    }, [formId, relayArea]);
     useEffect(() => {
         if (descriptor.guard && formId)
             void readGuard().catch(() => undefined);
@@ -255,7 +282,7 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
      * about what submitting means -- the button shows the loading state of a submit somebody else
      * started, because there is only one submit to be in.
      */
-    const submitSlot = usePhiFormWidgetSubmit(() => requestSubmit(), labels?.["actions.submitLabel"]);
+    const submitSlot = usePhiFormWidgetSubmit(() => requestSubmit());
     /*
      * What has been typed, kept for as long as the tab is open, where the form asks for it.
      *
@@ -301,8 +328,31 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
      * stays to read.
      */
     const success = descriptor.success;
-    const reportSuccess = useCallback(() => {
+    /*
+     * The same outcome, said a second time where the reader is looking.
+     *
+     * Only where the placement asked for it: a Form on a Page of its own has the reader's attention and
+     * says everything it needs to say in place, while a Settings panel is one of several and a switch
+     * that saves on change shows nothing at all. What a success says is the descriptor's own words where
+     * it has them, and otherwise the placement's; a failure says what went wrong, which only the answer
+     * knows.
+     */
+    const feedback = widgetConfig?.feedback ?? null;
+    const { showMessage, showNotification } = usePhiApplicationFeedback();
+    const report = useCallback((level, content, correlationId) => {
+        if (!feedback || !content) {
+            return;
+        }
+        const options = correlationId ? { correlationId } : undefined;
+        if (feedback.mode === "notification") {
+            showNotification({ level, title: content }, options);
+            return;
+        }
+        showMessage({ level, content }, options);
+    }, [feedback, showMessage, showNotification]);
+    const reportSuccess = useCallback((correlationId = null) => {
         clearDraft();
+        report("success", (success ? resolvePhiFormText(success.title, labels) : null) ?? feedback?.successText ?? "", correlationId);
         if (!success) {
             return;
         }
@@ -310,70 +360,105 @@ export function PhiFormDescriptorRuntimeClient({ descriptor, labels, loadedIniti
         if (success.reset) {
             formRef.current?.resetFields();
         }
-    }, [clearDraft, success]);
-    const content = loading ? _jsx(Skeleton, { active: true, paragraph: { rows: 4 } }) : (_jsxs(_Fragment, { children: [error ? _jsx(PhiAlertControl, { level: "error", showIcon: true, title: error }) : null, succeeded && success ? (_jsx(PhiAlertControl, { level: "success", showIcon: true, title: resolvePhiFormText(success.title, labels), description: success.text ? resolvePhiFormText(success.text, labels) : undefined })) : null, _jsx(PhiFormControl, { descriptor: descriptor, labels: labels, formConfig: widgetConfig?.formConfig, initialValues: record ?? undefined, onFormReady: (activeForm) => {
-                    formRef.current = activeForm;
-                }, conditionControllerStates: conditionControllerStates, onValuesChange: (changed, all) => {
-                    runtimeBinding.onValuesChange(changed, all);
-                    if (draftStorageKey) {
-                        try {
-                            window.sessionStorage.setItem(draftStorageKey, JSON.stringify(all));
-                        }
-                        catch {
-                            // Storage refused; what was typed simply is not kept.
-                        }
-                    }
-                }, onBlurCapture: runtimeBinding.onBlurCapture, onSubmittingChange: (submitting) => {
-                    submitSlot?.setSubmitting(submitting);
-                    emitCapability("submitting", submitting, submitCorrelationRef.current);
-                    if (!submitting)
-                        submitCorrelationRef.current = null;
-                }, onValidationFailed: (value) => {
-                    emitCapability("validationFailed", value, submitCorrelationRef.current);
-                    submitCorrelationRef.current = null;
-                }, onStateChange: (state) => emitCapability("stateChange", state, submitCorrelationRef.current), onSubmit: async (values) => {
-                    runtimeBinding.publishSnapshot();
-                    setError(null);
-                    setSucceeded(false);
-                    const correlationId = submitCorrelationRef.current;
-                    if (widgetConfig?.execution.mode === "signal") {
-                        emitCapability("submitValues", { values }, correlationId);
-                        emitCapability("submitSuccess", { ok: true, payload: null }, correlationId);
-                        reportSuccess();
-                        return;
-                    }
-                    if (!formId) {
-                        const message = "Form submit handler is not configured.";
-                        setError(message);
-                        emitCapability("submitError", { message }, correlationId);
-                        return;
-                    }
-                    try {
-                        const guard = descriptor.guard ? await readGuard() : null;
-                        const result = await formClient.submit({
-                            formId,
-                            values: guard ? { ...values, ...guard } : values,
-                            phase: widgetConfig?.execution.phase ?? "submit",
-                            correlationId: correlationId ?? undefined,
-                        });
-                        if (!result.ok) {
-                            const message = typeof result.payload?.error === "string"
-                                ? result.payload.error
-                                : "Form submission failed.";
-                            throw new Error(message);
-                        }
-                        emitCapability("submitSuccess", { ok: result.ok, status: result.status, payload: result.payload ?? null }, correlationId);
-                        reportSuccess();
-                        const rowIdentity = recordIdentityRef.current;
-                        if (source && (rowIdentity != null || !widgetConfig?.openActionKey)) {
-                            void loadRecord(rowIdentity);
-                        }
-                    }
-                    catch (submitError) {
-                        const message = submitError instanceof Error ? submitError.message : "Form submission failed.";
-                        setError(message);
-                        emitCapability("submitError", { message }, correlationId);
-                    }
-                } }, recordKey), _jsx(PhiFormWidgetSubmitOutlet, {})] }));
+    }, [clearDraft, feedback?.successText, labels, report, success]);
+    /*
+     * Where the answer belongs is the placement's decision, and naming a place is choosing it: a Form
+     * with a `feedback` config says it there and not also in place, because two answers to one submit
+     * read as two things having happened. Field validation is untouched -- that is not an answer to a
+     * submit, it is a question about a field, and it belongs next to the field either way.
+     */
+    const answersInPlace = feedback == null;
+    /*
+     * A form that has done its one job shows only what happened. Its fields go, and so does the Widget's
+     * submit: the registration is withdrawn, which is what takes the button out of the frame.
+     */
+    const completed = succeeded && success?.complete === true;
+    useEffect(() => {
+        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) => {
+                            formRef.current = activeForm;
+                        }, conditionControllerStates: conditionControllerStates, onValuesChange: (changed, all) => {
+                            // A value moved, so whatever validation refused before is no longer what is being asked.
+                            rejectedRef.current = false;
+                            runtimeBinding.onValuesChange(changed, all);
+                            /*
+                             * Announced only where somebody wired it: `emitCapability` walks the routes this Form was
+                             * given, so a Form nobody listens to that way pays a lookup and nothing else.
+                             */
+                            emitCapability("valuesChange", { values: all });
+                            if (draftStorageKey) {
+                                try {
+                                    window.sessionStorage.setItem(draftStorageKey, JSON.stringify(all));
+                                }
+                                catch {
+                                    // Storage refused; what was typed simply is not kept.
+                                }
+                            }
+                        }, onBlurCapture: runtimeBinding.onBlurCapture, onSubmittingChange: (submitting) => {
+                            submitSlot?.setSubmitting(submitting);
+                            emitCapability("submitting", submitting, submitCorrelationRef.current);
+                            if (!submitting)
+                                submitCorrelationRef.current = null;
+                        }, onValidationFailed: (value) => {
+                            rejectedRef.current = true;
+                            emitCapability("validationFailed", value, submitCorrelationRef.current);
+                            submitCorrelationRef.current = null;
+                        }, onStateChange: (state) => emitCapability("stateChange", state, submitCorrelationRef.current), onSubmit: async (values) => {
+                            runtimeBinding.publishSnapshot();
+                            setError(null);
+                            setSucceeded(false);
+                            const correlationId = submitCorrelationRef.current;
+                            if (widgetConfig?.execution.mode === "signal") {
+                                emitCapability("submitValues", { values }, correlationId);
+                                emitCapability("submitSuccess", { ok: true, payload: null }, correlationId);
+                                reportSuccess(correlationId);
+                                return;
+                            }
+                            if (!formId) {
+                                const message = "Form submit handler is not configured.";
+                                setError(message);
+                                report("error", message, correlationId);
+                                emitCapability("submitError", { message }, correlationId);
+                                return;
+                            }
+                            try {
+                                const guard = descriptor.guard ? await readGuard() : null;
+                                const result = await formClient.submit({
+                                    formId,
+                                    values: guard ? { ...values, ...guard } : values,
+                                    phase: widgetConfig?.execution.phase ?? "submit",
+                                    correlationId: correlationId ?? undefined,
+                                });
+                                if (!result.ok) {
+                                    /*
+                                     * The code first: it is the only part of a refusal that can be said in the visitor's
+                                     * language, because the descriptor maps it to a label. `error` is what the handler wrote
+                                     * 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;
+                                    const declared = code ? descriptor.errors?.[code] : undefined;
+                                    const message = declared
+                                        ? resolvePhiFormText(declared, labels)
+                                        : typeof result.payload?.error === "string"
+                                            ? result.payload.error
+                                            : "Form submission failed.";
+                                    throw new Error(message);
+                                }
+                                emitCapability("submitSuccess", { ok: result.ok, status: result.status, payload: result.payload ?? null }, correlationId);
+                                reportSuccess(correlationId);
+                                const rowIdentity = recordIdentityRef.current;
+                                if (source && (rowIdentity != null || !widgetConfig?.openActionKey)) {
+                                    void loadRecord(rowIdentity);
+                                }
+                            }
+                            catch (submitError) {
+                                const message = submitError instanceof Error ? submitError.message : "Form submission failed.";
+                                setError(message);
+                                report("error", message, correlationId);
+                                emitCapability("submitError", { message }, correlationId);
+                            }
+                        } }, recordKey), _jsx(PhiFormWidgetSubmitOutlet, {})] }))] }));
     return content;
 }

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

@@ -2,7 +2,7 @@ import type { PhiFormGuardProps } from "./contracts";
 /**
  * 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 of the page asking,
- * so a refusal is a wiring fault to show, not something to retry.
+ * 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): Promise<PhiFormGuardProps>;
+export declare function requestPhiFormGuard(formId: string, area: string | null): Promise<PhiFormGuardProps>;

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

@@ -1,12 +1,14 @@
 /**
  * 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 of the page asking,
- * so a refusal is a wiring fault to show, not something to retry.
+ * 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 async function requestPhiFormGuard(formId) {
-    const search = new URLSearchParams({ phase: "guard", formId });
-    const response = await fetch(`/api/site/forms?${search.toString()}`, { cache: "no-store" });
+export async function requestPhiFormGuard(formId, area) {
+    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") {
         throw new Error(typeof payload?.error === "string" ? payload.error : "The form could not be prepared.");