@orkestrel/form 0.0.9 → 0.0.10

package/dist/src/core/index.d.cts

@@ -502,8 +502,10 @@ export declare class Form implements FormInterface {
     get schema(): FormSchema;
     /** Reports the answers the form holds. */
     get values(): FormValues;
-    /** Holds the answers the form opened with. */
+    /** Holds the acknowledged answers, initially the schema's defaults overlaid with seeded values. */
     get baseline(): FormValues;
+    /** Holds the submission awaiting acknowledgement, or `undefined` when none is pending. */
+    get pending(): FormSubmission | undefined;
     /** Holds every error the last completed evaluation produced. */
     get errors(): readonly FieldError[];
     /** Lists the names of the fields somebody has visited. */
@@ -514,7 +516,7 @@ export declare class Form implements FormInterface {
     get status(): FormStatus;
     /** Reports whether the last completed evaluation found no error. */
     get valid(): boolean;
-    /** Reports whether any answer has moved since the form opened. */
+    /** Reports whether any answer differs from its acknowledged baseline. */
     get dirty(): boolean;
     /**
      * Holds the answers after the form settles.
@@ -557,13 +559,15 @@ export declare class Form implements FormInterface {
      *
      * @param name - The field's name.
      * @param message - What to tell the person.
+     * @param submission - The active receipt to check against the field's captured revision.
+     * @returns True if the failure was applied; false if the receipt or field revision is stale.
      * @remarks
      * One field holds one external failure: a second call replaces the first. The failure lasts
      * until that field is filled again or the form is cleared.
      * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
      *   `FIELD` when the schema declares no such name.
      */
-    invalidate(name: string, message: string): void;
+    invalidate(name: string, message: string, submission?: FormSubmission): boolean;
     /** Takes every field out of the form. */
     disable(): void;
     /**
@@ -610,8 +614,34 @@ export declare class Form implements FormInterface {
      */
     submit(): FormResult;
     /**
-     * Returns every answer to the ones the form opened with: the schema's defaults, overlaid with
-     * any seeded `values`. Reset the runtime disabled state to the schema's declarations.
+     * Prepares an owned enabled snapshot for acknowledgement while leaving the form editable.
+     *
+     * @returns The submission on success, or the errors that prevented preparation.
+     * @remarks
+     * A failed check refuses its checked errors even if an observer repairs them. A passing check
+     * drains observer mutations through one further check. The receipt always carries that check's
+     * snapshot, including when its notifications produce later edits. A throwing validator creates
+     * no receipt. The pending identity is installed before `prepare` listeners run.
+     * @throws A {@link FormError} coded `PENDING` while another preparation or receipt is pending,
+     *   or when clear interrupts preparation; terminal forms retain their terminal refusals.
+     */
+    prepare(): FormPreparationResult;
+    /**
+     * Adopts the active submission's captured answers into the baseline without changing live state.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was accepted; false otherwise, including after teardown.
+     */
+    accept(submission: FormSubmission): boolean;
+    /**
+     * Consumes the active submission and aborts its signal without changing answers or baseline.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was aborted; false otherwise, including after teardown.
+     */
+    abort(submission: FormSubmission): boolean;
+    /**
+     * Returns every answer to its acknowledged baseline and aborts pending acknowledgement.
      *
      * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
      */
@@ -679,9 +709,10 @@ export declare class FormError extends Error {
  * @remarks
  * `SCHEMA` rejects a malformed schema. `FIELD` names a field the schema does not declare.
  * `CONTROL` reports a value the field's control cannot hold. `SETTLED` and `ABANDONED`
- * refuse a write to a form that has already ended.
+ * refuse a write to a form that has already ended. `PENDING` refuses a preparation or terminal
+ * submit while preparation or acknowledgement is pending, or a preparation interrupted by clear.
  */
-export declare type FormErrorCode = 'SCHEMA' | 'FIELD' | 'CONTROL' | 'SETTLED' | 'ABANDONED';
+export declare type FormErrorCode = 'SCHEMA' | 'FIELD' | 'CONTROL' | 'SETTLED' | 'ABANDONED' | 'PENDING';
 
 /**
  * Lists everything a form announces.
@@ -691,14 +722,19 @@ export declare type FormErrorCode = 'SCHEMA' | 'FIELD' | 'CONTROL' | 'SETTLED' |
  * being cleared. `validate` carries the errors a check produced, empty when it found none.
  * `disable` and `enable` each carry one field, and fire once per field whose state actually
  * moved, in the order the schema declares them. `submit` fires only on a submit that passed.
- * `clear` and `abandon` are signals.
+ * `touch` announces the first visit since clear. `prepare`, `accept`, and `abort` carry the receipt
+ * after their state is committed. `clear` and `abandon` are signals.
  */
 export declare type FormEventMap = {
     readonly fill: readonly [name: string, value: FieldValue | undefined];
+    readonly touch: readonly [name: string];
     readonly validate: readonly [errors: readonly FieldError[]];
     readonly disable: readonly [name: string];
     readonly enable: readonly [name: string];
     readonly submit: readonly [values: FormValues];
+    readonly prepare: readonly [submission: FormSubmission];
+    readonly accept: readonly [submission: FormSubmission];
+    readonly abort: readonly [submission: FormSubmission];
     readonly clear: readonly [];
     readonly abandon: readonly [];
 };
@@ -737,7 +773,7 @@ export declare interface FormGroup {
  *
  * @remarks
  * `valid` is true when the last completed evaluation found no error, and `dirty` is true once
- * an answer differs from the one the form opened with. Both are derived, never stored.
+ * an answer differs from its acknowledged baseline. Both are derived, never stored.
  *
  * `touched` holds the fields somebody has visited, which is what lets a renderer withhold an
  * error until the person has had their turn at it.
@@ -757,13 +793,15 @@ export declare interface FormInterface {
     /** Reports the answers the form holds. */
     readonly values: FormValues;
     /**
-     * Holds the answers the form opened with: the schema's defaults, overlaid with any seeded values.
+     * Holds the acknowledged answers, initially the schema's defaults overlaid with seeded values.
      *
      * @remarks
-     * It is fixed when the form opens and never moves again, so it is what `dirty` measures
-     * against and what {@link FormInterface.clear} returns to.
+     * Acceptance advances only the enabled fields captured by the submission, including absence.
+     * It is what `dirty` measures against and what {@link FormInterface.clear} returns to.
      */
     readonly baseline: FormValues;
+    /** Holds the submission awaiting acknowledgement, or `undefined` when none is pending. */
+    readonly pending: FormSubmission | undefined;
     /** Holds every error the last check produced. */
     readonly errors: readonly FieldError[];
     /** Lists the names of the fields somebody has visited. */
@@ -781,7 +819,7 @@ export declare interface FormInterface {
     readonly status: FormStatus;
     /** Reports whether the last completed evaluation found no error. */
     readonly valid: boolean;
-    /** Reports whether any answer has moved since the form opened. */
+    /** Reports whether any answer differs from its acknowledged baseline. */
     readonly dirty: boolean;
     /**
      * Holds the answers after the form settles.
@@ -823,11 +861,16 @@ export declare interface FormInterface {
      * @remarks
      * One field holds one external failure, so a second call replaces the first, and the failure
      * lasts until that field is filled again or the form is cleared.
+     * A receipt admits only a captured enabled field whose fill revision still matches. Stale,
+     * foreign, copied, consumed, and teardown-invalidated receipts return `false`; unknown fields
+     * still throw `FIELD`.
      *
      * @param name - The field's name.
      * @param message - What to tell the person.
+     * @param submission - The active receipt to check against the field's captured revision.
+     * @returns True if the failure was applied; false if the receipt or field revision is stale.
      */
-    invalidate(name: string, message: string): void;
+    invalidate(name: string, message: string, submission?: FormSubmission): boolean;
     /**
      * Takes one field, several fields, or every field out of the form.
      *
@@ -885,7 +928,29 @@ export declare interface FormInterface {
      */
     submit(): FormResult;
     /**
-     * Returns every answer to the ones the form opened with.
+     * Prepares an owned enabled snapshot for acknowledgement while leaving the form editable.
+     *
+     * @returns The submission on success, or the errors that prevented preparation.
+     * @throws A {@link FormError} coded `PENDING` for an overlapping preparation or pending receipt,
+     *   or when clear interrupts preparation; terminal forms retain their terminal refusals.
+     */
+    prepare(): FormPreparationResult;
+    /**
+     * Adopts the active submission's captured answers into the baseline without changing live state.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was accepted; false otherwise, including after teardown.
+     */
+    accept(submission: FormSubmission): boolean;
+    /**
+     * Consumes the active submission and aborts its signal without changing answers or baseline.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was aborted; false otherwise, including after teardown.
+     */
+    abort(submission: FormSubmission): boolean;
+    /**
+     * Returns every answer to its acknowledged baseline and aborts pending acknowledgement.
      *
      * @remarks
      * Those answers are {@link FormInterface.baseline}. The runtime disabled overlay resets with
@@ -927,6 +992,9 @@ export declare interface FormOptions {
     readonly messages?: Readonly<Partial<Record<FieldRuleName, string>>>;
 }
 
+/** Reports a prepared submission, or every error that prevented its preparation. */
+export declare type FormPreparationResult = Result<FormSubmission, readonly FieldError[]>;
+
 /**
  * Reports what a submit answers with: the values, or every error that stopped them.
  *
@@ -978,6 +1046,18 @@ export declare interface FormSchema {
  */
 export declare type FormStatus = 'editing' | 'settled' | 'abandoned';
 
+/**
+ * Carries an owned, frozen answer snapshot and the signal for its pending acknowledgement.
+ *
+ * @remarks
+ * Only the producing form accepts this object's identity. Copying its members cannot create a
+ * receipt. The values and their lists are frozen; the native signal remains usable by transports.
+ */
+export declare interface FormSubmission {
+    readonly values: FormValues;
+    readonly signal: AbortSignal;
+}
+
 /**
  * Represents a form's answers, keyed by field name.
  *

package/dist/src/core/index.d.ts

@@ -502,8 +502,10 @@ export declare class Form implements FormInterface {
     get schema(): FormSchema;
     /** Reports the answers the form holds. */
     get values(): FormValues;
-    /** Holds the answers the form opened with. */
+    /** Holds the acknowledged answers, initially the schema's defaults overlaid with seeded values. */
     get baseline(): FormValues;
+    /** Holds the submission awaiting acknowledgement, or `undefined` when none is pending. */
+    get pending(): FormSubmission | undefined;
     /** Holds every error the last completed evaluation produced. */
     get errors(): readonly FieldError[];
     /** Lists the names of the fields somebody has visited. */
@@ -514,7 +516,7 @@ export declare class Form implements FormInterface {
     get status(): FormStatus;
     /** Reports whether the last completed evaluation found no error. */
     get valid(): boolean;
-    /** Reports whether any answer has moved since the form opened. */
+    /** Reports whether any answer differs from its acknowledged baseline. */
     get dirty(): boolean;
     /**
      * Holds the answers after the form settles.
@@ -557,13 +559,15 @@ export declare class Form implements FormInterface {
      *
      * @param name - The field's name.
      * @param message - What to tell the person.
+     * @param submission - The active receipt to check against the field's captured revision.
+     * @returns True if the failure was applied; false if the receipt or field revision is stale.
      * @remarks
      * One field holds one external failure: a second call replaces the first. The failure lasts
      * until that field is filled again or the form is cleared.
      * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
      *   `FIELD` when the schema declares no such name.
      */
-    invalidate(name: string, message: string): void;
+    invalidate(name: string, message: string, submission?: FormSubmission): boolean;
     /** Takes every field out of the form. */
     disable(): void;
     /**
@@ -610,8 +614,34 @@ export declare class Form implements FormInterface {
      */
     submit(): FormResult;
     /**
-     * Returns every answer to the ones the form opened with: the schema's defaults, overlaid with
-     * any seeded `values`. Reset the runtime disabled state to the schema's declarations.
+     * Prepares an owned enabled snapshot for acknowledgement while leaving the form editable.
+     *
+     * @returns The submission on success, or the errors that prevented preparation.
+     * @remarks
+     * A failed check refuses its checked errors even if an observer repairs them. A passing check
+     * drains observer mutations through one further check. The receipt always carries that check's
+     * snapshot, including when its notifications produce later edits. A throwing validator creates
+     * no receipt. The pending identity is installed before `prepare` listeners run.
+     * @throws A {@link FormError} coded `PENDING` while another preparation or receipt is pending,
+     *   or when clear interrupts preparation; terminal forms retain their terminal refusals.
+     */
+    prepare(): FormPreparationResult;
+    /**
+     * Adopts the active submission's captured answers into the baseline without changing live state.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was accepted; false otherwise, including after teardown.
+     */
+    accept(submission: FormSubmission): boolean;
+    /**
+     * Consumes the active submission and aborts its signal without changing answers or baseline.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was aborted; false otherwise, including after teardown.
+     */
+    abort(submission: FormSubmission): boolean;
+    /**
+     * Returns every answer to its acknowledged baseline and aborts pending acknowledgement.
      *
      * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
      */
@@ -679,9 +709,10 @@ export declare class FormError extends Error {
  * @remarks
  * `SCHEMA` rejects a malformed schema. `FIELD` names a field the schema does not declare.
  * `CONTROL` reports a value the field's control cannot hold. `SETTLED` and `ABANDONED`
- * refuse a write to a form that has already ended.
+ * refuse a write to a form that has already ended. `PENDING` refuses a preparation or terminal
+ * submit while preparation or acknowledgement is pending, or a preparation interrupted by clear.
  */
-export declare type FormErrorCode = 'SCHEMA' | 'FIELD' | 'CONTROL' | 'SETTLED' | 'ABANDONED';
+export declare type FormErrorCode = 'SCHEMA' | 'FIELD' | 'CONTROL' | 'SETTLED' | 'ABANDONED' | 'PENDING';
 
 /**
  * Lists everything a form announces.
@@ -691,14 +722,19 @@ export declare type FormErrorCode = 'SCHEMA' | 'FIELD' | 'CONTROL' | 'SETTLED' |
  * being cleared. `validate` carries the errors a check produced, empty when it found none.
  * `disable` and `enable` each carry one field, and fire once per field whose state actually
  * moved, in the order the schema declares them. `submit` fires only on a submit that passed.
- * `clear` and `abandon` are signals.
+ * `touch` announces the first visit since clear. `prepare`, `accept`, and `abort` carry the receipt
+ * after their state is committed. `clear` and `abandon` are signals.
  */
 export declare type FormEventMap = {
     readonly fill: readonly [name: string, value: FieldValue | undefined];
+    readonly touch: readonly [name: string];
     readonly validate: readonly [errors: readonly FieldError[]];
     readonly disable: readonly [name: string];
     readonly enable: readonly [name: string];
     readonly submit: readonly [values: FormValues];
+    readonly prepare: readonly [submission: FormSubmission];
+    readonly accept: readonly [submission: FormSubmission];
+    readonly abort: readonly [submission: FormSubmission];
     readonly clear: readonly [];
     readonly abandon: readonly [];
 };
@@ -737,7 +773,7 @@ export declare interface FormGroup {
  *
  * @remarks
  * `valid` is true when the last completed evaluation found no error, and `dirty` is true once
- * an answer differs from the one the form opened with. Both are derived, never stored.
+ * an answer differs from its acknowledged baseline. Both are derived, never stored.
  *
  * `touched` holds the fields somebody has visited, which is what lets a renderer withhold an
  * error until the person has had their turn at it.
@@ -757,13 +793,15 @@ export declare interface FormInterface {
     /** Reports the answers the form holds. */
     readonly values: FormValues;
     /**
-     * Holds the answers the form opened with: the schema's defaults, overlaid with any seeded values.
+     * Holds the acknowledged answers, initially the schema's defaults overlaid with seeded values.
      *
      * @remarks
-     * It is fixed when the form opens and never moves again, so it is what `dirty` measures
-     * against and what {@link FormInterface.clear} returns to.
+     * Acceptance advances only the enabled fields captured by the submission, including absence.
+     * It is what `dirty` measures against and what {@link FormInterface.clear} returns to.
      */
     readonly baseline: FormValues;
+    /** Holds the submission awaiting acknowledgement, or `undefined` when none is pending. */
+    readonly pending: FormSubmission | undefined;
     /** Holds every error the last check produced. */
     readonly errors: readonly FieldError[];
     /** Lists the names of the fields somebody has visited. */
@@ -781,7 +819,7 @@ export declare interface FormInterface {
     readonly status: FormStatus;
     /** Reports whether the last completed evaluation found no error. */
     readonly valid: boolean;
-    /** Reports whether any answer has moved since the form opened. */
+    /** Reports whether any answer differs from its acknowledged baseline. */
     readonly dirty: boolean;
     /**
      * Holds the answers after the form settles.
@@ -823,11 +861,16 @@ export declare interface FormInterface {
      * @remarks
      * One field holds one external failure, so a second call replaces the first, and the failure
      * lasts until that field is filled again or the form is cleared.
+     * A receipt admits only a captured enabled field whose fill revision still matches. Stale,
+     * foreign, copied, consumed, and teardown-invalidated receipts return `false`; unknown fields
+     * still throw `FIELD`.
      *
      * @param name - The field's name.
      * @param message - What to tell the person.
+     * @param submission - The active receipt to check against the field's captured revision.
+     * @returns True if the failure was applied; false if the receipt or field revision is stale.
      */
-    invalidate(name: string, message: string): void;
+    invalidate(name: string, message: string, submission?: FormSubmission): boolean;
     /**
      * Takes one field, several fields, or every field out of the form.
      *
@@ -885,7 +928,29 @@ export declare interface FormInterface {
      */
     submit(): FormResult;
     /**
-     * Returns every answer to the ones the form opened with.
+     * Prepares an owned enabled snapshot for acknowledgement while leaving the form editable.
+     *
+     * @returns The submission on success, or the errors that prevented preparation.
+     * @throws A {@link FormError} coded `PENDING` for an overlapping preparation or pending receipt,
+     *   or when clear interrupts preparation; terminal forms retain their terminal refusals.
+     */
+    prepare(): FormPreparationResult;
+    /**
+     * Adopts the active submission's captured answers into the baseline without changing live state.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was accepted; false otherwise, including after teardown.
+     */
+    accept(submission: FormSubmission): boolean;
+    /**
+     * Consumes the active submission and aborts its signal without changing answers or baseline.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was aborted; false otherwise, including after teardown.
+     */
+    abort(submission: FormSubmission): boolean;
+    /**
+     * Returns every answer to its acknowledged baseline and aborts pending acknowledgement.
      *
      * @remarks
      * Those answers are {@link FormInterface.baseline}. The runtime disabled overlay resets with
@@ -927,6 +992,9 @@ export declare interface FormOptions {
     readonly messages?: Readonly<Partial<Record<FieldRuleName, string>>>;
 }
 
+/** Reports a prepared submission, or every error that prevented its preparation. */
+export declare type FormPreparationResult = Result<FormSubmission, readonly FieldError[]>;
+
 /**
  * Reports what a submit answers with: the values, or every error that stopped them.
  *
@@ -978,6 +1046,18 @@ export declare interface FormSchema {
  */
 export declare type FormStatus = 'editing' | 'settled' | 'abandoned';
 
+/**
+ * Carries an owned, frozen answer snapshot and the signal for its pending acknowledgement.
+ *
+ * @remarks
+ * Only the producing form accepts this object's identity. Copying its members cannot create a
+ * receipt. The values and their lists are frozen; the native signal remains usable by transports.
+ */
+export declare interface FormSubmission {
+    readonly values: FormValues;
+    readonly signal: AbortSignal;
+}
+
 /**
  * Represents a form's answers, keyed by field name.
  *