declarative-forms 2.0.1 → 2.1.0

package/dist/index.d.cts

@@ -507,6 +507,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,6 +681,21 @@ 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;
     /** Resolves once initial options and default values have been applied. */
     whenReady(): Promise<void>;
@@ -761,6 +786,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.
  *
@@ -1232,4 +1297,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

@@ -507,6 +507,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,6 +681,21 @@ 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;
     /** Resolves once initial options and default values have been applied. */
     whenReady(): Promise<void>;
@@ -761,6 +786,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.
  *
@@ -1232,4 +1297,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.
@@ -2104,6 +2119,7 @@ var DeclarativeForm = class _DeclarativeForm {
       closeWith: (action) => this.close(action)
     });
     this.buildFields();
+    this.applyInitialLayout();
     this.ready = this.initialize();
   }
   // ------------------------------------------------------------------ setup
@@ -2125,12 +2141,40 @@ var DeclarativeForm = class _DeclarativeForm {
         );
       }
       const field = this.registry.create(descriptor, context);
+      field.applyStaticDefaultValue();
       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(
@@ -2468,6 +2512,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