@rak200/ui 0.3.0 → 0.5.0

package/dist/radio.d.ts

@@ -1,101 +1,184 @@
-import { LitElement, type TemplateResult } from 'lit';
+import { LitElement, type CSSResult, type TemplateResult } from 'lit';
 /** Which way a group lays its options out, and announces that it did. */
 export type RadioOrientation = 'vertical' | 'horizontal';
 /**
- * One option's control, drawn from the token layer rather than replaced.
+ * One choice in a {@link UiRadioGroup}: a value, and the text beside it.
  *
- * **The `<input type="radio">` is yours.** You write it, you set its `name`, `value`,
- * `checked` and `disabled`, and it stays in the light DOM — the shape every control in
- * this kit 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>` around it.
- *
- * **This element carries no state and no name.** It is a drawing, and everything that
- * makes a set of radios *a group* — one tab stop, arrow keys that move and select, one
- * value out of the set — is the platform's, because they are native radios sharing a
- * `name`. Wrapping each one changes none of that: measured in this suite, a group whose
- * radios sit inside custom elements is still one group.
+ * **It draws nothing.** The group renders the real `<input type="radio">` and the
+ * `<label>` around it, because a `role="radiogroup"`, the name pointing at it and the
+ * controls it contains have to share one tree scope — `ARCHITECTURE.md`, *A relationship
+ * needs one tree scope*. So this element exists to be read rather than to be seen, the way
+ * `<ui-option>` does for `<ui-select>`.
  *
  * @example
  * ```html
- * <label>
- *   <ui-radio><input type="radio" name="plan" value="free" /></ui-radio>
- *   Free
- * </label>
+ * <ui-radio value="free">Free</ui-radio>
  * ```
  */
 export declare class UiRadio extends LitElement {
-    static readonly styles: import("lit").CSSResult;
+    #private;
+    static readonly styles: CSSResult;
+    static readonly properties: {
+        value: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        checked: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+    };
+    /** What the group submits while this choice is the one in force. */
+    value: string;
+    /** Whether this is the choice a group with no `value` starts on, and resets to. */
+    checked: boolean;
+    /** Whether this one choice refuses interaction, the rest of the set staying live. */
+    disabled: boolean;
+    /**
+     * Tells the group something changed, on every update and on every slot change.
+     *
+     * A property write is not something a `MutationObserver` reports, which is what makes a
+     * declaration this package owns different from an element a host wrote: the property is
+     * reactive here. It bubbles because the choices are the group's own light-DOM children,
+     * and it is dispatched from `updated()` rather than from `disconnectedCallback`, which
+     * has no path left to bubble along.
+     */
+    updated(): void;
     render(): TemplateResult;
 }
 /**
- * A set of radios, laid out and named as one thing.
+ * A set of choices, laid out and named as one thing.
  *
- * **It hand-rolls no roving tabindex and it brings no state machine**, and that is this
- * element's whole claim rather than a gap in it. Issue #15 asked which of the two it would
- * be, because the APG **Radio Group** pattern — one tab stop, arrow keys that move *and*
- * select, wrapping at the ends — is the first behaviour in the v0 cut that could have
- * justified Zag. Neither was needed: native radios sharing a `name` **are** that pattern,
- * and this suite measures it here rather than trusting it, wrappers and all.
+ * **It hand-rolls no roving tabindex and it brings no state machine.** Native radios
+ * sharing a `name` **are** the APG **Radio Group** pattern — one tab stop, arrow keys that
+ * move *and* select, wrapping at the ends, and left/right swapped under `dir="rtl"` — and
+ * that holds inside a shadow root, where the group is scoped by its tree because the
+ * controls have no form owner. `tests/radio.test.ts` measures it rather than trusting it.
+ * `ARCHITECTURE.md`, *Behaviour is delegated*, carries why no machine arrived.
  *
- * That is the test `ROADMAP.md` states, applied: Zag arrives where the platform has **no
- * element** for the pattern, not merely where the pattern has state. `ui-menu` is where
- * that question is open; a radio group is not.
- *
- * **What is left for this element is what the platform leaves out**: the layout, the
- * `role` that makes a set of radios a group to a screen reader, and the group-level name,
- * description and error state — which {@link UiField} wires onto *this* element rather
- * than onto an option, because a `<label for>` naming one radio names one option and
- * leaves the group anonymous.
+ * **What it owns is what the platform leaves out**: the drawing, the layout, the group's
+ * own name, help and message, and form participation through `ElementInternals` — a
+ * control in a shadow root has no form owner, so the element answers for the value, the
+ * validity and the three form lifecycle callbacks.
  *
  * @example
  * ```html
- * <ui-field>
- *   <label slot="label">Plan</label>
- *   <ui-radio-group>
- *     <label><ui-radio><input type="radio" name="plan" value="free" /></ui-radio> Free</label>
- *     <label><ui-radio><input type="radio" name="plan" value="pro" /></ui-radio> Pro</label>
- *   </ui-radio-group>
- * </ui-field>
+ * <ui-radio-group label="Plan" name="plan" help="Change it any time.">
+ *   <ui-radio value="free">Free</ui-radio>
+ *   <ui-radio value="pro" checked>Pro</ui-radio>
+ * </ui-radio-group>
  * ```
  */
 export declare class UiRadioGroup extends LitElement {
-    static readonly styles: import("lit").CSSResult;
+    #private;
+    static readonly styles: CSSResult;
+    static readonly formAssociated = true;
+    /**
+     * Focus is delegated, so `focus()` and `reportValidity()` reach a control — the host is
+     * not a focusable element. Measured with the group: the delegation lands on the first
+     * option rather than making all of them tab stops, because the roving one is still the
+     * platform's.
+     */
+    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;
+        };
         orientation: {
             type: StringConstructor;
             reflect: boolean;
         };
