@object-ui/plugin-form 17.6.0 → 17.7.0

package/dist/sectionGroups.d.ts

@@ -0,0 +1,62 @@
+import { ObjectFormSection } from '@object-ui/types';
+/**
+ * The keys `@objectstack/spec` REFUSES beside `group`, measured against
+ * `FormSectionSchema` in `@objectstack/spec` 17.3.0 and pinned in
+ * `__tests__/formSectionGroupReference-7051.test.tsx`.
+ *
+ * There are no override semantics: each of these is something the object's
+ * `fieldGroups` entry declares, so restating one on the referencing section
+ * would be a second writable spelling of one fact. Authored metadata carrying
+ * one never reaches this renderer (the spec door rejects it); a programmatic
+ * SDUI caller, which does not pass that door, is reported instead of quietly
+ * having its key honoured or quietly having it dropped.
+ */
+export declare const GROUP_OWNED_SECTION_KEYS: readonly ["name", "label", "description", "collapsible", "collapsed", "visibleWhen"];
+/**
+ * The keys the spec PERMITS beside `group`. They describe how THIS form lays
+ * the section out, which is the form's business and not the group's, so the
+ * authored value wins over the derived section.
+ */
+export declare const SECTION_LAYOUT_KEYS: readonly ["columns", "pane"];
+/** Test seam — forget which section-group diagnostics have been reported. */
+export declare function resetSectionGroupReports(): void;
+/** Does any section in this list use the reference form? */
+export declare function hasSectionGroupReference(sections: unknown): boolean;
+export interface ResolveSectionGroupsOptions {
+    /** Object name — diagnostics say WHICH object is missing the group. */
+    objectName: string;
+    /** The form's layout. `wizard` is the one the spec bans `group` on. */
+    formType?: string;
+    /**
+     * The object definition (`{ fields, fieldGroups }`), or `null`/`undefined`
+     * while it is still loading. A `group` section is rendered EMPTY until it
+     * arrives — never dropped, see the note on the return value.
+     */
+    objectDef: any;
+    /**
+     * `false` when this form can never load an object definition (no
+     * DataSource), so an unresolvable reference is reported as such instead of
+     * being left to look like a load that never finished.
+     */
+    resolvable?: boolean;
+}
+/**
+ * Replace every `{ group }` section with the section that group declares.
+ *
+ * Returns the SAME array reference when nothing uses the reference form, so a
+ * caller can keep this in a `useMemo` without perturbing any existing form.
+ *
+ * ⚠️ A reference that cannot be resolved yields `{ fields: [] }` — an empty
+ * section — and NOT a dropped one. Both render nothing, which is what the spec
+ * assigns to an unresolvable reference (`deriveFieldGroupLayout` already drops
+ * a declared group nothing references, and `@objectstack/lint`'s
+ * `form-section-group-unknown` is the declared reporter of a dangling key).
+ * The choice between them is forced by THIS surface and was measured: a form
+ * whose `sections` array empties out stops being a sectioned form at all and
+ * falls back to the flat every-field layout, so dropping would make a single
+ * mistyped key render MORE than the author asked for. Emptying renders
+ * exactly nothing, and leaves the array length — which is the wizard's step
+ * count and the container routing's condition — untouched.
+ */
+export declare function resolveSectionGroupReferences(sections: ObjectFormSection[] | undefined, opts: ResolveSectionGroupsOptions): ObjectFormSection[] | undefined;
+//# sourceMappingURL=sectionGroups.d.ts.map

package/dist/sectionGroups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sectionGroups.d.ts","sourceRoot":"","sources":["../src/sectionGroups.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,sFAO3B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,8BAA+B,CAAC;AAWhE,6EAA6E;AAC7E,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,4DAA4D;AAC5D,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAKnE;AAcD,MAAM,WAAW,2BAA2B;IAC1C,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,EAAE,GAAG,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,iBAAiB,EAAE,GAAG,SAAS,EACzC,IAAI,EAAE,2BAA2B,GAChC,iBAAiB,EAAE,GAAG,SAAS,CAyEjC"}

