@optionfactory/fml 9.0.0-rc1 → 9.0.0-rc10

package/dist/ful.d.mts

@@ -102,6 +102,41 @@ declare class Claims {
     /** Supersedes every claim without holding a new one. */
     invalidate(): void;
 }
+export type Describable = {
+    describedBy(el: HTMLElement): boolean;
+};
+/**
+ * The protocol by which content standing inside a field becomes part of the
+ * accessible description of that field's control.
+ *
+ * A field owns its control's `aria-describedby`: it is the only thing that
+ * knows which element the description belongs on, and it already writes the
+ * entry for its own error region. Content the author slotted into the field
+ * cannot write that attribute itself without becoming a second owner of it, and
+ * it cannot be wired by the field either, because a slotted custom element
+ * renders after the field has mounted and has nothing to point at when the
+ * field looks.
+ *
+ * So the content asks, once it has something to offer. `describable(el)`
+ * answers the nearest ancestor that accepts a description, and the caller hands
+ * its element to that ancestor's `describedBy`, which answers whether it was
+ * taken. Nothing here names a field or a tooltip: the relation is expressed as
+ * a capability, so the two ends need not import each other, which matters
+ * because the library's own arrow runs from the forms to the disclosures.
+ *
+ * The lookup lives here rather than at its one call site so the protocol has a
+ * name, a place to be documented and a single definition to change.
+ */
+/**
+ * @typedef {{ describedBy(el: HTMLElement): boolean }} Describable
+ */
+/**
+ * The nearest ancestor of `el` that accepts elements into the description of
+ * whatever it considers its control, or null when nothing in the ancestry does.
+ * @param {Element} el
+ * @returns {(Element & Describable) | null}
+ */
+declare const describable: (el: Element) => (Element & Describable) | null;
 /**
  * Sleeping, debouncing and throttling. Debounce and throttle both return the
  * wrapped function together with a cancel function.
@@ -226,6 +261,34 @@ declare class Field extends ParsedElement {
     /** the role the element internals carry, 'presentation' unless the control is its own */
     static ROLE: string;
     constructor();
+    /**
+     * Adds an element to the accessible description of the field's control and
+     * answers whether the field took it.
+     *
+     * A field takes one whenever it is offered, before its own render as
+     * readily as after: content slotted into a field is a custom element of its
+     * own and may upgrade on either side of the field it stands in, which
+     * happens in both directions in practice, a tooltip beating an async select
+     * to its render while losing to a plain input. A description handed over
+     * early waits here and is written the moment the field has somewhere to
+     * write it, so the caller never has to know the order.
+     *
+     * The reference lands on the element handed over rather than on a wrapper
+     * around it: a hidden element is included in a description only where it is
+     * named directly, and content that reaches the description through a
+     * wrapper is skipped while it is hidden. A popover closed until someone
+     * opens it is exactly that, so the caller passes the popover itself.
+     *
+     * An attribute rather than `ariaDescribedByElements`: the property reflects
+     * to nothing, so the description would live in the accessibility tree alone
+     * and vanish entirely on a browser without aria element reflection.
+     *
+     * This is the field's half of the description protocol; `describable` in
+     * `ful/descriptions.mjs` is the half the content uses to find the field.
+     * @param {HTMLElement} el
+     * @returns {boolean}
+     */
+    describedBy(el: HTMLElement): boolean;
     focus(options: any): void;
     /**
      * Clears or reports one validation problem: the text lands on the field's
@@ -336,8 +399,9 @@ declare class Field extends ParsedElement {
      *   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
+     * - `described` moves the description off the control and onto another
+     *   element, the host where no single control can carry it: the error
+     *   region and anything `describedBy` is later handed both land there
      * - `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
@@ -539,6 +603,52 @@ declare class InputFile extends Input {
     get dropzone(): any;
     set dropzone(v: any);
 }
+/**
+ * CSS anchor positioning for a popover and the invoker it belongs to, with the
+ * hand-placed fallback for the platforms that do not have it.
+ */
+declare class Anchors {
+    /**
+     * Anchors a popover to its invoker.
+     *
+     * The invoker is given an `anchor-name` and the popover a `position-anchor`
+     * pointing at it, which is what a stylesheet needs to place the popover
+     * itself: the library's own menus say `top: anchor(bottom); left:
+     * anchor(left)`. **Writing that css is the caller's half of this.** Without
+     * it the popover lands wherever the user agent puts a popover, which is not
+     * beside the invoker.
+     *
+     * Where the platform has no anchor positioning the popover is placed here
+     * instead, beside the invoker whenever it opens, clamped into the viewport,
+     * following it on scroll and resize, and cleaned up on close. That placement
+     * draws the geometry the css above describes, so the two agree.
+     *
+     * @param {HTMLElement} invoker the element the popover belongs to
+     * @param {HTMLElement} popover the `[popover]` element to place
+     * @param {object} [options]
+     * @param {string} [options.prefix] prefixes the generated anchor name and id,
+     *   so the dom says which component a name belongs to
+     * @param {boolean} [options.invoke] points the invoker's `popovertarget` at
+     *   the popover, giving toggle and light dismiss with no script of your own
+     * @param {boolean} [options.expanded] keeps the invoker's `aria-expanded` in
+     *   step with the popover
+     * @param {boolean} [options.stretch] widens the popover to its invoker, which
+     *   is what a combobox dropdown wants
+     * @param {boolean} [options.handPlace] places here on every platform rather
+     *   than only as a fallback, which a popover asks for when it needs to know
+     *   where its invoker ended up: the tooltip's note points a callout at it, and
+     *   a pseudo-element cannot read an anchor outside its own containing block.
+     *   Such a popover declares no anchor placement in css, there being none to
+     *   agree with
+     */
+    static wire(invoker: HTMLElement, popover: HTMLElement, { prefix, invoke, expanded, stretch, handPlace }?: {
+        prefix?: string;
+        invoke?: boolean;
+        expanded?: boolean;
+        stretch?: boolean;
+        handPlace?: boolean;
+    }): void;
+}
 /**
  * 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
@@ -959,8 +1069,24 @@ declare class BooleanFilter extends Field {
     get disabled(): boolean;
     set disabled(d: boolean);
 }
-/** An info icon button toggling a popover with a short explanation. */
+/**
+ * An info icon button toggling a popover with a short explanation.
+ *
+ * The marker is the page's `config.icon`, and the `icon` attribute names a
+ * `ful-icon` for the tooltip that means something other than plain information:
+ * a caveat, a warning, a setting. A name the library does not paint is the
+ * page's own, declared as `ful-icon[name='...'] { mask-image: ... }`.
+ *
+ * `describes` is for the tooltip standing in a field: the note becomes part of
+ * the accessible description of that field's control, so it is announced on
+ * reaching the field rather than only on opening the marker, and the marker
+ * leaves the tab order, so a form of hinted fields costs no extra keystrokes to
+ * walk. The marker stays clickable, and stays a tab stop wherever the note was
+ * not taken, a tooltip claiming `describes` outside a field among them: the
+ * stop only goes where something else delivers the content.
+ */
 declare class Tooltip extends ParsedElement {
+    #private;
     static slots: boolean;
     static attributes: string[];
     static config: {
@@ -971,7 +1097,37 @@ declare class Tooltip extends ParsedElement {
         slots: any;
     }): void;
 }
