@react-x11/components 0.12.0 → 0.14.0

package/dist/html/form.d.ts

@@ -0,0 +1,200 @@
+import type { AnyNode, Element } from 'domhandler';
+export type FormMethod = 'get' | 'post';
+export type FormEnctype = 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
+/** A form, submitted: everything a host needs to make the request. */
+export interface FormSubmission {
+    /** The `<form>`. */
+    form: Element;
+    /**
+     * The button that submitted it — a submit `<button>`, an `<input
+     * type=submit>` or an `<input type=image>` — or null for Enter in a form
+     * that has none.
+     */
+    submitter: Element | null;
+    method: FormMethod;
+    /**
+     * Where the request goes: the action, resolved against the document's
+     * base, and for a GET with the entries as its query — so a GET is a link
+     * to exactly this.
+     */
+    url: string;
+    enctype: FormEnctype;
+    /** The name–value pairs the form carries, in tree order, unencoded. A
+     *  file field's value is the name of its file: always empty here. */
+    entries: [name: string, value: string][];
+    /** A POST's body, encoded as `enctype` says; null for a GET. */
+    body: string | null;
+    /** The `Content-Type` a POST's body goes with — `multipart/form-data`'s
+     *  names its boundary; null for a GET. */
+    contentType: string | null;
+    /**
+     * The browsing context it asked for: `formtarget` on the button, `target`
+     * on the form, or `<base target>`. `'_blank'` is a new one; empty is the
+     * one the document is in.
+     */
+    target: string;
+}
+/** Where a submission's relative URLs resolve, and the document it leaves. */
+export interface SubmitContext {
+    /** What the document's relative URLs resolve against: its `<base href>`,
+     *  or the URL it came from. */
+    base: string | null;
+    /** The URL the document came from — an empty `action` is it (HTML
+     *  4.10.21.3, step 11), not its base. Defaults to `base`. */
+    documentUrl?: string | null;
+    /** What a text control holds now, where that is not what its markup
+     *  says: typed text. `undefined` is "what the markup says". */
+    live?: (el: Element) => string | undefined;
+    /** Where an `<input type=image>` submitter was pressed, in CSS pixels
+     *  from its top left. */
+    point?: {
+        x: number;
+        y: number;
+    };
+    /** `multipart/form-data`'s boundary. Made up when absent; a test pins it. */
+    boundary?: string;
+}
+/** An `<input>`'s type state: its `type`, lowercased, or `text` where it
+ *  names none HTML knows. */
+export declare function inputType(el: Element): string;
+/**
+ * What pressing a control does: submits its form, resets it, nothing
+ * (`'button'`) — or null for something that is not a button at all. A
+ * `<button>` with no `type`, or one HTML does not know, submits.
+ */
+export declare function buttonType(el: Element): 'submit' | 'reset' | 'button' | null;
+/** The top of the tree an element is in: its document. */
+export declare function rootOf(el: AnyNode): AnyNode;
+/**
+ * The form a control belongs to (HTML 4.10.17.3): the one its `form`
+ * attribute names by id, or else the nearest `<form>` around it. A `form`
+ * attribute that names nothing, or names something that is not a form,
+ * leaves it with none — it does not fall back to the form around it.
+ */
+export declare function formOwner(el: Element, root?: AnyNode): Element | null;
+/**
+ * The submittable controls a form owns, in tree order — those inside it and
+ * those elsewhere that name it with `form`. Not those in a `<template>`,
+ * whose content is inert, or a `<datalist>`, whose are its suggestions.
+ */
+export declare function controlsOf(form: Element): Element[];
+/**
+ * Whether a control is disabled (HTML 4.10.18.5): by its own `disabled`, or
+ * by a disabled `<fieldset>` around it — except inside that fieldset's first
+ * `<legend>`, which stays live, so a checkbox there can switch the rest on.
+ */
+export declare function isDisabled(el: Element): boolean;
+/** A `<select>`'s `<option>`s, in tree order, through its `<optgroup>`s. */
+export declare function optionElements(select: Element): Element[];
+/** An option's text, its white space collapsed, as HTML's `text` IDL
+ *  attribute reads it. */
+export declare function optionLabel(option: Element): string;
+/** An option's value: its `value`, or else its text. */
+export declare function optionValue(option: Element): string;
+/** Whether a `<select>` is a list box that takes many options. */
+export declare function isMultiple(select: Element): boolean;
+/**
+ * The options a `<select>` has selected. A drop-down one has exactly one
+ * where it has any: the last marked `selected`, as the parser leaves it, or
+ * else the first that is not disabled (HTML 4.10.7, "selectedness setting").
+ * A `multiple` one has those marked, and no default.
+ */
+export declare function selectedOptions(select: Element): Element[];
+/** A `<textarea>`'s text as its markup has it — HTML drops one newline
+ *  straight after the open tag, so a pretty-printed one does not start on
+ *  a blank line. */
+export declare function textareaDefault(el: Element): string;
+/**
+ * What a text control holds: typed text where there is some, and else its
+ * markup's — a `<textarea>`'s content, an `<input>`'s `value` — put through
+ * the type's value sanitization (HTML 4.10.5.1): a single-line field holds no
+ * line breaks, an email or a URL no white space at its ends, and a number
+ * field nothing that is not a number.
+ */
+export declare function controlValue(el: Element, live?: (el: Element) => string | undefined): string;
+/** The entries as `application/x-www-form-urlencoded`: a query string, and
+ *  a POST body of that type. */
+export declare function urlencoded(entries: readonly [string, string][]): string;
+/** The entries as `text/plain`: a line each, `name=value`, unescaped. */
+export declare function plainText(entries: readonly [string, string][]): string;
+/**
+ * A form's submission by `submitter` (HTML 4.10.21.3): its entries, and the
+ * request they make. The button's `formaction`, `formmethod`, `formenctype`
+ * and `formtarget` win over the form's own. Null for `method="dialog"`,
+ * which closes a dialog rather than submitting anything, and for a
+ * submitter the form does not own.
+ */
+export declare function formSubmission(form: Element, submitter: Element | null, context: SubmitContext): FormSubmission | null;
+/**
+ * What Enter in a field submits (HTML 4.10.21.2, "implicit submission"): its
+ * form, by the form's default button — the first submit button it owns —
+ * or, where it has none, by no button at all, so long as the form has at
+ * most one field of the kinds that would make Enter ambiguous. Null where
+ * Enter submits nothing: no form, a disabled default button, or a form of
+ * several fields and no button.
+ */
+export declare function implicitSubmission(field: Element): {
+    form: Element;
+    submitter: Element | null;
+} | null;
+/**
+ * The control a `<label>` is for (HTML 4.10.4): the one its `for` names by
+ * id, where that is one a label can label, or else the first such control
+ * inside it. A press on the label is a press on that control.
+ */
+export declare function labeledControl(label: Element): Element | null;
+/**
+ * What is wrong with a control's value, in the words a browser uses, or
+ * null where nothing is: the constraints a static document can state —
+ * `required`, `minlength` and `maxlength`, `pattern`, `min` and `max`, and
+ * an email, a URL or a number that is not one (HTML 4.10.20). A length is
+ * checked only once the value has been typed, as HTML checks it; a
+ * document's own value is the author's to get right.
+ */
+export declare function validationMessage(el: Element, live?: (el: Element) => string | undefined): string | null;
+/**
+ * The first control a submission would be refused over, and why — HTML's
+ * interactive validation (4.10.21.3), which a form's `novalidate` or its
+ * submitter's `formnovalidate` turns off. Null where the form may go.
+ */
+export declare function firstInvalid(form: Element, submitter: Element | null, live?: (el: Element) => string | undefined): {
+    element: Element;
+    message: string;
+} | null;
+/**
+ * What a document's controls hold that its markup does not, and what their
+ * markup said before. One per `<Html>`, keyed by element, so a re-parse —
+ * new elements — starts clean.
+ *
+ * Typed text lives here rather than in the DOM because HTML's `value`
+ * attribute is the field's *default*: it is what a reset puts back, and
+ * what a `<textarea>` has is its content, which is not an attribute at all.
+ * A checkbox, a radio and a `<select>` do keep what they hold in the DOM —
+ * `checked` and `selected` — because `:checked` is a selector documents
+ * really use and it reads those; so for them this keeps the markup's
+ * attributes, from before the first change, for a reset.
+ */
+export declare class FormState {
+    private _typed;
+    private _markup;
+    /** Typed text, where the field has any — the `live` a submission reads. */
+    typed(el: Element): string | undefined;
+    /** What a text control holds now: typed, or its markup's. */
+    value(el: Element): string;
+    setTyped(el: Element, text: string): void;
+    /** Keep what `el`'s markup says, before a change to its attributes. */
+    remember(el: Element): void;
+    /**
+     * Put every control `form` owns back as its markup had it (HTML 4.10.21.5,
+     * "reset"). True when anything changed — the widgets then mount again, to
+     * show it.
+     */
+    reset(form: Element): boolean;
+}
+/**
+ * The other radios in `radio`'s group (HTML 4.10.5.1.18): the inputs of type
+ * radio with the same name, in the same form — or, for one in no form, in
+ * no form either. Checking one unchecks these.
+ */
+export declare function radioGroup(radio: Element): Element[];
+//# sourceMappingURL=form.d.ts.map

package/dist/html/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/html/form.ts"],"names":[],"mappings":"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"}