declarative-forms 2.1.1 → 2.1.4

package/dist/index.d.cts

@@ -372,18 +372,45 @@ declare class TooltipController {
  */
 declare class UpdateScheduler {
     private pending;
+    private updates;
     private generations;
     /** Register async work and drop it from the set once it settles. */
     track<T>(work: Promise<T>): Promise<T>;
+    /**
+     * Register an `update()` pass.
+     *
+     * Update passes are tracked separately from field work because `update()`
+     * waits for field work *as part of* running, so a single set would make it
+     * wait for itself. `whenSettled` drains both; `whenFieldWorkSettled`, which
+     * is what `update()` itself calls, drains only `pending`.
+     *
+     * Tracking these at all is the point: `requestUpdate` fires an update and
+     * returns, so before this existed `whenSettled()` could resolve with an
+     * update still running and the button bar not yet refreshed. `ButtonBar`
+     * awaits `whenSettled()` and then re-reads the primary button's `disabled`
+     * class to decide whether to accept a confirm -- against a stale class, that
+     * check passes and an invalid record is confirmed.
+     */
+    trackUpdate<T>(work: Promise<T>): Promise<T>;
     /** Number of currently in-flight operations. Test/diagnostics only. */
     get pendingCount(): number;
     /**
-     * Resolve once nothing is in flight.
+     * Resolve once nothing is in flight: no field work, and no update pass that
+     * might still be about to act on it.
+     */
+    whenSettled(): Promise<void>;
+    /**
+     * Resolve once field work is done, ignoring update passes.
      *
+     * For `update()`'s own use. It cannot wait on `whenSettled`, because it is
+     * itself one of the update passes that would be waited for.
+     */
+    whenFieldWorkSettled(): Promise<void>;
+    /**
      * Loops because settling one batch may schedule another (an options load
      * whose completion triggers a dependent field's reload).
      */
-    whenSettled(): Promise<void>;
+    private drain;
     /**
      * Claim the next generation for `key` and return a predicate that reports
      * whether that claim is still the newest.
@@ -425,10 +452,12 @@ interface FormContext {
     /**
      * Build a nested form that knows this form as its parent.
      *
-     * Lets `ArrayField` open entry dialogs without importing `DeclarativeForm`,
-     * keeping the field layer free of a cycle back into the core.
+     * Lets `ArrayField` open entry dialogs without importing `DeclarativeForm` at
+     * runtime, keeping the field layer free of a cycle back into the core. The
+     * return type is the full form so the dialog can be handed to descriptor
+     * callbacks as `ctx.form`.
      */
-    createSubForm(options: SubFormOptions): SubForm;
+    createSubForm(options: SubFormOptions): DeclarativeForm;
 }
 interface SubFormOptions {
     fields: readonly FieldDescriptor[];
@@ -749,6 +778,7 @@ declare class DeclarativeForm implements SubForm, StackableDialog {
      * @param includeTab treat a tab switch as a change
      */
     update(source?: FieldHandle, force?: boolean, includeTab?: boolean): Promise<void>;
+    private runUpdate;
     private buttonContext;
     /** Recompute every `computed` field. Runs before a button action fires. */
     updateComputedFields(): Promise<void>;
@@ -877,6 +907,15 @@ declare class ArrayField extends Field<ArrayFieldDescriptor> {
     private openEntryDialog;
     /** Seed each field with the entry's current value, then apply `mapFieldsOnEdit`. */
     private editFields;
+    /**
+     * Run `isValidRecord` against the entry dialog.
+     *
+     * `ctx.form` is the entry dialog rather than the form owning the array field:
+     * the entry's fields — and their tooltip markers — live in the dialog, and
+     * tooltips are scoped per form, so `ctx.form.setTooltipError(…)` on the outer
+     * form was a silent no-op. The rest of the context still describes the outer
+     * field.
+     */
     private validateEntry;
     private notifyChange;
 }
@@ -989,6 +1028,8 @@ declare class MessageField extends Field<MessageFieldDescriptor> {
 /** A `<dl-select>` combobox, single or multiple. */
 declare class SelectField extends Field<SelectFieldDescriptor> {
     private select;
+    /** True while the tooltip shows a message from {@link reportOptionsError}. */
+    private showsOptionsError;
     protected get wrapperExtraClass(): string;
     protected createControl(): HTMLElement;
     initialize(): Promise<void>;
@@ -1179,6 +1220,12 @@ declare function injectStyles(): void;
 interface ButtonBarCallbacks {
     /** Resolve once all pending form work has settled. */
     whenSettled(): Promise<void>;
+    /**
+     * Claim the newest generation for `key`; the returned predicate reports
+     * whether that claim is still current. Used to discard a stale async
+     * predicate result -- see `refresh`.
+     */
+    claim(key: string): () => boolean;
     /** Recompute `computed` fields before an action runs. */
     updateComputedFields(): Promise<void>;
     getValues(): Record<string, unknown>;

package/dist/index.d.ts

@@ -372,18 +372,45 @@ declare class TooltipController {
  */
 declare class UpdateScheduler {
     private pending;
+    private updates;
     private generations;
     /** Register async work and drop it from the set once it settles. */
     track<T>(work: Promise<T>): Promise<T>;
+    /**
+     * Register an `update()` pass.
+     *
+     * Update passes are tracked separately from field work because `update()`
+     * waits for field work *as part of* running, so a single set would make it
+     * wait for itself. `whenSettled` drains both; `whenFieldWorkSettled`, which
+     * is what `update()` itself calls, drains only `pending`.
+     *
+     * Tracking these at all is the point: `requestUpdate` fires an update and
+     * returns, so before this existed `whenSettled()` could resolve with an
+     * update still running and the button bar not yet refreshed. `ButtonBar`
+     * awaits `whenSettled()` and then re-reads the primary button's `disabled`
+     * class to decide whether to accept a confirm -- against a stale class, that
+     * check passes and an invalid record is confirmed.
+     */
+    trackUpdate<T>(work: Promise<T>): Promise<T>;
     /** Number of currently in-flight operations. Test/diagnostics only. */
     get pendingCount(): number;
     /**
-     * Resolve once nothing is in flight.
+     * Resolve once nothing is in flight: no field work, and no update pass that
+     * might still be about to act on it.
+     */
+    whenSettled(): Promise<void>;
+    /**
+     * Resolve once field work is done, ignoring update passes.
      *
+     * For `update()`'s own use. It cannot wait on `whenSettled`, because it is
+     * itself one of the update passes that would be waited for.
+     */
+    whenFieldWorkSettled(): Promise<void>;
+    /**
      * Loops because settling one batch may schedule another (an options load
      * whose completion triggers a dependent field's reload).
      */
-    whenSettled(): Promise<void>;
+    private drain;
     /**
      * Claim the next generation for `key` and return a predicate that reports
      * whether that claim is still the newest.
@@ -425,10 +452,12 @@ interface FormContext {
     /**
      * Build a nested form that knows this form as its parent.
      *
-     * Lets `ArrayField` open entry dialogs without importing `DeclarativeForm`,
-     * keeping the field layer free of a cycle back into the core.
+     * Lets `ArrayField` open entry dialogs without importing `DeclarativeForm` at
+     * runtime, keeping the field layer free of a cycle back into the core. The
+     * return type is the full form so the dialog can be handed to descriptor
+     * callbacks as `ctx.form`.
      */
-    createSubForm(options: SubFormOptions): SubForm;
+    createSubForm(options: SubFormOptions): DeclarativeForm;
 }
 interface SubFormOptions {
     fields: readonly FieldDescriptor[];
@@ -749,6 +778,7 @@ declare class DeclarativeForm implements SubForm, StackableDialog {
      * @param includeTab treat a tab switch as a change
      */
     update(source?: FieldHandle, force?: boolean, includeTab?: boolean): Promise<void>;
+    private runUpdate;
     private buttonContext;
     /** Recompute every `computed` field. Runs before a button action fires. */
     updateComputedFields(): Promise<void>;
@@ -877,6 +907,15 @@ declare class ArrayField extends Field<ArrayFieldDescriptor> {
     private openEntryDialog;
     /** Seed each field with the entry's current value, then apply `mapFieldsOnEdit`. */
     private editFields;
+    /**
+     * Run `isValidRecord` against the entry dialog.
+     *
+     * `ctx.form` is the entry dialog rather than the form owning the array field:
+     * the entry's fields — and their tooltip markers — live in the dialog, and
+     * tooltips are scoped per form, so `ctx.form.setTooltipError(…)` on the outer
+     * form was a silent no-op. The rest of the context still describes the outer
+     * field.
+     */
     private validateEntry;
     private notifyChange;
 }
@@ -989,6 +1028,8 @@ declare class MessageField extends Field<MessageFieldDescriptor> {
 /** A `<dl-select>` combobox, single or multiple. */
 declare class SelectField extends Field<SelectFieldDescriptor> {
     private select;
+    /** True while the tooltip shows a message from {@link reportOptionsError}. */
+    private showsOptionsError;
     protected get wrapperExtraClass(): string;
     protected createControl(): HTMLElement;
     initialize(): Promise<void>;
@@ -1179,6 +1220,12 @@ declare function injectStyles(): void;
 interface ButtonBarCallbacks {
     /** Resolve once all pending form work has settled. */
     whenSettled(): Promise<void>;
+    /**
+     * Claim the newest generation for `key`; the returned predicate reports
+     * whether that claim is still current. Used to discard a stale async
+     * predicate result -- see `refresh`.
+     */
+    claim(key: string): () => boolean;
     /** Recompute `computed` fields before an action runs. */
     updateComputedFields(): Promise<void>;
     getValues(): Record<string, unknown>;

package/dist/index.js

@@ -486,7 +486,7 @@ var ArrayField = class extends Field {
       buttons: {
         OK: {
           id: confirmId,
-          isActive: ({ data }) => this.validateEntry(data),
+          isActive: ({ data }) => this.validateEntry(data, form),
           action: (values) => {
             if (editing && index !== void 0) this.entries[index] = values;
             else this.entries.push(values);
@@ -507,9 +507,21 @@ var ArrayField = class extends Field {
     }));
     return this.descriptor.mapFieldsOnEdit?.(seeded, entry) ?? seeded;
   }
-  validateEntry(entry) {
+  /**
+   * Run `isValidRecord` against the entry dialog.
+   *
+   * `ctx.form` is the entry dialog rather than the form owning the array field:
+   * the entry's fields — and their tooltip markers — live in the dialog, and
+   * tooltips are scoped per form, so `ctx.form.setTooltipError(…)` on the outer
+   * form was a silent no-op. The rest of the context still describes the outer
+   * field.
+   */
+  validateEntry(entry, dialog) {
     if (!this.descriptor.isValidRecord) return true;
-    return this.descriptor.isValidRecord(entry, this.context.contextFor(this.descriptor));
+    return this.descriptor.isValidRecord(entry, {
+      ...this.context.contextFor(this.descriptor),
+      form: dialog
+    });
   }
   notifyChange() {
     const onChange = this.descriptor.onChange;
@@ -1327,6 +1339,8 @@ function defineDlSelect() {
 // src/fields/SelectField.ts
 var SelectField = class extends Field {
   select;
+  /** True while the tooltip shows a message from {@link reportOptionsError}. */
+  showsOptionsError = false;
   get wrapperExtraClass() {
     return "dl-select-wrapper";
   }
@@ -1364,7 +1378,7 @@ var SelectField = class extends Field {
     }
     const dependsOnTrigger = triggerName !== void 0 && this.descriptor.reloadOnChangeOf?.includes(triggerName) === true;
     if (dependsOnTrigger && typeof this.descriptor.options === "function") {
-      void this.loadOptions({ reload: true });
+      void this.loadOptions();
     }
   }
   /**
@@ -1375,16 +1389,20 @@ var SelectField = class extends Field {
    * fresher options. v1 had no such guard, so a slow response from an earlier
    * keystroke could repopulate the select with outdated values.
    */
-  async loadOptions(opts = {}) {
+  async loadOptions() {
     const isCurrent = this.context.scheduler.claim(`options:${this.descriptor.name}`);
     const source = this.descriptor.options;
-    const requested = typeof source === "function" ? source(this.context.contextFor(this.descriptor)) : source;
-    const isAsync = requested instanceof Promise;
-    if (isAsync) this.select.setLoadingStatus();
+    let isAsync = false;
     try {
+      const requested = typeof source === "function" ? source(this.context.contextFor(this.descriptor)) : source;
+      isAsync = requested instanceof Promise;
+      if (isAsync) this.select.setLoadingStatus();
       const options = await requested ?? [];
       if (!isCurrent()) return;
-      if (opts.reload) this.context.tooltips.reset(this.descriptor.name);
+      if (this.showsOptionsError) {
+        this.context.tooltips.reset(this.descriptor.name);
+        this.showsOptionsError = false;
+      }
       const previous = this.select.getValue();
       this.select.removeAllOptions();
       for (const option of options) this.select.addOption(this.createOption(option));
@@ -1418,6 +1436,7 @@ var SelectField = class extends Field {
     });
     if (message) {
       this.context.tooltips.setMessage(this.descriptor.name, message.level, message.text);
+      this.showsOptionsError = true;
     }
   }
 };
@@ -1599,6 +1618,7 @@ var IdGenerator = class {
 // src/core/UpdateScheduler.ts
 var UpdateScheduler = class {
   pending = /* @__PURE__ */ new Set();
+  updates = /* @__PURE__ */ new Set();
   generations = /* @__PURE__ */ new Map();
   /** Register async work and drop it from the set once it settles. */
   track(work) {
@@ -1609,25 +1629,64 @@ var UpdateScheduler = class {
     work.then(forget, forget);
     return work;
   }
+  /**
+   * Register an `update()` pass.
+   *
+   * Update passes are tracked separately from field work because `update()`
+   * waits for field work *as part of* running, so a single set would make it
+   * wait for itself. `whenSettled` drains both; `whenFieldWorkSettled`, which
+   * is what `update()` itself calls, drains only `pending`.
+   *
+   * Tracking these at all is the point: `requestUpdate` fires an update and
+   * returns, so before this existed `whenSettled()` could resolve with an
+   * update still running and the button bar not yet refreshed. `ButtonBar`
+   * awaits `whenSettled()` and then re-reads the primary button's `disabled`
+   * class to decide whether to accept a confirm -- against a stale class, that
+   * check passes and an invalid record is confirmed.
+   */
+  trackUpdate(work) {
+    this.updates.add(work);
+    const forget = () => {
+      this.updates.delete(work);
+    };
+    work.then(forget, forget);
+    return work;
+  }
   /** Number of currently in-flight operations. Test/diagnostics only. */
   get pendingCount() {
-    return this.pending.size;
+    return this.pending.size + this.updates.size;
+  }
+  /**
+   * Resolve once nothing is in flight: no field work, and no update pass that
+   * might still be about to act on it.
+   */
+  async whenSettled() {
+    await this.drain(() => [...this.pending, ...this.updates]);
   }
   /**
-   * Resolve once nothing is in flight.
+   * Resolve once field work is done, ignoring update passes.
    *
+   * For `update()`'s own use. It cannot wait on `whenSettled`, because it is
+   * itself one of the update passes that would be waited for.
+   */
+  async whenFieldWorkSettled() {
+    await this.drain(() => [...this.pending]);
+  }
+  /**
    * Loops because settling one batch may schedule another (an options load
    * whose completion triggers a dependent field's reload).
    */
-  async whenSettled() {
+  async drain(snapshot) {
     let guard = 0;
-    while (this.pending.size > 0) {
+    let outstanding = snapshot();
+    while (outstanding.length > 0) {
       if (++guard > 100) {
         throw new Error(
           "declarative-forms: form updates did not settle after 100 rounds \u2014 a field callback is most likely scheduling work on every update."
         );
       }
-      await Promise.allSettled([...this.pending]);
+      await Promise.allSettled(outstanding);
+      outstanding = snapshot();
     }
   }
   /**
@@ -1648,6 +1707,7 @@ var UpdateScheduler = class {
   /** Invalidate every outstanding claim and forget all pending work. */
   reset() {
     this.pending.clear();
+    this.updates.clear();
     for (const key of this.generations.keys()) {
       this.generations.set(key, (this.generations.get(key) ?? 0) + 1);
     }
@@ -1722,16 +1782,20 @@ var ButtonBar = class {
     for (const { descriptor, element } of this.buttons) {
       if (!descriptor.id) continue;
       if (descriptor.isActive) {
+        const isCurrent = this.callbacks.claim(`button:isActive:${descriptor.id}`);
         work.push(
           this.applyPredicate(descriptor.isActive(ctx), (active) => {
+            if (!isCurrent()) return;
             element.classList.toggle("disabled", !active);
             element.toggleAttribute("disabled", !active);
           })
         );
       }
       if (descriptor.isVisible) {
+        const isCurrent = this.callbacks.claim(`button:isVisible:${descriptor.id}`);
         work.push(
           this.applyPredicate(descriptor.isVisible(ctx), (visible) => {
+            if (!isCurrent()) return;
             element.classList.toggle("invisible", !visible);
           })
         );
@@ -2128,6 +2192,7 @@ var DeclarativeForm = class _DeclarativeForm {
     this.tabBar = new TabBar((tab) => this.setActiveTab(tab));
     this.buttonBar = new ButtonBar(this.resolveButtons(), {
       whenSettled: () => this.scheduler.whenSettled(),
+      claim: (key) => this.scheduler.claim(key),
       updateComputedFields: () => this.updateComputedFields(),
       getValues: () => this.getValues(),
       closeWith: (action) => this.close(action)
@@ -2324,6 +2389,9 @@ var DeclarativeForm = class _DeclarativeForm {
    * @param includeTab treat a tab switch as a change
    */
   async update(source, force = false, includeTab = false) {
+    return this.scheduler.trackUpdate(this.runUpdate(source, force, includeTab));
+  }
+  async runUpdate(source, force = false, includeTab = false) {
     const values = this.getValues();
     const changed = this.model.hasChanged(values, includeTab);
     if (!changed && !force) return;
@@ -2347,7 +2415,7 @@ var DeclarativeForm = class _DeclarativeForm {
       field.onFormUpdate(ctx, triggerName);
     }
     this.renderTabs(activeTabs);
-    await this.scheduler.whenSettled();
+    await this.scheduler.whenFieldWorkSettled();
     if (changed) this.model.notify(this.getValues());
     await this.buttonBar.refresh(this.buttonContext());
   }