@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/forms.js

@@ -0,0 +1,777 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The form entity: what a form IS, separately from the shape an author drew.
+ *
+ * `docs/specs/reusable-forms.md` §2. Before this module a form's whole
+ * identity was `formName` — the free-text caption an author typed into an
+ * inspector field, copied onto each submission at write time and reconciled
+ * with nothing. Renaming a form split its history; two pages sharing a label
+ * were one list. A document at `hosts/{hostId}/forms/{formId}` is the identity
+ * those surfaces were reading a caption in place of.
+ *
+ * Pure and dependency-free on purpose. This barrel reaches client bundles
+ * through `app-utils/index`, so nothing here may import a Node builtin — the
+ * constraint that holds `personKey` in its own module one directory over.
+ * Everything that needs Firestore or `node:crypto` lives at the call sites.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { FORMS_PLUGIN_ID } from "../plugin-manager/enabled-plugins.js";
+import { submissionMonthKey } from "./form-abuse-ceiling.js";
+/**
+ * The `componentId` of the node that RENDERS a form, and of the node that
+ * renders one of its fields.
+ *
+ * Persisted in screen, layout, component and form documents — never rename.
+ * Restated as constants because the walkers below, the promotion route and the
+ * graft all have to name the same two ids, and a copy that drifted would read
+ * as "this page has no form" rather than as an error.
+ */ export const FORM_COMPONENT_ID = 'form';
+export const FORM_FIELD_COMPONENT_ID = 'formField';
+/**
+ * The prop on a `form` node naming the entity it is a placement OF.
+ *
+ * Persisted in screen documents — never rename.
+ */ export const FORM_ID_PROP = 'formId';
+/**
+ * What `/api/forms/submit` answers a submission to a site that switched Forms
+ * off (AGL-3029). A visitor reads it, so it names no plugin and no setting.
+ */ export const FORMS_OFF_FOR_SITE_REFUSAL = 'This site is not accepting form submissions';
+/**
+ * The marketing plugin's id, as the submission door below names it. Core
+ * holds no import of the plugin; the catalog is where the string is defined.
+ */ const MARKETING_PLUGIN_ID = 'marketing';
+/**
+ * The plugin whose door a submission to `/api/forms/submit` came through
+ * (AGL-3029) — the plugin that must run on the site for it to be accepted.
+ *
+ * The endpoint is shared. A form element posts to it, and so does a Marketing
+ * popup's email capture, which is a Marketing element rather than a form: a
+ * site that switched Forms off and still shows its popup must not silently
+ * lose every address the popup collects. The popup names its door in the
+ * body; everything else is a form's.
+ *
+ * A body that names a form ENTITY or a dataset binding is a form's, whatever
+ * door it claims. Those are what a form element sends and a popup never does,
+ * so the popup door cannot be used to file rows under a form, or into a
+ * dataset, on a site that switched Forms off.
+ */ export function formSubmissionDoorPlugin(body) {
+    var _ref;
+    const namesFormData = Boolean(String((_ref = body == null ? void 0 : body['formId']) != null ? _ref : '').trim()) || Boolean(body == null ? void 0 : body['datasetBinding']);
+    return (body == null ? void 0 : body['door']) === 'popup' && !namesFormData ? MARKETING_PLUGIN_ID : FORMS_PLUGIN_ID;
+}
+/**
+ * How many forms one query for a site's catalog reads.
+ *
+ * ⛔ **NOT the allowance.** How many forms a site may hold is
+ * `PLAN_ENTITLEMENTS[plan].formsPerHost`, enforced at creation through
+ * `checkQuota` in `/api/hosts/resources`. A surface that shows a customer
+ * their ceiling MUST read that entitlement — this number is larger, so
+ * reading it instead overstates the cap on every plan.
+ *
+ * What this bounds is a READ. `hosts/{hostId}/forms` is small enough to list
+ * in one page, and the listing surfaces (the submissions filter, the entity
+ * picker) say so — but a bound below the allowance would make them silently
+ * drop forms the customer made and can see elsewhere, which is the invisible
+ * half of a wrong limit and the expensive one to discover.
+ *
+ * So it sits at or above every per-plan allowance, with headroom for the
+ * catalogs that legitimately exceed one: a per-org contract override, and any
+ * site that built past a ceiling before it was lowered. `forms.spec.ts` pins
+ * that relationship rather than trusting the two numbers to be moved
+ * together. A catalog past even this needs real pagination, not a larger
+ * constant.
+ */ export const FORMS_MAX_PER_HOST = 1000;
+/**
+ * Whether a form has been retired — see {@link FormDocument.archivedAt}.
+ *
+ * PRESENCE, not a number. Absent, `null` and `0` are "in use"; any other
+ * value is a retirement marker.
+ *
+ * ⛔ Deliberately NOT shaped like `isPipelineArchived`, which asks for a
+ * positive number. A pipeline stores its own numeric stamp; a form's is
+ * written by whatever retired it, and the marker already in production on at
+ * least one form is a Firestore `Timestamp` rather than a number. The two
+ * readers that predate this function — the list filter and
+ * `/api/health/funnel`'s probe — both test truthiness, so a stricter rule
+ * here does not tighten anything: it just disagrees with them, and the
+ * disagreement surfaces as a retired form reappearing in the catalog while
+ * the funnel goes on ignoring it.
+ *
+ * Measured, not assumed: with the numeric rule this function un-hid a form
+ * the probe was still skipping, and the two counts were 5 against 4.
+ *
+ * ⚠️ Asked of the STORED document. A caller that has already filtered a list
+ * must not re-derive this from a display flag; the field is the fact.
+ */ export function isFormArchived(form) {
+    return Boolean(form == null ? void 0 : form.archivedAt);
+}
+export const FORM_STAT_KINDS = [
+    'views',
+    'starts',
+    'submissions',
+    'leads'
+];
+/** The next month after `period`, or `null` for a key that is not one. */ function nextPeriod(period) {
+    const match = /^(\d{4})-(\d{2})$/.exec(period);
+    if (!match) return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    if (month < 1 || month > 12) return null;
+    return month === 12 ? `${year + 1}-01` : `${year}-${String(month + 1).padStart(2, '0')}`;
+}
+/**
+ * A form's history as a dense month series, from the first month anything was
+ * recorded to the last.
+ *
+ * ⛔ THE SERIES NEVER STARTS BEFORE THE COUNTER DID. A month with no key is
+ * two different facts — "nothing happened" and "nothing was counted yet" —
+ * and they are told apart by WHERE the month falls: inside the recorded range
+ * an absent key is a true zero, because the counter was live and wrote
+ * nothing; before it, there is no measurement to draw and the series simply
+ * does not extend there. Padding to a fixed twelve months would render the
+ * form's pre-counter history as a row of confident zeros.
+ *
+ * Interior gaps ARE filled, at zero, so a quiet month reads as a quiet month
+ * rather than closing up and making two distant months look adjacent.
+ *
+ * @param stats - the stored counters, or nothing.
+ * @param maxPeriods - how many of the most recent months to return.
+ * @returns oldest first, so a chart reads left to right. Empty when nothing
+ *          has ever been recorded.
+ */ export function formPeriodSeries(stats, maxPeriods = 12) {
+    const periods = stats == null ? void 0 : stats.periods;
+    if (!periods) return [];
+    const keys = Object.keys(periods).filter((key)=>/^\d{4}-(0[1-9]|1[0-2])$/.test(key)).sort();
+    if (!keys.length) return [];
+    const series = [];
+    const last = keys[keys.length - 1];
+    let cursor = keys[0];
+    // Bounded by the span rather than by a `while (true)`: a stored key far in
+    // the future would otherwise walk the calendar forever.
+    for(let step = 0; cursor && step <= 1200; step += 1){
+        var _periods_cursor, _month_views, _month_starts, _month_submissions, _month_leads;
+        const month = (_periods_cursor = periods[cursor]) != null ? _periods_cursor : {};
+        series.push({
+            period: cursor,
+            views: Number((_month_views = month.views) != null ? _month_views : 0),
+            starts: Number((_month_starts = month.starts) != null ? _month_starts : 0),
+            submissions: Number((_month_submissions = month.submissions) != null ? _month_submissions : 0),
+            leads: Number((_month_leads = month.leads) != null ? _month_leads : 0)
+        });
+        if (cursor === last) break;
+        cursor = nextPeriod(cursor);
+    }
+    return maxPeriods > 0 && series.length > maxPeriods ? series.slice(series.length - maxPeriods) : series;
+}
+/**
+ * Sum `of` and `over` across exactly the months in which `over` was recorded.
+ *
+ * This is what stops a rate being a lie of arithmetic. `views` began being
+ * counted the day the beacon shipped and `submissions` has counted since the
+ * form entity existed, so dividing the lifetime totals answers "submissions
+ * ever, over views since Tuesday" — a number that is not wrong by a little.
+ *
+ * A month is IN the window when it carries a non-zero `over`, not merely a
+ * key: a month the beacon never reported is not a month with no views, it is
+ * a month with no measurement, and including it would deflate every rate
+ * taken over the window by however long the counter was dark.
+ *
+ * @returns `periods: 0` when nothing qualifies, which every caller must
+ *          render as a dash rather than as a zero rate.
+ */ export function formStatsWindow(stats, over, of) {
+    var _ref;
+    const window = {
+        periods: 0,
+        over: 0,
+        of: 0
+    };
+    for (const month of Object.values((_ref = stats == null ? void 0 : stats.periods) != null ? _ref : {})){
+        var _ref1, _ref2;
+        const denominator = Number((_ref1 = month == null ? void 0 : month[over]) != null ? _ref1 : 0);
+        if (!Number.isFinite(denominator) || denominator <= 0) continue;
+        window.periods += 1;
+        window.over += denominator;
+        const numerator = Number((_ref2 = month == null ? void 0 : month[of]) != null ? _ref2 : 0);
+        if (Number.isFinite(numerator)) window.of += numerator;
+    }
+    return window;
+}
+/**
+ * The month key a moment falls in, or `null` for a moment that is not one.
+ *
+ * UTC, through {@link submissionMonthKey}, because that is the function every
+ * writer of `stats.periods` keys by. A month derived any other way reads zero
+ * on exactly the months the two definitions disagree about — which is the
+ * boundary month, the one a reader is most likely to be asking about.
+ */ export function formPeriodKey(atMs) {
+    if (typeof atMs !== 'number' || !Number.isFinite(atMs)) return null;
+    return submissionMonthKey(new Date(atMs));
+}
+/** The counters, with nothing recorded for any of them. */ function emptyTotals(periods) {
+    return {
+        views: null,
+        starts: null,
+        submissions: null,
+        leads: null,
+        periods
+    };
+}
+/** A stored counter as a number, or `null` where nothing was stored. */ function countedStat(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * Sum a form's counters — over its whole history, or over a span of months.
+ *
+ * ## Lifetime and windowed are different questions, and the caller picks
+ *
+ * The flat counters on {@link FormStats} have counted since the form entity
+ * existed. Passing no range returns those, and `periods: null` says so, so a
+ * surface can label the figure lifetime instead of implying it belongs to
+ * whatever the surface is about.
+ *
+ * Passing a range sums `stats.periods` instead, over exactly the month keys
+ * inside it. The two can differ by a lot in both directions: the month series
+ * began later than the flat counters, so a windowed total over a form's whole
+ * history can still be smaller than its lifetime total.
+ *
+ * ## What `null` means here, and why an in-range zero is not it
+ *
+ * A counter stays `null` unless some in-range month actually carries it. This
+ * is the same rule {@link formStatsWindow} applies to a rate's denominator,
+ * and it exists for the same reason: a month that carries `submissions` and
+ * no `leads` key is not a month with zero leads, it is a month in which
+ * nothing counted leads.
+ *
+ * ## Whole months, and a range boundary that lands inside one
+ *
+ * `stats.periods` is keyed by calendar month, so the finest a windowed total
+ * can be is a month. A range that starts on the 20th takes that whole month,
+ * including the days before it. A caller reporting a windowed figure has to
+ * say the window is measured in whole months; nothing here can narrow it.
+ *
+ * @param stats - the stored counters, or nothing.
+ * @param range - the months to confine the sum to. Omitted, or with neither
+ *                end, gives lifetime totals.
+ */ export function formStatsTotals(stats, range) {
+    var _ref, _ref1, _ref2;
+    const from = (_ref = range == null ? void 0 : range.from) != null ? _ref : null;
+    const to = (_ref1 = range == null ? void 0 : range.to) != null ? _ref1 : null;
+    if (!from && !to) {
+        return {
+            views: countedStat(stats == null ? void 0 : stats.views),
+            starts: countedStat(stats == null ? void 0 : stats.starts),
+            submissions: countedStat(stats == null ? void 0 : stats.submissions),
+            leads: countedStat(stats == null ? void 0 : stats.leads),
+            periods: null
+        };
+    }
+    const totals = emptyTotals(0);
+    for (const [key, month] of Object.entries((_ref2 = stats == null ? void 0 : stats.periods) != null ? _ref2 : {})){
+        var _totals_periods;
+        // The same key shape `formPeriodSeries` accepts. A stored key of another
+        // shape is not a month and cannot be compared against a range as one.
+        if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(key)) continue;
+        // Lexical comparison IS chronological for a zero-padded `YYYY-MM`.
+        if (from && key < from) continue;
+        if (to && key > to) continue;
+        totals.periods = ((_totals_periods = totals.periods) != null ? _totals_periods : 0) + 1;
+        for (const kind of FORM_STAT_KINDS){
+            var _totals_kind;
+            const value = countedStat(month == null ? void 0 : month[kind]);
+            if (value === null) continue;
+            totals[kind] = ((_totals_kind = totals[kind]) != null ? _totals_kind : 0) + value;
+        }
+    }
+    return totals;
+}
+export const FORM_SLUG_MAX_LENGTH = 64;
+export const FORM_DISPLAY_NAME_MAX_LENGTH = 100;
+/**
+ * A stable, url-safe handle for a form, derived from its display name.
+ *
+ * The slug is NOT the identity — `formId` is, and the slug is free to be
+ * regenerated. It exists so a console URL and an export filename can name a
+ * form in something a human recognizes without either becoming a second
+ * identity the way `formName` did.
+ *
+ * @returns the slug, or `''` when the input reduces to nothing — a caller
+ *          must fall back to the document id rather than store an empty slug.
+ */ export function normalizeFormSlug(input) {
+    return String(input != null ? input : '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, FORM_SLUG_MAX_LENGTH).replace(/-+$/g, '');
+}
+const FORM_FIELD_TYPES = new Set([
+    'text',
+    'email',
+    'textarea',
+    'select',
+    'radio',
+    'checkbox',
+    'rating'
+]);
+/**
+ * Splits a `FormField` node's newline- or comma-separated choice list.
+ *
+ * Restated rather than imported from `libs/plugins/mui`: this module is in the
+ * foundation layer and a plugin may not be a dependency of it. The two must
+ * agree, and `forms.spec.ts` asserts they do against the same inputs
+ * `parseFieldOptions` is specified on.
+ */ function parseDeclaredOptions(options) {
+    return String(options != null ? options : '').split(/[\n,]/).map((entry)=>entry.trim()).filter(Boolean);
+}
+/** Child ids of a node in the stored map form, in the author's order. */ function childIdsOf(node) {
+    return Array.isArray(node == null ? void 0 : node.nodes) ? node.nodes : [];
+}
+/**
+ * Every `formField` descendant of `formNodeId`, in the order the author
+ * placed them.
+ *
+ * Depth-first pre-order, because that IS the reading order of the rendered
+ * form and the order a per-form submission list wants its columns in. A
+ * breadth-first walk would interleave the fields of two adjacent groups.
+ *
+ * Nesting between the form and its fields is arbitrary — the `Form` runtime
+ * makes a point of riding the DOM precisely so it needs no React context — so
+ * the walk cannot assume fields are direct children.
+ *
+ * Repeated and unknown ids are skipped, which bounds a cyclic document.
+ */ export function collectFormFieldNodeIds(nodes, formNodeId, formFieldComponentId = FORM_FIELD_COMPONENT_ID) {
+    if (!(nodes == null ? void 0 : nodes[formNodeId])) return [];
+    const found = [];
+    const seen = new Set([
+        formNodeId
+    ]);
+    const stack = [
+        ...childIdsOf(nodes[formNodeId])
+    ].reverse();
+    while(stack.length){
+        var _nodes_id;
+        const id = stack.pop();
+        if (seen.has(id) || !nodes[id]) continue;
+        seen.add(id);
+        if (((_nodes_id = nodes[id]) == null ? void 0 : _nodes_id.componentId) === formFieldComponentId) found.push(id);
+        // Pushed reversed so the first child is popped first — the walk is
+        // pre-order, and a nested field must not overtake its own siblings.
+        const children = childIdsOf(nodes[id]);
+        for(let index = children.length - 1; index >= 0; index -= 1){
+            stack.push(children[index]);
+        }
+    }
+    return found;
+}
+/**
+ * Reads a form's declared field list off the nodes an author already drew.
+ *
+ * This is the whole of what adoption has to invent, and it invents nothing:
+ * `fieldName`, `fieldType`, `label`, `required`, `options` and
+ * `datasetFieldId` are all already props on the `formField` nodes. A form
+ * adopted from a page therefore declares exactly the form that page was
+ * already submitting.
+ *
+ * A field with no `fieldName` is DROPPED rather than defaulted. The runtime
+ * falls back to `name = fieldName || 'field'`, so several unnamed fields
+ * collapse onto one submission key — declaring them would put a key in the
+ * schema that does not identify a value.
+ *
+ * A duplicate `fieldName` keeps its FIRST occurrence, matching the submission
+ * the runtime produces: `FormData` entries under one key are joined into that
+ * one key, so the second node contributes no separate value.
+ */ export function formFieldDeclsFromNodes(nodes, formNodeId, formFieldComponentId = FORM_FIELD_COMPONENT_ID) {
+    const declarations = [];
+    const claimed = new Set();
+    for (const id of collectFormFieldNodeIds(nodes, formNodeId, formFieldComponentId)){
+        var _ref, _props_fieldName, _props_fieldType, _props_label, _props_datasetFieldId;
+        var _nodes_id;
+        const props = (_ref = nodes == null ? void 0 : (_nodes_id = nodes[id]) == null ? void 0 : _nodes_id.props) != null ? _ref : {};
+        const fieldName = String((_props_fieldName = props['fieldName']) != null ? _props_fieldName : '').trim();
+        if (!fieldName || claimed.has(fieldName)) continue;
+        claimed.add(fieldName);
+        const rawType = String((_props_fieldType = props['fieldType']) != null ? _props_fieldType : 'text');
+        const options = parseDeclaredOptions(props['options']);
+        const label = String((_props_label = props['label']) != null ? _props_label : '').trim();
+        const datasetFieldId = String((_props_datasetFieldId = props['datasetFieldId']) != null ? _props_datasetFieldId : '').trim();
+        declarations.push(_extends({
+            fieldName,
+            fieldType: FORM_FIELD_TYPES.has(rawType) ? rawType : 'text'
+        }, label ? {
+            label
+        } : {}, props['required'] === true ? {
+            required: true
+        } : {}, options.length ? {
+            options
+        } : {}, datasetFieldId ? {
+            datasetFieldId
+        } : {}));
+    }
+    return declarations;
+}
+/**
+ * Finds every `form` node in one document's node map.
+ *
+ * The corpus and the shape are the *Used by* scan's: a flat
+ * `Record<NodeId, AglynNodeSchema>` per screen, layout and component
+ * definition. That scan is idle until asked, for the reason its card states
+ * in full — reading every screen and every layout on mount is the
+ * expensive-read shape this codebase has a standing rule against — and this
+ * one inherits that posture rather than re-arguing it.
+ */ export function discoverFormNodes(nodes, source, ids = {}) {
+    var _ids_form, _ids_formField;
+    const formComponentId = (_ids_form = ids.form) != null ? _ids_form : FORM_COMPONENT_ID;
+    const formFieldComponentId = (_ids_formField = ids.formField) != null ? _ids_formField : FORM_FIELD_COMPONENT_ID;
+    const found = [];
+    for (const [nodeId, node] of Object.entries(nodes != null ? nodes : {})){
+        var _node_props, _props_formId;
+        if ((node == null ? void 0 : node.componentId) !== formComponentId) continue;
+        const props = (_node_props = node.props) != null ? _node_props : {};
+        const boundId = String((_props_formId = props['formId']) != null ? _props_formId : '').trim();
+        found.push(_extends({
+            sourceKind: source.kind,
+            sourceId: source.id
+        }, source.name ? {
+            sourceName: source.name
+        } : {}, {
+            nodeId,
+            // Mirrors the runtime default: an unnamed form submits as `Form`, so
+            // that is the caption its history is filed under and the one an
+            // adoption has to claim.
+            formName: normalizeSubmissionFormName(props['formName'])
+        }, boundId ? {
+            formId: boundId
+        } : {}, {
+            fields: formFieldDeclsFromNodes(nodes, nodeId, formFieldComponentId)
+        }));
+    }
+    return found;
+}
+/**
+ * Whether any node in this map PLACES a form entity (as opposed to merely
+ * drawing an unbound form inline).
+ *
+ * The cost gate in front of the forms read, and cheap on purpose: one scan of
+ * a map the caller already holds, against a read that is a whole collection
+ * query. Most pages carry no form at all, and a page whose form nodes are all
+ * unbound has nothing an entity could contribute — either way there is nothing
+ * for the graft to resolve, so the query buys nothing.
+ *
+ * Says nothing about whether the named form EXISTS or is published; that is
+ * settled by the graft, against documents this cannot see.
+ */ export function placesFormEntity(nodes) {
+    for (const node of Object.values(nodes != null ? nodes : {})){
+        var _node_props;
+        if ((node == null ? void 0 : node.componentId) !== FORM_COMPONENT_ID) continue;
+        const formId = (_node_props = node.props) == null ? void 0 : _node_props[FORM_ID_PROP];
+        if (typeof formId === 'string' && formId.trim()) return true;
+    }
+    return false;
+}
+/**
+ * Whether any node in this map places THIS form.
+ *
+ * The per-id half of {@link placesFormEntity}, and the predicate a usage scan
+ * asks of a screen, a layout or a component definition. Deliberately the same
+ * reader the graft resolves against: a scan that disagreed about what counts
+ * as a placement would drop the caches of the wrong pages, and the pages it
+ * missed would serve the old form for the whole revalidate window with nothing
+ * recording that they were skipped.
+ */ export function nodesPlaceForm(nodes, formId) {
+    if (!formId) return false;
+    for (const node of Object.values(nodes != null ? nodes : {})){
+        var _node_props;
+        if ((node == null ? void 0 : node.componentId) !== FORM_COMPONENT_ID) continue;
+        const bound = (_node_props = node.props) == null ? void 0 : _node_props[FORM_ID_PROP];
+        if (typeof bound === 'string' && bound.trim() === formId) return true;
+    }
+    return false;
+}
+/**
+ * The `form` node inside a form's OWN design.
+ *
+ * A form document's tree holds exactly one, because the document IS that
+ * form — but the tree is a flat map under a synthetic canvas root, so the
+ * node has to be found rather than assumed to be the root itself.
+ *
+ * Here rather than at each surface because every reader of a form's design
+ * needs it before it can ask anything else: the form's page to run
+ * `checkFormContract`, the promotion route to publish, the preview to draw,
+ * {@link formDesignReboundTo} to rewrite the binding. A caller that found
+ * the node its own way and one that found it this way must agree, or a
+ * design reads as "no form here" on one surface and as bound on the next.
+ */ export function formNodeIdIn(nodes) {
+    return Object.keys(nodes != null ? nodes : {}).find((id)=>{
+        var _nodes_id;
+        return (nodes == null ? void 0 : (_nodes_id = nodes[id]) == null ? void 0 : _nodes_id.componentId) === FORM_COMPONENT_ID;
+    });
+}
+/**
+ * The same design, naming `identity` instead of whichever form it named
+ * before — or `null` when it already did.
+ *
+ * ## Why a copied design must be rewritten rather than carried
+ *
+ * A form's design names its own form in a prop (AGL-3024). That binding is
+ * what `/api/forms/submit` stamps a submission with and what the form's own
+ * submission list is an equality on, so a design that travels to a SECOND
+ * form — duplicated, imported, installed from a starter — arrives naming the
+ * first one, and every submission the second form collects is filed under the
+ * first. Nothing about that is visible: the copy renders, the visitor
+ * submits, the row lands, and the copy's own list simply never grows.
+ * `checkFormContract` calls it `form-id-unbound`, and it is the one violation
+ * a copy CAUSES rather than inherits.
+ *
+ * So every path that gives a stored design to a different form rebinds it
+ * here, with the same two props the Forms page's Create stamps on a new one:
+ * the id the submissions are keyed on, and the caption they are labelled
+ * with in the Inbox. Leaving the caption behind is the quieter half of the
+ * same bug — the copy's submissions arrive titled with the source's name.
+ *
+ * `null` for "nothing to write", so a caller holding a compressed tree can
+ * skip the decode-rewrite-encode round trip entirely in the common case.
+ * A design with no form node in it returns `null` too: there is no binding
+ * to move, and inventing one is not this function's decision.
+ *
+ * Pure — the input map and its nodes are not changed.
+ */ export function formDesignReboundTo(nodes, identity) {
+    var _identity_formId, _identity_formName;
+    const formId = String((_identity_formId = identity.formId) != null ? _identity_formId : '').trim();
+    if (!formId || !nodes) return null;
+    const requested = String((_identity_formName = identity.formName) != null ? _identity_formName : '').trim();
+    const formName = requested ? requested.slice(0, FORM_DISPLAY_NAME_MAX_LENGTH) : '';
+    const rebound = {};
+    let changed = false;
+    for (const entry of Object.entries(nodes)){
+        var _ref, _props_FORM_ID_PROP;
+        const [id, node] = entry;
+        const props = (_ref = node == null ? void 0 : node.props) != null ? _ref : {};
+        if ((node == null ? void 0 : node.componentId) !== FORM_COMPONENT_ID) {
+            rebound[id] = node;
+            continue;
+        }
+        const bound = String((_props_FORM_ID_PROP = props[FORM_ID_PROP]) != null ? _props_FORM_ID_PROP : '').trim();
+        if (bound === formId && (!formName || props['formName'] === formName)) {
+            rebound[id] = node;
+            continue;
+        }
+        changed = true;
+        rebound[id] = _extends({}, node, {
+            props: _extends({}, props, {
+                [FORM_ID_PROP]: formId
+            }, formName ? {
+                formName
+            } : {})
+        });
+    }
+    return changed ? rebound : null;
+}
+/**
+ * The placement kind that makes a placed form render its ENTITY'S design.
+ *
+ * Until this existed the entity's tree was written on every publish and read
+ * by nothing: a form's fields had to be redrawn on each page that placed it,
+ * and editing the form propagated nowhere. The two documents disagreed the
+ * moment either changed, and the page always won.
+ *
+ * `replacesAuthoredChildren` is what makes that propagation real, and it is
+ * the reason the resolution rule is strict. The rule, stated once:
+ *
+ * - Entity has a published design → the entity's fields ARE the form. Whatever
+ *   the page drew inside the form node is discarded, exactly as a reusable
+ *   instance's child list is replaced by its definition's. This is what "edit
+ *   the form once" means; a merge would render a page's stale copy of a field
+ *   beside the entity's current one.
+ * - Entity has no published design, is archived away, or the `formId` names
+ *   nothing → the form node is left completely alone, inline fields included.
+ *   Every form built before the entity existed is in this state, so this is
+ *   the branch that keeps the live site rendering exactly what it renders
+ *   today.
+ *
+ * A deleted or unpublished entity therefore degrades to the page's own copy
+ * rather than to an empty form — the same fail-open posture the component
+ * graft takes for an unresolvable `refId`, and for the same reason: a
+ * document going missing must not take a published page's content with it.
+ *
+ * The discard is a COMPOSE-time one, so it takes nothing away permanently:
+ * the page's fields stay in its document, and clearing the binding brings
+ * them straight back. That is what makes binding an existing hand-built form
+ * to an entity a reversible act rather than a destructive one.
+ */ export function placedFormPlacement(formsById) {
+    return {
+        componentId: FORM_COMPONENT_ID,
+        refProp: FORM_ID_PROP,
+        definitionsById: formsById,
+        replacesAuthoredChildren: true
+    };
+}
+/**
+ * The caption as the submit route stores it.
+ *
+ * Restated here so discovery and the backfill compare the same string the
+ * route wrote: `String(formName ?? 'Form').slice(0, 100)`. A differently
+ * derived caption on either side would make every legacy match miss, silently
+ * and in the safe direction — which is the failure that looks like success.
+ */ export function normalizeSubmissionFormName(value) {
+    return String(value != null ? value : '').trim() ? String(value).slice(0, FORM_DISPLAY_NAME_MAX_LENGTH) : 'Form';
+}
+/** The page path as the submit route stores it. */ export function normalizeSubmissionPath(value) {
+    return String(value != null ? value : '').slice(0, 500);
+}
+/**
+ * Which adopted form, if any, a pre-entity submission belongs to.
+ *
+ * ⛔ **An ambiguous submission is left UNSTAMPED, always.** The two failure
+ * modes are not symmetric and the asymmetry is the whole rule:
+ *
+ *  - An unmatched row is still in the Inbox, still readable, still exportable
+ *    over `/v1`. It is missing from ONE form's list, the Forms page says how
+ *    many rows are in that state, and a later adoption can still claim it.
+ *  - A wrongly stamped row is filed under a form it was never sent to. It
+ *    leaves the Inbox's *Unassigned* view, joins a stranger's submission list,
+ *    and nothing on any screen says it moved. It is invisible, and invisible
+ *    is not recoverable.
+ *
+ * So the match is on the PAIR. `formName` alone is a caption two pages may
+ * legitimately share — that shared caption is the defect the form entity
+ * exists to fix, and using it as the migration key would carry the defect into
+ * the migration. `path` is what tells two same-named forms apart, and it only
+ * does so when it was distinct, so both must agree and exactly one form may
+ * claim the pair.
+ *
+ * @returns the form id to stamp, or `null` to leave the row alone. Never a
+ *          best guess.
+ */ export function matchSubmissionToForm(submission, candidates) {
+    const formName = normalizeSubmissionFormName(submission.formName);
+    const path = normalizeSubmissionPath(submission.path);
+    // A submission that recorded no path cannot be disambiguated by one, and
+    // the pair rule has nothing to stand on. Older rows genuinely predate the
+    // field; they stay unstamped rather than falling back to the caption.
+    if (!path) return null;
+    const matched = candidates.filter((candidate)=>{
+        var _candidate_legacyMatch, _candidate_legacyMatch1;
+        return ((_candidate_legacyMatch = candidate.legacyMatch) == null ? void 0 : _candidate_legacyMatch.formName) === formName && Array.isArray((_candidate_legacyMatch1 = candidate.legacyMatch) == null ? void 0 : _candidate_legacyMatch1.paths) && candidate.legacyMatch.paths.includes(path);
+    });
+    return matched.length === 1 ? matched[0].formId : null;
+}
+/**
+ * The value of the declared consent field, as a marketing opt-in.
+ *
+ * ⛔ THE FACT OF SUBMISSION IS NOT AN OPT-IN, and a form that declares no
+ * consent field produces no consent record — on any plan, at any time. This
+ * reads ONE field, named by the form's own `consentFieldName`, and asks
+ * whether the visitor ticked it.
+ *
+ * That is not in tension with the standing rule that consent is never
+ * inferred: a checkbox the visitor ticked IS an explicit checkbox. What the
+ * entity adds is a declared place to look, in place of the closed name list
+ * the route has to fall back on when no form is bound.
+ *
+ * What counts as the tick is {@link isConsentCheckboxTicked}'s, asked with
+ * the consent field's own declaration from `form.fields`.
+ *
+ * Returns `false`, never `undefined`: every writer downstream stores consent
+ * absent-or-true and must never write `false` over an opt-in captured
+ * elsewhere.
+ */ export function readFormDeclaredConsent(form, fields) {
+    var _ref;
+    const fieldName = String((_ref = form == null ? void 0 : form.consentFieldName) != null ? _ref : '').trim();
+    if (!fieldName || !fields) return false;
+    const declaration = Array.isArray(form == null ? void 0 : form.fields) ? form.fields.find((entry)=>(entry == null ? void 0 : entry.fieldName) === fieldName) : undefined;
+    return isConsentCheckboxTicked(fields[fieldName], declaration);
+}
+/**
+ * Whether a posted value ticks a consent checkbox.
+ *
+ * A tick arrives in one of two shapes. A box with no text of its own posts
+ * one of {@link AFFIRMATIVE_CHECKBOX_VALUES}. A Checkboxes field posts the
+ * TEXT of the option that was ticked — which is what lets its option say what
+ * the person agrees to — so when the field's declaration is a checkbox with
+ * exactly one option, that option's text, alone, is a tick too: compared as
+ * the renderer draws it, trimmed, or as a list holding only it. A field with
+ * several options is a question with several answers, and none of them is
+ * the opt-in by its text.
+ *
+ * ⛔ The declaration must come from the STORED form document, never from the
+ * request: a declaration a caller could send would let any submission name
+ * its own words as the opt-in.
+ */ export function isConsentCheckboxTicked(value, declaration) {
+    if (value === true) return true;
+    if (AFFIRMATIVE_CHECKBOX_VALUES.has(String(value != null ? value : '').trim().toLowerCase())) {
+        return true;
+    }
+    const option = soleCheckboxOption(declaration);
+    if (!option) return false;
+    const posted = Array.isArray(value) ? value.length === 1 ? value[0] : undefined : value;
+    return typeof posted === 'string' && posted.trim() === option;
+}
+/** A checkbox declaration's one option, or `null` for any other declaration. */ function soleCheckboxOption(declaration) {
+    if ((declaration == null ? void 0 : declaration.fieldType) !== 'checkbox' || !Array.isArray(declaration.options)) {
+        return null;
+    }
+    const options = declaration.options.map((option)=>String(option != null ? option : '').trim()).filter(Boolean);
+    return options.length === 1 ? options[0] : null;
+}
+/** Checkbox values a browser form actually posts for a ticked box. */ export const AFFIRMATIVE_CHECKBOX_VALUES = new Set([
+    'true',
+    'on',
+    'yes',
+    '1',
+    'checked'
+]);
+/**
+ * The field names the submit route reads an opt-in from when the form
+ * declares no consent field.
+ *
+ * A CLOSED list rather than a substring match on "consent": a merchant's
+ * field called `consentToTreatment` on a clinic intake form is a different
+ * instrument entirely, and matching it would manufacture a marketing basis
+ * out of a medical one. Compared after {@link isMarketingConsentFieldName}'s
+ * normalization, so `Subscribe to newsletter` and `subscribeToNewsletter`
+ * are one name.
+ */ export const MARKETING_CONSENT_FIELD_NAMES = new Set([
+    'marketingconsent',
+    'marketingoptin',
+    'emailoptin',
+    'newsletteroptin',
+    'subscribe',
+    'subscribetonewsletter'
+]);
+/**
+ * Whether a field, by its name alone, is one the submit route reads an
+ * opt-in out of when no consent field is declared.
+ *
+ * Asked of a DESIGN by the publish check and of a PAYLOAD by the route, so
+ * the two cannot disagree about which undeclared field counts as consent.
+ */ export function isMarketingConsentFieldName(name) {
+    return MARKETING_CONSENT_FIELD_NAMES.has(String(name != null ? name : '').toLowerCase().replace(/[^a-z]/g, ''));
+}
+/**
+ * The marketing consent field: the props the Forms editor's **Marketing
+ * consent** preset places on a Form Field, and the ones a form generated from
+ * a brief carries.
+ *
+ * A Checkboxes field with ONE option, unticked and not required. The option
+ * says what the person agrees to, because a Checkboxes field posts the text
+ * of the option that was ticked and {@link isConsentCheckboxTicked} reads that
+ * text as the tick. So the option holds no comma and no line break: the
+ * Options setting starts a new box at each, and a second box is an answer
+ * that is not the opt-in. A site owner may reword the label and the option;
+ * the form names the field as its `consentFieldName` for a tick to count.
+ */ export const MARKETING_CONSENT_FORM_FIELD = {
+    fieldName: 'marketingConsent',
+    label: 'Marketing emails',
+    fieldType: 'checkbox',
+    options: 'Email me news and offers',
+    required: false
+};
+
+//# sourceMappingURL=forms.js.map