@pilotiq/pilotiq 0.7.1 → 0.8.0

package/dist/pageData/helpers.js

@@ -0,0 +1,703 @@
+import { Field } from '../fields/Field.js';
+import { Column } from '../Column.js';
+import { SelectField } from '../fields/SelectField.js';
+import { isRepeaterField, RepeaterField } from '../fields/RepeaterField.js';
+import { isBuilderField, BuilderField } from '../fields/BuilderField.js';
+import { isServerDataElement } from '../schema/ServerDataElement.js';
+import { findActions, findRowExtraActions } from '../elements/dispatchAction.js';
+import { findForms, loadRelationRows } from '../elements/dispatchForm.js';
+import { findTables } from '../elements/dispatchTable.js';
+import { getMorphRelationDescriptor, getPrimaryKey, } from '../orm/modelDefaults.js';
+// ─── pageData shared helpers ────────────────────────────────
+//
+// URL-tag helpers (stamp dispatch URLs / cell-edit endpoints / wizard
+// endpoints / mention-resolve endpoints), the load-record fill pipeline
+// (`applyFillPipeline` + relationship Repeater/Builder fills),
+// server-data widget resolution, and the two `*Ctx` helpers that the
+// per-role builders use to construct the `SchemaContext` they pass into
+// `resolveSchema`. Pure (mostly stateless) helpers — no per-page-role
+// orchestration.
+export function userCtx(ctx, user) {
+    if (user === null || user === undefined)
+        return ctx;
+    return { ...ctx, user: user };
+}
+/**
+ * Run a (possibly async) boolean predicate; fail closed when it throws.
+ *
+ * Every page-builder pre-flight that consults `canX(user, …)` needs this
+ * shape — predicates may be sync booleans, Promises, or throw at the
+ * remote-auth layer; a throw must never propagate to the wire as an
+ * unhandled 500.
+ */
+export async function safeBool(fn) {
+    try {
+        return Boolean(await fn());
+    }
+    catch {
+        return false;
+    }
+}
+/** Plan #6 — stamp the panel-wide upload URL so `FileUpload` fields
+ *  emit it on their meta. Single URL for the whole panel; no per-field
+ *  variation. The route is always registered (see `_uploads` in
+ *  `routes.ts`) — meta is stamped regardless of whether an adapter is
+ *  configured so the renderer can show a clear error rather than
+ *  silently breaking. The companion `hasUploadAdapter` flag distinguishes
+ *  "URL exists but adapter missing" so fields with optional upload
+ *  affordances (e.g. `MarkdownField`'s `attachFiles` button) can hide
+ *  themselves rather than render a broken control. */
+export function uploadCtx(ctx, cfg) {
+    return {
+        ...ctx,
+        uploadUrl: `${cfg.path}/_uploads`,
+        ...(cfg.uploads ? { hasUploadAdapter: true } : {}),
+    };
+}
+export async function callPageSchema(PageClass, ctx) {
+    return Promise.resolve(PageClass.schema(ctx));
+}
+/** Mark every Form on the page with its action URL so the rendered <form> posts to itself. */
+export function tagFormActions(elements, action) {
+    for (const form of findForms(elements)) {
+        if (!form.getAction())
+            form.action(action);
+    }
+}
+/**
+ * Plan #5 — stamp the partial-resolve endpoint URL on every form whose
+ * descendants include at least one `live()` field. The client uses
+ * `FormMeta.stateUrl` to flip into controlled-state mode; forms without
+ * any live fields stay uncontrolled (zero-cost legacy path).
+ *
+ * `urlBuilder(formId)` lets the caller compose a per-form URL — the
+ * endpoint shape is `${base}/${slug}/_form/${formId}/state` so each
+ * form on a multi-form page gets its own route segment.
+ */
+export function tagFormStateUrls(elements, urlBuilder) {
+    for (const form of findForms(elements)) {
+        if (formHasLiveField(form)) {
+            form.withStateUrl(urlBuilder(form.getFormId()));
+        }
+    }
+}
+/**
+ * Reorderable rows — stamp the POST-reorder URL on every `Table` that
+ * has `Table.reorderable()` set. The renderer reads `TableMeta.reorderUrl`
+ * to wire the drop handler; tables that aren't reorderable skip wiring
+ * entirely. Same shape as `tagFormStateUrls` so the call site stays
+ * consistent.
+ */
+export function tagTableReorderUrls(elements, url) {
+    for (const table of findTables(elements)) {
+        if (table.isReorderable() && !table.getReorderUrl()) {
+            table.withReorderUrl(url);
+        }
+    }
+}
+// Marks every Table on the page deferred and stamps the URL the
+// renderer will fetch from after mount. Must run BEFORE `loadTableRecords`
+// so the records handler short-circuits.
+export function tagTableDeferred(elements, url) {
+    for (const table of findTables(elements)) {
+        table.withDeferred(true);
+        table.withTableUrl(url);
+    }
+}
+/**
+ * Editable cell columns — walk every table on the page and stamp
+ * `_cellEditUrls[colName]` per row, but only on rows that already
+ * carry a `_cellEditable[colName]` marker (set by `loadTableRecords`
+ * after `R.canEdit(user, row)` passed). The dispatcher stays
+ * URL-shape-agnostic; URL building lives here parallel to
+ * `tagFormStateUrls / tagTableReorderUrls`.
+ *
+ * `idOf` extracts the per-row primary key. Defaults to reading `id` —
+ * works for the rudder ORM convention. Resources with a different
+ * primary-key column should pass an override (none in v1).
+ */
+export function tagCellEditUrls(elements, resourceUrl, idOf = row => row['id']) {
+    for (const table of findTables(elements)) {
+        const rows = table.getRows();
+        if (!rows || rows.length === 0)
+            continue;
+        // Optimisation: skip the table when none of its columns are editable.
+        const editable = (table.getChildren() ?? []).some(c => c instanceof Column && c.isEditable());
+        if (!editable)
+            continue;
+        for (const row of rows) {
+            const editableMap = row['_cellEditable'];
+            if (!editableMap)
+                continue;
+            const id = idOf(row);
+            if (id === undefined || id === null || id === '')
+                continue;
+            const urls = {};
+            for (const colName of Object.keys(editableMap)) {
+                urls[colName] = `${resourceUrl}/${encodeURIComponent(String(id))}/_cell/${encodeURIComponent(colName)}`;
+            }
+            ;
+            row['_cellEditUrls'] = urls;
+        }
+    }
+}
+/**
+ * Plan #8 — stamp the wizard step-validate endpoint URL on every form
+ * whose descendants include a `Wizard` element. `FormMeta.wizardUrl` is
+ * what the client posts to on Next-button clicks; forms without a wizard
+ * descendant skip wiring.
+ */
+export function tagFormWizardUrls(elements, urlBuilder) {
+    for (const form of findForms(elements)) {
+        if (formHasWizard(form)) {
+            form.withWizardUrl(urlBuilder(form.getFormId()));
+        }
+    }
+}
+/**
+ * Stamp `_agentRunBase` on every field element in the resolved
+ * `ElementMeta[]` tree that carries `aiActions`. Operates on the
+ * post-`resolveSchema` wire shape (plain objects) rather than on
+ * `Element` instances — `aiActions` is added by the `field-ai.ts`
+ * wrapper during `toMeta()`, so it isn't visible to pre-resolve walkers.
+ *
+ * Only called on edit pages where a `recordId` is known. Create pages
+ * deliberately skip it — field AI actions target existing content.
+ */
+export function tagFieldAiUrls(elements, agentBase) {
+    for (const el of elements) {
+        if (Array.isArray(el['aiActions']) && el['aiActions'].length > 0) {
+            ;
+            el['_agentRunBase'] = agentBase;
+        }
+        const children = el['children'];
+        if (Array.isArray(children))
+            tagFieldAiUrls(children, agentBase);
+        // Repeater rows
+        const rows = el['rows'];
+        if (Array.isArray(rows)) {
+            for (const row of rows) {
+                const rowChildren = row['children'];
+                if (Array.isArray(rowChildren))
+                    tagFieldAiUrls(rowChildren, agentBase);
+            }
+        }
+    }
+}
+/**
+ * Audit row 2026-05-07 cont'd⁸ — stamp the inline-create-option endpoint
+ * URL on every `SelectField` that has called `createOptionForm()`. Walks
+ * every form on the page so the URL carries the parent form's id; URL
+ * shape `${formScopeUrl}/_form/${formId}/create-option/${fieldName}` so
+ * the route handler can pick the form by id and the field by name.
+ *
+ * Mirrors `tagFormStateUrls / tagFormWizardUrls` — operates on the
+ * un-resolved Element tree, mutates field-instance state via
+ * `field.withCreateOptionUrl(url)`, and the field's `toMeta()` reads it
+ * back to emit `createOption.url`.
+ *
+ * Stops at Repeater / Builder boundaries (parallel to the form-state /
+ * wizard walkers): inside-row schemas are dispatched per-row and the
+ * createOption shape doesn't compose with row body coercion in v1.
+ */
+export function tagSelectCreateOptionUrls(elements, urlBuilder) {
+    for (const form of findForms(elements)) {
+        const formId = form.getFormId();
+        walkSelectFields(form.getChildren() ?? [], (field) => {
+            if (field.hasCreateOption() && !field.getCreateOptionUrl()) {
+                field.withCreateOptionUrl(urlBuilder(formId, field.name));
+            }
+        });
+    }
+}
+export function walkSelectFields(elements, visit) {
+    for (const el of elements) {
+        if (el instanceof SelectField) {
+            visit(el);
+            // SelectField has no children of its own — no recursion needed.
+            continue;
+        }
+        // Stop at row-array boundaries — see comment on `tagSelectCreateOptionUrls`.
+        if (el instanceof RepeaterField)
+            continue;
+        if (el instanceof BuilderField)
+            continue;
+        const children = el.getChildren();
+        if (children && children.length > 0)
+            walkSelectFields(children, visit);
+    }
+}
+export function isAsyncMentionField(el) {
+    if (el.getType() !== 'richtext')
+        return false;
+    const candidate = el;
+    return typeof candidate.hasAsyncMentions === 'function'
+        && typeof candidate.withMentionsUrl === 'function';
+}
+export function tagRichTextMentionUrls(elements, urlBuilder) {
+    for (const form of findForms(elements)) {
+        const url = urlBuilder(form.getFormId());
+        const visit = (els) => {
+            for (const el of els) {
+                // Don't cross into nested forms — each form gets its own URL.
+                if (el !== form && el.getType() === 'form')
+                    continue;
+                if (isAsyncMentionField(el) && el.hasAsyncMentions()) {
+                    el.withMentionsUrl(url);
+                }
+                // Builder.getChildren() returns undefined to keep the field-level
+                // walkers from treating heterogeneous rows as flat children. Manual
+                // descent into each block's schema covers the URL-stamping path
+                // without changing the no-cross posture for save/coerce.
+                if (isBuilderField(el)) {
+                    for (const block of el.getBlocks())
+                        visit(block.getSchema());
+                    continue;
+                }
+                const children = el.getChildren();
+                if (children)
+                    visit(children);
+            }
+        };
+        const children = form.getChildren();
+        if (children)
+            visit(children);
+    }
+}
+export function formHasLiveField(form) {
+    let found = false;
+    const visit = (els) => {
+        for (const el of els) {
+            if (found)
+                return;
+            // Either a server-side `live()` (drives a roundtrip) OR a
+            // client-side `afterStateUpdatedJs(body)` (JS-only) is enough to
+            // mount the controlled-form path: the FormStateProvider holds the
+            // values map either path needs, and the client gates the actual
+            // network POST on `live` separately. Cost of the over-stamp for
+            // JS-only forms is one unused endpoint URL per form — endpoint
+            // never gets hit because the client only POSTs on `live`.
+            if (el instanceof Field && (el.isLive() || el.getAfterStateUpdatedJs() !== undefined)) {
+                found = true;
+                return;
+            }
+            const children = el.getChildren();
+            if (children)
+                visit(children);
+        }
+    };
+    const children = form.getChildren();
+    if (children)
+        visit(children);
+    return found;
+}
+export function formHasWizard(form) {
+    let found = false;
+    const visit = (els) => {
+        for (const el of els) {
+            if (found)
+                return;
+            if (el.getType() === 'wizard') {
+                found = true;
+                return;
+            }
+            const children = el.getChildren();
+            if (children)
+                visit(children);
+        }
+    };
+    const children = form.getChildren();
+    if (children)
+        visit(children);
+    return found;
+}
+/**
+ * Run the edit-mode fill pipeline on a loaded record:
+ *   mutateFormDataBeforeFill  →  fillFromRecord  →  mutateFormDataAfterFill
+ *
+ * `fillFromRecord` defaults to `{ ...record }` when not configured. Both
+ * mutators are optional and may be async. `ctx.record` is the loaded
+ * record so mutators can read from fields the form doesn't surface.
+ */
+export async function applyFillPipeline(form, record) {
+    const recordObj = record;
+    let values = { ...recordObj };
+    const before = form.getMutateFormDataBeforeFill();
+    if (before)
+        values = await before(values, { values, record });
+    const fill = form.getFillFromRecord();
+    if (fill)
+        values = fill(record);
+    const after = form.getMutateFormDataAfterFill();
+    if (after)
+        values = await after(values, { values, record });
+    return values;
+}
+/**
+ * Walk the form's top-level Repeaters and replace `values[fieldName]`
+ * with rows fetched from `parent.related(name)` for any
+ * relationship-backed Repeater. Each loaded row stamps `__id` to the
+ * child's primary key so the renderer can round-trip identity through
+ * a hidden input and the save-side diff can match submitted rows back
+ * to existing records.
+ *
+ * No-op when the parent record is null (create mode), when no
+ * relationship-backed Repeaters exist on the form, or when the
+ * resource has no `R.model` (relation queries need it).
+ *
+ * Mutates and returns a fresh values object — never the input.
+ */
+export async function applyRelationshipRepeaterFill(form, values, record, parentModel) {
+    if (record == null)
+        return values;
+    if (!parentModel)
+        return values;
+    const repeaters = findRelationshipRepeaters(form.getChildren() ?? []);
+    if (repeaters.length === 0)
+        return values;
+    const out = { ...values };
+    for (const repeater of repeaters) {
+        const cfg = repeater.getRelationship();
+        const pivotColumns = cfg.pivotColumns;
+        let rows;
+        try {
+            rows = await loadRelationRows(parentModel, record, cfg.name, pivotColumns);
+        }
+        catch {
+            // Failed lookup (e.g. missing `relations` map on a test stub)
+            // — fall back to whatever value applyFillPipeline produced
+            // rather than wiping the field. Better to render stale data
+            // than to silently empty the row list.
+            continue;
+        }
+        // The child model is opaque here — we don't have the full
+        // descriptor at this seam, so use the configured override or
+        // peek the parent's relations map for the FK column. Strip it
+        // (and the PK) from each row's payload so the inner schema
+        // doesn't surface them as form values. For morphMany the
+        // attachment is two columns instead of one — strip both.
+        const pkColumn = pickChildPrimaryKey(parentModel, cfg.name) ?? 'id';
+        const fkColumn = cfg.foreignKey ?? pickChildForeignKey(parentModel, cfg.name);
+        const morph = getMorphRelationDescriptor(parentModel, cfg.name);
+        const morphIdCol = morph ? `${morph.morphName}Id` : undefined;
+        const morphTyCol = morph ? `${morph.morphName}Type` : undefined;
+        out[repeater.name] = rows.map(row => {
+            const r = (row && typeof row === 'object') ? { ...row } : {};
+            const pkValue = r[pkColumn];
+            delete r[pkColumn];
+            if (fkColumn)
+                delete r[fkColumn];
+            if (morphIdCol)
+                delete r[morphIdCol];
+            if (morphTyCol)
+                delete r[morphTyCol];
+            // M2M pivot extras — flatten `row.pivot[col]` onto the row's data
+            // so each pivot column round-trips through the inner schema as a
+            // regular form field. The pivot envelope itself is dropped from
+            // the values shape — the persist side splits pivot vs child
+            // columns by name lookup against `cfg.pivotColumns`.
+            const pivotEnvelope = r['pivot'];
+            delete r['pivot'];
+            const stamped = { ...r };
+            if (pivotColumns && pivotColumns.length > 0
+                && pivotEnvelope && typeof pivotEnvelope === 'object') {
+                const pe = pivotEnvelope;
+                for (const col of pivotColumns) {
+                    if (col in pe)
+                        stamped[col] = pe[col];
+                }
+            }
+            if (pkValue !== undefined && pkValue !== null) {
+                stamped['__id'] = String(pkValue);
+            }
+            return stamped;
+        });
+    }
+    return out;
+}
+/** Walk the form's children for top-level relationship-backed Repeaters. */
+export function findRelationshipRepeaters(elements) {
+    const out = [];
+    const walk = (els) => {
+        for (const el of els) {
+            if (isRepeaterField(el)) {
+                const r = el;
+                if (r.getRelationship())
+                    out.push(r);
+                // Don't dive into Repeater children — relationship-on-relationship
+                // isn't supported in v1.
+                continue;
+            }
+            // Don't dive into Builder children either — relationship-backed
+            // Builders are resolved separately by `findRelationshipBuilders`.
+            if (isBuilderField(el))
+                continue;
+            const children = el.getChildren();
+            if (children && children.length > 0)
+                walk(children);
+        }
+    };
+    walk(elements);
+    return out;
+}
+/**
+ * Walk the form's top-level Builders and replace `values[fieldName]` with
+ * rows fetched from `parent.related(name)` for any relationship-backed
+ * Builder. Each loaded row stamps `__id` (child PK) + `type` (block
+ * discriminator) + `data` (per-block JSON payload) so the renderer can
+ * round-trip the heterogeneous envelope.
+ *
+ * Mirrors `applyRelationshipRepeaterFill`. No-op when the parent record
+ * is null (create mode), the resource has no `R.model`, or no
+ * relationship-backed Builders exist on the form.
+ */
+export async function applyRelationshipBuilderFill(form, values, record, parentModel) {
+    if (record == null)
+        return values;
+    if (!parentModel)
+        return values;
+    const builders = findRelationshipBuilders(form.getChildren() ?? []);
+    if (builders.length === 0)
+        return values;
+    const out = { ...values };
+    for (const builder of builders) {
+        const cfg = builder.getRelationship();
+        let rows;
+        try {
+            rows = await loadRelationRows(parentModel, record, cfg.name);
+        }
+        catch {
+            // Failed lookup (e.g. missing `relations` map on a test stub) —
+            // fall back to whatever value applyFillPipeline produced rather
+            // than wiping the field. Better stale than silently empty.
+            continue;
+        }
+        const pkColumn = pickChildPrimaryKey(parentModel, cfg.name) ?? 'id';
+        const fkColumn = cfg.foreignKey ?? pickChildForeignKey(parentModel, cfg.name);
+        const typeColumn = cfg.typeColumn ?? 'type';
+        const dataColumn = cfg.dataColumn ?? 'data';
+        out[builder.name] = rows.map(row => {
+            const r = (row && typeof row === 'object') ? { ...row } : {};
+            const pkValue = r[pkColumn];
+            const blockType = typeof r[typeColumn] === 'string' ? r[typeColumn] : '';
+            const dataRaw = r[dataColumn];
+            const blockData = parseBuilderDataPayload(dataRaw);
+            const stamped = {
+                type: blockType,
+                data: blockData,
+            };
+            if (pkValue !== undefined && pkValue !== null) {
+                stamped['__id'] = String(pkValue);
+            }
+            // Non-`type` / `data` / FK / PK columns aren't surfaced — the
+            // JSON envelope is the source of truth for per-block fields. If
+            // a user denormalizes a column, they handle it via per-block
+            // mutate hooks, not by leaking the column into row values.
+            void fkColumn;
+            return stamped;
+        });
+    }
+    return out;
+}
+/**
+ * Normalize the JSON payload column into a plain object. Prisma
+ * hydrates `Json` columns to objects; some adapters return strings.
+ * Anything that isn't a parseable object falls back to `{}` so the
+ * inner schema renders fresh defaults.
+ */
+export function parseBuilderDataPayload(raw) {
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        return raw;
+    }
+    if (typeof raw === 'string') {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // fall through to {}
+        }
+    }
+    return {};
+}
+/** Walk the form's children for top-level relationship-backed Builders. */
+export function findRelationshipBuilders(elements) {
+    const out = [];
+    const walk = (els) => {
+        for (const el of els) {
+            if (isBuilderField(el)) {
+                const b = el;
+                if (b.getRelationship())
+                    out.push(b);
+                continue;
+            }
+            // Don't dive into Repeater children either — both array-row
+            // boundaries are walker stops here.
+            if (isRepeaterField(el))
+                continue;
+            const children = el.getChildren();
+            if (children && children.length > 0)
+                walk(children);
+        }
+    };
+    walk(elements);
+    return out;
+}
+/** Read the child model's PK column from the parent's relations map, when present. */
+export function pickChildPrimaryKey(parentModel, name) {
+    const relations = parentModel['relations'];
+    if (!relations || typeof relations !== 'object')
+        return undefined;
+    const entry = relations[name];
+    if (!entry || typeof entry !== 'object')
+        return undefined;
+    const e = entry;
+    if (typeof e['model'] !== 'function')
+        return undefined;
+    try {
+        const child = e['model']();
+        return getPrimaryKey(child);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the FK column from the parent's relations map, when present. */
+export function pickChildForeignKey(parentModel, name) {
+    const relations = parentModel['relations'];
+    if (!relations || typeof relations !== 'object')
+        return undefined;
+    const entry = relations[name];
+    if (!entry || typeof entry !== 'object')
+        return undefined;
+    const e = entry;
+    return typeof e['foreignKey'] === 'string' ? e['foreignKey'] : undefined;
+}
+/**
+ * Plan #15 — collect every `ServerDataElement` in the schema tree and
+ * resolve their `getServerData(ctx)` payloads in parallel. Returns a
+ * map keyed by element id, ready to ship as `viewProps._widgetData`.
+ *
+ * Lazy elements (default — `lazy(false)` opts out) skip the hook and
+ * stamp `null` so the renderer paints a skeleton and fetches the
+ * payload via `POST {base}/_widget/:id` on mount. Eager elements
+ * resolve synchronously and ship the data with the page.
+ *
+ * Per-widget errors are caught and surfaced as `{ error: '...' }` —
+ * one flaky `getStats()` shouldn't 500 the entire dashboard.
+ *
+ * Visibility is **not** re-evaluated here. The schema resolver
+ * (`resolveSchema → evaluateVisibility`) drops hidden layout elements
+ * before any widget code runs. Widgets inside still-rendered branches
+ * always resolve (or stamp lazy null).
+ */
+export async function resolveServerDataElements(elements, ctx) {
+    const widgets = collectServerDataElements(elements);
+    if (widgets.length === 0)
+        return {};
+    const out = {};
+    await Promise.all(widgets.map(async (el) => {
+        const id = el.getId();
+        if (el.isLazy()) {
+            out[id] = null; // sentinel — renderer paints skeleton, fetches on mount
+            return;
+        }
+        try {
+            out[id] = await el.resolveServerData(ctx);
+        }
+        catch (err) {
+            out[id] = { error: err instanceof Error ? err.message : 'Widget failed to load' };
+        }
+    }));
+    return out;
+}
+/** Walk the tree collecting every `ServerDataElement`. Walks into
+ *  containers but stops at Form/Repeater/Builder boundaries — widgets
+ *  inside an editable form don't make sense in v1. */
+export function collectServerDataElements(elements) {
+    const out = [];
+    const walk = (els) => {
+        for (const el of els) {
+            if (isServerDataElement(el)) {
+                out.push(el);
+                // Don't recurse into a widget's children — `View` etc. are leaves
+                // for v1 (no nested widgets inside widgets).
+                continue;
+            }
+            // Skip walkers that imply per-row resolution — widgets inside
+            // Repeater/Builder rows don't have a stable id space.
+            const type = el.getType();
+            if (type === 'form' || type === 'repeater' || type === 'builder' || type === 'table' || type === 'tableWidget')
+                continue;
+            const children = el.getChildren();
+            if (children)
+                walk(children);
+        }
+    };
+    walk(elements);
+    return out;
+}
+/**
+ * Plan #15 — stamp the polling-endpoint URL on every `ServerDataElement`
+ * in the tree. Mirrors `tagFormStateUrls / tagTableReorderUrls`. Walks
+ * with the same boundaries as `collectServerDataElements` so the wire
+ * stays in sync (no orphan widgets without URLs and vice versa).
+ *
+ * `urlBuilder(id)` typically produces `${base}/_widget/${id}` for
+ * dashboard widgets and `${base}/${pageSlug}/_widget/${id}` for
+ * custom-page widgets — the route handlers for both shapes are wired up
+ * in `routes.ts` (see Phase A.4).
+ */
+export function tagWidgetUrls(elements, urlBuilder) {
+    for (const widget of collectServerDataElements(elements)) {
+        if (widget.getWidgetUrl())
+            continue; // user-set wins
+        widget.withWidgetUrl(urlBuilder(widget.getId()));
+    }
+}
+/**
+ * Stamp every form-subresource URL the page might need in one pass:
+ *  - `_form/${formId}/state`         (Plan #5 partial-resolve)
+ *  - `_form/${formId}/wizard`        (Plan #8 step-validate)
+ *  - `_form/${formId}/mentions`      (async-mention typeahead)
+ *  - `_form/${formId}/create-option/${fieldName}` (SelectField inline-create)
+ *
+ * Every page-builder that mounts a form (dashboard / resource create+edit /
+ * global edit / custom page) needs all four — the underlying taggers skip
+ * forms that don't carry the matching feature, so this is always safe to
+ * call. `base` is the route prefix (e.g. `${cfg.path}` / `${resourceBase}` /
+ * `${resourceBase}/${recordId}` / `${pageUrl}`).
+ */
+export function tagFormSubresourceUrls(elements, base) {
+    tagFormStateUrls(elements, formId => `${base}/_form/${formId}/state`);
+    tagFormWizardUrls(elements, formId => `${base}/_form/${formId}/wizard`);
+    tagRichTextMentionUrls(elements, formId => `${base}/_form/${formId}/mentions`);
+    tagSelectCreateOptionUrls(elements, (formId, fieldName) => `${base}/_form/${formId}/create-option/${fieldName}`);
+}
+/** Stamp dispatchUrl on every handler-style Action so the client knows where to POST. */
+export function tagActionDispatch(elements, baseUrl) {
+    for (const action of findActions(elements)) {
+        if (!action.getHandler())
+            continue;
+        if (action.getHref() || action.getMethod())
+            continue;
+        if (action.getDispatchUrl())
+            continue;
+        action.dispatchUrl(`${baseUrl}/_action/${action.name}`);
+    }
+    // Row-scoped extraItemActions (Repeater/Builder). Stamped here too so
+    // the client can POST to the same `_action/:name` route — the renderer
+    // attaches `_rowPath=<fieldName>.<index>` per click; the server's
+    // dispatcher uses that to walk into the right row when building
+    // `ctx.row`. See `findRowExtraActions` in `dispatchAction.ts`.
+    for (const { action } of findRowExtraActions(elements)) {
+        if (!action.getHandler())
+            continue;
+        if (action.getDispatchUrl())
+            continue;
+        action.dispatchUrl(`${baseUrl}/_action/${action.name}`);
+    }
+}
+//# sourceMappingURL=helpers.js.map