-/** A modal dialog on the native platform, open()/ask() resolving with the closer's data-result. */
+export type DialogOutcome = {
+    dismissed: boolean;
+    result: string | null;
+    response: any;
+};
+/**
+ * A modal dialog on the native platform, open()/ask() resolving with the
+ * closer's data-result.
+ *
+ * The header carries a close button, as the drawer's does: Escape dismisses a
+ * modal on its own, but nothing says so, and a dialog whose only exit is a key
+ * you have to know about leaves a pointer with nowhere to go. It answers the way
+ * Escape does, with null.
+ *
+ * `requires-answer` is for the dialog that must be answered: the close button is not
+ * rendered and Escape is refused, so the only way out is a button that carries a
+ * result. It has to be both, a close button withheld while Escape still worked
+ * being decoration rather than a rule.
+ *
+ * The chrome is reachable by class as well as by tag, so a plain `<dialog
+ * class="ful-dialog">` written by a page gets the same look whatever its
+ * structure: the tag form matches a direct child, and `ful-dialog-header`,
+ * `ful-dialog-body` and `ful-dialog-footer` match at any depth, which is what a
+ * dialog whose content is wrapped in a form needs.
+ */
+/**
+ * How a dialog ended: `dismissed` tells a cancel from an answer, `result` carries
+ * the `data-result` of the button that closed it and `response` what a submit
+ * answered with, the one that did not happen being null.
+ * @typedef {{ dismissed: boolean, result: string|null, response: any }} DialogOutcome
+ */
 declare class Dialog extends ParsedElement {
     #private;
     static attributes: string[];
@@ -983,15 +1139,31 @@ declare class Dialog extends ParsedElement {
     disconnectedCallback(): void;
     open(): Promise<any>;
     ask(): Promise<any>;
+    /**
+     * Opens the dialog and waits for the callback, as `ful-drawer`'s does: a
+     * resolved value paints the body (which is returned), a rejection paints the
+     * problems and travels to the caller, and an update superseded by a newer one
+     * paints nothing. The title is the `header` attribute, configuration like the
+     * rest of the dialog's chrome, so what update() owns is the body alone.
+     */
+    update(cb: any): 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.
+     * problems, nothing rejects: update() stays the rejecting call.
      */
     refresh(): Promise<any[] | undefined>;
     close(result: any): void;
 }
-/** A side panel drawer on the native dialog platform, update() owning its open-deliver cycle. */
+/**
+ * A side panel drawer on the native dialog platform, update() owning its
+ * open-deliver cycle.
+ *
+ * The `header` slot is content beside the title, before it: an icon, a badge, a
+ * status. It sits outside the heading rather than in it because `update()` sets
+ * the title through `textContent`, which would take anything nested there with
+ * it.
+ */
 declare class Drawer extends ParsedElement {
     #private;
     static attributes: string[];
@@ -1141,6 +1313,6 @@ declare class Plugin {
     });
     configure(registry: any): void;
 }
-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 { Accordion, Anchors, 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, describable };
 
 export as namespace ful;