declarative-forms 2.0.1 → 2.1.1

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}.
@@ -507,6 +522,16 @@ declare abstract class Field<D extends BaseFieldDescriptor = FieldDescriptor> im
      * resolved before being applied.
      */
     applyDefaultValue(): Promise<void>;
+    /**
+     * Apply a plainly declared default value straight away.
+     *
+     * {@link applyDefaultValue} is awaited during initialisation, so a value it
+     * applies cannot be seen by the first layout pass. A default that is neither a
+     * function nor a promise needs no awaiting, so it is applied at build time and
+     * `isActive` predicates reading it are right from the first paint. The async
+     * pass runs afterwards regardless and simply sets the same value again.
+     */
+    applyStaticDefaultValue(): void;
     /**
      * Hook for setup that cannot happen in {@link build} — loading select
      * options, or a first render that needs the form context. May be synchronous.
@@ -671,7 +696,31 @@ declare class DeclarativeForm implements SubForm, StackableDialog {
     constructor(options: DeclarativeFormOptions, internal?: InternalOptions);
     private resolveButtons;
     private buildFields;
+    /**
+     * Decide field visibility and build the tab strip synchronously, before the
+     * caller gets the form back.
+     *
+     * {@link initialize} is async — it awaits option loads and default values —
+     * but `openInModal()` normally runs in the same tick as the constructor.
+     * Without this pass the dialog paints every field of every tab, then collapses
+     * to the active tab once that first async update lands, which is a visible
+     * layout shift as soon as any field loads its options over the network.
+     *
+     * Only visibility is decided here: no `onFormChange`, no `onFormUpdate`, and
+     * the value model is left untouched, so the regular update cycle still sees
+     * the first real change and refreshes the buttons.
+     */
+    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;
@@ -761,6 +810,46 @@ declare class DeclarativeForm implements SubForm, StackableDialog {
     resetTooltips(fieldNames: Iterable<string>): void;
 }
 
+/**
+ * Everything {@link DeclarativeForm} accepts, minus the three things `ask`
+ * owns: the fields it is given, and the two callbacks it turns into a promise.
+ */
+interface AskOptions extends Omit<DeclarativeFormOptions, 'fields' | 'onConfirm' | 'onCancel'> {
+    /** Class names for the dialog chrome, as passed to `openInModal`. */
+    modal?: OpenInModalOptions;
+    /**
+     * Whether the dialog can be dismissed with Esc or the close button.
+     *
+     * Defaults to `true`. When `false` no close button is rendered and the
+     * promise can only settle with values — so only turn it off when a button of
+     * yours is guaranteed to close the dialog.
+     */
+    dismissable?: boolean;
+}
+/**
+ * Ask the user for a record, the way `prompt()` asks for a string.
+ *
+ * Opens the fields as a modal dialog and resolves with its values, or with
+ * `undefined` when the user dismisses it.
+ *
+ * ```ts
+ * const release = await ask([
+ *   { name: 'title', displayName: 'Release title' },
+ *   { name: 'notes', kind: 'textarea', displayName: 'What changed' },
+ * ]);
+ *
+ * if (release) publish(release);
+ * ```
+ *
+ * With custom {@link AskOptions.buttons | buttons}, the promise resolves when
+ * any button that closes the dialog has run its action; a `doNotCloseModal`
+ * button (a wizard's "Next") leaves it pending, as it leaves the dialog open.
+ *
+ * Use `new DeclarativeForm(…)` directly when you need the form object itself —
+ * to embed it in a page, subscribe to its values, or close it from elsewhere.
+ */
+declare function ask(fields: readonly FieldDescriptor[], options?: AskOptions): Promise<FormValues | undefined>;
+
 /**
  * A repeating list of sub-records, each edited in its own nested dialog.
  *
@@ -971,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;
@@ -1232,4 +1337,4 @@ declare class NativeTooltipProvider implements TooltipProvider {
  */
 declare function deepEqual(a: unknown, b: unknown): boolean;
 
