stimeo-ui 0.5.0 → 0.6.0

package/dist/controllers/radio_group_controller.d.ts

@@ -1,48 +1,74 @@
 import { Controller } from '@hotwired/stimulus';
 
 /**
- * Headless, accessible radio-group behavior for **custom** (non-native) radios.
+ * Headless, accessible radio-group behavior for **custom** radios.
  *
  * Markup contract (identifier: `stimeo--radio-group`):
  *   <div data-controller="stimeo--radio-group" role="radiogroup" aria-label="Plan">
  *     <div role="radio" aria-checked="true" tabindex="0" data-value="basic"
- *          data-stimeo--radio-group-target="radio"
- *          data-action="click->stimeo--radio-group#select
- *                       keydown->stimeo--radio-group#onKeydown">Basic</div>
- *     <!-- more radios; exactly one tabindex=0 -->
+ *          data-stimeo--radio-group-target="radio">Basic</div>
+ *     <!-- more radios; exactly one navigable radio has tabindex=0 -->
  *     <input type="hidden" data-stimeo--radio-group-target="field" />
  *   </div>
  *
  * Implements the WAI-ARIA APG **Radio Group** pattern. Use this only for custom
- * radios (e.g. button-styled cards); native `<input type="radio">` already does
- * this and should be preferred when its look suffices.
+ * radios; native `<input type="radio">` already owns its activation and form
+ * semantics and should be preferred when its appearance is sufficient.
  *
  * @remarks
  * Behavior only — selection is exposed through `aria-checked`, the single Tab
  * stop through roving `tabindex` ({@link RovingTabindex}); the consumer styles
- * off `[role="radio"][aria-checked="true"]`. Per APG, **selection follows
- * focus**: arrow keys move focus and select in one step.
+ * those attributes. Selection follows focus for enabled radios.
+ *
+ * A supported radio is either `<button type="button">` or a non-interactive
+ * host such as `<div role="radio">`. Other native interactive elements retain
+ * their activation model and this controller stands down on them.
+ *
+ * Click and keydown handling are delegated from the group, so radios added at
+ * runtime need only the `radio` target. Per-radio `data-action` bindings to
+ * {@link select} and {@link onKeydown} remain supported and are idempotent when
+ * combined with delegation.
  *
  * Behavior provided:
  * - Click selects a radio.
  * - `ArrowDown`/`ArrowRight` select the next, `ArrowUp`/`ArrowLeft` the previous
  *   (wrapping); `Home`/`End` the first/last; `Space` selects the focused radio.
- * - The selected radio's `data-value` is mirrored to the optional hidden `field`,
- *   and `stimeo--radio-group:change` is dispatched on every change.
+ * - Native-disabled and hidden radios are skipped. ARIA-disabled radios remain
+ *   discoverable in the roving order but cannot be selected.
+ * - The selected radio's `data-value` is mirrored to the optional hidden field.
+ *   `stimeo--radio-group:change` is dispatched only when selection identity
+ *   changes through user interaction.
+ * - `stimeo--radio-group:reconcile` reports a selection this controller decided
+ *   on its own — a removed selection, or first-wins over duplicate checked state
+ *   — carrying the same detail as `change`. The hidden field's native `change`
+ *   stays reserved for user edits, so form automation never sees a repair as one.
  */
 declare class RadioGroupController extends Controller<HTMLElement> {
     #private;
     static targets: string[];
     static actions: readonly ["onKeydown", "select"];
-    static events: readonly ["change"];
+    static events: readonly ["change", "reconcile"];
     readonly radioTargets: HTMLElement[];
     readonly fieldTarget: HTMLInputElement;
     readonly hasFieldTarget: boolean;
-    /** Establishes the roving entry point and reflects the initial selection. */
+    /**
+     * Normalizes authored selection, establishes the APG Tab entry point, and
+     * reflects derived form state without reporting a user edit.
+     */
     connect(): void;
-    /** Selects the clicked radio. Bound via `data-action` (click). */
+    /** Releases every listener, observer, and queued pass while retaining live DOM state. */
+    disconnect(): void;
+    /** Removes a newly connected radio from the Tab sequence before batch reconciliation. */
+    radioTargetConnected(radio: HTMLElement): void;
+    /** Releases target-only attributes and repairs selection, form state, focus, and roving. */
+    radioTargetDisconnected(radio: HTMLElement): void;
+    /** Reflects the current selection into a field added or replaced at runtime. */
+    fieldTargetConnected(): void;
+    /** Reconciles after a field target is removed from a retained group. */
+    fieldTargetDisconnected(): void;
+    /** Selects the action's radio. Per-radio action wiring is optional. */
     select(event: Event): void;
-    /** Arrow/Home/End/Space navigation with selection-follows-focus. */
+    /** Applies the APG key map to the action's radio. Per-radio action wiring is optional. */
     onKeydown(event: KeyboardEvent): void;
 }