@aglyn/plugins-forms 1.0.0-beta.246 → 1.0.0-beta.247

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/plugins-forms",
-  "version": "1.0.0-beta.246",
+  "version": "1.0.0-beta.247",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,19 +25,19 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/aglyn": "1.0.0-beta.246",
-    "@aglyn/shared-data-enums": "1.0.0-beta.246",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.246",
-    "@aglyn/shared-ui-jsx": "1.0.0-beta.246",
-    "@aglyn/shared-ui-jsx-forms": "1.0.0-beta.246",
-    "@aglyn/shared-ui-snackstack": "1.0.0-beta.246",
-    "@aglyn/shared-util-email": "1.0.0-beta.246",
-    "@aglyn/shared-util-http": "1.0.0-beta.246",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.246",
-    "@aglyn/shared-util-tools": "1.0.0-beta.246",
-    "@aglyn/tenant-data-admin": "1.0.0-beta.246",
-    "@aglyn/tenant-feature-instance": "1.0.0-beta.246",
-    "@aglyn/tenant-runtime": "1.0.0-beta.246",
+    "@aglyn/aglyn": "1.0.0-beta.247",
+    "@aglyn/shared-data-enums": "1.0.0-beta.247",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.247",
+    "@aglyn/shared-ui-jsx": "1.0.0-beta.247",
+    "@aglyn/shared-ui-jsx-forms": "1.0.0-beta.247",
+    "@aglyn/shared-ui-snackstack": "1.0.0-beta.247",
+    "@aglyn/shared-util-email": "1.0.0-beta.247",
+    "@aglyn/shared-util-http": "1.0.0-beta.247",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.247",
+    "@aglyn/shared-util-tools": "1.0.0-beta.247",
+    "@aglyn/tenant-data-admin": "1.0.0-beta.247",
+    "@aglyn/tenant-feature-instance": "1.0.0-beta.247",
+    "@aglyn/tenant-runtime": "1.0.0-beta.247",
     "@swc/helpers": "0.5.23"
   },
   "peerDependencies": {

package/src/lib/components/form.d.ts

@@ -201,6 +201,15 @@ export declare const parseFieldOptions: (options?: string) => string[];
 declare const FormField: import("react").ForwardRefExoticComponent<FormFieldProps & import("react").RefAttributes<HTMLDivElement>>;
 export declare const formSchema: Aglyn.ComponentSchema<FormProps>;
 export declare const formFieldSchema: Aglyn.ComponentSchema<FormFieldProps>;
+/**
+ * A field as a preset: the all-in-one Form Field's props rebuilt as MUI's
+ * separate form elements by `formFieldToElements` — the same function the
+ * backfill migrates saved fields with, so a field added today and a field
+ * migrated from a Form Field are the same tree. Ids are left `null` (fresh
+ * ones are minted at insertion) and every node names `mui`, the bundle that
+ * registers it.
+ */
+export declare function fieldPresetData(props: FormFieldProps): Aglyn.NodePresetData;
 export declare const formPresets: Aglyn.PresetSchema[];
 /**
  * The composed section a form usually arrives inside.

package/src/lib/components/form.js

@@ -27,6 +27,7 @@ import { parseFormUnavailableRefusal } from "../model/form-unavailable.js";
 import { mdiEmailFastOutline, mdiEmailOutline, mdiFormTextbox } from "@aglyn/shared-data-mdi";
 import { isSameOriginPath } from "@aglyn/shared-util-http/safe-redirect";
 import Alert from "@mui/material/Alert";
+import Box from "@mui/material/Box";
 import Button from "@mui/material/Button";
 import Checkbox from "@mui/material/Checkbox";
 import FormControl from "@mui/material/FormControl";
@@ -40,9 +41,11 @@ import Radio from "@mui/material/Radio";
 import RadioGroup from "@mui/material/RadioGroup";
 import Rating from "@mui/material/Rating";
 import Stack from "@mui/material/Stack";
+import { useForkRef } from "@mui/material/utils";
 import TextField from "@mui/material/TextField";
 import { createContext, forwardRef, useCallback, useContext, useEffect, useRef, useState } from "react";
 import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { formFieldToElements, LEGACY_FORM_FIELD_COMPONENT_ID } from "../model/form-field-elements.js";
 import { generatePresetId } from "../utils/generate-preset-id.js";
 /*
  * The heading and the stack this block's form sits inside are mui elements,
@@ -73,6 +76,39 @@ export const FORM_FIELD_ID = 'formField';
  * A form whose consent field never mounted posts no key, and its opt-in is
  * recorded for the one site the visitor is on.
  */ export const CONSENT_GROUP_INPUT = '__consentGroup';
+/**
+ * The class on a form's built-in submit button. It hides while the form holds
+ * a Button the author placed with Type: Submit (see the Form's `:has` rule).
+ */ const BUILT_IN_SUBMIT_CLASS = 'aglyn-form-submit-built-in';
+/**
+ * The consent-group sentence (AGL-3320), as the all-in-one Form Field draws it
+ * under the opt-in, and as the Form draws it for a form built from MUI's own
+ * form elements, which know nothing of consent. The Form's copy hides while a
+ * Form Field's is on the page, so a form never shows it twice.
+ */ const FIELD_CONSENT_NOTE_CLASS = 'aglyn-form-consent-note-field';
+const FORM_CONSENT_NOTE_CLASS = 'aglyn-form-consent-note';
+/**
+ * Whether the form's opt-in is one of MUI's form elements (an input named as
+ * the declared opt-in field) rather than an all-in-one Form Field, which
+ * draws its own sentence. Read off the rendered form after mount: the
+ * elements know nothing of consent, and until it is read the form shows no
+ * sentence and posts no key — the safe way to be early.
+ */ function useOptInDrawnByElements(formRef, fieldName) {
+    const [drawn, setDrawn] = useState(false);
+    useEffect(()=>{
+        const form = formRef.current;
+        if (!form || !fieldName) {
+            setDrawn(false);
+            return;
+        }
+        const hasInput = Array.from(form.elements).some((element)=>element.name === fieldName);
+        setDrawn(hasInput && !form.querySelector(`.${FIELD_CONSENT_NOTE_CLASS}`));
+    }, [
+        formRef,
+        fieldName
+    ]);
+    return drawn;
+}
 /**
  * The disclosure a Form fetched, handed to the fields inside it. A context
  * because the answer flows DOWN, from the one request the Form makes to the
@@ -179,6 +215,8 @@ const REVEAL_NODE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
     ]);
     const { hostId } = Aglyn.useSite();
     const siteFetch = Aglyn.useSiteFetch();
+    const formRef = useRef(null);
+    const handleRef = useForkRef(ref, formRef);
     // Resolves the redirect screen like ScreenLink does (rename-safe) and
     // flags editing surfaces, where outcomes must never fire (AGL-557).
     const { href: redirectScreenHref, suppressNavigation } = Aglyn.useScreenLink(afterSubmit === 'redirect' ? redirectScreenId : undefined);
@@ -265,6 +303,7 @@ const REVEAL_NODE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
         formId,
         siteFetch
     ]);
+    const optInDrawnByElements = useOptInDrawnByElements(formRef, disclosure == null ? void 0 : disclosure.fieldName);
     const handleSubmit = useCallback(async (event)=>{
         event.preventDefault();
         if (!hostId || status === 'sending') return;
@@ -437,12 +476,30 @@ const REVEAL_NODE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
         });
     }
     return /*#__PURE__*/ _jsxs(Stack, _extends({
-        ref: ref,
+        ref: handleRef,
         component: "form",
         spacing: 2,
+        // Gap, not margins, between children: a form turned into a row with
+        // the Styles panel's Flex direction lines its input and button up
+        // instead of pushing every item after the first down a step.
+        useFlexGap: true,
         onSubmit: handleSubmit,
         onInput: handleFirstInput
     }, rest, {
+        sx: [
+            {
+                // A Button placed in the form with Type: Submit is the form's
+                // button — styled like any element — so the built-in one steps
+                // aside. CSS rather than a registration, so the server's first
+                // paint is already right.
+                [`&:has(button[type="submit"]:not(.${BUILT_IN_SUBMIT_CLASS})) .${BUILT_IN_SUBMIT_CLASS}`]: {
+                    display: 'none'
+                }
+            },
+            ...Array.isArray(rest['sx']) ? rest['sx'] : [
+                rest['sx']
+            ]
+        ],
         children: [
             revealSelector ? /*#__PURE__*/ _jsx("style", {
                 children: `${revealSelector}{display:none !important}`
@@ -451,6 +508,20 @@ const REVEAL_NODE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
                 value: disclosure,
                 children: children
             }),
+            disclosure && optInDrawnByElements ? /*#__PURE__*/ _jsxs(Box, {
+                className: FORM_CONSENT_NOTE_CLASS,
+                children: [
+                    /*#__PURE__*/ _jsx(FormHelperText, {
+                        children: disclosure.text
+                    }),
+                    /*#__PURE__*/ _jsx("input", {
+                        type: "hidden",
+                        name: CONSENT_GROUP_INPUT,
+                        value: disclosure.key,
+                        readOnly: true
+                    })
+                ]
+            }) : null,
             /*#__PURE__*/ _jsx("input", {
                 type: "text",
                 name: "website",
@@ -511,6 +582,7 @@ const REVEAL_NODE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
             /*#__PURE__*/ _jsx(Button, {
                 type: "submit",
                 variant: "contained",
+                className: BUILT_IN_SUBMIT_CLASS,
                 disabled: status === 'sending',
                 sx: {
                     alignSelf: 'flex-start'
@@ -586,6 +658,7 @@ Form.displayName = 'AglynForm';
     const consentNote = disclosure && describesOptIn ? /*#__PURE__*/ _jsxs(_Fragment, {
         children: [
             /*#__PURE__*/ _jsx(FormHelperText, {
+                className: FIELD_CONSENT_NOTE_CLASS,
                 children: disclosure.text
             }),
             /*#__PURE__*/ _jsx("input", {
@@ -937,7 +1010,61 @@ export const formFieldSchema = {
         }
     ]
 };
-export const formPresets = [
+/**
+ * A field as a preset: the all-in-one Form Field's props rebuilt as MUI's
+ * separate form elements by `formFieldToElements` — the same function the
+ * backfill migrates saved fields with, so a field added today and a field
+ * migrated from a Form Field are the same tree. Ids are left `null` (fresh
+ * ones are minted at insertion) and every node names `mui`, the bundle that
+ * registers it.
+ */ export function fieldPresetData(props) {
+    const built = formFieldToElements({
+        $id: 'field',
+        componentId: LEGACY_FORM_FIELD_COMPONENT_ID,
+        props: props
+    });
+    if (!built) throw new Error('formFieldToElements refused a Form Field');
+    const nest = (id)=>{
+        var _node_nodes, _node_props;
+        const node = built.nodes[id];
+        const children = ((_node_nodes = node.nodes) != null ? _node_nodes : []).map(String);
+        return _extends({
+            $id: null,
+            componentId: node.componentId,
+            pluginId: node.pluginId,
+            props: (_node_props = node.props) != null ? _node_props : {}
+        }, children.length ? {
+            nodes: children.map(nest)
+        } : {});
+    };
+    return nest(built.rootId);
+}
+/** The name/email/message fields every contact form starts with. */ const contactFields = ()=>[
+        fieldPresetData({
+            fieldName: 'name',
+            label: 'Name',
+            required: true
+        }),
+        fieldPresetData({
+            fieldName: 'email',
+            label: 'Email',
+            fieldType: 'email',
+            required: true
+        }),
+        fieldPresetData({
+            fieldName: 'message',
+            label: 'Message',
+            fieldType: 'textarea',
+            required: true
+        })
+    ];
+/*
+ * The all-in-one Form Field has no preset: every piece of a field is its own
+ * element in the mui plugin now (Form Control, Form Label, Input, …, with
+ * Text/Email/Message/Dropdown/Radio/Checkbox/Rating field presets there), so
+ * the Add Element picker no longer offers it. Its component and schema stay
+ * registered so a document nobody has migrated keeps drawing and editing.
+ */ export const formPresets = [
     {
         $id: generatePresetId(FORM_ID, 'contact'),
         type: Aglyn.NodeType.PRESET,
@@ -958,70 +1085,16 @@ export const formPresets = [
             props: {
                 formName: 'Contact'
             },
-            nodes: [
-                {
-                    $id: null,
-                    componentId: FORM_FIELD_ID,
-                    pluginId: BUNDLE_ID,
-                    props: {
-                        fieldName: 'name',
-                        label: 'Name',
-                        required: true
-                    }
-                },
-                {
-                    $id: null,
-                    componentId: FORM_FIELD_ID,
-                    pluginId: BUNDLE_ID,
-                    props: {
-                        fieldName: 'email',
-                        label: 'Email',
-                        fieldType: 'email',
-                        required: true
-                    }
-                },
-                {
-                    $id: null,
-                    componentId: FORM_FIELD_ID,
-                    pluginId: BUNDLE_ID,
-                    props: {
-                        fieldName: 'message',
-                        label: 'Message',
-                        fieldType: 'textarea',
-                        required: true
-                    }
-                }
-            ]
-        }
-    },
-    {
-        $id: generatePresetId(FORM_FIELD_ID),
-        type: Aglyn.NodeType.PRESET,
-        displayName: 'Form Field',
-        pluginId: BUNDLE_ID,
-        description: 'Single input inside a form',
-        category: Aglyn.ComponentCategory.FORMS,
-        icon: {
-            path: mdiFormTextbox.path,
-            sx: {
-                color: 'info.main'
-            }
-        },
-        data: {
-            $id: null,
-            componentId: FORM_FIELD_ID,
-            pluginId: BUNDLE_ID,
-            props: {
-                fieldName: 'field',
-                label: 'Field'
-            }
+            nodes: contactFields()
         }
     },
     /*
-   * The marketing consent field as one preset rather than a recipe. Its props
-   * are the platform's `MARKETING_CONSENT_FORM_FIELD`, which every place that adds
-   * this field reads, so each adds the same unticked one-option checkbox. It
-   * records consent once the form names it as its Marketing consent field.
+   * The marketing consent field as one preset rather than a recipe. It is the
+   * platform's `MARKETING_CONSENT_FORM_FIELD` rebuilt as elements — a lone,
+   * unticked, not-required Checkbox named `marketingConsent` in a Choice
+   * Label whose words say what the person agrees to and are also what the box
+   * posts — so every place that adds this field adds the same one. It records
+   * consent once the form names it as its Marketing consent field.
    */ {
         $id: generatePresetId(FORM_FIELD_ID, 'marketing-consent'),
         type: Aglyn.NodeType.PRESET,
@@ -1035,12 +1108,7 @@ export const formPresets = [
                 color: 'info.main'
             }
         },
-        data: {
-            $id: null,
-            componentId: FORM_FIELD_ID,
-            pluginId: BUNDLE_ID,
-            props: _extends({}, Aglyn.MARKETING_CONSENT_FORM_FIELD)
-        }
+        data: fieldPresetData(_extends({}, Aglyn.MARKETING_CONSENT_FORM_FIELD))
     }
 ];
 /**
@@ -1099,32 +1167,12 @@ export const formPresets = [
                         submitLabel: 'Send message',
                         successMessage: 'Thanks — we will get back to you soon.'
                     },
-                    nodes: [
-                        contactField('name', 'Name'),
-                        contactField('email', 'Email', {
-                            fieldType: 'email'
-                        }),
-                        contactField('message', 'Message', {
-                            fieldType: 'textarea'
-                        })
-                    ]
+                    nodes: contactFields()
                 }
             ]
         }
     }
 ];
-function contactField(fieldName, label, extra) {
-    return {
-        $id: null,
-        componentId: FORM_FIELD_ID,
-        pluginId: BUNDLE_ID,
-        props: _extends({
-            fieldName,
-            label,
-            required: true
-        }, extra)
-    };
-}
 export { Form, FormField };
 export default Form;