-export { ArrayField, type ArrayFieldDescriptor, type BaseFieldDescriptor, ButtonBar, type ButtonContext, type ButtonDescriptor, type ButtonMap, CardsField, type CardsFieldDescriptor, CheckboxField, type CheckboxFieldDescriptor, ComputedField, type ComputedFieldDescriptor, CustomField, type CustomFieldDescriptor, DL_SELECT_STYLES, DeclarativeForm, type DeclarativeFormOptions, DlOption, DlSelect, Field, type FieldConstructor, type FieldContext, type FieldDescriptor, type FieldHandle, type FieldKind, type FieldMessage, FieldRegistry, FileField, type FileFieldDescriptor, type FormChangeContext, type FormContext, FormModel, type FormValues, IdGenerator, MessageField, type MessageFieldDescriptor, ModalStack, ModalView, NativeTooltipProvider, type OpenInModalOptions, type OptionsErrorContext, type Reactive, type RenderContext, SafeHtml, SelectField, type SelectFieldDescriptor, type SelectOption, type StackableDialog, type SubForm, type SubFormOptions, TabBar, type TabSpec, TextAreaField, type TextAreaFieldDescriptor, TextField, type TextFieldDescriptor, type TextOrHtml, TooltipController, type TooltipDescriptor, type TooltipProvider, UpdateScheduler, deepEqual, defaultFieldRegistry, defineDlSelect, escapeHtml, globalModalStack, html, injectStyles, isSafeHtml };
+export { ArrayField, type ArrayFieldDescriptor, type AskOptions, type BaseFieldDescriptor, ButtonBar, type ButtonContext, type ButtonDescriptor, type ButtonMap, CardsField, type CardsFieldDescriptor, CheckboxField, type CheckboxFieldDescriptor, ComputedField, type ComputedFieldDescriptor, CustomField, type CustomFieldDescriptor, DL_SELECT_STYLES, DeclarativeForm, type DeclarativeFormOptions, DlOption, DlSelect, Field, type FieldConstructor, type FieldContext, type FieldDescriptor, type FieldHandle, type FieldKind, type FieldMessage, FieldRegistry, FileField, type FileFieldDescriptor, type FormChangeContext, type FormContext, FormModel, type FormValues, IdGenerator, MessageField, type MessageFieldDescriptor, ModalStack, ModalView, NativeTooltipProvider, type OpenInModalOptions, type OptionsErrorContext, type Reactive, type RenderContext, SafeHtml, SelectField, type SelectFieldDescriptor, type SelectOption, type StackableDialog, type SubForm, type SubFormOptions, TabBar, type TabSpec, TextAreaField, type TextAreaFieldDescriptor, TextField, type TextFieldDescriptor, type TextOrHtml, TooltipController, type TooltipDescriptor, type TooltipProvider, UpdateScheduler, ask, deepEqual, defaultFieldRegistry, defineDlSelect, escapeHtml, globalModalStack, html, injectStyles, isSafeHtml };

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}.
@@ -507,6 +522,16 @@ declare abstract class Field<D extends BaseFieldDescriptor = FieldDescriptor> im
      * resolved before being applied.
      */
     applyDefaultValue(): Promise<void>;
+    /**
+     * Apply a plainly declared default value straight away.
+     *
+     * {@link applyDefaultValue} is awaited during initialisation, so a value it
+     * applies cannot be seen by the first layout pass. A default that is neither a
+     * function nor a promise needs no awaiting, so it is applied at build time and
+     * `isActive` predicates reading it are right from the first paint. The async
+     * pass runs afterwards regardless and simply sets the same value again.
+     */
+    applyStaticDefaultValue(): void;
     /**
      * Hook for setup that cannot happen in {@link build} — loading select
      * options, or a first render that needs the form context. May be synchronous.
@@ -671,7 +696,31 @@ declare class DeclarativeForm implements SubForm, StackableDialog {
     constructor(options: DeclarativeFormOptions, internal?: InternalOptions);
     private resolveButtons;
     private buildFields;
+    /**
+     * Decide field visibility and build the tab strip synchronously, before the
+     * caller gets the form back.
+     *
+     * {@link initialize} is async — it awaits option loads and default values —
+     * but `openInModal()` normally runs in the same tick as the constructor.
+     * Without this pass the dialog paints every field of every tab, then collapses
+     * to the active tab once that first async update lands, which is a visible
+     * layout shift as soon as any field loads its options over the network.
+     *
+     * Only visibility is decided here: no `onFormChange`, no `onFormUpdate`, and
+     * the value model is left untouched, so the regular update cycle still sees
+     * the first real change and refreshes the buttons.
+     */
+    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;
@@ -761,6 +810,46 @@ declare class DeclarativeForm implements SubForm, StackableDialog {
     resetTooltips(fieldNames: Iterable<string>): void;
 }
 