+        required: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
     };
     /**
-     * Which way the options are laid out.
+     * The accessible name, and the text above the set.
      *
      * A plain field rather than the `accessor` keyword, for the reason `src/button.ts`
-     * gives beside its own: the browser this suite runs in does not implement
-     * auto-accessors, and the module would fail to parse.
+     * gives beside its own — and so for every property below.
      */
-    orientation: RadioOrientation;
+    label: string;
+    /** Supporting text under the set, which survives an error rather than yielding. */
+    help: string;
+    /** The message, which paints the boundaries and is announced with the group. */
+    error: string;
     /**
-     * Marks the element a group before anything asks what it is.
+     * The name the value is submitted under.
      *
-     * In `connectedCallback` rather than at first render, and the timing is the point:
-     * {@link UiField} reads this attribute to decide that the group — and not the first
-     * radio inside it — is the thing to name, and it does so on its own first update,
-     * which lands before this element's. Set a microtask later, the role would arrive
-     * after the only reader that needs it.
+     * **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.
      *
-     * A `role` the host wrote is never overwritten, the same courtesy {@link UiField}
-     * extends to an `id` it finds already there.
+     * **Empty means _the declared default_ rather than _nothing_**, which is what lets a
+     * `<ui-radio checked>` mean what `<input checked>` means and a reset return to it.
+     * Not reflected, the way a native control's `checked` IDL attribute is not.
      */
+    value: string;
+    /** Which way the options are laid out, and what the group announces it did. */
+    orientation: RadioOrientation;
+    /** Whether a form is invalid while no choice is made. */
+    required: boolean;
+    /** Whether the whole set refuses interaction, and submits nothing. */
+    disabled: boolean;
     connectedCallback(): void;
     /**
-     * Keeps the announced orientation on the drawn one.
+     * The value and the validity, which move together here or disagree anywhere.
      *
-     * Written unconditionally rather than only for the horizontal case: the default a
-     * screen reader assumes for a `radiogroup` is not something a component should have an
-     * opinion about, and the attribute costs nothing to state.
+     * The first control is the one asked, and it is the one the browser would focus when a
+     * form reports an invalid group. Iterated rather than asserted, for the reason
+     * `src/input.ts` gives beside the same shape: a null branch here is unreachable, which
+     * is a coverage hole and an immortal mutant at once.
      */
