@rak200/ui 0.2.19 → 0.4.0

package/dist/select.d.ts

@@ -1,12 +1,117 @@
 import { LitElement, type CSSResult, type TemplateResult } from 'lit';
+/**
+ * What {@link UiOption} and {@link UiOptgroup} have in common, which is that they draw
+ * nothing.
+ *
+ * **A declaration rather than a control**, and the first of its kind here: every other
+ * element in this package renders something a person can see. These two exist so that the
+ * choices a host writes stay markup, while the thing the platform actually needs — real
+ * `<option>` elements inside a real `<select>` — is built from them.
+ *
+ * They announce themselves on every update, and that is the half a `MutationObserver`
+ * cannot do: `option.selected = true` is a property write, and no observer reports one.
+ * Measured on the shape this replaced, where the control simply never moved. Because these
+ * are this package's own elements the property is reactive, so the announcement is the
+ * platform's own change detection rather than a watcher over somebody else's element.
+ *
+ * **Arriving and leaving are announced from the slot rather than from a callback**, and
+ * that is measured rather than chosen: an event dispatched from `disconnectedCallback` has
+ * no path left to bubble along — the option is already out of the tree, and the removal
+ * never reached the select. A slot reports both directions, which is the thing it exists
+ * to tell you.
+ *
+ * **Each declaration carries its own slot, and that is why**: a slot reports only the
+ * nodes assigned to *it*, so `<ui-select>`'s own slot sees a choice added or removed at the
+ * top level and sees nothing at all when one moves inside an `<ui-optgroup>`. Measured, as
+ * a removal from inside a group that left the control showing a choice that was gone.
+ */
+declare class UiDeclaration extends LitElement {
+    #private;
+    static readonly styles: CSSResult;
+    updated(): void;
+    render(): TemplateResult;
+}
+/**
+ * One choice in a {@link UiSelect}.
+ *
+ * The text is what the reader sees; `value` is what a form submits. `selected` is the
+ * **default** — the choice the control starts on and returns to on reset — which is what
+ * `selected` means on a native `<option>`.
+ *
+ * @example
+ * ```html
+ * <ui-option value="brl">Real</ui-option>
+ * ```
+ */
+export declare class UiOption extends UiDeclaration {
+    static readonly properties: {
+        value: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        selected: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+    };
+    /**
+     * What a form submits when this is the choice made.
+     *
+     * A plain field rather than the `accessor` keyword, for the reason `src/button.ts`
+     * gives beside its own.
+     */
+    value: string;
+    /** Whether this is the choice the control starts on. */
+    selected: boolean;
+    /** Whether this choice can be made at all. */
+    disabled: boolean;
+}
+/**
+ * A named set of choices, which the platform draws as a heading inside the list.
+ *
+ * @example
+ * ```html
+ * <ui-optgroup label="Americas">
+ *   <ui-option value="brl">Real</ui-option>
+ * </ui-optgroup>
+ * ```
+ */
+export declare class UiOptgroup extends UiDeclaration {
+    static readonly properties: {
+        label: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+    };
+    /** The heading the platform draws above the set. */
+    label: string;
+    /** Whether every choice in the set is unavailable. */
+    disabled: boolean;
+}
 /**
  * A native `<select>`, styled by the token layer rather than replaced.
  *
- * **The `<select>` is yours.** You write it and its `<option>`s, and it stays in the light
- * DOM — the same shape {@link UiInput} has, and forced by the same constraint: an ARIA
- * relationship by IDREF does not cross a shadow boundary, so a control rendered in here
- * could not be labelled by the `<label>` beside it. It reaches a form submit because it is
- * a native control inside a `<form>`.
+ * **The `<select>` is this element's**, rendered into its shadow root with its label, its
+ * help and its message, so the IDREFs resolve in one tree scope. What a host writes is the
+ * tag, its attributes, and the choices — as {@link UiOption} and {@link UiOptgroup}.
+ *
+ * **The choices could not stay as `<option>`s**, and that is measured rather than
+ * preferred: a `<slot>` inside a `<select>` assigns the nodes and the select sees none of
+ * them. `HTMLSelectElement.options` is built from its own children, not from the flattened
+ * tree — `options.length` was `0`, `value` empty and `selectedIndex` `-1`, with two options
+ * assigned. So the choices are declarations this package owns, and the `<option>` elements
+ * the platform needs are built from them.
+ *
+ * The element joins the form itself, through `ElementInternals`: a control in a shadow root
+ * has no form owner.
  *
  * **The native element is the decision, not a shortcut.** A custom listbox is an
  * accessibility project of its own, and it would have to reimplement the platform picker
@@ -31,24 +136,125 @@ import { LitElement, type CSSResult, type TemplateResult } from 'lit';
  *
  * @example
  * ```html
- * <ui-field>
- *   <label slot="label">Currency</label>
- *   <ui-select>
- *     <select name="currency">
- *       <option value="brl">Real</option>
- *       <option value="usd">Dollar</option>
- *     </select>
- *   </ui-select>
- * </ui-field>
+ * <ui-select label="Currency" name="currency">
+ *   <ui-option value="brl">Real</ui-option>
+ *   <ui-option value="usd">Dollar</ui-option>
+ * </ui-select>
  * ```
  */
 export declare class UiSelect extends LitElement {
+    #private;
     static readonly styles: CSSResult;
+    static readonly formAssociated = true;
+    /**
+     * Focus is delegated, so `focus()` and `reportValidity()` reach the control — the host
+     * is not a focusable element, and the second is what the browser calls itself when a
+     * form with an invalid control is submitted.
+     */
+    static readonly shadowRootOptions: {
+        delegatesFocus: boolean;
+        clonable?: boolean;
+        customElementRegistry?: CustomElementRegistry | null;
+        mode: ShadowRootMode;
+        serializable?: boolean;
+        slotAssignment?: SlotAssignmentMode;
+    };
+    static readonly properties: {
+        label: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        help: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        error: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        name: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        value: {
+            type: StringConstructor;
+        };
+        required: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        multiple: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+    };
+    /**
+     * The accessible name, and the text above the control.
+     *
+     * A plain field rather than the `accessor` keyword, for the reason `src/button.ts`
+     * gives beside its own — and so for every property below.
+     */
+    label: string;
+    /** Supporting text under the control, which survives an error rather than yielding. */
+    help: string;
+    /** The message, which paints the boundary and is announced with the control. */
+    error: string;
+    /**
+     * The name the value is submitted under.
+     *
+     * **Reflected, and that is a requirement rather than a convenience.** A form names a
+     * form-associated custom element's entry from the content attribute, so a host who set
+     * only the property would submit nothing at all — silently.
+     */
+    name: string;
+    /**
+     * The choice currently made.
+     *
+     * **Empty means _the declared default_ rather than _nothing_**, which is what lets an
+     * `<ui-option selected>` mean what `<option selected>` means and a reset return to it.
+     * Not reflected, the way a native control's `value` IDL attribute is not.
+     */
+    value: string;
+    /** Whether a form is invalid while no choice is made. */
+    required: boolean;
+    /** Whether the control refuses interaction, and submits nothing. */
+    disabled: boolean;
+    /** Whether the control is a list rather than a drop-down. */
+    multiple: boolean;
+    connectedCallback(): void;
+    /**
+     * The value and the validity, which move together here or disagree anywhere.
+     *
+     * **Iterated rather than asserted**, and there is exactly one control to iterate —
+     * `render()` puts it there unconditionally. A query and a null check would put a branch
+     * here that no test could reach, which is a coverage hole and an immortal mutant at
+     * once rather than safety. `src/input.ts` carries the same shape for the same reason.
+     */
+    updated(): void;
+    /** A form reset, which returns to the choice the declarations name. */
+    formResetCallback(): void;
+    /** A `<fieldset disabled>` above this element, which reaches it and nothing below. */
+    formDisabledCallback(disabled: boolean): void;
+    /** Restoring after a back-navigation, where the browser hands the value back. */
+    formStateRestoreCallback(state: string | null): void;
+    /** The form this element participates in, for a host that needs it. */
+    get form(): HTMLFormElement | null;
+    /** Whether the control currently satisfies its constraints. */
+    get validity(): ValidityState;
+    /** The message a form would report for it, empty while the control is valid. */
+    get validationMessage(): string;
     render(): TemplateResult;
 }
 declare global {
     interface HTMLElementTagNameMap {
         'ui-select': UiSelect;
+        'ui-option': UiOption;
+        'ui-optgroup': UiOptgroup;
     }
 }
