@rak200/ui 0.2.19 → 0.4.0

package/README.md

@@ -29,26 +29,14 @@ npm install @rak200/ui
   import '@rak200/ui';
 </script>
 
-<ui-field>
-  <label slot="label">Amount</label>
-  <ui-input><input type="number" name="amount" /></ui-input>
-  <span slot="help">In BRL, two decimals.</span>
-</ui-field>
-
-<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-field>
-  <label slot="label">Email notifications</label>
-  <ui-switch><input type="checkbox" name="notify" checked /></ui-switch>
-</ui-field>
+<ui-input label="Amount" help="In BRL, two decimals." type="number" name="amount"></ui-input>
+
+<ui-select label="Currency" name="currency">
+  <ui-option value="brl">Real</ui-option>
+  <ui-option value="usd">Dollar</ui-option>
+</ui-select>
+
+<ui-switch label="Email notifications" name="notify" checked></ui-switch>
 
 <ui-button><ui-icon name="check"></ui-icon> Save</ui-button>
 <ui-button variant="secondary">Cancel</ui-button>
@@ -89,9 +77,10 @@ schemes rather than one.
 
 ## Status
 
-**v0.** Seventeen components — `<ui-button>`, `<ui-card>`, `<ui-field>`, `<ui-dialog>`, `<ui-input>`,
-`<ui-textarea>`, `<ui-checkbox>`, `<ui-switch>`, `<ui-select>`, `<ui-radio-group>`, `<ui-radio>`,
-`<ui-tooltip>`, `<ui-toaster>`, `<ui-toast>`, `<ui-menu>`, `<ui-table>` and `<ui-icon>` — the token layer
+**v0.** Nineteen components — `<ui-button>`, `<ui-card>`, `<ui-field>`, `<ui-dialog>`, `<ui-input>`,
+`<ui-textarea>`, `<ui-checkbox>`, `<ui-switch>`, `<ui-select>`, `<ui-option>`, `<ui-optgroup>`,
+`<ui-radio-group>`, `<ui-radio>`, `<ui-tooltip>`, `<ui-toaster>`, `<ui-toast>`, `<ui-menu>`,
+`<ui-table>` and `<ui-icon>` — the token layer
 under them, and an adopted glyph set, built to the ecosystem's full quality bar rather than
 sketched: type-checked at the strictest available setting, formatted, tested in a real browser and
 **asserted against axe** for WCAG A/AA, 100% coverage and **100% mutation score**, scanned, and

package/dist/checkbox.d.ts

