@samline/forms 2.7.2 → 2.9.0

package/dist/browser/global.d.ts

@@ -106,7 +106,38 @@ interface AppendContentOptions {
     class?: string;
     atStart?: boolean;
 }
+/** One `<option>` written by `setOptions()`. */
+interface SelectOption {
+    value: string | number;
+    /** Visible text. Defaults to `String(value)`. Written as text, never HTML. */
+    label?: string;
+    disabled?: boolean;
+    /** Selects the option and makes it the default restored by `reset()`. */
+    selected?: boolean;
+}
+/** One `<optgroup>` written by `setOptions()`. */
+interface SelectOptionGroup {
+    label: string;
+    options: Array<string | number | SelectOption>;
+    disabled?: boolean;
+}
+/** A plain string or number is shorthand for `{ value, label: String(value) }`. */
+type SelectOptionInput = string | number | SelectOption | SelectOptionGroup;
+interface SetOptionsConfig {
+    /**
+     * Keep the current selection when its value is still in the new list.
+     * Ignored for a select when any new option has `selected: true`.
+     * Defaults to `true`.
+     */
+    keepValue?: boolean;
+}
 type FormFieldWatcher = (value: FormFieldValue, field: FormFieldElement | FormFieldElement[] | null, form: HTMLFormElement, state: FormStateSnapshot) => void;
+/**
+ * Callback for `watch()` / `observe()` with a list of fields. `values` has
+ * one entry per watched field. `changed` is the field that triggered the
+ * call, or `null` on registration and after `reset()`.
+ */
+type FormFieldsWatcher = (values: FormValues, changed: string | null, form: HTMLFormElement, state: FormStateSnapshot) => void;
 type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void | Promise<void>;
 type FormCleanup = () => void;
 interface FormController {
@@ -115,15 +146,30 @@ interface FormController {
     readonly options: FormControllerOptions;
     onSubmit: (callback: FormSubmitHandler, preventDefault?: boolean) => FormController;
     addCleanup: (cleanup: FormCleanup) => () => void;
-    watch: (field: string, callback: FormFieldWatcher) => FormController;
-    observe: (field: string, callback: FormFieldWatcher) => () => void;
-    unwatch: (field?: string, callback?: FormFieldWatcher) => FormController;
+    watch: {
+        (field: string, callback: FormFieldWatcher): FormController;
+        (fields: string[], callback: FormFieldsWatcher): FormController;
+    };
+    observe: {
+        (field: string, callback: FormFieldWatcher): () => void;
+        (fields: string[], callback: FormFieldsWatcher): () => void;
+    };
+    unwatch: {
+        (field?: string, callback?: FormFieldWatcher): FormController;
+        (fields: string[], callback?: FormFieldsWatcher): FormController;
+    };
     subscribe: (listener: FormStateListener) => () => void;
     prefill: (fieldName?: string) => FormController;
     append: (options: AppendContentOptions) => HTMLElement | null;
     setErrors: (fields: string[] | FormErrors) => FormController;
     clearErrors: (fields?: string[]) => FormController;
     setValue: (name: string, value: unknown) => FormController;
+    /**
+     * Replace the `<option>` / `<optgroup>` children of every `<select>`
+     * named `name`. Fires the normal change pipeline only when the
+     * selected value changes. Chainable.
+     */
+    setOptions: (name: string, options: SelectOptionInput[], config?: SetOptionsConfig) => FormController;
     validate: (fields?: string[]) => ValidationResult;
     revalidate: (fields?: string[]) => ValidationResult;
     /**
@@ -153,22 +199,10 @@ interface NewFormInput {
 interface FormsAvailable {
     [id: string]: FormController;
 }
-interface FormsApi {
-    form: (target: FormTarget, options?: FormControllerOptions) => FormController;
-    newForm: (input: NewFormInput) => FormController | undefined;
-    destroyForm: (id: string) => void;
-    available: FormsAvailable;
-}
 
-declare const Forms: FormsApi;
 declare const form: (target: FormTarget, options?: FormControllerOptions) => FormController;
 declare const newForm: (input: NewFormInput) => FormController | undefined;
 declare const destroyForm: (id: string) => void;
 declare const available: FormsAvailable;
-declare global {
-    interface Window {
-        Forms: FormsApi;
-    }
-}
 
-export { available, Forms as default, destroyForm, form, newForm };
+export { available, destroyForm, form, newForm };