@pilotiq/pilotiq 0.1.0

package/dist/elements/dispatchForm.d.ts

@@ -0,0 +1,220 @@
+import { Element } from '../schema/Element.js';
+import { RepeaterField } from '../fields/RepeaterField.js';
+import type { RepeaterRelationshipConfig } from '../fields/RepeaterField.js';
+import { BuilderField } from '../fields/BuilderField.js';
+import type { BuilderRelationshipConfig } from '../fields/BuilderField.js';
+import { Form, type FormContext } from './Form.js';
+import { type ValidationErrors } from '../validation/index.js';
+import { type NotificationMeta } from '../notifications/index.js';
+import { type ModelLike } from '../orm/modelDefaults.js';
+export interface DispatchSuccess<R> {
+    ok: true;
+    record: R;
+    redirect: string | undefined;
+    /**
+     * Resolved success notifications to flash to the client. Empty when the
+     * form has `disableSavedNotification()` or no spec configured. Currently
+     * only delivered through the JSON action-modal path; the form-post 303
+     * path drops them until a flash mechanism lands.
+     */
+    notifications: NotificationMeta[];
+}
+export interface DispatchFailure {
+    ok: false;
+    errors: ValidationErrors;
+}
+export type DispatchResult<R> = DispatchSuccess<R> | DispatchFailure;
+/**
+ * Run the full form submit lifecycle on a `Form` element. Mode is inferred
+ * from `ctx.record`: undefined → create, set → update. Mode-specific hooks
+ * fire after their generic counterparts so cross-cutting logic (auth
+ * stamping, audit fields) lives above mode-specific business rules.
+ *
+ * Order:
+ *
+ *   validateSchema
+ *     → form-level validators
+ *     → mutateData (both modes)
+ *     → mutateDataBeforeCreate / mutateDataBeforeUpdate
+ *     → beforeSave (both modes)
+ *     → beforeCreate / beforeUpdate
+ *     → handleCreate || handleUpdate || save     ← persistence
+ *     → afterCreate / afterUpdate
+ *     → afterSave (both modes)
+ *     → redirectAfterSave
+ *
+ * Validation failures short-circuit and return `{ ok: false, errors }`. On
+ * success the result includes the saved record and the resolved redirect URL
+ * (when `redirectAfterSave` is configured).
+ *
+ * Form-level validator errors are keyed under `_form` so the renderer can
+ * surface them as a top-of-form banner without colliding with field names.
+ */
+export declare function dispatchFormSubmit<R = unknown>(form: Form<R>, body: Record<string, unknown>, ctx: FormContext<R>): Promise<DispatchResult<R>>;
+/**
+ * Coerce raw form-body strings into the runtime types each field expects:
+ * booleans for toggles, numbers for number inputs, Dates for dates. The
+ * browser submits everything as a string by default, but ORM layers (Prisma,
+ * etc.) expect actual booleans/numbers/Dates. Runs after validation so
+ * validators still see the raw submitted text.
+ *
+ * Empty / missing values are normalized:
+ *   - `toggle`  → `false` when missing or 'false'/empty; `true` otherwise.
+ *   - `number`  → `null` when empty; otherwise `Number(v)` (NaN passes through).
+ *   - `date`    → `null` when empty; otherwise a `Date` parsed from the string.
+ *
+ * Other field types are passed through untouched.
+ */
+export declare function coerceFormValues(elements: Element[], body: Record<string, unknown>): Record<string, unknown>;
+/**
+ * After `coerceFormValues` has produced wrapped `[{<innerName>: v}]`
+ * rows for every Repeater in the schema, flatten the `simple()` ones
+ * back to `[v, v, …]` for storage. Non-simple repeaters are left alone.
+ *
+ * Runs before `mutateData` / `save` so user-facing data already uses
+ * the storage shape they declared via `.simple(field)` — they don't
+ * have to remember the internal wrapping at the save site.
+ *
+ * Tolerates already-flat input (e.g. when a `dehydrated(false)` upstream
+ * has dropped wrapping, or when the user manually fed a flat array
+ * through `withValues`) by re-emitting verbatim.
+ */
+export declare function unwrapSimpleRepeaters(elements: Element[], values: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Walk an Element tree and return every `Form` instance, in document order.
+ * Used by route handlers to locate the form being submitted on a page that
+ * may declare more than one.
+ *
+ * Uses a structural `getType() === 'form'` check rather than `instanceof
+ * Form`. Vite's SSR module cache can load the package through two
+ * different module paths during a single dev session — the path used by
+ * the rudder SSR route and the path used by Vike's `+data` hook for SPA
+ * navigations end up importing different `Form` classes, so `instanceof`
+ * silently returns false and the form goes "missing" on SPA nav while
+ * SSR keeps working. The structural check is robust to that and matches
+ * the convention used elsewhere in the codebase (see Filter, Column,
+ * Action — all keyed on the serialized type, not class identity).
+ */
+export declare function findForms(elements: ReadonlyArray<Element>): Form[];
+/**
+ * Plan #8 — locate the children of a Wizard step at the given index inside
+ * the form's tree. Returns `undefined` when the form has no Wizard
+ * descendant or the step index is out of range. Step children are returned
+ * as a fresh Element[] so callers can pass them straight to
+ * `validateSchema`. Walks structurally (`getType() === 'wizard'/'step'`)
+ * to stay robust to Vite SSR module-cache duplication.
+ */
+export declare function findWizardStepFields(formChildren: ReadonlyArray<Element>, stepIndex: number): Element[] | undefined;
+/**
+ * Pick the `Form` matching the submitted `_formId`, or fall back to the
+ * first form on the page when no id was sent OR the submitted id misses.
+ *
+ * Use this on **legacy form-submit paths** (POST create / edit / global-edit
+ * / custom-page) where a single page may host multiple forms and the
+ * fallback to "first form" is a back-compat affordance for submissions that
+ * predate the `_formId` hidden input.
+ *
+ * Do NOT use this on partial-resolve paths (Plan #5 form-state, Plan #8
+ * wizard step-validate) — those must hard-fail on a mismatched id so the
+ * client gets a 404 instead of silently writing the wrong form's state.
+ * Use `selectFormById` there.
+ */
+export declare function selectForm(forms: ReadonlyArray<Form>, submittedId: unknown): Form | undefined;
+/**
+ * ID-match counterpart to `selectForm`, used by partial-resolve endpoints
+ * (Plan #5 form-state, Plan #8 wizard step-validate).
+ *
+ * - If `id` matches a form, return it.
+ * - If there's no match AND the page has exactly one form, return that
+ *   form. This is safe — there's no ambiguity about which form the POST
+ *   meant — and it removes the auto-counter desync footgun: the GET
+ *   render and the partial-resolve POST run through `Form.make()` in
+ *   different requests, so the process-global formId counter ticks
+ *   forward and a strict match would 404. See
+ *   `feedback_pilotiq_live_forms_pin_formid.md`.
+ * - Otherwise return `undefined`. Multi-form pages with a missing/wrong
+ *   id must hard-fail so the client surfaces a 404 instead of writing
+ *   the wrong form's state.
+ *
+ * Pages with multiple reactive forms still need to pin a stable
+ * `Form.make().formId(...)` to disambiguate.
+ */
+export declare function selectFormById(forms: ReadonlyArray<Form>, id: string): Form | undefined;
+export interface StateUpdateContext<R = unknown> {
+    record?: R;
+    user?: unknown;
+    request?: unknown;
+}
+export interface StateUpdateResult {
+    /**
+     * Updated values map after coercing the changed field and running
+     * its `afterStateUpdated` hook. The same object the client should
+     * rebind to its inputs on the next render.
+     */
+    values: Record<string, unknown>;
+    /**
+     * Field names whose value was written via `$set` during this resolve.
+     * Includes the changed field itself. The client uses this to decide
+     * which inputs to update without disrupting focus on others.
+     */
+    dirty: string[];
+}
+/**
+ * Apply a partial-resolve update from the client. Coerces the changed
+ * field's value (other fields keep whatever the client sent), runs the
+ * field's `afterStateUpdated` hook with bound `$get / $set` helpers,
+ * and returns the updated values + names of fields whose values were
+ * mutated. The caller (the partial-resolve route handler) feeds the
+ * resulting values into `resolveSchema` to produce a fresh form meta.
+ *
+ * Returns `null` when the changed field name doesn't correspond to a
+ * field on the form — the route handler turns this into a 404.
+ *
+ * Plan #14 — `changed` may be a dotted path into a Repeater row
+ * (`items.2.quantity` or, for nested Repeaters, `items.0.modifiers.1.name`).
+ * The dotted form routes through `applyRepeaterStateUpdate` which scopes
+ * `$get / $set` to the innermost row by default; cross-row reads / writes
+ * go through the parent `$get / $set` using a full dotted path.
+ */
+export declare function applyStateUpdate<R = unknown>(form: Form<R>, values: Record<string, unknown>, changed: string, ctx?: StateUpdateContext<R>): Promise<StateUpdateResult | null>;
+interface RelationshipDeferral {
+    field: RepeaterField;
+    rows: Array<Record<string, unknown>>;
+    cfg: RepeaterRelationshipConfig;
+}
+/**
+ * Walk the form's top-level Repeaters and extract values for any that
+ * have a `relationship(...)` config. Returns the deferral list and
+ * mutates `data` in place by deleting each extracted key — the parent's
+ * save handler doesn't need to see those values (they aren't real
+ * columns on the parent).
+ *
+ * Inner / nested Repeaters aren't supported in v1; we only walk the top
+ * level (consistent with the existing `walkRepeatersTopLevel` helper)
+ * so a relationship-backed Repeater nested inside a JSON-backed
+ * Repeater silently falls back to JSON storage. Documented as a
+ * v1 limitation in `docs/plans/repeater-relationship.md`.
+ */
+export declare function extractRelationshipRepeaters(elements: Element[], data: Record<string, unknown>): RelationshipDeferral[];
+/**
+ * Read all rows from `parent.related(name)`. Used both by the load-
+ * side fill (in pageData) and the save-side diff (above). Caps at
+ * 10k — admin Repeaters should never get that large; if they do we'll
+ * add explicit pagination.
+ */
+export declare function loadRelationRows(parentModel: ModelLike, parent: unknown, name: string, pivotColumns?: readonly string[]): Promise<unknown[]>;
+interface BuilderRelationshipDeferral {
+    field: BuilderField;
+    rows: Array<Record<string, unknown>>;
+    cfg: BuilderRelationshipConfig;
+}
+/**
+ * Walk the form's top-level Builders and extract values for any that have
+ * a `relationship(...)` config. Same shape + posture as
+ * `extractRelationshipRepeaters`; mutates `data` in place by deleting each
+ * extracted key. Heterogeneous-row sibling — each row is a
+ * `{ __id?, type, data: {…} }` envelope after `coerceBuilderValue`.
+ */
+export declare function extractRelationshipBuilders(elements: Element[], data: Record<string, unknown>): BuilderRelationshipDeferral[];
+export {};
+//# sourceMappingURL=dispatchForm.d.ts.map

package/dist/elements/dispatchForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatchForm.d.ts","sourceRoot":"","sources":["../../src/elements/dispatchForm.ts"],"names":[],"mappings":"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"}