@optionfactory/fml 9.0.0-rc30 → 9.0.0-rc31

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.
@@ -2086,6 +2103,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 +2191,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;
@@ -2342,14 +2327,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);
     /**
@@ -2440,7 +2426,10 @@ 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;
@@ -3044,7 +3033,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 +3229,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 +3259,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 +3469,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 +3597,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 +3618,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 +3630,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 +3641,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 +3653,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 {