@object-ui/plugin-form 17.6.0 → 18.0.0

package/dist/initialFieldFocus.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 first control, in document order, that a user can edit in the first
+ * field row that has one. `null` while no field row is drawn (the body is
+ * loading) or when every field is read-only (a view-mode form).
+ */
+export declare function findFirstEditableField(root: ParentNode): HTMLElement | null;
+/**
+ * The `onOpenAutoFocus` / `onCloseAutoFocus` pair for a dialog content whose
+ * body loads after it opens. Pass both to the dialog content; the observer the
+ * open handler may start is stopped on close, on the next open and on unmount.
+ */
+export declare function useInitialFieldFocus(): {
+    onOpenAutoFocus: (event: Event) => void;
+    onCloseAutoFocus: (event: Event) => void;
+};
+//# sourceMappingURL=initialFieldFocus.d.ts.map

package/dist/initialFieldFocus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialFieldFocus.d.ts","sourceRoot":"","sources":["../src/initialFieldFocus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmDH;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAO3E;AAeD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI;IACtC,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACxC,gBAAgB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC1C,CAmEA"}

package/dist/initialRecord.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 opening record an `object-form`-shaped schema authors through its two
+ * seed keys — `initialValues` and its alternate spelling `initialData`
+ * (objectui#9760).
+ *
+ * ## The defect this replaces
+ *
+ * Every presentation arm used to choose between the two keys as WHOLE OBJECTS:
+ *
+ * ```ts
+ * schema.initialData || schema.initialValues
+ * ```
+ *
+ * `||` tests the object, never its size, and `{}` is truthy. So an author who
+ * prefilled three fields through `initialValues` and added a one-member
+ * `initialData` lost the other two, and an author whose `initialData` computed
+ * to an EMPTY object — the shape a `?? {}` producer hands over when it has
+ * nothing to contribute — got a completely blank form where a populated
+ * `initialValues` sat right beside it. No warning, no empty state, no
+ * diagnostic: the form simply opened blank where it used to open seeded.
+ *
+ * Nothing declared ever said that. The registration calls `initialData` an
+ * "alternate spelling of `initialValues` … read FIRST", which is a statement of
+ * PRECEDENCE — the reading a per-member merge implements — and is what an
+ * author gets here now.
+ *
+ * ## Why it is one function rather than a corrected expression per arm
+ *
+ * The `||` was spelled at every read site of every presentation arm — the set a
+ * `git grep` for this module's name now enumerates — and the two spellings
+ * around it were not even the same: the create branches passed the chosen
+ * object into `seedCreateValues` (which layers the object schema's declared
+ * `defaultValue`s underneath it) while the rest installed it directly with a
+ * trailing `|| {}`. Two expressions free to drift are how one arm comes to
+ * answer "which spelling wins" differently from its neighbour, which is a
+ * question no author can even ask of a JSON schema. One function cannot drift.
+ *
+ * ## The contract
+ *
+ * `initialData` wins PER MEMBER, `initialValues` supplies every member it says
+ * nothing about, and the result is always a fresh plain object — never `null`,
+ * never `undefined`, never either authored object by reference. Callers may
+ * therefore spread it, hand it to `seedCreateValues` as the caller layer, or
+ * install it as form state without a `|| {}` tail.
+ *
+ * An explicit `null` MEMBER is preserved, on both sides: a caller writing
+ * `{ status: null }` is saying "open this control blank", which is a value and
+ * not an absence — the same reading `seedCreateValues`' docblock takes of the
+ * seed as a whole. Only a missing or nullish KEY contributes nothing.
+ */
+/** The two seed keys, as every presentation arm's schema declares them. */
+export interface InitialRecordSchemaLike {
+    /** Values to prefill in `create` mode. */
+    initialValues?: Record<string, any> | null;
+    /** Alternate spelling of `initialValues`, read FIRST — i.e. per member it wins. */
+    initialData?: Record<string, any> | null;
+}
+/**
+ * The record a form opens with, merged per member with `initialData` on top.
+ *
+ * Returns a fresh object (never shared with either input, never nullish), so
+ * every caller can install or spread it unconditionally.
+ */
+export declare function resolveInitialRecord(schema: InitialRecordSchemaLike | null | undefined): Record<string, any>;
+//# sourceMappingURL=initialRecord.d.ts.map

package/dist/initialRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialRecord.d.ts","sourceRoot":"","sources":["../src/initialRecord.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC3C,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GACjD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAErB"}

package/dist/loadFailure.d.ts

@@ -0,0 +1,28 @@
+import { Dispatch, MutableRefObject, SetStateAction } from 'react';
+/** The two reads a record form makes before it can draw. */
+export type LoadSource = 'schema' | 'record';
+/** The latest failure of each read, or `null` when its current run has not failed. */
+export type LoadFailures = Readonly<Record<LoadSource, Error | null>>;
+/** Neither read has failed. */
+export declare const NO_LOAD_FAILURES: LoadFailures;
+/** The number of the latest run of each read. Held in a ref: nothing renders from it. */
+export type LoadRunSeq = Record<LoadSource, number>;
+/** One run of one read. Each method is a no-op once a newer run of that read has begun. */
+export interface LoadRun {
+    /** This run failed: its read's failure becomes `err`. */
+    fail(err: unknown): void;
+    /** This run committed what it read: its read's failure, if any, is cleared. */
+    commit(): void;
+}
+/**
+ * Number a new run of `source` and hand back its two writes. Call it once per
+ * run of the fetch effect, synchronously in the effect body, so the number
+ * moves when the effect does rather than when a read happens to settle.
+ */
+export declare function beginLoadRun(seqRef: MutableRefObject<LoadRunSeq>, setFailures: Dispatch<SetStateAction<LoadFailures>>, source: LoadSource): LoadRun;
+/**
+ * The failure the error screen reports, or `null` when the form may draw. The
+ * schema's comes first: without it the fields the record fills are unknown.
+ */
+export declare function shownLoadFailure(failures: LoadFailures): Error | null;
+//# sourceMappingURL=loadFailure.d.ts.map

package/dist/loadFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadFailure.d.ts","sourceRoot":"","sources":["../src/loadFailure.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAExE,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC;AAEtE,+BAA+B;AAC/B,eAAO,MAAM,gBAAgB,EAAE,YAA6C,CAAC;AAE7E,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AAEpD,2FAA2F;AAC3F,MAAM,WAAW,OAAO;IACtB,yDAAyD;IACzD,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,+EAA+E;IAC/E,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,CAAC,UAAU,CAAC,EACpC,WAAW,EAAE,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,EACnD,MAAM,EAAE,UAAU,GACjB,OAAO,CAYT;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,GAAG,IAAI,CAErE"}

package/dist/masterDetailTx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"masterDetailTx.d.ts","sourceRoot":"","sources":["../src/masterDetailTx.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAGlE,eAAO,MAAM,IAAI,GAAI,KAAK,GAAG,KAAG,MAAM,GAAG,SACsB,CAAC;AAEhE;qDACqD;AACrD,MAAM,MAAM,WAAW,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AAiB9E,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAC5B;8EAC0E;IAC1E,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,yBAAyB,CAAC;AAIhD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,CAMxF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,EAAE,CAWX;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,OAAO,EAAE,oBAAoB,EAAE,GAC9B,OAAO,EAAE,CAqBX;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAC7B,OAAO,CAST;AAED,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM1E"}
+{"version":3,"file":"masterDetailTx.d.ts","sourceRoot":"","sources":["../src/masterDetailTx.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAKlE,eAAO,MAAM,IAAI,GAAI,KAAK,GAAG,KAAG,MAAM,GAAG,SACsB,CAAC;AAEhE;qDACqD;AACrD,MAAM,MAAM,WAAW,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AA+B9E,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAC5B;8EAC0E;IAC1E,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,yBAAyB,CAAC;AAIhD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,CAMxF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,EAAE,CAWX;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,OAAO,EAAE,oBAAoB,EAAE,GAC9B,OAAO,EAAE,CAwCX;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAC7B,OAAO,CAST;AAED,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM1E"}

package/dist/occSave.d.ts

@@ -17,7 +17,9 @@
  * forms were the only link in the chain not sending it.
  *
  * `useOccSave` centralises the guarded write:
- *   1. `update` is issued with `ifMatch` = the `updated_at` the form read.
+ *   1. `update` is issued with `ifMatch` = the `updated_at` the form read —
+ *      or, once this hook has itself saved that record, the version its last
+ *      successful write returned (objectui#10565; see `versionToSend`).
  *   2. On `409 CONCURRENT_UPDATE` a dialog offers **Keep editing** (stay in
  *      the form, draft intact) or **Overwrite** (retry re-keyed to the
  *      server's `currentVersion` — "I know it changed, mine wins").
@@ -60,6 +62,9 @@ export interface OccSaveArgs {
     /**
      * The record as the form read it (`findOne` result) — supplies the
      * `updated_at` version token. Optional: without it the write is unguarded.
+     * It decides WHETHER the write is guarded; after this hook's own save of
+     * the same record it no longer decides WHICH version is sent (see
+     * `versionToSend`).
      */
     baseRecord?: unknown;
 }

package/dist/occSave.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"occSave.d.ts","sourceRoot":"","sources":["../src/occSave.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA6B/B;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI/D;AAED,MAAM,MAAM,cAAc;AACxB,+DAA+D;AAC7D;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE;AAClC,6EAA6E;GAC3E;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC;AAE5B,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,GAAG,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAeD;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI;IAC5B,WAAW,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC;CACjC,CAyFA"}
+{"version":3,"file":"occSave.d.ts","sourceRoot":"","sources":["../src/occSave.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA8B/B;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI/D;AAED,MAAM,MAAM,cAAc;AACxB,+DAA+D;AAC7D;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE;AAClC,6EAA6E;GAC3E;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC;AAE5B,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,GAAG,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA0ED;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI;IAC5B,WAAW,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC;CACjC,CAmIA"}

package/dist/recordInvalidation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+export interface RecordInvalidation {
+    /**
+     * Bumped once per re-read this form decides to run. The record read effect
+     * names it in its dependency list; nothing else reads it.
+     */
+    refetch: number;
+    /**
+     * The form renderer's `onDirtyChange`. A host with dirty state of its own
+     * composes this with it; `false` replays a held re-read.
+     */
+    onDirtyChange: (dirty: boolean) => void;
+    /**
+     * This form's edit landed: what it shows is what the server holds. Clears
+     * dirty and replays a held re-read once (the write's own bus echo included).
+     */
+    saved: () => void;
+}
+/**
+ * @param objectName the object the form reads
+ * @param recordId the record it reads
+ * @param readsRecord whether it reads one at all — edit or view mode with a
+ *   `recordId`, and (for the default arm) no inline field source. When `false`
+ *   the bus is not subscribed to and `refetch` never moves.
+ */
+export declare function useRecordInvalidation(objectName: string | undefined, recordId: string | number | undefined, readsRecord: boolean): RecordInvalidation;
+//# sourceMappingURL=recordInvalidation.d.ts.map

package/dist/recordInvalidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordInvalidation.d.ts","sourceRoot":"","sources":["../src/recordInvalidation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6CH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACrC,WAAW,EAAE,OAAO,GACnB,kBAAkB,CAuCpB"}

package/dist/recordReadGate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 first-record-read gate, shared by the two overlay containers
+ * (`DrawerForm`, objectui#10190; `ModalForm`, objectui#10659).
+ *
+ * Each container builds its fields and reads its record in two effects, and
+ * both key on `objectSchema`. The commit that publishes the schema therefore
+ * runs both, fetch first: the fetch effect enters the loading state and fires
+ * `findOne`, and a fields effect that ended the loading state unconditionally
+ * then won. That painted an empty, EDITABLE form while the read was in flight,
+ * and the landing record replaced whatever had been typed. The save that
+ * followed compared the record with itself and sent it whole, with its
+ * original values.
+ *
+ * So the fields effect ends the loading state only when this answers `false`.
+ * A load the fetch effect started is ended by the fetch effect. The condition
+ * mirrors that effect's own branches: create mode, no `recordId`, or no
+ * `dataSource` never read a record. `loadedRecordId` is the id of the record
+ * the form currently holds, which the fetch effect sets when its read lands,
+ * so this covers the FIRST load and a record swap alike.
+ */
+export declare function isRecordReadOutstanding(state: {
+    mode?: string;
+    recordId?: string | number;
+    dataSource: unknown;
+    loadedRecordId: string | number | undefined;
+}): boolean;
+//# sourceMappingURL=recordReadGate.d.ts.map

package/dist/recordReadGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordReadGate.d.ts","sourceRoot":"","sources":["../src/recordReadGate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC7C,GAAG,OAAO,CAOV"}

package/dist/sanitize.d.ts

@@ -6,18 +6,285 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Strip server-managed and computed fields from a form payload before sending
+ * The refused-field roster: every field name the SERVER owns on write.
+ *
+ * ## What it is
+ *
+ * The framework's `applySystemFields` stamps these columns onto every business
+ * object — record identity, audit provenance (`created_*` / `updated_*`), and
+ * the reassignable ownership / tenancy FKs (`owner_id`,
+ * `owning_business_unit_id`, `organization_id`, `tenant_id`, `company_id`,
+ * `space`). They are not author-declared business data, and a form may never
+ * echo one back.
+ *
+ * One of them is also a value a user may set: the record's owner. The spec
+ * declares `owner_id` `system` but NOT `readonly`, because ownership is
+ * transferable from a form. It stays in this roster — an untouched owner is
+ * still never sent, and an auto-laid-out form still never renders it — and an
+ * EDIT adds it back only when the user changed it against the record the form
+ * read ({@link dirtyEditPayload}, objectui#12205), and a CREATE only when the
+ * user picked it against the values the form opened with
+ * ({@link createOwnerPayload}, objectui#12359). The rest of the family is
+ * not reassignable from a form: the spec declares the business-unit and tenant
+ * anchors `readonly`, so they stay refused even when they differ.
+ *
+ * ## Why one roster, and why it is THIS roster
+ *
+ * `filterSystemFields` in `autoLayout.ts` reads the same set to decide what an
+ * auto-laid-out form RENDERS, in create and edit mode alike. The two readings
+ * are deliberately the same object, because the invariant they express is one
+ * invariant: **a form never writes a field it refuses to render.** Spelling the
+ * refusal separately at each call site is how they drifted — the render side
+ * had dropped `owner_id` since it was written, while the write side had not, so
+ * an edit form that showed the user two business inputs still sent back every
+ * ownership and audit column it had read (objectui#10108).
+ *
+ * That drift is not a cosmetic one. The platform refuses a write to a
+ * system-managed ownership column unless the caller holds the transfer grant
+ * (`allowTransfer` / `modifyAllRecords`), and it cannot tell a round-trip of
+ * the value it just served from an attempted ownership transfer. So a form
+ * echoing an UNCHANGED `owner_id` back is a 403 for every role that does not
+ * hold the grant — which, for a line-entry role, is the whole point of the
+ * role. The master-detail save sends its operations as one atomic batch, so a
+ * single echoed column refuses the entire save.
+ *
+ * ## What is deliberately NOT here
+ *
+ * The lifecycle bookkeeping columns (`locked`, `instance_state`, `deleted`,
+ * `is_deleted`) are left out. They are plausibly author-writable — a workflow
+ * or an admin form that drives record state is writing business meaning, not
+ * echoing provenance — and nothing has measured them refusing a write. Adding
+ * one here on the strength of the pattern alone would silently drop a value a
+ * form was asked to persist, which is the failure direction this module must
+ * not take.
+ *
+ * ⚠️ A name list alone cannot close the class: the NEXT injected column the
+ * platform adds will not be in it. {@link sanitizeFormData} therefore branches
+ * on the spec `system` flag first whenever a field definition is available —
+ * that flag is the registry's own mark on everything it injects, and
+ * `isSystemManagedField` in `@object-ui/types` reads the same one. This roster
+ * is the fallback for metadata that arrives without the flag.
+ */
+export declare const SERVER_OWNED_FIELD_NAMES: ReadonlySet<string>;
+/**
+ * Strip server-owned and computed fields from a form payload before sending
  * it to `dataSource.create()` / `dataSource.update()`.
  *
- * - Drops well-known server-owned keys (id, created_at, organization_id, …).
+ * - Drops every name in {@link SERVER_OWNED_FIELD_NAMES}.
+ * - When `objectSchema` is provided, drops any field the spec marks
+ *   `system: true` — the registry's own mark on the columns it injects, so a
+ *   column added to the platform after this module was written is refused
+ *   without anyone editing the roster.
  * - When `objectSchema` is provided, drops fields that are flagged as
- *   `computed` / `formula` / `readOnly` or whose type is in
- *   {@link COMPUTED_FIELD_TYPES}.
+ *   `computed` / `readOnly` or whose type is in {@link COMPUTED_FIELD_TYPES}.
+ *   A `formula` key is NOT a flag this reads (objectui#11070 round 6): every
+ *   `type: 'formula'` field is already dropped by its type, and
+ *   `@objectstack/spec`'s `FieldSchema` refuses `formula` by name on every
+ *   field type (renaming it to `expression`), so no served definition can use
+ *   it to mark some other type computed.
  * - When `objectSchema` is provided, also drops keys that don't appear in
  *   `objectSchema.fields` at all (these are typically server-projected
  *   relationships or flattened lookups like `full_name`).
+ * - When `options.canEdit` is provided, drops every field that predicate
+ *   refuses — the CALLER's field-level security, which no schema can answer.
+ *
+ * Its output never carries the owner. An edit's changed owner is judged after
+ * this, against the record the form read, by {@link dirtyEditPayload}
+ * (objectui#12205), and a create's picked owner against the values the form
+ * opened with, by {@link createOwnerPayload} (objectui#12359) — the two places
+ * that can tell a user's pick from an echo.
+ *
+ * The two server-owned branches are separate on purpose and neither subsumes
+ * the other: the name roster fires with no schema at all (an inline form passes
+ * `null`), and the `system` flag fires for a name the roster has never heard
+ * of.
+ *
+ * ## Why field-level security arrives as a PREDICATE, not as more schema
+ *
+ * The branches above are properties of the OBJECT: the same for every caller,
+ * readable off metadata this function is already handed. Field-level security
+ * is a property of the CALLER — `score` is writable for one principal and
+ * refused for the next, on the identical object — so it cannot be read off
+ * `objectSchema` and must not be re-derived here. `fieldWriteGate` in
+ * `./fieldWriteGate` adapts the ONE resolver that owns that answer
+ * (`checkField` in `@object-ui/permissions`, asked the question the form's
+ * mode reads from the affordance-to-grant map — objectui#12082) into this
+ * predicate. It arrives here, at the single outbound filter, rather than as a
+ * strip loop after each container's call, because every such loop is a copy
+ * that can be forgotten — and one of the three containers had forgotten it
+ * (`80c54122e`).
  */
 export declare function sanitizeFormData(data: Record<string, any>, objectSchema?: {
     fields?: Record<string, any>;
-} | null): Record<string, any>;
+} | null, options?: {
+    canEdit?: (fieldName: string) => boolean;
+}): Record<string, any>;
+/**
+ * Whether two payload values are the SAME stored value — the one comparison
+ * every dirty-field diff in this package uses: the master-detail child rows in
+ * `masterDetailTx.ts` (objectui#10108) and the edit form's own record
+ * (objectui#10156). ⛔ Do not write a second equality rule beside it; two rules
+ * would drift, and the one that drifted towards "equal" would drop edits.
+ *
+ * ⚠️ The comparison is deliberately asymmetric in its failure direction. Saying
+ * "changed" about an equal pair costs one redundant column on the wire; saying
+ * "unchanged" about a changed pair DISCARDS the user's edit, silently, with a
+ * 200 back. So every case this cannot settle confidently reads as changed.
+ *
+ * The rule, pair by pair:
+ *
+ * - The same value (`===`) is equal.
+ * - `null` and `undefined` are one blank — the only two blanks a form
+ *   round-trip actually interchanges. `''` is NOT a blank here: `null` and
+ *   `''` read as different, and so do `undefined` and `''`.
+ * - Numbers never equal strings: `1000` and `'1000'` read as different.
+ * - Two `Date`s are equal only when both hold the same finite time. A `Date`
+ *   and a date STRING read as different, and so do two date strings in
+ *   different formats (`'2026-01-02'` and `'2026-01-02T00:00:00Z'`).
+ * - Two objects or arrays are equal only when they serialize identically. A
+ *   reordered key or array element reads as changed, which is the safe side.
+ * - A lookup's id and its expanded object (`'a1'` and `{ id: 'a1', … }`) read
+ *   as different: one is a string and the other an object.
+ * - Anything else is different, including `NaN` against itself.
+ */
+export declare function isSameStoredValue(a: unknown, b: unknown): boolean;
+/**
+ * The subset of `next` that differs from the loaded snapshot `prev` — the
+ * DIRTY fields, and only those, judged by {@link isSameStoredValue}.
+ *
+ * An update that carries an unchanged column is not free: the platform refuses
+ * a write to a system-managed ownership column unless the caller holds the
+ * transfer grant, and it cannot tell a round-trip of the value it just served
+ * from an attempted transfer. A master-detail save commits as ONE atomic batch,
+ * so one such column on any row refuses every row (objectui#10108).
+ * `sanitizeFormData` already refuses the columns the server owns by name;
+ * sending only what the user actually changed is the half that does not depend
+ * on a roster being complete.
+ */
+export declare function changedFields(next: Record<string, any>, prev: Record<string, any>): Record<string, any>;
+/**
+ * The record an edit form READ from its data source, tagged with the object
+ * and record it was read for (objectui#10156).
+ *
+ * It is the baseline an edit save diffs against, and it is held by the form
+ * component that performed the read — never passed in by a host. A record a
+ * caller supplied (`initialData`, inline `customFields`) is a prefill, not the
+ * row as stored, so no snapshot is taken for it and its save sends every field.
+ */
+export interface LoadedRecordSnapshot {
+    objectName: string;
+    recordId: string;
+    record: Record<string, unknown>;
+}
+/** The three facts of a form schema that decide whether a snapshot applies. */
+export interface EditSaveTarget {
+    mode?: string;
+    objectName: string;
+    recordId?: string | number | null;
+}
+/**
+ * Take the snapshot for a record just read with `findOne`, or `null` when the
+ * read returned nothing usable.
+ */
+export declare function snapshotLoadedRecord(target: EditSaveTarget, data: unknown): LoadedRecordSnapshot | null;
+/**
+ * The payload an EDIT save writes: only the fields that differ from the record
+ * the form loaded (objectui#10156).
+ *
+ * `payload` is the output of {@link sanitizeFormData}. Every case that cannot
+ * be settled resolves towards SENDING, because a false "clean" drops the user's
+ * edit and the server still answers 200:
+ *
+ * - Not an edit, or no snapshot was read for this object and record (a create,
+ *   a caller-supplied record, a record swap still in flight) → `payload`
+ *   unchanged, every field sent.
+ * - A snapshot applies → the fields {@link changedFields} reports. Fields the
+ *   form itself moved after the load — a cascade clear, a clear-on-hide, a
+ *   value the form computed — differ from the loaded record, so they are sent.
+ * - The diff is EMPTY → `payload` unchanged. A save with nothing changed stays
+ *   the request it has always been: the same write, the same OCC guard and a
+ *   real server record for `onSuccess`. Emitting no request instead would
+ *   report success for a save no server saw, and that is the one outcome a
+ *   wrong baseline must never be able to produce.
+ *
+ * ## The owner (objectui#12205)
+ *
+ * `payload` never carries the owner: `sanitizeFormData` drops it, because the
+ * platform refuses an echoed owner from every role without the transfer grant
+ * and cannot tell an echo from a transfer (objectui#10108). That drop also
+ * swallowed a REAL reassignment or clear — the form closed as if it saved and
+ * the record kept its owner. This is the one place that can tell the two
+ * apart, so `owner` hands it the values the form holds and the strip's own
+ * inputs, and the owner is added to the diff when, and only when:
+ *
+ * - a snapshot applies — with none, nothing proves the owner changed, so it
+ *   stays off the wire exactly as before;
+ * - the form holds a value for it (`undefined` is not a clear; a clear is
+ *   `null`) and {@link changedFields} reports it against the record read;
+ * - everything else `sanitizeFormData` asks still allows it: the caller's
+ *   field-level security, the object declaring it, and it not being
+ *   `readonly` or computed.
+ *
+ * The server stays the authority: a role without the transfer grant is refused
+ * with a 403, which the form shows as its error. A caller that passes no
+ * `owner` gets the diff it always got.
+ */
+export declare function dirtyEditPayload(payload: Record<string, unknown>, snapshot: LoadedRecordSnapshot | null | undefined, target: EditSaveTarget, owner?: EditOwnerSource | null): Record<string, unknown>;
+/**
+ * The payload a CREATE save writes: `payload`, plus the owner when the user
+ * picked one on this New form (objectui#12359).
+ *
+ * `payload` is the output of {@link sanitizeFormData}, which never carries the
+ * owner. Before this, a New form that rendered Owner let the user pick a user,
+ * showed the pick, and then saved the record under the creator with no error.
+ *
+ * "Picked" means the same thing it means on an edit, judged against the values
+ * the form OPENED with instead of a record it read: `seed` is the create
+ * form's opening values (`seedCreateValues` — the declared defaults, a
+ * `current_user` default resolved to the acting user, and any caller-supplied
+ * initial values). So the owner is added when, and only when:
+ *
+ * - the caller hands a `seed` — with none, nothing proves the user set the
+ *   owner, so it stays off the wire exactly as before;
+ * - the form holds a value for it (`undefined` is not a pick) and
+ *   {@link changedFields} reports it against `seed`. An owner the form was
+ *   seeded with and the user left alone — the creator from a `current_user`
+ *   default, or a caller's prefill — is NOT a pick, and is never sent
+ *   (objectui#10108);
+ * - everything else {@link sanitizeFormData} asks still allows it: the
+ *   caller's field-level security, the object declaring it, and it not being
+ *   `readonly` or computed.
+ *
+ * The client does not guess whether the caller may assign another owner. The
+ * server judges it: an insert naming another user is refused without the
+ * transfer grant (`allowTransfer` / `modifyAllRecords`), and the form shows
+ * that refusal as its error. A caller that passes no `owner` gets `payload`.
+ */
+export declare function createOwnerPayload(payload: Record<string, unknown>, seed: Record<string, unknown> | null | undefined, owner?: EditOwnerSource | null): Record<string, unknown>;
+/**
+ * What a save hands {@link dirtyEditPayload} (an edit) or
+ * {@link createOwnerPayload} (a create) so it can judge the owner.
+ */
+export interface EditOwnerSource {
+    /** The values the form holds — BEFORE `sanitizeFormData`, which drops the owner. */
+    values: Record<string, unknown>;
+    /** The definition `payload` was sanitized against (`null` for inline members). */
+    objectSchema?: {
+        fields?: Record<string, unknown>;
+    } | null;
+    /** The field-level verdict `payload` was sanitized with. */
+    canEdit?: (fieldName: string) => boolean;
+}
+/**
+ * The snapshot after an edit save SUCCEEDED: the fields just written, laid over
+ * the record as read.
+ *
+ * A form that stays mounted after a save must not diff its next save against
+ * the row as FIRST read. Changing a field and then changing it back to the
+ * value first read would compare equal to that stale baseline and be dropped,
+ * while the server still holds the first save's value. Advancing the baseline
+ * by what the server accepted closes that. A snapshot read for another record
+ * is returned untouched.
+ */
+export declare function advanceLoadedRecord(snapshot: LoadedRecordSnapshot | null | undefined, target: EditSaveTarget, written: Record<string, unknown>): LoadedRecordSnapshot | null;
 //# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+BH;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,YAAY,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GAAG,IAAI,GACrD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAwBrB"}
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"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"}