@optionfactory/fml 8.0.3 → 9.0.0-rc1

package/dist/ful.d.mts

@@ -1,24 +1,24 @@
 import { ParsedElement } from './ftl.mjs';
-declare class LocalStorage extends Storage {
-    static save(k: any, v: any): void;
-    static load(k: any): any;
-    static remove(k: any): void;
-    static pop(k: any): any;
-}
-declare class SessionStorage extends Storage {
-    static save(k: any, v: any): void;
-    static load(k: any): any;
-    static remove(k: any): void;
-    static pop(k: any): any;
-}
-declare class VersionedLocalStorage {
-    static save(key: any, revision: any, data: any): void;
-    static load(key: any, revision: any): any;
-}
-declare class VersionedSessionStorage {
-    static save(key: any, revision: any, data: any): void;
-    static load(key: any, revision: any): any;
-}
+declare const LocalStorage: {
+    save: (k: any, v: any) => void;
+    load: (k: any) => any;
+    remove: (k: any) => void;
+    pop: (k: any) => any;
+};
+declare const SessionStorage: {
+    save: (k: any, v: any) => void;
+    load: (k: any) => any;
+    remove: (k: any) => void;
+    pop: (k: any) => any;
+};
+declare const VersionedLocalStorage: {
+    save(key: any, revision: any, data: any): void;
+    load(key: any, revision: any): any;
+};
+declare const VersionedSessionStorage: {
+    save(key: any, revision: any, data: any): void;
+    load(key: any, revision: any): any;
+};
 export type AsyncExtension = {
     promises: Promise<any>[];
 };