+export {};
 //# sourceMappingURL=select.d.ts.map

package/dist/select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../src/select.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAqBjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,QAAS,SAAQ,UAAU;IACpC,gBAAyB,MAAM,EAAE,SAAS,CA8FxC;IAEO,MAAM,IAAI,cAAc;CAGpC;AAQD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,WAAW,EAAE,QAAQ,CAAC;KACzB;CACJ"}
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../src/select.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAsB,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAiC1F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,cAAM,aAAc,SAAQ,UAAU;;IAClC,gBAAyB,MAAM,EAAE,SAAS,CAIxC;IAEO,OAAO,IAAI,IAAI;IAQf,MAAM,IAAI,cAAc;CAGpC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,QAAS,SAAQ,aAAa;IACvC,gBAAyB,UAAU;;;;;;;;;;;;;MAIjC;IAEF;;;;;OAKG;IACH,KAAK,SAAM;IAEX,wDAAwD;IACxD,QAAQ,UAAS;IAEjB,8CAA8C;IAC9C,QAAQ,UAAS;CACpB;AAED;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,aAAa;IACzC,gBAAyB,UAAU;;;;;;;;;MAGjC;IAEF,oDAAoD;IACpD,KAAK,SAAM;IAEX,sDAAsD;IACtD,QAAQ,UAAS;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,QAAS,SAAQ,UAAU;;IACpC,gBAAyB,MAAM,EAAE,SAAS,CA6HxC;IAEF,MAAM,CAAC,QAAQ,CAAC,cAAc,QAAQ;IAEtC;;;;OAIG;IACH,gBAAyB,iBAAiB;;;;;;;MAGxC;IAEF,gBAAyB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAajC;IAEF;;;;;OAKG;IACH,KAAK,SAAM;IAEX,uFAAuF;IACvF,IAAI,SAAM;IAEV,gFAAgF;IAChF,KAAK,SAAM;IAEX;;;;;;OAMG;IACH,IAAI,SAAM;IAEV;;;;;;OAMG;IACH,KAAK,SAAM;IAEX,yDAAyD;IACzD,QAAQ,UAAS;IAEjB,oEAAoE;IACpE,QAAQ,UAAS;IAEjB,6DAA6D;IAC7D,QAAQ,UAAS;IAQR,iBAAiB,IAAI,IAAI;IAgDlC;;;;;;;OAOG;IACM,OAAO,IAAI,IAAI;IAkBxB,uEAAuE;IACvE,iBAAiB,IAAI,IAAI;IAIzB,sFAAsF;IACtF,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAI7C,iFAAiF;IACjF,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIpD,uEAAuE;IACvE,IAAI,IAAI,IAAI,eAAe,GAAG,IAAI,CAEjC;IAED,+DAA+D;IAC/D,IAAI,QAAQ,IAAI,aAAa,CAE5B;IAED,gFAAgF;IAChF,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAgCQ,MAAM,IAAI,cAAc;CAmCpC;AAcD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,WAAW,EAAE,QAAQ,CAAC;QACtB,WAAW,EAAE,QAAQ,CAAC;QACtB,aAAa,EAAE,UAAU,CAAC;KAC7B;CACJ"}