@@ -2,20 +2,202 @@ import { LitElement, type CSSResult, type TemplateResult } from 'lit';
 /**
  * A boolean control, drawn from the token layer rather than replaced.
  *
- * The `<input type="checkbox">` is the host's own and stays in the light DOM; this element
- * is the box around it. {@link UiCheckbox} and {@link UiSwitch} differ in what they draw
- * and in what they announce, never in what they are made of.
+ * {@link UiCheckbox} and {@link UiSwitch} differ in what they draw and in what they
+ * announce, never in what they are made of. Both render a native `<input type="checkbox">`
+ * inside a `<label>` in this element's shadow root, so every behaviour a boolean control
+ * has stays the platform's — see the docblock on the shared styles above.
+ *
+ * **The element is the form control**, through `ElementInternals`. An `<input>` inside a
+ * shadow root has no form owner, so the value reaches a submit because this element passes
+ * it on and never because the input did.
+ *
+ * That is the entire price, and it is worth listing because it is smaller than it looks:
+ * `setFormValue`, `setValidity`, the three form lifecycle callbacks a form can no longer
+ * perform directly, and a re-dispatch of `change`, which is non-composed. **None of it is
+ * accessibility** — the role, the checked state, the tab stop and what `disabled` does to
+ * it are all still the platform's, because the control really is one.
+ *
+ * The same object pays the other half, which is a cost of the control being *in here*
+ * rather than of the form: two states a host stylesheet could no longer see. See
+ * {@link UiToggle.expose}.
  */
 declare class UiToggle extends LitElement {
+    #private;
+    static readonly formAssociated = true;
+    /**
+     * Focus is delegated, so `focus()` and `reportValidity()` reach the control.
+     *
+     * Neither is optional: the host is not a focusable element, so without this a call to
+     * either lands on something that cannot take focus and does nothing — and the second
+     * one is what the browser does on its own 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;
+        };
+        name: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        value: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        checked: {
+            type: BooleanConstructor;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        required: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        error: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    /**
+     * The short road to a label. `slot="label"` overrides it where markup is needed.
+     *
+     * 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;
+    /**
+     * The name the value is submitted under.
+     *
+     * **Reflected, and that is a requirement rather than a convenience.** A form reads a
+     * form-associated custom element's name from the content attribute, so a host who sets
+     * only the property would submit nothing at all — silently, with a value published and
+     * no entry to carry it.
+     */
+    name: string;
+    /** What a checked control submits, which the platform spells `on` by default. */
+    value: string;
+    /**
+     * Whether the control is on.
+     *
+     * **Not reflected, which is the platform's own answer rather than an omission.** A
+     * native checkbox's `checked` IDL attribute does not reflect either: the content
+     * attribute is the *default*, which is what a form reset returns to, and an attribute
+     * that followed every click would make the default whatever the user last did.
+     *
+     * A host stylesheet reaches the live state through `:state(checked)` — see
+     * {@link UiToggle.expose}, and the measurement there for why it is not `::part()`.
+     */
+    checked: boolean;
+    /** Whether the control rejects interaction. Reflected, the way the platform's is. */
+    disabled: boolean;
+    /** Whether a form is invalid while this control is off. Reflected, likewise. */
+    required: boolean;
+    /** The error message, which paints the boundary and is announced with the control. */
+    error: string;
+    /**
+     * Published after every render, and after the first one too — Lit calls this on the
+     * initial update as well, which is why there is no `firstUpdated` beside it. A second
+     * call from there would be a statement no test could distinguish from its own absence.
+     */
+    updated(): void;
+    /**
+     * Puts one internal state where a host stylesheet can select on it.
+     *
+     * **This is what replaces the attribute `checked` deliberately does not reflect**, and
+     * the alternative was measured rather than assumed: `::part(box):checked` does not
+     * match. A `::part()` may be followed by user-action pseudo-classes and not by state
+     * ones, so a host had no way at all to reach a state this element keeps in its shadow
+     * root — which would have made *not reflecting* a decision that costs the host
+     * something, rather than one that costs nothing.
+     *
+     * Only the two states with no other route are exposed. `:valid`, `:invalid` and
+     * `:disabled` already match on this element, measured, because a form-associated
+     * custom element takes part in them; `required` reflects, so `[required]` reaches it.
+     *
+     * @param state - The name, as `:state(name)` spells it.
+     */
+    protected expose(state: string, on: boolean): void;
+    /**
+     * What the inner control announces itself as, where the platform needs telling.
+     *
+     * Empty here, and the attribute is then omitted rather than written blank: an
+     * `<input type="checkbox">` already announces `checkbox`, and restating it would be
+     * this component overriding the platform with the platform. {@link UiSwitch} is the
+     * one that has something to add.
+     */
+    protected readonly controlRole: string;
+    /**
+     * The listener, as a field rather than a method, which is this repository's shape for
+     * one — `src/toast.ts` carries the same. What it delegates to is a method, so a
+     * subclass can extend the mirroring without restating the binding.
+     *
+     * **The `change` is re-dispatched rather than left to bubble**, because it does not:
+     * `change` is one of the events the platform marks non-composed, so the one the inner
+     * control fires stops at the shadow boundary and a host listening on the tag would
+     * hear nothing. `input` needs no such help — it is composed, and arrives retargeted to
+     * this element on its own.
+     */
+    protected readonly changed: (event: Event) => void;
+    /**
+     * Mirrors the platform's own state back into the properties it came from.
+     *
+     * Read off the control rather than inverted from what was there: the platform is what
+     * just changed it, and asking is the only way to stay right about a state this element
+     * did not decide.
+     */
+    protected sync(control: HTMLInputElement): void;
+    /**
+     * A form reset, which the platform calls and this element cannot see any other way.
+     *
+     * The content attribute is what it returns to, which is exactly `defaultChecked` on a
+     * native control — and it stays a usable default only because `checked` is not
+     * reflected onto it.
+     */
+    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;
+    /**
+     * The whole drawing, with the one thing the two elements disagree on passed in.
+     *
+     * **A parameter rather than an overridable hook**, and the difference is one the
+     * mutation floor found: a hook returning `false` is indistinguishable from a hook
+     * returning nothing, because `input.indeterminate` coerces `undefined` to `false` — so
+     * no test could tell the base implementation from its own absence. Passed at the call
+     * site it is a value, and `<ui-switch>` reading back an unmixed control is what checks
+     * it.
+     *
+     * The mixed state is bound rather than written onto the control after render, which is
+     * what keeps this element free of a query whose null branch nothing could reach.
+     */
+    protected template(mixed: boolean): TemplateResult;
 }
 /**
  * A checkbox, styled by the token layer rather than replaced.
  *
- * **The `<input>` is yours.** You write it, you set its attributes, and it stays in the
- * light DOM — so `name`, `checked`, `required` and `disabled` are the platform's business,
- * and it reaches a form submit because it is a native control inside a `<form>`. The same
- * shape `<ui-input>` has, for the same reason.
+ * **The control is this element's**, which RFC 0005 decided and reversed an earlier rule to
+ * do: the `<input>` and its `<label>` are rendered together in one shadow root, so `name`,
+ * `checked`, `required` and `disabled` are properties here rather than attributes a host
+ * writes on a control it supplies.
  *
  * **The indeterminate state is drawn, and that is not a feature being added.**
  * `appearance: none` takes the platform's dash away with the rest of the drawing, so a
@@ -23,19 +205,68 @@ declare class UiToggle extends LitElement {
  * rather than a missing one. The dash below is what stops that, and nothing here invites
  * a tri-state that APG says is rare.
  *
- * Composes with {@link UiField}, which finds the control through this wrapper and wires
- * the label, the help, the error and `aria-invalid` to it.
- *
  * @example
  * ```html
- * <ui-field>
- *   <label slot="label">Send a receipt</label>
- *   <ui-checkbox><input type="checkbox" name="receipt" /></ui-checkbox>
- * </ui-field>
+ * <ui-checkbox label="Send a receipt" name="receipt"></ui-checkbox>
+ * ```
+ *
+ * @example A label an attribute cannot hold.
+ * ```html
+ * <ui-checkbox name="terms">
+ *   <span slot="label">I accept the <a href="/terms">terms</a></span>
+ * </ui-checkbox>
  * ```
  */
 export declare class UiCheckbox extends UiToggle {
+    static readonly properties: {
+        indeterminate: {
+            type: BooleanConstructor;
+        };
+        label: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        name: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        value: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        checked: {
+            type: BooleanConstructor;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        required: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        error: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    /**
+     * The mixed state, which the platform stopped drawing once `appearance` was removed.
+     *
+     * It takes an attribute where the platform offers none, which is this element having
+     * become the control rather than a box around one — and it is not reflected, for the
+     * reason `checked` is not.
+     */
+    indeterminate: boolean;
     static readonly styles: CSSResult[];
+    render(): TemplateResult;
+    updated(): void;
+    /**
+     * A toggle answers the question the mixed state was asking, and the platform has
+     * already cleared it on the control — so this reads it back rather than assuming.
+     * Without it the next render would put the mixed state straight back.
+     */
+    protected sync(control: HTMLInputElement): void;
 }
 /**
  * A switch, which is a checkbox that says *on* and *off* rather than *checked*.
@@ -43,28 +274,22 @@ export declare class UiCheckbox extends UiToggle {
  * **The difference is semantic and the drawing follows it**, which is the order that
  * matters: a switch takes effect immediately and a checkbox is a value you submit, so the
  * two are not one component with two skins. `role="switch"` is what carries that to a
- * screen reader, and this element sets it on the slotted control rather than asking the
- * host to remember — forgetting it would leave a control that looks like a switch and
- * announces as a checkbox, with nothing anywhere to read. A role the host wrote is never
- * overwritten, the same way {@link UiField} never overwrites an `id` it did not generate.
+ * screen reader, and this element writes it on the control it renders — so a host has
+ * nothing to remember and nothing to forget.
  *
  * There is no native switch to delegate to: `<input type="checkbox" switch>` is
  * unsupported in the engine this suite measures, so the element is a checkbox with a role
  * and a drawing. A host who wants the mixed state wants {@link UiCheckbox} — `switch` has
- * no third value, so this element does not draw one.
+ * no third value, so this element does not draw one and offers no property for one.
  *
  * @example
  * ```html
- * <ui-field>
- *   <label slot="label">Email notifications</label>
- *   <ui-switch><input type="checkbox" name="notify" checked /></ui-switch>
- * </ui-field>
+ * <ui-switch label="Email notifications" name="notify" checked></ui-switch>
  * ```
  */
 export declare class UiSwitch extends UiToggle {
-    #private;
     static readonly styles: CSSResult[];
-    render(): TemplateResult;
+    protected readonly controlRole: string;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/checkbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkbox.d.ts","sourceRoot":"","sources":["../src/checkbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AA6IjF;;;;;;GAMG;AACH,cAAM,QAAS,SAAQ,UAAU;IACpB,MAAM,IAAI,cAAc;CAGpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACpC,gBAAyB,MAAM,EAAE,SAAS,EAAE,CA+B1C;CACL;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,QAAS,SAAQ,QAAQ;;IAClC,gBAAyB,MAAM,EAAE,SAAS,EAAE,CAuC1C;IAEO,MAAM,IAAI,cAAc;CAmBpC;AAWD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,aAAa,EAAE,UAAU,CAAC;QAC1B,WAAW,EAAE,QAAQ,CAAC;KACzB;CACJ"}
+{"version":3,"file":"checkbox.d.ts","sourceRoot":"","sources":["../src/checkbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAsB,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAqL1F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,cAAM,QAAS,SAAQ,UAAU;;IAC7B,MAAM,CAAC,QAAQ,CAAC,cAAc,QAAQ;IAEtC;;;;;;;OAOG;IACH,gBAAyB,iBAAiB;;;;;;;MAGxC;IAEF,gBAAyB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAQjC;IAEF;;;;;OAKG;IACH,KAAK,SAAM;IAEX;;;;;;;OAOG;IACH,IAAI,SAAM;IAEV,iFAAiF;IACjF,KAAK,SAAQ;IAEb;;;;;;;;;;OAUG;IACH,OAAO,UAAS;IAEhB,qFAAqF;IACrF,QAAQ,UAAS;IAEjB,gFAAgF;IAChF,QAAQ,UAAS;IAEjB,sFAAsF;IACtF,KAAK,SAAM;IAoBX;;;;OAIG;IACM,OAAO,IAAI,IAAI;IAKxB;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI;IAQlD;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAM;IAE5C;;;;;;;;;;OAUG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,GAAI,OAAO,KAAK,KAAG,IAAI,CAG/C;IAEF;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAI/C;;;;;;OAMG;IACH,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;IAEQ,MAAM,IAAI,cAAc;IAIjC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc;CAwBrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACpC,gBAAyB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAGjC;IAEF;;;;;;OAMG;IACH,aAAa,UAAS;IAEtB,gBAAyB,MAAM,EAAE,SAAS,EAAE,CA6C1C;IAEO,MAAM,IAAI,cAAc;IAIxB,OAAO,IAAI,IAAI;IAKxB;;;;OAIG;cACgB,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;CAI3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,QAAS,SAAQ,QAAQ;IAClC,gBAAyB,MAAM,EAAE,SAAS,EAAE,CAuC1C;IAEF,mBAA4B,WAAW,EAAE,MAAM,CAAY;CAC9D;AAWD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,aAAa,EAAE,UAAU,CAAC;QAC1B,WAAW,EAAE,QAAQ,CAAC;KACzB;CACJ"}