-    willUpdate(): void;
+    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 group currently satisfies its constraints. */
+    get validity(): ValidityState;
+    /** The message a form would report for it, empty while the group is valid. */
+    get validationMessage(): string;
     render(): TemplateResult;
 }
 declare global {

package/dist/radio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"radio.d.ts","sourceRoot":"","sources":["../src/radio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAGjE,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,YAAY,CAAC;AAmCzD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,OAAQ,SAAQ,UAAU;IACnC,gBAAyB,MAAM,0BA8G7B;IAEO,MAAM,IAAI,cAAc;CAGpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,YAAa,SAAQ,UAAU;IACxC,gBAAyB,MAAM,0BAiC7B;IAEF,gBAAyB,UAAU;;;;;MAEjC;IAEF;;;;;;OAMG;IACH,WAAW,EAAE,gBAAgB,CAAc;IAE3C;;;;;;;;;;;OAWG;IACM,iBAAiB,IAAI,IAAI;IAQlC;;;;;;OAMG;IACM,UAAU,IAAI,IAAI;IAIlB,MAAM,IAAI,cAAc;CAGpC;AAWD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,UAAU,EAAE,OAAO,CAAC;QACpB,gBAAgB,EAAE,YAAY,CAAC;KAClC;CACJ"}
+{"version":3,"file":"radio.d.ts","sourceRoot":"","sources":["../src/radio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAsB,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAG1F,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,YAAY,CAAC;AAmDzD;;;;;;;;;;;;;GAaG;AACH,qBAAa,OAAQ,SAAQ,UAAU;;IACnC,gBAAyB,MAAM,EAAE,SAAS,CAIxC;IAEF,gBAAyB,UAAU;;;;;;;;;;;;;MAIjC;IAEF,oEAAoE;IACpE,KAAK,SAAM;IAEX,mFAAmF;IACnF,OAAO,UAAS;IAEhB,qFAAqF;IACrF,QAAQ,UAAS;IAEjB;;;;;;;;OAQG;IACM,OAAO,IAAI,IAAI;IAQf,MAAM,IAAI,cAAc;CAGpC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,YAAa,SAAQ,UAAU;;IACxC,gBAAyB,MAAM,EAAE,SAAS,CAiLxC;IAEF,MAAM,CAAC,QAAQ,CAAC,cAAc,QAAQ;IAEtC;;;;;OAKG;IACH,gBAAyB,iBAAiB;;;;;;;MAGxC;IAEF,gBAAyB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAajC;IAEF;;;;;OAKG;IACH,KAAK,SAAM;IAEX,mFAAmF;IACnF,IAAI,SAAM;IAEV,gFAAgF;IAChF,KAAK,SAAM;IAEX;;;;;;OAMG;IACH,IAAI,SAAM;IAEV;;;;;;OAMG;IACH,KAAK,SAAM;IAEX,+EAA+E;IAC/E,WAAW,EAAE,gBAAgB,CAAc;IAE3C,yDAAyD;IACzD,QAAQ,UAAS;IAEjB,sEAAsE;IACtE,QAAQ,UAAS;IAQR,iBAAiB,IAAI,IAAI;IA+ClC;;;;;;;OAOG;IACM,OAAO,IAAI,IAAI;IAoBxB,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,6DAA6D;IAC7D,IAAI,QAAQ,IAAI,aAAa,CAE5B;IAED,8EAA8E;IAC9E,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAoCQ,MAAM,IAAI,cAAc;CAiCpC;AAWD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,UAAU,EAAE,OAAO,CAAC;QACpB,gBAAgB,EAAE,YAAY,CAAC;KAClC;CACJ"}