+/**
+ * Everything {@link DeclarativeForm} accepts, minus the three things `ask`
+ * owns: the fields it is given, and the two callbacks it turns into a promise.
+ */
+interface AskOptions extends Omit<DeclarativeFormOptions, 'fields' | 'onConfirm' | 'onCancel'> {
+    /** Class names for the dialog chrome, as passed to `openInModal`. */
+    modal?: OpenInModalOptions;
+    /**
+     * Whether the dialog can be dismissed with Esc or the close button.
+     *
+     * Defaults to `true`. When `false` no close button is rendered and the
+     * promise can only settle with values — so only turn it off when a button of
+     * yours is guaranteed to close the dialog.
+     */
+    dismissable?: boolean;
+}
+/**
+ * Ask the user for a record, the way `prompt()` asks for a string.
+ *
+ * Opens the fields as a modal dialog and resolves with its values, or with
+ * `undefined` when the user dismisses it.
+ *
+ * ```ts
+ * const release = await ask([
+ *   { name: 'title', displayName: 'Release title' },
+ *   { name: 'notes', kind: 'textarea', displayName: 'What changed' },
+ * ]);
+ *
+ * if (release) publish(release);
+ * ```
+ *
+ * With custom {@link AskOptions.buttons | buttons}, the promise resolves when
+ * any button that closes the dialog has run its action; a `doNotCloseModal`
+ * button (a wizard's "Next") leaves it pending, as it leaves the dialog open.
+ *
+ * Use `new DeclarativeForm(…)` directly when you need the form object itself —
+ * to embed it in a page, subscribe to its values, or close it from elsewhere.
+ */
+declare function ask(fields: readonly FieldDescriptor[], options?: AskOptions): Promise<FormValues | undefined>;
+
 /**
  * A repeating list of sub-records, each edited in its own nested dialog.
  *
@@ -971,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;
@@ -1232,4 +1337,4 @@ declare class NativeTooltipProvider implements TooltipProvider {
  */
 declare function deepEqual(a: unknown, b: unknown): boolean;
 
-export { ArrayField, type ArrayFieldDescriptor, type BaseFieldDescriptor, ButtonBar, type ButtonContext, type ButtonDescriptor, type ButtonMap, CardsField, type CardsFieldDescriptor, CheckboxField, type CheckboxFieldDescriptor, ComputedField, type ComputedFieldDescriptor, CustomField, type CustomFieldDescriptor, DL_SELECT_STYLES, DeclarativeForm, type DeclarativeFormOptions, DlOption, DlSelect, Field, type FieldConstructor, type FieldContext, type FieldDescriptor, type FieldHandle, type FieldKind, type FieldMessage, FieldRegistry, FileField, type FileFieldDescriptor, type FormChangeContext, type FormContext, FormModel, type FormValues, IdGenerator, MessageField, type MessageFieldDescriptor, ModalStack, ModalView, NativeTooltipProvider, type OpenInModalOptions, type OptionsErrorContext, type Reactive, type RenderContext, SafeHtml, SelectField, type SelectFieldDescriptor, type SelectOption, type StackableDialog, type SubForm, type SubFormOptions, TabBar, type TabSpec, TextAreaField, type TextAreaFieldDescriptor, TextField, type TextFieldDescriptor, type TextOrHtml, TooltipController, type TooltipDescriptor, type TooltipProvider, UpdateScheduler, deepEqual, defaultFieldRegistry, defineDlSelect, escapeHtml, globalModalStack, html, injectStyles, isSafeHtml };
+export { ArrayField, type ArrayFieldDescriptor, type AskOptions, type BaseFieldDescriptor, ButtonBar, type ButtonContext, type ButtonDescriptor, type ButtonMap, CardsField, type CardsFieldDescriptor, CheckboxField, type CheckboxFieldDescriptor, ComputedField, type ComputedFieldDescriptor, CustomField, type CustomFieldDescriptor, DL_SELECT_STYLES, DeclarativeForm, type DeclarativeFormOptions, DlOption, DlSelect, Field, type FieldConstructor, type FieldContext, type FieldDescriptor, type FieldHandle, type FieldKind, type FieldMessage, FieldRegistry, FileField, type FileFieldDescriptor, type FormChangeContext, type FormContext, FormModel, type FormValues, IdGenerator, MessageField, type MessageFieldDescriptor, ModalStack, ModalView, NativeTooltipProvider, type OpenInModalOptions, type OptionsErrorContext, type Reactive, type RenderContext, SafeHtml, SelectField, type SelectFieldDescriptor, type SelectOption, type StackableDialog, type SubForm, type SubFormOptions, TabBar, type TabSpec, TextAreaField, type TextAreaFieldDescriptor, TextField, type TextFieldDescriptor, type TextOrHtml, TooltipController, type TooltipDescriptor, type TooltipProvider, UpdateScheduler, ask, deepEqual, defaultFieldRegistry, defineDlSelect, escapeHtml, globalModalStack, html, injectStyles, isSafeHtml };

package/dist/index.js

@@ -193,6 +193,21 @@ var Field = class {
     );
     if (value !== void 0) this.setValue(value);
   }