@@ -30,6 +30,12 @@ export type AsyncEvent = Event & {
  * @property {Promise<any>[]} promises
  * @typedef {Event & { async?: AsyncExtension }} AsyncEvent
  */
+/**
+ * Dispatching an event and waiting for what its listeners answer. A listener
+ * registered through `asyncOn` attaches its promise to the event, and
+ * `fireAsync` resolves once they have all settled: `broadcast` collects every
+ * answer, `pipeline` allows at most one, `delegate` requires exactly one.
+ */
 declare class AsyncEvents {
     /**
      * Dispatches an event and handles asynchronous resolution based on the execution mode.
@@ -64,36 +70,78 @@ declare class AsyncEvents {
      */
     static mixInto(...classes: Function[]): void;
 }
+export type Claim = {
+    readonly stale: boolean;
+};
+/**
+ * @typedef {{ readonly stale: boolean }} Claim
+ */
+/**
+ * The generations of claims over one contended resource. Every take() starts a
+ * new generation, superseding every claim before it, and a holder asks its
+ * claim `stale` before painting chrome, storing state or throwing towards a
+ * caller: a superseded outcome owns nothing. hold() joins the current
+ * generation without superseding it (a fetch that any later reconfiguration
+ * must detach), and invalidate() supersedes without claiming (a hide ending
+ * every pending show). One Claims per contended resource: a component whose
+ * dropdown, value labels and loader configuration contend separately holds one
+ * each.
+ */
+declare class Claims {
+    #private;
+    /**
+     * Starts a new generation, superseding every earlier claim, and holds it.
+     * @returns {Claim}
+     */
+    take(): Claim;
+    /**
+     * Holds the current generation without superseding anything.
+     * @returns {Claim}
+     */
+    hold(): Claim;
+    /** Supersedes every claim without holding a new one. */
+    invalidate(): void;
+}
+/**
+ * Sleeping, debouncing and throttling. Debounce and throttle both return the
+ * wrapped function together with a cancel function.
+ */
 declare class Timing {
-    static sleep(ms: any): Promise<any>;
-    static DEBOUNCE_DEFAULT: number;
-    static DEBOUNCE_IMMEDIATE: number;
+    /** Resolves after the given milliseconds. @param {number} ms */
+    static sleep(ms: number): Promise<any>;
     /**
      * Executes only after a period of inactivity (pause in events).
      * Respond to the "end" of a series of events.
-     * @param {*} timeoutMs
-     * @param {*} func
-     * @param {*} [options]
+     * @param {number} timeoutMs
+     * @param {function} func
+     * @param {{ immediate?: boolean }} [options] - immediate fires on the leading edge instead of the trailing one
      * @returns {[function, function]}
      */
-    static debounce(timeoutMs: any, func: any, options?: any): [Function, Function];
-    static THROTTLE_DEFAULT: number;
-    static THROTTLE_NO_LEADING: number;
-    static THROTTLE_NO_TRAILING: number;
+    static debounce(timeoutMs: number, func: Function, options?: {
+        immediate?: boolean;
+    }): [Function, Function];
     /**
      * Executes at most once per specified time interval, regardless of ongoing events.
-     * @param {*} timeoutMs
-     * @param {*} func
-     * @param {*} [options]
+     * @param {number} timeoutMs
+     * @param {function} func
+     * @param {{ leading?: boolean, trailing?: boolean }} [options] - which edges of the interval call, both by default
      * @returns {[function, function]}
      */
-    static throttle(timeoutMs: any, func: any, options?: any): [Function, Function];
+    static throttle(timeoutMs: number, func: Function, options?: {
+        leading?: boolean;
+        trailing?: boolean;
+    }): [Function, Function];
 }
+/** Field wiring: extracting and filling values, pinning problems to the fields they name. */
 declare class Bindings {
+    #private;
     /**
+     * Flattens a nested object into dotted keys, stopping wherever `stops` names
+     * a key: a field named `address` takes the whole object, while one named
+     * `address.city` takes the leaf.
      * @param {{ [x: string]: any; }} obj
      * @param {string} prefix
-     * @param {Set<String>} stops
+     * @param {Set<String>} stops - the names the form actually has fields for
      * @return {{ [x: string]: any; }}
      */
     static flatten(obj: {
@@ -102,15 +150,20 @@ declare class Bindings {
         [x: string]: any;
     };
     /**
+     * Writes a value into an object at a dotted path, creating the intermediate
+     * objects and arrays the path implies. A numeric segment makes an array.
      * @param {any} result
-     * @param {string} path
+     * @param {string} path - a field name, `a.b` or `a[0].b`
      * @param {any} value
      */
     static providePath(result: any, path: string, value: any): any;
     /**
-     *
+     * Reads one control's value the way its kind demands: an unchecked radio
+     * answers undefined so it contributes nothing, a checkbox answers its
+     * checked state, a multiple select answers its selected values, and a blank
+     * native control answers null rather than an empty string.
      * @param {Element & {dataset?: any} & {checked?: boolean} & {value?: any}} el
-     * @returns
+     * @returns {any} the value, or undefined where the control contributes none
      */
     static extract(el: Element & {
         dataset?: any;
@@ -119,17 +172,13 @@ declare class Bindings {
     } & {
         value?: any;
     }): any;
+    static extractFrom(form: any, submitter: any): {};
     /**
-     *
-     * @param {HTMLFormElement} form
-     * @param {HTMLElement} [submitter]
-     * @returns
-     */
-    static extractFrom(form: HTMLFormElement, submitter?: HTMLElement): {};
-    /**
-     *
+     * Writes a value into one control, the inverse of `extract`: a radio is
+     * checked when its own value matches, a checkbox takes the value as its
+     * checked state, and a multiple select selects the options the list names.
      * @param {Element & {dataset?: any} & {checked?: boolean} & {value?: any}} el
-     * @returns
+     * @param {any} raw the value as it arrived, coerced per control kind
      */
     static mutate(el: Element & {
         dataset?: any;
@@ -141,82 +190,276 @@ declare class Bindings {
     static mutateIn(form: any, values: any): void;
     static errors(form: any, es: any, scrollOnError: any): void;
 }
+/**
+ * The base of every form-associated ful field: a form-associated custom element
+ * carrying the validity protocol, the field error live region, focus
+ * delegation, the label chrome and the disabled, readonly and required claims.
+ *
+ * A subclass owns its template, its value semantics and its change events. It
+ * implements `_build(conf)`, which builds its dom and returns the pieces the
+ * base drives: the control, the error region, the label, and the optional
+ * `claims`, `announces`, `freeze` and `also`. The base does the wiring,
+ * the mounting and the application of the declared state. Nothing in the base
+ * is there to be called from a subclass's build.
+ *
+ * The pieces are the contract: the claim setters, the validity protocol and
+ * the aria wiring all act on them, so a field with no native control returns a
+ * focusable piece of its own chrome as the control. The getters and `focus()`
+ * are the only members that tolerate a not-yet-rendered element, where page
+ * code may read a claim or ask for the focus before the upgrade; the
+ * properties go live only after the render, as ParsedElement documents. The
+ * base references no ful vocabulary, only what its subclasses return to it.
+ */
+declare class Field extends ParsedElement {
+    #private;
+    static formAssociated: boolean;
+    /**
+     * The claim attributes and the value are observed here so every field,
+     * including the custom ones, keeps them live after the upgrade: the
+     * attribute is a third way to author a claim, beside the markup and the
+     * property,
+     * exactly as a native input's. The value defaults to the string mapper and
+     * every field with its own vocabulary overrides it (`value:bool`,
+     * `value:csv`, `value:json`).
+     */
+    static observed: string[];
+    /** the role the element internals carry, 'presentation' unless the control is its own */
+    static ROLE: string;
+    constructor();
+    focus(options: any): void;
+    /**
+     * Clears or reports one validation problem: the text lands on the field's
+     * live region and the state on the element internals, driving `:invalid`
+     * styling. Validation is the server's: the submit travels regardless, and
+     * the problems come back pinned here. The error mapping pins on the most
+     * specific field name a problem's context reaches, handing over the
+     * remaining path ('' on an exact match): the base ignores it, a composite
+     * field owning a whole subtree overrides to route the problem to the inner
+     * control it names.
+     * @param {string} [error]
+     * @param {string} [context] the path below this field's name, '' when exact
+     */
+    setCustomValidity(error?: string, context?: string): void;
+    /** Submits the associated form through its first submitter, as Enter on a native control would. */
+    _requestSubmit(): void;
+    /**
+     * Dispatches the field's change event: bubbling, not cancelable, the value
+     * in the detail. Every field announces through this one method, and the detail
+     * always carries the field's own `value`, so a listener can rely on
+     * `el.value === evt.detail.value` whatever the field is. A field with more to
+     * say adds keys beside it; none can replace it.
+     * @param {Record<string, any>} [extras]
+     */
+    _notifyChange(extras?: Record<string, any>): void;
+    /**
+     * Whether the field's chrome should answer a gesture. Badges, dropzones,
+     * menus and labels are not form controls, so their handlers must ask the
+     * effective state: matches(':disabled') covers the fieldset ancestry the
+     * disabled property deliberately does not reflect, readonly the field's
+     * own claim.
+     */
+    _interactive(): boolean;
+    /**
+     * The field's value: every concrete field owns its semantics and overrides
+     * this pair. The base pair exists so the form integration (the reset
+     * protocol among others) has a member to write through; a custom field
+     * forgetting its own keeps the base's inert one.
+     * @type {any}
+     */
+    get value(): any;
+    set value(v: any);
+    /**
+     * A reset restores the field's declared value, as a native control's reset
+     * restores its markup default: the `value` attribute goes back through the
+     * element's own mapper and value setter, so every field resets through its
+     * own semantics. A field whose value is not attribute backed overrides this.
+     */
+    formResetCallback(): void;
+    /**
+     * The disabled protocol follows the semantics of a native form control:
+     *
+     * - the `disabled` attribute on the host is the field's own claim, and nothing
+     *   but its author ever writes or removes it, in markup or through the
+     *   property. The framework never claims on the form's behalf, so there is
+     *   nothing to unclaim and nothing to lose: a field declared disabled inside
+     *   a disabled `<fieldset>` stays disabled when the fieldset comes back,
+     *   exactly like a native input keeps its attribute.
+     * - the effective state is the claim OR a disabled fieldset ancestry, which
+     *   the platform maintains on its own: `:disabled` matches both, a disabled
+     *   field is left out of the submitted values, and the inner native controls
+     *   are reached by the ancestry as descendants of the fieldset.
+     * - the property reflects the claim only, like a native input's: a field
+     *   disabled by its ancestry reads `false` while `matches(':disabled')`
+     *   tells the effective state. Un-claiming inside a disabled fieldset
+     *   cannot enable the field.
+     * - the inner controls mirror the claim and nothing else: the ancestry state
+     *   is never written anywhere, so it can never go stale, and the browser
+     *   composes the two on its own when it disables and re-enables a fieldset's
+     *   descendants. Subclass setters call super for the claim, then reach their
+     *   own controls, which mirror the claim like a native input's would.
+     *
+     * Because of this, formDisabledCallback carries nothing the framework needs
+     * to apply, and the protocol does not define it.
+     */
+    get disabled(): boolean;
+    set disabled(d: boolean);
+    /**
+     * A field is readonly through its control's native readOnly when it has one:
+     * the control stays focusable and its text selectable, only editing is off.
+     * Fields whose chrome must freeze too (popovers, buttons, label clicks) name
+     * a `freeze` piece instead, whose gestures the base refuses while the claim
+     * holds; the claim reflects on the host either way.
+     */
+    get readonly(): boolean;
+    set readonly(v: boolean);
+    /**
+     * A field is required through aria: the claim reflects on the host, the
+     * announcement lives on the adopted control.
+     */
+    get required(): boolean;
+    set required(d: boolean);
+    /**
+     * The field's render is the base's: the subclass builds its dom in `_build`
+     * and hands back what it built, the base wiring the pieces, mounting the
+     * fragment and applying the declared state. Nothing in the base is there to
+     * be called from a subclass's build. `_build` may be async (a select
+     * awaiting its prefetch); a field that builds synchronously stays so.
+     */
+    render(conf: any): Promise<void> | undefined;
+    /**
+     * Builds the field's dom and answers the pieces the base drives. The one
+     * method a concrete field implements beside its value pair, and the only
+     * place its dom is created; the base does the wiring and the mounting.
+     *
+     * - `fragment` is mounted on the host
+     * - `control` is the focusable target: focus, the aria and, by default, all
+     *   three claims reach it
+     * - `error` is the field's live region
+     * - `label`, when given, names the control and focuses it on click
+     * - `described` moves the error's description off the control and onto
+     *   another element, the host where no single control can carry it
+     * - `claims` moves the three claims onto a wrapper the field disables as a
+     *   whole, leaving focus and aria on the control
+     * - `announces` is the element whose role carries `aria-readonly` and
+     *   `aria-required`, the host where the widget role lives there; `null` for a
+     *   field whose control has no role that accepts them
+     * - `freeze` is for a field with no usable native readOnly: the readonly
+     *   claim refuses the gestures inside it, leaving it focusable and readable
+     * - `also` are further controls mirroring disabled and readOnly beside the
+     *   first
+     *
+     * A subclass extending another field's build spreads the pieces it answered
+     * and overrides the keys it owns.
+     * @param {{slots: any}} conf
+     * @returns {any}
+     */
+    _build(conf: {
+        slots: any;
+    }): any;
+}
+/** Submits a form's values as json to a url, mapping the request and the response through the configured mappers. */
 declare class RemoteJsonFormLoader {
     #private;
     constructor(http: any, url: any, method: any, requestMapper: any, responseMapper: any);
     prepare(values: any, form: any): any;
-    submit(values: any, form: any): Promise<any>;
+    submit(request: any, form: any): Promise<any>;
     transform(response: any, form: any): any;
 }
+/** Submits a form without a request: the request mapper produces the result the response mapper then reads, for a form handled entirely on the page. */
 declare class LocalFormLoader {
     #private;
     constructor(requestMapper: any, responseMapper: any);
     prepare(values: any, form: any): Promise<any>;
-    submit(values: any, form: any, response: any): Promise<any>;
+    submit(request: any, form: any, response: any): Promise<any>;
     transform(response: any, form: any): Promise<any>;
 }
+/**
+ * Builds the form's loader from its attributes: a local one when no action is
+ * declared, a json post to it otherwise.
+ *
+ * A component registered under the `loader` attribute replaces this one and
+ * must implement three methods, called in this order:
+ *
+ * - `prepare(values, form)` turns the extracted values into the request to send
+ * - `submit(request, form, response)` performs it and returns the response. The
+ *   third argument is whatever a `submit:requested` listener already answered,
+ *   which is how a loader with nothing to send returns it unchanged
+ * - `transform(response, form)` turns that response into the detail of the
+ *   `submit:success` event
+ *
+ * A rejection from any of the three is reported as a `submit:failure`.
+ */
 declare class FormLoader {
     static create(el: any, conf: any): LocalFormLoader | RemoteJsonFormLoader;
 }
+/**
+ * Wraps its fields in a native form, extracts their values on submit and hands
+ * them to a loader (loaders:form, or the action url as a json post),
+ * announcing failures through the errors setter.
+ */
 declare class Form extends ParsedElement {
     #private;
+    static attributes: string[];
     form: any;
     render(): void;
     /**
-     *
+     * Submits once: a submit while one is in flight is dropped before the
+     * values are even extracted, so nothing fires and nothing travels; the
+     * settled exchange re-arms the form. A write must not double behind a
+     * second Enter or a programmatic call racing the first.
      * @param {HTMLElement} [submitter]
      * @returns
      */
     submit(submitter?: HTMLElement): Promise<void>;
+    /** The native reset, routing every field through its own value semantics. */
     reset(): void;
+    /** Shows the spinners and holds the submit buttons off, overlapping spins sharing one claim. */
     spinner(spin: any): void;
+    /** The values of the fields the form contains, extracted and filled back through Bindings. */
     set values(vs: {});
     get values(): {};
+    /** Pins problems to the fields they name, the banner taking the nameless ones. */
     set errors(es: any);
 }
-declare class Input extends ParsedElement {
-    internals: ElementInternals;
+/** A labelled text input over any native type or textarea; the temporal inputs are its subclasses. */
+declare class Input extends Field {
     static observed: string[];
+    static attributes: string[];
     static slots: boolean;
     static template: string;
-    static formAssociated: boolean;
     _input: any;
-    _fieldError: any;
-    constructor();
-    _type(): string;
-    _fragment(type: any, slots: any): any;
-    render({ slots, observed, disabled, skipObservedSetup }: {
-        disabled: any;
-        observed: any;
-        skipObservedSetup: any;
+    _type(): any;
+    _build({ slots }: {
         slots: any;
-    }): void;
+    }): {
+        fragment: any;
+        control: any;
+        error: any;
+        label: any;
+    };
     get value(): any;
     set value(value: any);
-    get readonly(): any;
-    set readonly(v: any);
-    get disabled(): boolean;
-    set disabled(d: boolean);
-    get required(): boolean;
-    set required(d: boolean);
     get placeholder(): any;
     set placeholder(d: any);
-    focus(options: any): void;
-    setCustomValidity(error: any): void;
-    formResetCallback(): void;
 }
+/** Formats the yyyy-mm-dd date in its content in the page's locale, or the one its locale attribute names. */
 declare class LocalDate extends ParsedElement {
+    static attributes: string[];
     render(): void;
 }
+/** Formats the ISO instant in its content in the page's locale and timezone. */
 declare class Instant extends ParsedElement {
+    #private;
+    static attributes: string[];
     render(): void;
     static isoToLocal(iso: any): string;
+    static localToIso(local: any): string | null;
 }
+/** A date input whose bounds accept a date, now, or an offset such as +1d. */
 declare class InputLocalDate extends Input {
     #private;
     static observed: string[];
     _type(): string;
-    render(conf: any): void;
     get min(): any;
     set min(v: any);
     get max(): any;
@@ -224,6 +467,7 @@ declare class InputLocalDate extends Input {
     get step(): any;
     set step(v: any);
 }
+/** A time input whose bounds accept a time, now, or an hour or minute offset, snapped to the step grid. */
 declare class InputLocalTime extends InputLocalDate {
     #private;
     _type(): string;
@@ -232,10 +476,10 @@ declare class InputLocalTime extends InputLocalDate {
     get max(): any;
     set max(v: any);
 }
+/** A datetime input whose value is read and written as an ISO instant. */
 declare class InputInstant extends Input {
     static observed: string[];
     _type(): string;
-    render(conf: any): void;
     get value(): string | null;
     set value(v: string | null);
     get min(): string | null;
@@ -245,38 +489,18 @@ declare class InputInstant extends Input {
     get step(): any;
     set step(v: any);
 }
+/** A file input with an optional dropzone and item list, enforcing the size and count limits it declares. */
 declare class InputFile extends Input {
     #private;
-    static l10n: {
-        en: {
-            dropzonelabel: string;
-            unacceptablefiletype: string;
-            maxfilesizeexceeded: string;
-            maxtotalsizeexceeded: string;
-            maxfilesexceeded: string;
-        };
-        it: {
-            dropzonelabel: string;
-            unacceptablefiletype: string;
-            maxfilesizeexceeded: string;
-            maxtotalsizeexceeded: string;
-            maxfilesexceeded: string;
-        };
-        es: {
-            dropzonelabel: string;
-            unacceptablefiletype: string;
-            maxfilesizeexceeded: string;
-            maxtotalsizeexceeded: string;
-            maxfilesexceeded: string;
-        };
-        fr: {
-            dropzonelabel: string;
-            unacceptablefiletype: string;
-            maxfilesizeexceeded: string;
-            maxtotalsizeexceeded: string;
-            maxfilesexceeded: string;
-        };
-    };
+    /** how long a warning stands before the field retires it, matching the css fade */
+    static WARNING_TIMEOUT: number;
+    /**
+     * A FileList holding exactly these files. The platform gives no way to
+     * build one but through a DataTransfer, and every place that narrows a
+     * selection rebuilt it by hand: five loops and three empty ones.
+     * @param {Iterable<File>} [files]
+     */
+    static list(files?: Iterable<File>): FileList;
     static observed: string[];
     _type(): string;
     static template: string;
@@ -284,7 +508,13 @@ declare class InputFile extends Input {
         items: string;
         warning: string;
     };
-    render(conf: any): void;
+    _build(conf: any): {
+        fragment: any;
+        control: any;
+        error: any;
+        label: any;
+        freeze: any;
+    };
     warning(key: any, args: any): void;
     get accept(): any;
     set accept(vs: any);
@@ -296,18 +526,24 @@ declare class InputFile extends Input {
     set file(v: any);
     get value(): any;
     set value(v: any);
+    formResetCallback(): void;
     get totalsize(): any;
-    get maxfiles(): any;
-    set maxfiles(v: any);
-    get maxfilesize(): any;
-    set maxfilesize(v: any);
-    get maxtotalsize(): any;
-    set maxtotalsize(v: any);
-    get itemlist(): any;
-    set itemlist(v: any);
+    get maxFiles(): any;
+    set maxFiles(v: any);
+    get maxFileSize(): any;
+    set maxFileSize(v: any);
+    get maxTotalSize(): any;
+    set maxTotalSize(v: any);
+    get itemList(): any;
+    set itemList(v: any);
     get dropzone(): any;
     set dropzone(v: any);
 }
+/**
+ * Fetches a select's whole vocabulary from a url and serves every later read
+ * from it. Concurrent callers share one request, the options may be cached in
+ * local storage under a revision, and reconfiguring the url discards both.
+ */
 declare class RemoteLoader {
     #private;
     constructor({ http, url, method, responseMapper, prefetch, revision }: {
@@ -321,8 +557,15 @@ declare class RemoteLoader {
     prefetch(): Promise<void>;
     exact(...keys: any[]): Promise<any>;
     load(needle: any): Promise<any>;
+    /**
+     * Drops the cached vocabulary so the next question refetches it. Any fetch
+     * still in flight is detached: its outcome belongs to the configuration that
+     * started it and must neither be served nor stored for the new one.
+     */
+    invalidate(): Promise<void>;
     reconfigureUrl(url: any): Promise<void>;
 }
+/** Asks the endpoint per query instead of fetching the vocabulary once, for a list too large to hold in memory. */
 declare class PartialRemoteLoader {
     #private;
     constructor({ http, url, method, responseMapper }: {
@@ -331,22 +574,65 @@ declare class PartialRemoteLoader {
         responseMapper: any;
         url: any;
     });
+    /**
+     * Nothing is held between queries, so there is no cache to drop: the method
+     * exists so a caller can invalidate any loader without knowing which it has.
+     */
+    invalidate(): Promise<void>;
+    reconfigureUrl(url: any): Promise<void>;
     exact(...keys: any[]): Promise<any>;
     load(needle: any): Promise<any>;
 }
+/** Serves a select's options from an array held in memory, which is what the slotted `<option>` elements become. */
 declare class InMemoryLoader {
     #private;
     constructor(data: any);
     update(data: any): void;
+    /** The vocabulary is the data itself: update replaces it, so there is nothing to drop. */
+    invalidate(): Promise<void>;
     exact(...keys: any[]): any;
     load(needle: any): any;
 }
+/**
+ * Builds the select's loader from its attributes: the slotted options in
+ * memory, or a remote or chunked loader over src.
+ *
+ * A component registered under the `loader` attribute replaces this one and
+ * must implement the same three methods, each answering `{ key, label,
+ * metadata }` entries:
+ *
+ * - `prefetch()` warms the vocabulary if it can, and resolves either way
+ * - `load(needle)` answers the entries matching the typed text, all of them
+ *   when the needle is nullish, which is the empty search the list opens with
+ * - `exact(...keys)` answers the entries for those keys, used to label a value
+ *   assigned without going through the list
+ */
 declare class SelectLoader {
     #private;
+    /**
+     * Builds a loader from a plain configuration, reading no dom: `data` alone
+     * is the in-memory vocabulary, a `url` is fetched whole or, under
+     * `mode: 'chunked'`, per query. A test, or a caller holding its own
+     * configuration, builds a loader this way; `create` is the same thing with
+     * an element's attributes parsed first.
+     * @param {{ data?: any[], http?: any, url?: string, method?: string, mode?: string, prefetch?: boolean, revision?: string|null, responseMapper?: any }} conf
+     */
+    static from({ data, http, url, method, mode, prefetch, revision, responseMapper }: {
+        data?: any[];
+        http?: any;
+        url?: string;
+        method?: string;
+        mode?: string;
+        prefetch?: boolean;
+        revision?: string | null;
+        responseMapper?: any;
+    }): InMemoryLoader | PartialRemoteLoader | RemoteLoader;
     static create(el: any, conf: any): InMemoryLoader | PartialRemoteLoader | RemoteLoader;
 }
+/** The options popup of a select: listbox semantics, one loading claim per show, a localized empty state. */
 declare class Dropdown extends ParsedElement {
     #private;
+    static attributes: string[];
     static slots: boolean;
     static template: string;
     static templates: {
@@ -356,151 +642,131 @@ declare class Dropdown extends ParsedElement {
         slots: any;
     }): void;
     acceptSelection(): void;
-    update(values: any): void;
+    update(values: any, keys?: any[]): void;
     hide(): void;
     get shown(): boolean;
-    show(loader: any): Promise<void>;
-    moveOrShow(forward: any, loader: any): Promise<void>;
+    show(loader: any, keys?: any[]): Promise<void>;
+    moveOrShow(forward: any, loader: any, keys?: any[]): Promise<void>;
+    jump(first: any): void;
+    page(forward: any): void;
 }
-declare class Select extends ParsedElement {
+/** A combobox acting like a select over a loader's vocabulary, single or multiple. */
+declare class Select extends Field {
     #private;
+    static attributes: string[];
     static observed: string[];
     static slots: boolean;
     static template: string;
     static templates: {
         items: string;
     };
-    static formAssociated: boolean;
-    internals: ElementInternals;
-    constructor();
-    render({ slots, observed, disabled }: {
-        disabled: any;
-        observed: any;
+    _build({ slots }: {
         slots: any;
-    }): Promise<void>;
+    }): {
+        fragment: any;
+        control: any;
+        error: any;
+        label: any;
+    };
+    /** Hands the loader to the callback, for runtime reconfigurations. */
     withLoader(fn: any): Promise<any>;
+    /**
+     * Drops whatever the loader is holding and asks it about the current selection
+     * again, which is what a select whose vocabulary depends on another control
+     * needs when that control changes. A key the loader no longer knows is dropped
+     * from the selection, so a value invalidated by the change does not survive it,
+     * and one it still knows keeps its place with a fresh label.
+     *
+     * Pass a url first where the vocabulary lives at a different address:
+     *
+     *     citta.addEventListener('change', async () => {
+     *         await cap.withLoader((l) => l.reconfigureUrl(`/api/cap?citta=${citta.value}`));
+     *         await cap.reload();
+     *     });
+     */
+    reload(): Promise<void>;
     set value(vs: any);
     get value(): any;
-    get entry(): [any, any][] | [any, any];
-    get disabled(): boolean;
-    set disabled(d: boolean);
-    get readonly(): any;
-    set readonly(v: any);
-    get required(): boolean;
-    set required(d: boolean);
-    get itemlist(): any;
-    set itemlist(v: any);
-    focus(options: any): void;
-    setCustomValidity(error: any): void;
+    /** The selection as {key, label, metadata} entries, the change detail's vocabulary: the only one for a single select, every one when multiple. */
+    get entry(): any;
+    get multiple(): any;
+    set multiple(v: any);
+    get itemList(): any;
+    set itemList(v: any);
 }
-declare class RadioGroup extends ParsedElement {
+/** A group of radios declared as ful-radio children, a fieldset carrying the group semantics. */
+declare class RadioGroup extends Field {
     #private;
-    internals: ElementInternals;
-    static observed: string[];
+    static attributes: string[];
     static slots: boolean;
+    static ROLE: string;
     static template: string;
-    static formAssociated: boolean;
-    constructor();
-    render({ slots, observed, disabled }: {
-        disabled: any;
-        observed: any;
+    /**
+     * @param {{slots: any}} conf
+     * @returns {any}
+     */
+    _build({ slots }: {
         slots: any;
-    }): void;
+    }): any;
     get value(): string | boolean | null;
     set value(value: string | boolean | null);
-    get readonly(): any;
-    set readonly(v: any);
-    get disabled(): boolean;
-    set disabled(d: boolean);
-    get required(): boolean;
-    set required(d: boolean);
-    focus(options: any): void;
-    setCustomValidity(error: any): void;
 }
-declare class Checkbox extends ParsedElement {
+/** A checkbox, or a switch under the type=switch claim. */
+declare class Checkbox extends Field {
     #private;
-    internals: ElementInternals;
+    static attributes: string[];
     static observed: string[];
     static slots: boolean;
     static template: string;
-    static formAssociated: boolean;
-    constructor();
-    render({ slots, observed, disabled }: {
-        disabled: any;
-        observed: any;
+    _build({ slots }: {
         slots: any;
-    }): void;
+    }): {
+        fragment: any;
+        control: any;
+        error: any;
+        label: any;
+        freeze: any;
+    };
     get value(): any;
     set value(value: any);
-    get readonly(): any;
-    set readonly(v: any);
-    get disabled(): boolean;
-    set disabled(d: boolean);
-    get required(): boolean;
-    set required(d: boolean);
-    focus(options: any): void;
-    setCustomValidity(error: any): void;
-}
-declare class Spinner extends ParsedElement {
-    static slots: boolean;
-    static template: string;
-    render({ slots }: {
-        slots: any;
-    }): void;
 }
+/** The sort control of a table header: focusable, keyboard-activated, walking asc, desc, unsorted. */
 declare class SortButton extends ParsedElement {
     #private;
+    static attributes: string[];
     static observed: string[];
-    render({ observed }: {
-        observed: any;
-    }): void;
+    render(): void;
     get order(): any;
     set order(value: any);
 }
+/** The pager: a window of page links around the current one, and the reload control. */
 declare class Pagination extends ParsedElement {
     #private;
     static observed: string[];
-    static l10n: {
-        en: {
-            showing: string;
-            navigation: string;
-            previous: string;
-            next: string;
-        };
-        it: {
-            showing: string;
-            navigation: string;
-            previous: string;
-            next: string;
-        };
-        es: {
-            showing: string;
-            navigation: string;
-            previous: string;
-            next: string;
-        };
-        fr: {
-            showing: string;
-            navigation: string;
-            previous: string;
-            next: string;
-        };
-    };
+    static attributes: string[];
     static config: {
         prevIcon: string;
         nextIcon: string;
         reloadIcon: string;
     };
     static template: string;
-    render({ observed }: {
-        observed: any;
+    render(): void;
+    /**
+     * Moves the pager to a page, a page count, or both, and repaints once. The
+     * two are one state: writing them one at a time repainted the bar twice per
+     * load, the first pass drawing the new page against the old count.
+     * @param {{ current?: number|null, total?: number|null }} [state]
+     */
+    update({ current: toCurrent, total: toTotal }?: {
+        current?: number | null;
+        total?: number | null;
     }): void;
-    update(current: any, total: any): void;
     get total(): number;
     set total(value: number);
     get current(): number;
     set current(value: number);
 }
+/** Reads the schema declaration into the header and row templates a table renders from. */
 declare class TableSchemaParser {
     static parse(nodeOrFragment: any, template: any): {
         headersTemplate: any;
@@ -512,31 +778,47 @@ declare class TableSchemaParser {
         length: number;
     };
 }
+/** Serves a table's rows from an array held in memory, applying the sort and the paging itself. */
+declare class InMemoryTableLoader {
+    #private;
+    constructor(data: any);
+    load(pageRequest: any, sortRequest: any, filterRequest: any): Promise<{
+        data: any;
+        size: any;
+    }>;
+    update(data: any): void;
+}
+/** Requests one page of rows from a url, passing the page, the sort and the filters to the endpoint. */
+declare class RemoteTableLoader {
+    #private;
+    constructor(http: any, url: any, method: any, responseMapper?: (response: any) => any);
+    load(pageRequest: any, sortRequest: any, filterRequest: any): Promise<any>;
+}
+/**
+ * Builds the table's loader from its attributes: an in-memory one, or the
+ * remote loader over src.
+ *
+ * A component registered under the `loader` attribute replaces this one and
+ * must implement `load(pageRequest, sortRequest, filterRequest)`, answering
+ * `{ data, page, size }` for the requested page. `pageRequest` carries the page
+ * index and its size, `sortRequest` the column and direction, and
+ * `filterRequest` the values of the filters in the slot.
+ */
+declare class TableLoader {
+    static create(el: any, conf: any): InMemoryTableLoader | RemoteTableLoader;
+}
+/** A table loading its rows from a loader, with sorting, pagination and an optional filter form. */
 declare class Table extends ParsedElement {
     #private;
+    static attributes: string[];
+    /**
+     * The page size stays live: a rows-per-page control is a normal thing to
+     * put next to a table, and the size is the one piece of the request an
+     * author changes after the table is up. The rest of the request is the
+     * table's own state, moved by the pager, the sorters and the filter form.
+     */
+    static observed: string[];
     static slots: boolean;
-    static l10n: {
-        en: {
-            initial: string;
-            error: string;
-            nodata: string;
-        };
-        it: {
-            initial: string;
-            error: string;
-            nodata: string;
-        };
-        es: {
-            initial: string;
-            error: string;
-            nodata: string;
-        };
-        fr: {
-            initial: string;
-            error: string;
-            nodata: string;
-        };
-    };
     static config: {
         searchIcon: string;
     };
@@ -544,54 +826,321 @@ declare class Table extends ParsedElement {
     static templates: {
         row: string;
     };
-    render({ slots, observed }: {
-        observed: any;
+    /** How many rows a page asks the loader for: the size the next load will carry. */
+    get pageSize(): number;
+    /**
+     * Changes the page size and reloads from the first page, the current index
+     * meaning nothing under a new size. A table that has not loaded yet only
+     * records it: writing the size is not a request to start loading, which is
+     * what `autoload` and `reload()` are for.
+     *
+     * Absent or null is the default of ten, so removing the attribute restores
+     * it rather than asking the loader for NaN rows.
+     */
+    set pageSize(value: number);
+    render({ slots }: {
         slots: any;
     }): Promise<void>;
     reload(): Promise<void>;
     load(pageRequest: any, sortRequest: any, filterRequest: any): Promise<void>;
+    /** Hands the loader to the callback, for runtime reconfigurations. */
     withLoader(fn: any): Promise<any>;
     resetWithFilter(filterRequest: any): Promise<void>;
 }
-declare class InstantFilter extends Input {
-    #private;
+/**
+ * The shared shape of every operator-and-operands filter: an operator menu, one
+ * or two operands of the type the subclass declares, and a tuple that mirrors
+ * the data-jpa compare annotations.
+ */
+declare class CompareFilter extends Input {
     static observed: string[];
+    static OPERATORS: string[];
+    static DEFAULT_OPERATOR: string;
     static template: string;
-    render(conf: any): void;
-    get value(): any[] | undefined;
-    set value(v: any[] | undefined);
-    get readonly(): any;
-    set readonly(v: any);
+    _operator: any;
+    _container: any;
+    _value1: any;
+    _value2: any;
+    _build(conf: any): {
+        fragment: any;
+        control: any;
+        error: any;
+        label: any;
+        freeze: any;
+        also: any[];
+    };
+    _showDefaultOperator(): void;
+    formResetCallback(): void;
+    _type(): string;
+    _serialize(v: any): any;
+    _deserialize(v: any): any;
+    _defaultOperator(): string;
+    _vocabulary(): string[];
+    _declaredOperators: any;
+    get operators(): any;
+    set operators(declared: any);
+    get value(): any[] | null;
+    set value(v: any[] | null);
+    _tuple(): any[] | null;
+    _applyTuple(v: any): void;
+    _showOperator(operator: any): void;
+    /** only a BETWEEN carries a second operand */
+    _syncBetween(): void;
     get disabled(): boolean;
     set disabled(d: boolean);
+    /** every menu button the filter composes, so one claim reaches them all */
+    _choices(): any[];
 }
-declare class LocalDateFilter extends Input {
-    #private;
+/** The compare filter over ISO instants, defaulting to LTE. */
+declare class InstantFilter extends CompareFilter {
+    _defaultOperator(): string;
+    _type(): string;
+    _serialize(v: any): string | null;
+    _deserialize(v: any): string;
+}
+/** The compare filter over dates. */
+declare class LocalDateFilter extends CompareFilter {
+    _type(): string;
+}
+/** The compare filter over numbers. */
+declare class NumberFilter extends CompareFilter {
+    _type(): string;
+}
+/** The compare filter over text, carrying a case sensitivity beside the operator. */
+declare class TextFilter extends CompareFilter {
     static observed: string[];
     static template: string;
-    render(conf: any): void;
-    get value(): any[] | undefined;
-    set value(v: any[] | undefined);
-    get readonly(): any;
-    set readonly(v: any);
+    _defaultOperator(): string;
+    _vocabulary(): string[];
+    _sensitivityButton: any;
+    _build(conf: any): {
+        fragment: any;
+        control: any;
+        error: any;
+        label: any;
+        freeze: any;
+        also: any[];
+    };
+    _choices(): any[];
+    get _sensitivity(): any;
+    _declaredSensitivities: any;
+    get sensitivities(): any;
+    set sensitivities(declared: any);
+    get value(): any[] | null;
+    set value(v: any[] | null);
+    formResetCallback(): void;
+}
+/** The boolean filter: an EQ or NEQ operator and an any/yes/no menu. */
+declare class BooleanFilter extends Field {
+    static observed: string[];
+    static slots: boolean;
+    static OPERATORS: string[];
+    static DEFAULT_OPERATOR: string;
+    static template: string;
+    _operator: any;
+    _value: any;
+    _container: any;
+    _build({ slots }: {
+        slots: any;
+    }): {
+        fragment: any;
+        control: any;
+        error: any;
+        label: any;
+        announces: null;
+        freeze: any;
+    };
+    _declaredOperators: any;
+    get operators(): any;
+    set operators(declared: any);
+    _vocabulary(): string[];
+    get value(): any[] | null;
+    set value(v: any[] | null);
     get disabled(): boolean;
     set disabled(d: boolean);
 }
-declare class TextFilter extends Input {
+/** An info icon button toggling a popover with a short explanation. */
+declare class Tooltip extends ParsedElement {
+    static slots: boolean;
+    static attributes: string[];
+    static config: {
+        icon: string;
+    };
+    static template: string;
+    render({ slots }: {
+        slots: any;
+    }): void;
+}
+/** A modal dialog on the native platform, open()/ask() resolving with the closer's data-result. */
+declare class Dialog extends ParsedElement {
+    #private;
+    static attributes: string[];
+    static slots: boolean;
+    static template: string;
+    render({ slots }: {
+        slots: any;
+    }): void;
+    disconnectedCallback(): void;
+    open(): Promise<any>;
+    ask(): Promise<any>;
+    /**
+     * Re-fires section:requested on the body, open or closed: the explicit
+     * request for a body that wants refreshing. A failed refresh paints its
+     * problems, nothing rejects: there is no caller to reject towards.
+     */
+    refresh(): Promise<any[] | undefined>;
+    close(result: any): void;
+}
+/** A side panel drawer on the native dialog platform, update() owning its open-deliver cycle. */
+declare class Drawer extends ParsedElement {
+    #private;
+    static attributes: string[];
+    static slots: boolean;
+    static template: string;
+    render({ slots }: {
+        slots: any;
+    }): void;
+    get title(): any;
+    set title(v: any);
+    /**
+     * Opens the drawer under the given title and waits for the callback: a
+     * resolved value paints the content section (which is returned), a
+     * rejection paints the problems and travels to the caller, and an update
+     * superseded by a newer one paints nothing.
+     */
+    update(title: any, cb: any): Promise<any>;
+    /**
+     * Re-fires section:requested on the content, open or closed: the explicit
+     * request for a body that wants refreshing. A failed refresh paints its
+     * problems, nothing rejects: update() stays the rejecting call.
+     */
+    refresh(): Promise<any[] | undefined>;
+    open(): void;
+    close(): void;
+}
+/** A transient feedback region: each show() stacks a toast that retires on its own timer. */
+declare class Toasts extends ParsedElement {
+    #private;
+    static attributes: string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    render(): void;
+    /**
+     * Appends a toast carrying the message (a Failure shows its problems'
+     * reasons, one per line), severity picking the theme and the announcement,
+     * the toast retiring through its own timer or its dismiss button.
+     * @param {any} message
+     * @param {any} [options] severity and timeout
+     * @returns {HTMLElement}
+     */
+    show(message: any, options?: any): HTMLElement;
+}
+/**
+ * A tab panel: one visible panel at a time, announced through the tab pattern
+ * (a tablist of tab buttons, each panel a tabpanel named by its tab). The tabs
+ * are declared as <tab> elements in the tabs slot, the panels as the slotless
+ * children, paired in order. Entering a panel fires the section:requested
+ * family on it (generic and #index, panels being nameless) and awaits the
+ * answers, so a panel can deliver itself asynchronously.
+ */
+declare class Tabs extends ParsedElement {
     #private;
+    static slots: boolean;
     static observed: string[];
     static template: string;
-    render(conf: any): void;
-    get value(): any[] | undefined;
-    set value(v: any[] | undefined);
+    render({ slots }: {
+        slots: any;
+    }): void;
+    get active(): number;
+    /**
+     * Re-fires the section:requested family on the panel (by index or the
+     * panel element itself), whether active or not: the explicit request for a
+     * content that wants refreshing. A failed refresh paints its problems,
+     * nothing rejects: there is no caller to reject towards.
+     */
+    refresh(ref: any): Promise<any[] | undefined> | undefined;
+    set active(v: number);
 }
-declare class LocalizationModule {
-    static t(k: any, ...args: any[]): any;
-    static tl(k: any, args?: any[]): any;
+/**
+ * An accordion over native details/summary disclosures: the platform carries
+ * the semantics, the keyboard and the toggling, the chrome paints the group.
+ * With the exclusive claim the render assigns one shared name to every panel,
+ * which is the platform's own exclusive grouping: opening one closes the others.
+ */
+declare class Accordion extends ParsedElement {
+    #private;
+    static slots: boolean;
+    static observed: string[];
+    static template: string;
+    render({ slots }: {
+        slots: any;
+    }): void;
+    get exclusive(): boolean;
+    set exclusive(v: boolean);
+}
+/**
+ * A wizard: a progress of steps over one-of-N sections, the homeinsurance
+ * layout distilled. The steps are declared as <step> elements in the steps
+ * slot, the sections as the slotless children, paired in order; each section
+ * may carry a data-step name, which is what move() answers to. The current
+ * step is the aria-current=step claim, carried in lockstep by the step and
+ * its section: the chrome (including which section is shown) follows the
+ * claim alone, so the markup state and the style can never disagree. The
+ * progress chrome shows the current step alone by default; the progress
+ * attribute picks another shape over the same claims (timeline, dots, none).
+ * Entering a section
+ * fires the section:requested family on it and awaits the answers, so a
+ * section can deliver itself asynchronously; move() resolves when the entered
+ * section is painted, and rejects when its delivery fails.
+ */
+declare class Wizard extends ParsedElement {
+    #private;
+    static slots: boolean;
+    static observed: string[];
+    static template: string;
+    render({ slots }: {
+        slots: any;
+    }): void;
+    get index(): number;
+    get step(): any;
+    get progress(): any;
+    set progress(v: any);
+    next(): Promise<any[] | undefined> | undefined;
+    prev(): Promise<any[] | undefined> | undefined;
+    move(ref: any): Promise<any[] | undefined> | undefined;
+    /**
+     * Re-fires the section:requested family on the named section (or the
+     * section element itself), whether active or not: the explicit request for a
+     * content that wants refreshing. A failed refresh paints its problems,
+     * nothing rejects: move() stays the rejecting call.
+     */
+    refresh(ref: any): Promise<any[] | undefined> | undefined;
 }
+/**
+ * Registers everything ful provides on a registry: the elements, the loader
+ * components, an http client, and the translations for the configured
+ * language. A page calls `registry.plugin(new Plugin({…})).configure()` once.
+ */
 declare class Plugin {
+    #private;
+    /**
+     * @param {{ language?: string, translations?: Record<string, any>, httpClient?: any }} [options]
+     * `language` is fixed for the page: a full BCP-47 tag or a primary subtag,
+     * defaulting to the browser's language. `translations` is a flat
+     * active-language map applied over the built-in translations: reword built-in
+     * keys ('pagination.showing', …) or add your own ('checkout.total', …).
+     * `httpClient` is the client every ful component fetches through, registered
+     * as the `http-client` component: where an unauthorized session goes is an
+     * application decision, so a page that does not want the default's redirect
+     * to '/' builds its own.
+     */
+    constructor(options?: {
+        language?: string;
+        translations?: Record<string, any>;
+        httpClient?: any;
+    });
     configure(registry: any): void;
 }
-export { AsyncEvents, Bindings, Checkbox, Dropdown, Form, FormLoader, Input, InputFile, InputInstant, InputLocalDate, InputLocalTime, Instant, InstantFilter, LocalDate, LocalDateFilter, LocalStorage, LocalizationModule, Pagination, Plugin, RadioGroup, Select, SelectLoader, SessionStorage, SortButton, Spinner, Table, TableSchemaParser, TextFilter, Timing, VersionedLocalStorage, VersionedSessionStorage };
+export { Accordion, AsyncEvents, Bindings, BooleanFilter, Checkbox, Claims, CompareFilter, Dialog, Drawer, Dropdown, Field, Form, FormLoader, Input, InputFile, InputInstant, InputLocalDate, InputLocalTime, Instant, InstantFilter, LocalDate, LocalDateFilter, LocalStorage, NumberFilter, Pagination, Plugin, RadioGroup, Select, SelectLoader, SessionStorage, SortButton, Table, TableLoader, TableSchemaParser, Tabs, TextFilter, Timing, Toasts, Tooltip, VersionedLocalStorage, VersionedSessionStorage, Wizard };
 
 export as namespace ful;