declarative-forms 2.1.0 → 2.1.2

package/dist/index.d.cts

@@ -262,6 +262,21 @@ interface ButtonDescriptor {
 type ButtonMap = Record<string, ButtonDescriptor>;
 interface DeclarativeFormOptions {
     fields: readonly FieldDescriptor[];
+    /**
+     * The record to open the form with, keyed by field name — how you edit an
+     * existing object rather than asking for a new one.
+     *
+     * ```ts
+     * const updated = await ask(userFields, { defaultValues: user });
+     * ```
+     *
+     * Each entry wins over that field's own `defaultValue`, so the same field
+     * list serves both the "create" and the "edit" call. Keys naming no field are
+     * ignored — pass a whole domain object without filtering it first — as are
+     * keys whose value is `undefined`, which fall back to the field's
+     * `defaultValue`. An `array` field takes its list of records here directly.
+     */
+    defaultValues?: FormValues;
     /**
      * Buttons for the dialog's lower bar, keyed by label.
      * Defaults to a single `OK` button running {@link onConfirm}.
@@ -697,6 +712,15 @@ declare class DeclarativeForm implements SubForm, StackableDialog {
      */
     private applyInitialLayout;
     private initialize;
+    /**
+     * Seed one field from {@link DeclarativeFormOptions.defaultValues}.
+     *
+     * Run twice: once at build time so the first paint and the `isActive`
+     * predicates behind it already see the record being edited, and once after
+     * the `defaultValue` pass — which is async, and would otherwise overwrite the
+     * seeded value with the field's own default for the create case.
+     */
+    private applySeedValue;
     /** Resolves once initial options and default values have been applied. */
     whenReady(): Promise<void>;
     private createFieldContext;
@@ -1036,6 +1060,22 @@ declare class DlOption extends CustomElementBase {
  * `document.body` while open so it can escape a scrolling container.
  */
 declare class DlSelect extends CustomElementBase {
+    /**
+     * How long a load may run before the skeleton is shown at all. A load that
+     * finishes inside this window never flashes one.
+     */
+    static showLoadingAfterMs: number;
+    /**
+     * Once the skeleton *has* been shown, it is held for at least this long, so
+     * it cannot appear and vanish in the same instant.
+     *
+     * Both are statics so a test suite can set them to 0. They are deliberate
+     * pauses for human eyes; to a test they are pure latency, and they are why
+     * suites end up sleeping around these selects instead of waiting on a
+     * condition. Wait on `isLoading` rather than the `dl-select-loading` class:
+     * `isLoading` flips synchronously, the class lags by `showLoadingAfterMs`.
+     */
+    static minLoadingMs: number;
     readonly optionsWrapper: HTMLDivElement;
     readonly inputWrapper: HTMLSpanElement;
     readonly noMatchesHint: HTMLSpanElement;

package/dist/index.d.ts

@@ -262,6 +262,21 @@ interface ButtonDescriptor {
 type ButtonMap = Record<string, ButtonDescriptor>;
 interface DeclarativeFormOptions {
     fields: readonly FieldDescriptor[];
+    /**
+     * The record to open the form with, keyed by field name — how you edit an
+     * existing object rather than asking for a new one.
+     *
+     * ```ts
+     * const updated = await ask(userFields, { defaultValues: user });
+     * ```
+     *
+     * Each entry wins over that field's own `defaultValue`, so the same field
+     * list serves both the "create" and the "edit" call. Keys naming no field are
+     * ignored — pass a whole domain object without filtering it first — as are
+     * keys whose value is `undefined`, which fall back to the field's
+     * `defaultValue`. An `array` field takes its list of records here directly.
+     */
+    defaultValues?: FormValues;
     /**
      * Buttons for the dialog's lower bar, keyed by label.
      * Defaults to a single `OK` button running {@link onConfirm}.
@@ -697,6 +712,15 @@ declare class DeclarativeForm implements SubForm, StackableDialog {
      */
     private applyInitialLayout;
     private initialize;
+    /**
+     * Seed one field from {@link DeclarativeFormOptions.defaultValues}.
+     *
+     * Run twice: once at build time so the first paint and the `isActive`
+     * predicates behind it already see the record being edited, and once after
+     * the `defaultValue` pass — which is async, and would otherwise overwrite the
+     * seeded value with the field's own default for the create case.
+     */
+    private applySeedValue;
     /** Resolves once initial options and default values have been applied. */
     whenReady(): Promise<void>;
     private createFieldContext;
@@ -1036,6 +1060,22 @@ declare class DlOption extends CustomElementBase {
  * `document.body` while open so it can escape a scrolling container.
  */
 declare class DlSelect extends CustomElementBase {
+    /**
+     * How long a load may run before the skeleton is shown at all. A load that
+     * finishes inside this window never flashes one.
+     */
+    static showLoadingAfterMs: number;
+    /**
+     * Once the skeleton *has* been shown, it is held for at least this long, so
+     * it cannot appear and vanish in the same instant.
+     *
+     * Both are statics so a test suite can set them to 0. They are deliberate
+     * pauses for human eyes; to a test they are pure latency, and they are why
+     * suites end up sleeping around these selects instead of waiting on a
+     * condition. Wait on `isLoading` rather than the `dl-select-loading` class:
+     * `isLoading` flips synchronously, the class lags by `showLoadingAfterMs`.
+     */
+    static minLoadingMs: number;
     readonly optionsWrapper: HTMLDivElement;
     readonly inputWrapper: HTMLSpanElement;
     readonly noMatchesHint: HTMLSpanElement;

package/dist/index.js

@@ -942,8 +942,6 @@ function injectStyles() {
 // src/components/DlSelect.ts
 var SVG_NS = "http://www.w3.org/2000/svg";
 var ARROW_PATH = "M4.516 7.548c0.436-0.446 1.043-0.481 1.576 0l3.908 3.747 3.908-3.747c0.533-0.481 1.141-0.446 1.574 0 0.436 0.445 0.408 1.197 0 1.615-0.406 0.418-4.695 4.502-4.695 4.502-0.217 0.223-0.502 0.335-0.787 0.335s-0.57-0.112-0.789-0.335c0 0-4.287-4.084-4.695-4.502s-0.436-1.17 0-1.615z";
-var MIN_LOADING_MS = 1500;
-var LOADING_DELAY_MS = 100;
 var CustomElementBase = typeof HTMLElement === "undefined" ? class {
 } : HTMLElement;
 var DlOption = class extends CustomElementBase {
@@ -956,7 +954,23 @@ var DlOption = class extends CustomElementBase {
     return this.getAttribute("displayWhenSelected") ?? this.innerText;
   }
 };
-var DlSelect = class extends CustomElementBase {
+var DlSelect = class _DlSelect extends CustomElementBase {
+  /**
+   * How long a load may run before the skeleton is shown at all. A load that
+   * finishes inside this window never flashes one.
+   */
+  static showLoadingAfterMs = 100;
+  /**
+   * Once the skeleton *has* been shown, it is held for at least this long, so
+   * it cannot appear and vanish in the same instant.
+   *
+   * Both are statics so a test suite can set them to 0. They are deliberate
+   * pauses for human eyes; to a test they are pure latency, and they are why
+   * suites end up sleeping around these selects instead of waiting on a
+   * condition. Wait on `isLoading` rather than the `dl-select-loading` class:
+   * `isLoading` flips synchronously, the class lags by `showLoadingAfterMs`.
+   */
+  static minLoadingMs = 1500;
   optionsWrapper;
   inputWrapper;
   noMatchesHint;
@@ -1065,14 +1079,14 @@ var DlSelect = class extends CustomElementBase {
         this.classList.add("dl-select-loading");
         this.optionsWrapper.remove();
         this.loadingStartedAt = Date.now();
-      }, LOADING_DELAY_MS)
+      }, _DlSelect.showLoadingAfterMs)
     );
   }
   unsetLoadingStatus() {
     for (const timeout of this.loadingTimeouts) clearTimeout(timeout);
     this.loadingTimeouts = [];
     const elapsed = this.loadingStartedAt ? Date.now() - this.loadingStartedAt : 0;
-    const delay = this.loadingStartedAt ? Math.max(0, MIN_LOADING_MS - elapsed) : 0;
+    const delay = this.loadingStartedAt ? Math.max(0, _DlSelect.minLoadingMs - elapsed) : 0;
     const finish = () => {
       this.appendChild(this.optionsWrapper);
       this.classList.remove("dl-select-loading");
@@ -1364,10 +1378,11 @@ var SelectField = class extends Field {
   async loadOptions(opts = {}) {
     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);
@@ -2142,6 +2157,7 @@ var DeclarativeForm = class _DeclarativeForm {
       }
       const field = this.registry.create(descriptor, context);
       field.applyStaticDefaultValue();
+      this.applySeedValue(field);
       this.fieldList.push(field);
       this.fieldsByName.set(descriptor.name, field);
       this.tooltips.register(descriptor.name, field.tooltipMarker);
@@ -2184,8 +2200,24 @@ var DeclarativeForm = class _DeclarativeForm {
     await Promise.allSettled(
       this.fieldList.map((field) => this.scheduler.track(field.applyDefaultValue()))
     );
+    for (const field of this.fieldList) this.applySeedValue(field);
     await this.update();
   }
+  /**
+   * Seed one field from {@link DeclarativeFormOptions.defaultValues}.
+   *
+   * Run twice: once at build time so the first paint and the `isActive`
+   * predicates behind it already see the record being edited, and once after
+   * the `defaultValue` pass — which is async, and would otherwise overwrite the
+   * seeded value with the field's own default for the create case.
+   */
+  applySeedValue(field) {
+    const values = this.options.defaultValues;
+    if (!values) return;
+    if (!Object.prototype.hasOwnProperty.call(values, field.name)) return;
+    const value = values[field.name];
+    if (value !== void 0) field.setValue(value);
+  }
   /** Resolves once initial options and default values have been applied. */
   whenReady() {
     return this.ready.then(() => this.scheduler.whenSettled());