+  /**
+   * Apply a plainly declared default value straight away.
+   *
+   * {@link applyDefaultValue} is awaited during initialisation, so a value it
+   * applies cannot be seen by the first layout pass. A default that is neither a
+   * function nor a promise needs no awaiting, so it is applied at build time and
+   * `isActive` predicates reading it are right from the first paint. The async
+   * pass runs afterwards regardless and simply sets the same value again.
+   */
+  applyStaticDefaultValue() {
+    const value = this.descriptor.defaultValue;
+    if (value === void 0 || typeof value === "function") return;
+    if (value instanceof Promise) return;
+    this.setValue(value);
+  }
   /**
    * Hook for setup that cannot happen in {@link build} — loading select
    * options, or a first render that needs the form context. May be synchronous.
@@ -927,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 {
@@ -941,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;
@@ -1050,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");
@@ -2104,6 +2133,7 @@ var DeclarativeForm = class _DeclarativeForm {
       closeWith: (action) => this.close(action)
     });
     this.buildFields();
+    this.applyInitialLayout();
     this.ready = this.initialize();
   }
   // ------------------------------------------------------------------ setup
@@ -2125,12 +2155,41 @@ 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);
       this.formElement.appendChild(field.wrapper);
     }
   }
+  /**
+   * Decide field visibility and build the tab strip synchronously, before the
+   * caller gets the form back.
+   *
+   * {@link initialize} is async — it awaits option loads and default values —
+   * but `openInModal()` normally runs in the same tick as the constructor.
+   * Without this pass the dialog paints every field of every tab, then collapses
+   * to the active tab once that first async update lands, which is a visible
+   * layout shift as soon as any field loads its options over the network.
+   *
+   * Only visibility is decided here: no `onFormChange`, no `onFormUpdate`, and
+   * the value model is left untouched, so the regular update cycle still sees
+   * the first real change and refreshes the buttons.
+   */
+  applyInitialLayout() {
+    const values = this.getValues();
+    const activeTabs = /* @__PURE__ */ new Set();
+    for (const field of this.fieldList) {
+      const active = field.descriptor.isActive?.({
+        ...this.contextFor(field.descriptor),
+        data: values
+      }) ?? true;
+      field.setActive(active);
+      if (active) for (const tab of field.tabs()) activeTabs.add(tab);
+    }
+    this.renderTabs(activeTabs);
+  }
   async initialize() {
     await Promise.allSettled(
       this.fieldList.map(
@@ -2140,8 +2199,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());
@@ -2468,6 +2543,44 @@ var DeclarativeForm = class _DeclarativeForm {
   }
 };
 
-export { ArrayField, ButtonBar, CardsField, CheckboxField, ComputedField, CustomField, DL_SELECT_STYLES, DeclarativeForm, DlOption, DlSelect, Field, FieldRegistry, FileField, FormModel, IdGenerator, MessageField, ModalStack, ModalView, NativeTooltipProvider, SafeHtml, SelectField, TabBar, TextAreaField, TextField, TooltipController, UpdateScheduler, deepEqual, defaultFieldRegistry, defineDlSelect, escapeHtml, globalModalStack, html, injectStyles, isSafeHtml };
+// src/core/ask.ts
+function ask(fields, options = {}) {
+  return askWith(DeclarativeForm, fields, options);
+}
+function askWith(FormClass, fields, options = {}) {
+  const { modal, dismissable = true, buttons, ...formOptions } = options;
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (values) => {
+      if (settled) return;
+      settled = true;
+      setTimeout(() => resolve(values), 0);
+    };
+    new FormClass({
+      ...formOptions,
+      fields,
+      buttons: buttons && settleOnClose(buttons, settle),
+      onConfirm: (values) => settle(values),
+      onCancel: dismissable ? () => settle(void 0) : void 0
+    }).openInModal(modal);
+  });
+}
+function settleOnClose(buttons, settle) {
+  return Object.fromEntries(
+    Object.entries(buttons).map(([label, descriptor]) => [
+      label,
+      descriptor.doNotCloseModal ? descriptor : {
+        ...descriptor,
+        action: async (values) => {
+          const result = await descriptor.action?.(values);
+          settle(values);
+          return result;
+        }
+      }
+    ])
+  );
+}
+
+export { ArrayField, ButtonBar, CardsField, CheckboxField, ComputedField, CustomField, DL_SELECT_STYLES, DeclarativeForm, DlOption, DlSelect, Field, FieldRegistry, FileField, FormModel, IdGenerator, MessageField, ModalStack, ModalView, NativeTooltipProvider, SafeHtml, SelectField, TabBar, TextAreaField, TextField, TooltipController, UpdateScheduler, ask, deepEqual, defaultFieldRegistry, defineDlSelect, escapeHtml, globalModalStack, html, injectStyles, isSafeHtml };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map