@pilotiq/pilotiq 0.7.1 → 0.8.0

package/dist/pageData/helpers.d.ts

@@ -0,0 +1,239 @@
+import type { PilotiqConfig } from '../Pilotiq.js';
+import type { Page } from '../Page.js';
+import { Element } from '../schema/Element.js';
+import type { SchemaContext, RenderContext } from '../schema/resolveSchema.js';
+import { Form } from '../elements/Form.js';
+import { SelectField } from '../fields/SelectField.js';
+import { RepeaterField } from '../fields/RepeaterField.js';
+import { BuilderField } from '../fields/BuilderField.js';
+import { type ServerDataElement } from '../schema/ServerDataElement.js';
+import { type ModelLike } from '../orm/modelDefaults.js';
+export declare function userCtx<C extends SchemaContext>(ctx: C, user: unknown): C;
+/**
+ * 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 declare function safeBool(fn: () => boolean | Promise<boolean>): Promise<boolean>;
+/** 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 declare function uploadCtx<C extends SchemaContext>(ctx: C, cfg: PilotiqConfig): C;
+export declare function callPageSchema(PageClass: typeof Page, ctx: SchemaContext): Promise<Element[]>;
+/** Mark every Form on the page with its action URL so the rendered <form> posts to itself. */
+export declare function tagFormActions(elements: ReadonlyArray<Element>, action: string): void;
+/**
+ * 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 declare function tagFormStateUrls(elements: ReadonlyArray<Element>, urlBuilder: (formId: string) => string): void;
+/**
+ * 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 declare function tagTableReorderUrls(elements: ReadonlyArray<Element>, url: string): void;
+export declare function tagTableDeferred(elements: ReadonlyArray<Element>, url: string): void;
+/**
+ * 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 declare function tagCellEditUrls(elements: ReadonlyArray<Element>, resourceUrl: string, idOf?: (row: Record<string, unknown>) => unknown): void;
+/**
+ * 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 declare function tagFormWizardUrls(elements: ReadonlyArray<Element>, urlBuilder: (formId: string) => string): void;
+/**
+ * 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 declare function tagFieldAiUrls(elements: ReadonlyArray<Record<string, unknown>>, agentBase: string): void;
+/**
+ * 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 declare function tagSelectCreateOptionUrls(elements: ReadonlyArray<Element>, urlBuilder: (formId: string, fieldName: string) => string): void;
+export declare function walkSelectFields(elements: Element[], visit: (f: SelectField) => void): void;
+/**
+ * Adapter-package async-resolve walker. Stamps the per-form mentions URL
+ * on every field that ducks like a "rich text with at least one async
+ * mention provider". The duck-typed contract lives here (as opposed to
+ * importing from `@pilotiq/tiptap`) so pilotiq core stays adapter-free —
+ * any future field type with an async-resolve trigger can satisfy the
+ * same shape and pick up URL stamping for free.
+ *
+ * Contract:
+ *   - `getType() === 'richtext'`  (fast filter)
+ *   - `hasAsyncMentions(): boolean`
+ *   - `withMentionsUrl(url: string): unknown`
+ *
+ * Walks every form on the page so the URL builder can mint a per-form
+ * URL (mirrors `tagFormStateUrls / tagFormWizardUrls`). The route handler
+ * uses formId in the URL to select the form; the body carries `field`
+ * + `trigger` + `query`. One URL per (form, scope), reused across every
+ * async-mention field on that form.
+ */
+interface AsyncMentionFieldLike {
+    hasAsyncMentions(): boolean;
+    withMentionsUrl(url: string): unknown;
+}
+export declare function isAsyncMentionField(el: Element): el is Element & AsyncMentionFieldLike;
+export declare function tagRichTextMentionUrls(elements: ReadonlyArray<Element>, urlBuilder: (formId: string) => string): void;
+export declare function formHasLiveField(form: Form): boolean;
+export declare function formHasWizard(form: Form): boolean;
+/**
+ * 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 declare function applyFillPipeline<R>(form: Form<R>, record: R): Promise<Record<string, unknown>>;
+/**
+ * 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 declare function applyRelationshipRepeaterFill(form: Form, values: Record<string, unknown>, record: unknown, parentModel: ModelLike | undefined): Promise<Record<string, unknown>>;
+/** Walk the form's children for top-level relationship-backed Repeaters. */
+export declare function findRelationshipRepeaters(elements: ReadonlyArray<Element>): RepeaterField[];
+/**
+ * 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 declare function applyRelationshipBuilderFill(form: Form, values: Record<string, unknown>, record: unknown, parentModel: ModelLike | undefined): Promise<Record<string, unknown>>;
+/**
+ * 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 declare function parseBuilderDataPayload(raw: unknown): Record<string, unknown>;
+/** Walk the form's children for top-level relationship-backed Builders. */
+export declare function findRelationshipBuilders(elements: ReadonlyArray<Element>): BuilderField[];
+/** Read the child model's PK column from the parent's relations map, when present. */
+export declare function pickChildPrimaryKey(parentModel: ModelLike, name: string): string | undefined;
+/** Read the FK column from the parent's relations map, when present. */
+export declare function pickChildForeignKey(parentModel: ModelLike, name: string): string | undefined;
+/** Wire-shape of the per-widget data map shipped to the client.
+ *  Lazy elements stamp `null` (renderer paints skeleton + fetches);
+ *  eager elements stamp their resolved payload. Errors stamp
+ *  `{ error: '<message>' }` so the renderer can surface a per-widget
+ *  failure without blanking the page. */
+export type ServerDataMap = Record<string, unknown>;
+/**
+ * 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 declare function resolveServerDataElements(elements: ReadonlyArray<Element>, ctx: RenderContext): Promise<ServerDataMap>;
+/** 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 declare function collectServerDataElements(elements: ReadonlyArray<Element>): ServerDataElement[];
+/**
+ * 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 declare function tagWidgetUrls(elements: ReadonlyArray<Element>, urlBuilder: (id: string) => string): void;
+/**
+ * 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 declare function tagFormSubresourceUrls(elements: ReadonlyArray<Element>, base: string): void;
+/** Stamp dispatchUrl on every handler-style Action so the client knows where to POST. */
+export declare function tagActionDispatch(elements: ReadonlyArray<Element>, baseUrl: string): void;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/pageData/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/pageData/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,aAAa,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAE9C,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAA;AAG1C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,EAAmB,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC3E,OAAO,EAAkB,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACxE,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,gCAAgC,CAAA;AAI5F,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,yBAAyB,CAAA;AAahC,wBAAgB,OAAO,CAAC,CAAC,SAAS,aAAa,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC,CAGzE;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,EAAE,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAErF;AAED;;;;;;;;sDAQsD;AACtD,wBAAgB,SAAS,CAAC,CAAC,SAAS,aAAa,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,GAAG,CAAC,CAMhF;AAGD,wBAAsB,cAAc,CAAC,SAAS,EAAE,OAAO,IAAI,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAEnG;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAIrF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAI,aAAa,CAAC,OAAO,CAAC,EAClC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GACrC,IAAI,CAMN;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAChC,GAAG,EAAO,MAAM,GACf,IAAI,CAMN;AAKD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAChC,GAAG,EAAO,MAAM,GACf,IAAI,CAKN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAG,aAAa,CAAC,OAAO,CAAC,EACjC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAA0B,GACtE,IAAI,CAmBN;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAI,aAAa,CAAC,OAAO,CAAC,EAClC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GACrC,IAAI,CAMN;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAChD,SAAS,EAAE,MAAM,GAChB,IAAI,CAgBN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAI,aAAa,CAAC,OAAO,CAAC,EAClC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GACxD,IAAI,CASN;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAa3F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,UAAU,qBAAqB;IAC7B,gBAAgB,IAAI,OAAO,CAAA;IAC3B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtC;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,OAAO,GAAG,qBAAqB,CAKtF;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAI,aAAa,CAAC,OAAO,CAAC,EAClC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GACrC,IAAI,CAyBN;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAuBpD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAajD;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,IAAI,EAAI,IAAI,CAAC,CAAC,CAAC,EACf,MAAM,EAAE,CAAC,GACR,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAclC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,6BAA6B,CACjD,IAAI,EAAS,IAAI,EACjB,MAAM,EAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,MAAM,EAAO,OAAO,EACpB,WAAW,EAAE,SAAS,GAAG,SAAS,GACjC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+DlC;AAED,4EAA4E;AAC5E,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,aAAa,EAAE,CAoB3F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAS,IAAI,EACjB,MAAM,EAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,MAAM,EAAO,OAAO,EACpB,WAAW,EAAE,SAAS,GAAG,SAAS,GACjC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+ClC;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAe7E;AAED,2EAA2E;AAC3E,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,YAAY,EAAE,CAkBzF;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa5F;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO5F;AAID;;;;yCAIyC;AACzC,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAChC,GAAG,EAAO,aAAa,GACtB,OAAO,CAAC,aAAa,CAAC,CAiBxB;AAED;;sDAEsD;AACtD,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,iBAAiB,EAAE,CAoB/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAI,aAAa,CAAC,OAAO,CAAC,EAClC,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GACjC,IAAI,CAKN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAK3F;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAiBzF"}