@optionfactory/fml 9.0.0-rc30 → 9.0.0-rc32

package/dist/ful.d.mts

@@ -406,12 +406,13 @@ declare class Bindings {
  *
  * The claim setters, the validity protocol and the aria wiring all act on the
  * pieces, so a field with no native control returns a focusable piece of its
- * own chrome as the control. The claims, `value` and `focus()` are the
- * members that tolerate a not yet rendered element: before the render the
- * `value` getter answers what the rendered field would answer from its current
- * declared state, and a value written then is held and applied by the render
- * (see `_holdValue`). The other members need the pieces and so work only after
- * the render.
+ * own chrome as the control. The claims, `value`, `focus()` and
+ * `setCustomValidity` are the members that tolerate a not yet rendered
+ * element: before the render the `value` getter answers what the rendered
+ * field would answer from its current declared state, a value written then is
+ * held and applied by the render (see `_holdValue`), and a problem reported
+ * then is shown by it. The other members need the pieces and so work only
+ * after the render.
  *
  * The inner controls carry `form=""`, so the host is the only element the form
  * sees. Enter pressed in an inner `<input>` of any type but `file`, `button`,
@@ -485,7 +486,9 @@ declare class Field extends ParsedElement {
      * field owning a whole subtree overrides this to route the message to the
      * inner control the path names.
      *
-     * Needs the render: before it there is no error region to write to.
+     * Before the render there is no error region to write to: a message is
+     * kept (the last one wins) and shown once the field has rendered, and a
+     * clear drops the one kept. A field whose render failed shows nothing.
      * @param {string} [error] the message, empty or missing to clear
      * @param {string} [context] the path below this field's name, '' on an exact match
      */
@@ -608,7 +611,9 @@ declare class Field extends ParsedElement {
     /**
      * Calls `_build(conf)` and wires the pieces it answers. When `_build`
      * returns a promise the pieces are wired once it settles; a field that
-     * builds synchronously renders synchronously.
+     * builds synchronously renders synchronously. A default slot holding
+     * nothing but whitespace is emptied first, so the label it becomes is
+     * `:empty` and takes no row.
      * @param {{ slots: Record<string, DocumentFragment> | undefined }} conf
      * @returns {void | Promise<void>}
      */
@@ -1173,7 +1178,8 @@ declare class InputInstant extends Input {
  * size and count limits it declares.
  *
  * The `dropzone` and `item-list` attributes show the dropzone and the list of
- * chosen files. A `dropzone` slot replaces the default dropzone's content, and
+ * chosen files, and `no-input` takes the picker control out of sight, leaving
+ * it to the keyboard and to assistive technology. A `dropzone` slot replaces the default dropzone's content, and
  * an `items` slot holding a template replaces the stock item, rendered with the
  * same `files` overlay so that it reads the File objects it lists. Clicking the
  * dropzone opens the picker, and the host carries a `dragover` attribute while
@@ -1287,7 +1293,7 @@ declare class InputFile extends Input {
      * The size of the selected files together, in bytes.
      * @returns {number}
      */
-    get totalsize(): number;
+    get totalSize(): number;
     /**
      * The most files a selection may hold; a larger selection is cleared
      * entirely with a warning. Enforced from the next selection on.
@@ -1329,6 +1335,17 @@ declare class InputFile extends Input {
     get dropzone(): boolean;
     /** @param {boolean} v */
     set dropzone(v: boolean);
+    /**
+     * Whether the picker control is taken out of sight, the dropzone and the
+     * item list carrying the field alone; the stylesheet hides it from the
+     * reflected `no-input` attribute. The control stays in the tab order and
+     * keeps the label, the description and the error, and the dropzone shows
+     * the focus ring while it holds the focus.
+     * @returns {boolean}
+     */
+    get noInput(): boolean;
+    /** @param {boolean} v */
+    set noInput(v: boolean);
 }
 /**
  * Places a popover beside the element or the rectangle it belongs to.
@@ -2058,6 +2075,12 @@ export type TablePageResponse = {
     data: any[];
     size: number;
 };
+export type TableStatus = {
+    count: Element;
+    appending: Element;
+    failure: Element;
+    error: Element;
+};
 export type TableRowLoader = {
     load(pageRequest: TablePageRequest, sortRequest: TableSortRequest | null, filterRequest: Record<string, any>): Promise<TablePageResponse>;
 };
@@ -2073,6 +2096,10 @@ export type TableRowLoader = {
  * @typedef {{ data: any[], size: number }} TablePageResponse the rows of the
  * requested page and the total number of rows across every page
  */
+/**
+ * @typedef {{ count: Element, appending: Element, failure: Element, error: Element }} TableStatus the pieces
+ * of the status bar `paging="infinite"` and `paging="virtual"` show in place of the pager
+ */
 /**
  * @typedef {{ load(pageRequest: TablePageRequest, sortRequest: TableSortRequest|null, filterRequest: Record<string, any>): Promise<TablePageResponse> }} TableRowLoader
  */
@@ -2086,6 +2113,10 @@ export type TableRowLoader = {
  * current `order` in the cycle `asc`, `desc`, `null`. The button does not
  * change its own `order`: whoever handles the event sets it, which `ful-table`
  * does once the sorted page has loaded.
+ *
+ * The stylesheet draws an up arrow for `asc` and a down arrow for `desc`. An
+ * unsorted button shows the up arrow dimmed, `asc` being the order its first
+ * activation asks for.
  */
 declare class SortButton extends ParsedElement {
     #private;
@@ -2170,42 +2201,6 @@ declare class Pagination extends ParsedElement {
      */
     set current(value: number | null);
 }
-/** Reads the schema declaration into the header and row templates a table renders from. */
-declare class TableSchemaParser {
-    /**
-     * Builds a header `<tr>` and a row `<tr data-tpl-each="rows">` from the
-     * `<schema>` child of the slot. The `<schema>` attributes are copied onto
-     * both rows. Each `<column>` becomes a `<th>` and a `<td>` carrying the
-     * column's attributes except `title`, `sorter` and `order`, so a
-     * `data-tpl-*` on a column applies to both cells; the two templates carry
-     * `inHeaders` and `inRows` in their scope, so a column can tell them apart,
-     * as in `data-tpl-if="inRows"`. The header cell holds the `<title>` child
-     * element of the column, else the text of its `title` attribute, wrapped
-     * in a `ful-sorter` when the column declares `sorter` or `order`. The body
-     * cell holds the column's remaining children.
-     *
-     * The column elements are consumed: their `<title>`, `title`, `sorter` and
-     * `order` are removed and their children moved into the cells.
-     * @param {DocumentFragment|Element|undefined} nodeOrFragment the `schema`
-     * slot, undefined when the table has none
-     * @param {ReturnType<ParsedElement['template']>} template the template the
-     * header and row templates derive from, keeping its scope
-     * @returns {{ headersTemplate: ReturnType<ParsedElement['template']>, rowsTemplate: ReturnType<ParsedElement['template']>, sort: { sorter: string|null, order: string|null } | null, length: number }}
-     * `sort` is the initial sort, taken from the first column declaring both
-     * `order` and `sorter` (a column with only `order` gets an arrow but no
-     * initial sort), `null` when none does; `length` is the number of columns
-     * @throws {Error} when the slot is missing or holds no `<schema>`
-     */
-    static parse(nodeOrFragment: DocumentFragment | Element | undefined, template: ReturnType<ParsedElement['template']>): {
-        headersTemplate: ReturnType<ParsedElement['template']>;
-        rowsTemplate: ReturnType<ParsedElement['template']>;
-        sort: {
-            sorter: string | null;
-            order: string | null;
-        } | null;
-        length: number;
-    };
-}
 /** Serves a table's rows from an array held in memory, applying the sort and the paging itself. */
 declare class InMemoryTableLoader {
     #private;
@@ -2302,6 +2297,21 @@ declare class TableLoader {
  * for it. Without it the table shows an initial panel until `load`,
  * `reload` or `resetWithFilter` is called.
  *
+ * `paging="infinite"`, read once at the upgrade, replaces the pager with a
+ * status bar saying how many rows of how many are shown, with a reload
+ * button. A load still replaces the rows with one page, scrolling the rows
+ * back to the top; from then on, whenever a row of the last half page
+ * comes into view, the next page is asked with the same size, sort and
+ * filters and appended (see `load`). `reload`, a sort, a filter submit and a
+ * size change start over from the first page.
+ *
+ * `paging="virtual"` shows the same status bar, saying which rows of how many
+ * are in view, and keeps in the page only the page in view and one on either
+ * side of it, the others standing in as empty space sized on the height of
+ * the rows. The rows must scroll inside the table, as `ful-fill` makes them:
+ * a table whose rows the page scrolls appends as `paging="infinite"` does,
+ * and warns. See `load` and `reload`.
+ *
  * Inside the table, and not inside a `ful-table` nested in it, a
  * `page:requested` loads that page with the current size,
  * sort and filters; a `sort:requested` loads the current page with the new
@@ -2325,6 +2335,7 @@ declare class Table extends ParsedElement {
     static config: {
         searchIcon: string;
         emptyIcon: string;
+        reloadIcon: string;
     };
     static template: string;
     static templates: {
@@ -2342,14 +2353,15 @@ declare class Table extends ParsedElement {
      * writing the size is not a request to start loading, which is what
      * `autoload` and `reload()` are for. A write that does not change the size
      * does nothing. A write made before the render is replaced by the declared
-     * `page-size` when the table renders.
+     * `page-size` when the table renders, or by ten when that is not a number
+     * above zero.
      *
      * The reload is not awaited: a failure shows the error panel and its
      * rejection is unhandled.
      * @param {number|string|null|undefined} value a number or a string of
      * one, such as a select's value; absent or null is the default of ten,
      * so removing the attribute restores it, and a value that is not a
-     * number is ignored
+     * finite number above zero is ignored
      */
     set pageSize(value: number | string | null | undefined);
     /**
@@ -2414,6 +2426,14 @@ declare class Table extends ParsedElement {
      * `submit` listeners as the later ones, and the load its `submit:success`
      * starts is the one awaited. A filter submit that is cancelled, fails or
      * is dropped for one in flight loads nothing, and the promise resolves.
+     *
+     * Under `paging="virtual"`, once rows show, it asks again for the pages in
+     * the page, with the same size, sort and filters, and shows them where
+     * they are, the scroll position and the widths of the columns kept; the
+     * table is busy and settles, fails and dispatches as a load does, one
+     * `load:success` per page. When the answers report fewer rows than the
+     * window starts at, it loads the first page instead. A `src` or `method`
+     * write still starts over from the first page.
      * @returns {Promise<void>} as `load`
      */
     reload(): Promise<void>;
@@ -2440,12 +2460,49 @@ declare class Table extends ParsedElement {
      * `aria-busy` is removed, `load:failure` is dispatched (bubbling, not
      * cancelable) with `detail` set to
      * `{ pageRequest, sortRequest, filterRequest, exception }`, and the
-     * returned promise rejects with the same error.
+     * returned promise rejects with the same error. An answer the table cannot
+     * page fails the same way, with an error saying so: one whose `size` is
+     * not a number, as a response of another shape read without a
+     * `response-mapper` is, or a page size of zero.
      *
      * A load started after this one supersedes it: when this one's answer or
      * failure arrives it changes nothing, dispatches nothing and resolves;
      * superseded while its rows render, it leaves them to the newer load and
      * dispatches nothing.
+     *
+     * Under `paging="infinite"` the status bar takes the pager's place, and
+     * once the load has dispatched `load:success` the next page is awaited:
+     * when a row of the last half page comes into view, through
+     * whatever scrolls it, the following page is asked for with the same
+     * size, sort and filters and its rows are appended. An append runs
+     * without `aria-busy`, a spinner in the status bar standing in, and
+     * dispatches `load:success` or `load:failure` as a load does, its
+     * `pageRequest` naming the appended page. A failed append keeps the
+     * rows, shows the error in the status bar with a retry button and
+     * rejects to nobody, nothing awaiting it. Appending stops once the rows
+     * shown reach the total the last answer reported, or an answer carries
+     * no rows. A load supersedes an append in flight; `reload` repeats this
+     * load, not the pages appended to it.
+     *
+     * Under `paging="virtual"` the load shows its page as the window, scrolled
+     * to where it sits among the total, and measures two things on its rows:
+     * the height the empty space standing in for the other rows is sized on,
+     * and the width of the columns, which then stay as they are, in
+     * proportion, until the next load, so that the pages coming and going do
+     * not move them. From then on the window follows the scroll: the page in
+     * view and one on either side stay in the page and the others are dropped,
+     * the page holding the focus kept while it is within two pages of them. A
+     * page next to the window is asked for at once; a scroll landing farther
+     * waits for the scroll to rest. Window pages are asked for without
+     * `aria-busy`, a spinner in the status bar standing in, and dispatch
+     * `load:success` or `load:failure` per page as appends do; a failure keeps
+     * the rows and offers a retry. The row in view stays where it is as pages
+     * come and go above it: the table measures it before and after and
+     * corrects the scroll by whatever the browser's own scroll anchoring has
+     * not kept, which is all of it where the browser anchors no table rows
+     * (Firefox), has no scroll anchoring or the rows' container declares
+     * `overflow-anchor: none`, and nothing where it has. The table carries
+     * `aria-rowcount` and each row its `aria-rowindex`.
      * @param {TablePageRequest} pageRequest
      * @param {TableSortRequest|null} sortRequest
      * @param {Record<string, any>} filterRequest
@@ -3044,7 +3101,7 @@ declare class Dialog extends ParsedElement {
      * opening, hides the error and loading sections, and dispatches
      * `section:requested` on the element (bubbling, with
      * `detail: { section, first, name: null, index: null }`, `section` being
-     * the body and `first` true only on the first answered request), so a
+     * the body and `first` true until a delivery succeeds), so a
      * listener can fill the body. A failed request is painted into the body
      * and does not reject. On a dialog already open nothing is shown or
      * requested, and the call waits for the same ending as the calls before it;
@@ -3240,7 +3297,7 @@ declare class Drawer extends ParsedElement {
      * opening, hides the error and loading sections, and dispatches
      * `section:requested` on the element (bubbling, with
      * `detail: { section, first, name: null, index: null }`, `section` being
-     * the content section and `first` true only on the first answered request),
+     * the content section and `first` true until a delivery succeeds),
      * so a listener can fill the content. A failed request is painted into the
      * content section and does not reject. On a drawer already open nothing is
      * shown or requested, except that one sliding out stops and stays open,
@@ -3270,11 +3327,13 @@ declare class Drawer extends ParsedElement {
     /**
      * Slides the drawer out and closes it when the animation ends, setting the
      * `closing` attribute on the native dialog meanwhile; the `close` event is
-     * dispatched then, after this call has returned. Where the user prefers
-     * reduced motion, or no animation runs, it closes at once. A non-empty
-     * result answers as the button carrying that `data-result` would; no
-     * result, or an empty one, is a dismissal. Does nothing on a drawer that is
-     * closed or already sliding out.
+     * dispatched then, after this call has returned. An animation the page
+     * cancels, by hiding the drawer or an ancestor of it, closes it as one
+     * that ended does. Where the user prefers reduced motion, or no animation
+     * runs, it closes at once. A non-empty result answers as the button
+     * carrying that `data-result` would; no result, or an empty one, is a
+     * dismissal. Does nothing on a drawer that is closed or already sliding
+     * out.
      * @param {string} [result]
      */
     close(result?: string): void;
@@ -3478,7 +3537,7 @@ declare class Tabs extends ParsedElement {
     get active(): number;
     /**
      * Fires the section requests again for a panel, whether it is visible or
-     * not, with `first` false once an earlier request was answered.
+     * not, with `first` false once an earlier delivery succeeded.
      * @param {number | Element} ref the panel's index, or the panel itself
      * @returns {Promise<any[] | undefined> | undefined} a promise resolving to
      * the answers, or to undefined when nobody listened or the delivery
@@ -3606,7 +3665,7 @@ declare class Wizard extends ParsedElement {
     move(ref: string): Promise<any[] | undefined> | undefined;
     /**
      * Fires the section requests again for a section, whether it is current or
-     * not, with `first` false once an earlier request was answered.
+     * not, with `first` false once an earlier delivery succeeded.
      * @param {string | Element} ref the section's `data-step`, or the section
      * itself
      * @returns {Promise<any[] | undefined> | undefined} a promise resolving to
@@ -3627,8 +3686,11 @@ declare class Plugin {
     /**
      * @param {{ language?: string, translations?: Record<string, any>, httpClient?: HttpClient }} [options]
      * `language` is fixed for the page: a full BCP-47 tag or a primary subtag,
-     * defaulting to `navigator.language`, then to 'en'. Its primary subtag,
-     * lowercased, picks the built-in translations (en, it, es, fr); the messages
+     * defaulting to `navigator.language`, then to 'en', an empty one included.
+     * It is canonicalized (`IT-it` and `it_IT` both read `it-IT`), and one that
+     * is no language tag at all throws here, rather than at the first message
+     * or number formatted in it. Its primary subtag picks the built-in
+     * translations (en, it, es, fr); the messages
      * are the english ones, overridden by that language's, overridden by
      * `translations`, so a language without built-in translations reads in
      * english. `translations` is a flat map of keys to messages: reword built-in
@@ -3636,6 +3698,7 @@ declare class Plugin {
      * `httpClient` is the client every ful component fetches through, registered
      * as the `http-client` component; without one, `configure` builds a client
      * that sends the csrf token and navigates to '/' on a 401 response.
+     * @throws {RangeError} when `language` is not a language tag
      */
     constructor(options?: {
         language?: string;
@@ -3646,7 +3709,7 @@ declare class Plugin {
      * Defines on `registry` the `l10n` module, the `http-client` component,
      * every `ful-*` element, the `loaders:select`, `loaders:form` and
      * `loaders:table` components, and an overlay publishing `l10n` (the merged
-     * messages) and `locale` (the `language` as given) to every template.
+     * messages) and `locale` (the `language`, canonicalized) to every template.
      * @param {{ defineModule(name: string, module: any): any, defineComponent(name: string, component: any): any, defineElement(tag: string, klass: CustomElementConstructor): any, defineOverlay(...data: any[]): any }} registry
      * the ftl `Registry`, each of those methods answering the registry itself
      * @returns {void}
@@ -3658,7 +3721,7 @@ declare class Plugin {
         defineOverlay(...data: any[]): any;
     }): void;
 }
-export { Accordion, Anchors, AsyncEvents, Bindings, BooleanFilter, Checkbox, Claims, CompareFilter, Dialog, Drawer, Dropdown, Field, Form, FormLoader, InFilter, Input, InputFile, InputInstant, InputLocalDate, InputLocalTime, Instant, InstantFilter, LocalDate, LocalDateFilter, LocalStorage, Menu, NumberFilter, PageLeave, Pagination, Plugin, RadioGroup, Select, SelectLoader, SessionStorage, SortButton, Table, TableLoader, TableSchemaParser, Tabs, TextFilter, Timing, Toasts, Tooltip, VersionedLocalStorage, VersionedSessionStorage, Wizard, describable };
+export { Accordion, Anchors, AsyncEvents, Bindings, BooleanFilter, Checkbox, Claims, CompareFilter, Dialog, Drawer, Dropdown, Field, Form, FormLoader, InFilter, Input, InputFile, InputInstant, InputLocalDate, InputLocalTime, Instant, InstantFilter, LocalDate, LocalDateFilter, LocalStorage, Menu, NumberFilter, PageLeave, Pagination, Plugin, RadioGroup, Select, SelectLoader, SessionStorage, SortButton, Table, TableLoader, Tabs, TextFilter, Timing, Toasts, Tooltip, VersionedLocalStorage, VersionedSessionStorage, Wizard, describable };
 
 declare global {
     interface HTMLElementTagNameMap {