package/dist/sectionPredicateDiagnostic.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The one layout arm that still DROPS an authored `FormSection.visibleWhen`
+ * (objectui#6237).
+ *
+ * Of the six layout routes in `ObjectForm`, five honour the predicate:
+ * `split` / `drawer` / `modal` rebuild each section key by key and copy it
+ * (#6111), the flat arm carries it on the `section-divider` pseudo-field
+ * (#6236), and `tabbed` joined them by copying it onto the tab `TabbedForm`
+ * synthesises, where the renderer evaluates it (#6237). `wizard` is the
+ * remainder.
+ *
+ * ⛔ The wizard's gap is a DESIGN boundary, not an oversight, and it is not one
+ * copy line away. A step predicate would be step-boundary reactive against the
+ * ruled live-record reactivity, and it needs navigation, indicator, final-gate
+ * and re-selection semantics that the tab arm's machinery does not supply —
+ * `WizardStepConfig` carries the full measurement. Until that contract is ruled,
+ * an author who writes the key on a wizard is told so rather than watching it do
+ * nothing.
+ *
+ * Since objectstack#13622 (ruled 2026-08-31) the boundary is ALSO enforced at
+ * the author door: `@objectstack/spec` refuses `visibleWhen` on a wizard step
+ * at parse, so authored form-view metadata can no longer arrive here carrying
+ * it. This report is deliberately KEPT (Card R of that ruling): programmatic
+ * SDUI callers do not pass the spec door, and metadata published before the
+ * tightening still round-trips — for both, this warning is the only signal.
+ *
+ * Single-sourced so the runtime report and the pin that holds its wording cannot
+ * drift apart.
+ */
+export declare function sectionPredicateUnsupportedWarning(layout: 'wizard', sectionNames: string): string;
+//# sourceMappingURL=sectionPredicateDiagnostic.d.ts.map

package/dist/sectionPredicateDiagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sectionPredicateDiagnostic.d.ts","sourceRoot":"","sources":["../src/sectionPredicateDiagnostic.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,QAAQ,EAChB,YAAY,EAAE,MAAM,GACnB,MAAM,CASR"}

package/dist/submitTarget.d.ts

@@ -0,0 +1,119 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Does a form have anything to submit TO? — the ONE answer for every renderer
+ * `ObjectForm` routes to (objectui#6300).
+ *
+ * ## What went wrong
+ *
+ * Each of the five variant containers opened `handleSubmit` with
+ *
+ *     if (!dataSource) { await schema.onSuccess?.(data); return data; }
+ *
+ * — a SUCCESS signal emitted without consulting `submitHandler` and without
+ * persisting anything. Measured on `main` with a `submitHandler` supplied and no
+ * `dataSource`, all five read `onSuccess 1 / submitHandler 0`. Through
+ * `MasterDetailForm` — whose parent schema declares BOTH
+ * `submitHandler: submitViaBatch` and `onSuccess: handleSaved` — that early
+ * return reached `handleSaved` directly: a success toast (measured:
+ * `toast.success("Created")`) and, in create mode, a form reset clearing the
+ * line items nobody wrote. Silent data loss in the worst direction, because the
+ * submitter is told it worked.
+ *
+ * ## The rule this module carries
+ *
+ * A form has a submit target when it has EITHER a `dataSource` (it writes) or a
+ * declared `submitHandler` (the host writes — objectui#6176's seam, which needs
+ * no adapter of its own). With neither, exactly one shape is still legitimate:
+ * fields authored INLINE, where the author's `onSuccess` IS the write. Anything
+ * else must refuse, loudly, instead of confirming.
+ *
+ * ## What counts as inline, and why it has two limbs
+ *
+ * Neither limb is a new predicate. Both name a shape this package already
+ * documents as working with no adapter, and the test refuses everything else.
+ *
+ * **(a) `customFields` is non-empty.** `SimpleObjectForm` (`ObjectForm.tsx`)
+ * gates its own carve-out on exactly this, the `object-form` element gate
+ * (`index.tsx`) declares `requiresDataSource={!(schema?.customFields?.length > 0)
+ * && …}` and says so in as many words — *"The one escape hatch is inline
+ * `customFields`, which is exactly what `hasInlineFields` gates on inside the
+ * component, so the two stay in step"* — and `ObjectFormSchema` glosses the key
+ * as *"when used with inline field definitions (without dataSource), this
+ * becomes the primary field source"*.
+ *
+ * **(b) every section field is an inline runtime `FormField`.** This limb is not
+ * optional and not an invention: it is how a sectioned form expresses the same
+ * thing with no `customFields` at all — its sections carry the definitions.
+ * This package's README documents the shape and ships an example of
+ * it, `<WizardForm schema={wizard} />` under the comment *"dataSource omitted:
+ * every step lists inline fields"*, introduced by *"The inline shape is what
+ * lets a wizard run with no data source at all"*. Measured before this module
+ * existed: that example renders and submits. A `customFields`-only test would
+ * have made the repo's own published example throw — which is why the limb is
+ * here.
+ *
+ * The limb is deliberately ALL-or-nothing, and it is the taxonomy
+ * `normalizeSectionField` already keeps: a section field is a name string
+ * (shape 1), a spec `FormFieldSchema` whose identity key `field` is a STRING
+ * (shape 2), or an inline runtime `FormField` carrying its own `name` (shape 3).
+ * Only shape 3 is self-describing; shapes 1 and 2 name fields that only an
+ * object schema — and therefore only an adapter — can resolve. So one bare name
+ * anywhere in the sections means the form DID need metadata it could not get,
+ * and it refuses. Erring that way is the loud direction; the silent one is the
+ * defect.
+ *
+ * `TabbedForm` / `SplitForm` / `WizardForm` receive `customFields` through
+ * `ObjectForm`'s `{...schema}` spread. Until objectui#10254 they neither
+ * declared nor rendered it, and limb (a) read it there only as a SIGNAL; they
+ * now declare it and draw a member a section names, as the drawer and modal do.
+ */
+/** The shape this module reads — deliberately narrower than any form schema. */
+export interface InlineFieldSource {
+    customFields?: unknown;
+    sections?: unknown;
+}
+/**
+ * Whether the author declared the form's fields inline, i.e. the form is a
+ * self-contained collector whose `onSuccess` is the write.
+ *
+ * Literally `SimpleObjectForm`'s test, kept in one place so the six renderers
+ * cannot answer it six ways.
+ *
+ * The parameter is `object`, not `InlineFieldSource`: TypeScript's weak-type
+ * check rejects an argument sharing no property with a wholly-optional
+ * interface, so a caller whose schema type declares neither key could not pass
+ * it. `TabbedFormSchema` / `SplitFormSchema` / `WizardFormSchema` declared no
+ * `customFields` while they did not render it, since declaring a field source a
+ * renderer ignores is the declared-≠-enforced shape objectui#6300 set out to
+ * undo; they declare it since objectui#10254, which made them render it.
+ */
+export declare function hasInlineFieldSource(schema: object | null | undefined): boolean;
+/**
+ * The refusal message. `SimpleObjectForm`'s own wording, verbatim, so a host
+ * that already matches on it sees one string from all six renderers.
+ */
+export declare const NO_SUBMIT_TARGET_MESSAGE = "DataSource is required for form submission (inline mode not configured)";
+/**
+ * The refusal itself.
+ *
+ * Thrown from INSIDE each container's persistence chain — as the branch taken
+ * when none of the real routes (host seam / create / OCC-guarded edit) applies
+ * — rather than from a pre-`try` guard, for two reasons:
+ *
+ *  1. it is where the fact belongs: "there is no route to persist by" is a
+ *     verdict about the persistence chain, and expressing it there is also what
+ *     lets TypeScript narrow `dataSource` for the routes that use it, with no
+ *     assertion;
+ *  2. the container's `catch` runs `schema.onError?.(err)` and RETHROWS, so the
+ *     host learns why. That is what turns the `MasterDetailForm` reading above
+ *     from `toast.success("Created")` into `toast.error(<this message>)` with
+ *     the form left intact — the visible half of the fix.
+ */
+export declare function noSubmitTargetError(): Error;
+//# sourceMappingURL=submitTarget.d.ts.map

package/dist/submitTarget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submitTarget.d.ts","sourceRoot":"","sources":["../src/submitTarget.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAkCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAI/E;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,4EACsC,CAAC;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,IAAI,KAAK,CAE3C"}

package/dist/successBehavior.d.ts

@@ -9,34 +9,53 @@
  * for another entry (`resetOnSuccess`).
  *
  * Kept dependency-free on purpose: importing the redirect guard from
- * EmbeddableForm would create a cycle (EmbeddableForm → ObjectForm → WizardForm
- * → here), so the same-origin check is inlined.
+ * EmbeddableForm would create a cycle (EmbeddableForm -> ObjectForm ->
+ * WizardForm -> here), so the destination test below is local to this module.
  */
 export type { SubmitBehavior } from '@object-ui/types';
 /**
- * Same-origin guard for declarative navigation (relative or absolute URLs).
- *
- * **Scope note (objectui#4989).** This guard used to gate `submitBehavior:
- * { kind: 'redirect' }` too. It no longer does: objectstack#7496 ruled that key
- * RELATIVE-ONLY, and `submitRedirect.ts` gets that verdict from the spec's own
- * `FormViewSchema`. Relative-only is strictly stronger than same-origin — a
- * rooted relative path is same-origin by construction — so keeping this call in
- * that arm as defence-in-depth would add no defence, while its converse (it says
- * yes to `https://own-host/thanks`) was exactly the defect: this consumer
- * accepted a spelling the authoring door now refuses, which is how a rejected
- * spelling stays alive in a corpus.
- *
- * It survives because {@link resolveSuccessNavigate} still needs it. That serves
- * `navigateOnSuccess` — a DIFFERENT declared key with its own `{id}` /
- * `{recordId}` dialect, no relative-only ruling, and its own contract question
- * still open. Deleting the guard would silently widen that key.
- */
-export declare function isSameOriginUrl(rawUrl: string): boolean;
-/**
- * Resolve a `navigateOnSuccess` template into a safe URL: interpolate
- * `{id}` / `{recordId}` from the created/updated record and same-origin-guard it.
- * Returns null when there's no template, no usable id, or the URL fails the
- * guard — callers then fall back to a toast.
+ * Resolve a `navigateOnSuccess` template into the relative destination to
+ * navigate to, or refuse it. Returns null when there is no template, no usable
+ * id, or the resolved value is out of contract — callers then show the success
+ * toast carrying `NAVIGATE_ON_SUCCESS_REFUSED_NOTE`.
+ *
+ * ## The contract (maintainer ruling, 2026-08-17, objectui#5034)
+ *
+ * `navigateOnSuccess` is the pre-ruling ancestor of the `submitBehavior` family,
+ * not a second dialect, and it is **deprecated in favour of `submitBehavior`**
+ * (which already takes precedence over it, pinned). As a compat alias it runs
+ * under the semantics objectstack#7496 ruled for that family:
+ *
+ *   1. **relative paths only.** A same-origin ABSOLUTE value is refused like any
+ *      other out-of-contract value — not routed differently, refused. The
+ *      destination is authored metadata, which is exactly where an address
+ *      somebody else chose gets copied in.
+ *   2. **the interpolated value is URL-escaped** when the destination is built.
+ *   3. the `{id}` / `{recordId}` dialect **stays** for existing authors of this
+ *      key. It is the one part deliberately not converged: the ruling keeps the
+ *      spelling working and points new authoring at `submitBehavior` instead.
+ *
+ * ## Why both halves are needed, and neither substitutes for the other
+ *
+ * The escape is what stops a token from adding path STRUCTURE. Interpolated raw,
+ * `{id}` with an address in it becomes the whole destination, and `/r/{id}` with
+ * `a/b` in it silently grows a path segment. Relative-only is a rule about where
+ * a destination STARTS, so it has nothing to say about structure injected
+ * further along — the argument `submitRedirect.ts` records for the ruled sibling,
+ * which holds here verbatim.
+ *
+ * Conversely the escape alone would not refuse an authored absolute, because the
+ * template is the AUTHOR's and only the substituted value passes through
+ * `encodeURIComponent`. So: escape the data, judge the result.
+ *
+ * ## This can only narrow what is reachable
+ *
+ * Every destination this returns is a relative reference, and every relative
+ * reference was already accepted by the same-origin guard it replaces (a
+ * relative reference cannot carry an authority, RFC 3986, so it always resolves
+ * to the current origin). Escaping only ever maps an id onto one opaque segment.
+ * So the set of addresses reachable through this key is a strict subset of the
+ * set reachable before — there is no value that was refused and is now followed.
  */
 export declare function resolveSuccessNavigate(template: string | undefined, record: any): string | null;
 //# sourceMappingURL=successBehavior.d.ts.map

package/dist/successBehavior.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"successBehavior.d.ts","sourceRoot":"","sources":["../src/successBehavior.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAQvD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,GAAG,GACV,MAAM,GAAG,IAAI,CAMf"}
+{"version":3,"file":"successBehavior.d.ts","sourceRoot":"","sources":["../src/successBehavior.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA0DvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,GAAG,GACV,MAAM,GAAG,IAAI,CAWf"}

package/dist/thankYouRedirectCountdown.d.ts

@@ -1,4 +1,4 @@
-import { PendingThankYouRedirect } from './thankYouRedirectNavigation';
+import { PendingThankYouRedirect } from './thankYouRedirectNavigation.js';
 /** One tick per displayed second — matches the `{{seconds}}` unit the copy promises. */
 export declare const REDIRECT_COUNTDOWN_TICK_MS = 1000;
 /**

package/dist/uploadGate.d.ts

@@ -0,0 +1,35 @@
+import { default as React } from 'react';
+import { useUploadingScope } from '@object-ui/fields';
+export interface UploadGate {
+    /** True while at least one upload inside this form is still in flight. */
+    uploading: boolean;
+    /** Mount around the form body so its upload widgets report in. */
+    scope: ReturnType<typeof useUploadingScope>;
+    /** The Save button's label while `uploading`. */
+    busyLabel: string;
+    /** Why Save is unavailable — shown, and used as the refusal message. */
+    reason: string;
+}
+/**
+ * Own the gate for one record form. The host renders its form body inside
+ * {@link UploadGateProvider} with the returned `scope`.
+ */
+export declare function useUploadGate(): UploadGate;
+/** Re-exported under this package's own name so hosts import one module. */
+export declare function UploadGateProvider({ gate, children, }: {
+    gate: UploadGate;
+    children: React.ReactNode;
+}): React.ReactElement;
+/**
+ * The visible reason. Rendered beside the action row, not as a toast: the
+ * explanation has to be readable at the moment the user looks at the control
+ * that will not respond, and a toast is gone by then.
+ *
+ * `role="status"` (polite) rather than `alert`: nothing has gone wrong, an
+ * upload is simply still running, and an assertive live region would interrupt
+ * a screen-reader user mid-sentence every time a file is picked.
+ */
+export declare function UploadInFlightNotice({ gate }: {
+    gate: UploadGate;
+}): React.ReactElement | null;
+//# sourceMappingURL=uploadGate.d.ts.map

package/dist/uploadGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploadGate.d.ts","sourceRoot":"","sources":["../src/uploadGate.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,iBAAiB,EAA0B,MAAM,mBAAmB,CAAC;AAgD9E,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,KAAK,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;IAC5C,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAS1C;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EACJ,QAAQ,GACT,EAAE;IACD,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,GAAG,KAAK,CAAC,YAAY,CAErB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAO9F"}

package/dist/writePayload.d.ts

@@ -0,0 +1,68 @@
+import { LoadedRecordSnapshot } from './sanitize.js';
+import { FieldWriteGate } from './fieldWriteGate.js';
+/** The facts of a form schema the outbound sequence reads. */
+export interface FormWriteTarget {
+    mode?: string;
+    objectName: string;
+    recordId?: string | number | null;
+    /** Inline field definitions (`object-form.customFields`). */
+    customFields?: readonly unknown[] | null;
+}
+/** Where the outbound sequence gets its answers from. */
+export interface FormWriteSources {
+    /** The object definition the form loaded, or `null` when it has none. */
+    objectSchema: {
+        fields?: Record<string, Record<string, unknown> | undefined>;
+    } | null | undefined;
+    /** The caller's field-level write verdict — {@link FieldWriteGate}. */
+    canEdit: FieldWriteGate | undefined;
+    /** The record this form read for the record it edits (objectui#10156). */
+    snapshot: LoadedRecordSnapshot | null | undefined;
+}
+export interface FormWritePayloads {
+    /**
+     * Every value the form may write, as the form now holds it: stripped of what
+     * a form never writes and, on a create, of the fields the producer owns.
+     */
+    payload: Record<string, unknown>;
+    /**
+     * What the save sends — on BOTH routes, the host `submitHandler` and the
+     * form's own create / OCC-guarded update. On an edit, the fields of
+     * {@link FormWritePayloads.payload} that differ from the record the form
+     * read; otherwise `payload` itself.
+     */
+    writePayload: Record<string, unknown>;
+}
+/**
+ * The ONE outbound sequence of a record form: what a save writes, built from
+ * the values the form collected (objectui#10563).
+ *
+ * 1. `sanitizeFormData` drops what a form never writes — server-owned columns
+ *    (objectui#10108), computed / formula / read-only columns, keys the object
+ *    does not declare, and every field the caller's field-level security
+ *    refuses (`canEdit`, `80c54122e`).
+ * 2. On a create, `omitServerResolvedDefaults` drops an empty field whose
+ *    runtime default the producer resolves (#4069).
+ * 3. On an edit, `dirtyEditPayload` keeps only the fields that differ from the
+ *    record the form read (objectui#10156), and sends the whole of step 1's
+ *    result when it cannot settle that.
+ *
+ * ## Why it is one function
+ *
+ * `ObjectForm` routes a record save through several layouts, and each layout
+ * owns its save handler. When the sequence was spelled inline in each handler,
+ * three of them — `TabbedForm`, `SplitForm` and `WizardForm` (which also renders
+ * a simple form's mobile `stepper`) — carried none of it and wrote every value
+ * they held, `id`, `owner_id`, the formula columns and the field-level-refused
+ * ones included. ⛔ Do not spell any step of it beside a call to this function.
+ *
+ * ## The inline-members rule
+ *
+ * With a non-empty `customFields` the object definition is NOT handed to steps
+ * 1 and 2: an inline member may name a field the object never declares (it is
+ * appended after the generated set, objectui#9778), and the unknown-key strip
+ * would drop the value the author asked for. The server-owned roster and the
+ * field-level verdict still apply, because neither needs a definition.
+ */
+export declare function formWritePayload(values: Record<string, unknown>, form: FormWriteTarget, { objectSchema, canEdit, snapshot }: FormWriteSources): FormWritePayloads;
+//# sourceMappingURL=writePayload.d.ts.map

package/dist/writePayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writePayload.d.ts","sourceRoot":"","sources":["../src/writePayload.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;CAC1C;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,YAAY,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAC;IAClG,uEAAuE;IACvE,OAAO,EAAE,cAAc,GAAG,SAAS,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,eAAe,EACrB,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,gBAAgB,GACpD,iBAAiB,CAanB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/plugin-form",
-  "version": "17.6.0",
+  "version": "17.7.0",
   "type": "module",
   "license": "MIT",
   "description": "Form plugin for Object UI",
@@ -16,14 +16,14 @@
   },
   "dependencies": {
     "@objectstack/spec": "^17.0.0",
-    "lucide-react": "^1.31.0",
-    "@object-ui/components": "17.6.0",
-    "@object-ui/core": "17.6.0",
-    "@object-ui/fields": "17.6.0",
-    "@object-ui/i18n": "17.6.0",
-    "@object-ui/permissions": "17.6.0",
-    "@object-ui/react": "17.6.0",
-    "@object-ui/types": "17.6.0"
+    "lucide-react": "^1.43.0",
+    "@object-ui/components": "17.7.0",
+    "@object-ui/core": "17.7.0",
+    "@object-ui/fields": "17.7.0",
+    "@object-ui/i18n": "17.7.0",
+    "@object-ui/permissions": "17.7.0",
+    "@object-ui/react": "17.7.0",
+    "@object-ui/types": "17.7.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -35,7 +35,8 @@
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
     "vite-plugin-dts": "^5.0.3",
-    "@object-ui/data-objectstack": "17.6.0"
+    "@object-ui/data-objectstack": "17.7.0",
+    "@object-ui/test-support": "17.4.0"
   },
   "keywords": [
     "objectui",
@@ -71,7 +72,7 @@
   ],
   "scripts": {
     "build": "vite build",
-    "test": "vitest run",
+    "test": "vitest run --root ../.. packages/plugin-form/",
     "type-check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "lint": "eslint ."
   }