stimeo-ui 0.17.0 → 0.18.0

package/dist/controllers/currency_input_controller.d.ts

@@ -40,7 +40,8 @@ import { Controller } from '@hotwired/stimulus';
  * integer digits per locale, a leading sign and a trailing decimal mark stay in
  * place, fraction digits are kept verbatim, and the caret is restored after the
  * same significant character it followed. Negative amounts are in scope. The
- * fixed-precision rounding is applied on `blur`, never mid-entry.
+ * fixed-precision rounding is applied on `blur`, never mid-entry; one asked for
+ * mid-composition is applied with the text the composition confirms or leaves.
  * Full-width digits, signs, and marks (an IME confirming ０-９／．／－) are
  * normalized to their ASCII forms rather than stripped; the locale's own
  * digits (a non-Latin default numbering system such as ar-EG's) are mapped
@@ -73,7 +74,9 @@ import { Controller } from '@hotwired/stimulus';
  * hot path only ever sees validated values through cached `Intl.NumberFormat`
  * instances, never built per keystroke. Late-arriving or swapped `field` /
  * `srValue` / `display` targets are re-synced on connection; one that arrives
- * behind the target in charge is re-synced when that target leaves.
+ * behind the target in charge is re-synced when that target leaves. Only the
+ * display in charge — the first `display` target — is read: an input, blur or
+ * composition in a display behind it is never taken as the user's edit.
  *
  * Reconnecting starts from the committed value: a display still showing this
  * controller's own rendering is not read back but re-rendered from that value
@@ -85,6 +88,17 @@ import { Controller } from '@hotwired/stimulus';
  * and a value it moves is reported as `reconcile`. The composition listeners
  * are released on `disconnect()`.
  *
+ * A display already focused when first acquired or reconnected may carry a
+ * composition whose start was missed. Its text and selection stay untouched,
+ * including non-IME autofocus, until its `compositionend` or a non-composing
+ * `input` with a non-composition `inputType`. A bare input, a direct `onInput()`
+ * call, and blur alone provide no confirmation. While held, submission and the
+ * accessible output retain this instance's accepted value; with no accepted value,
+ * the page's hidden field and accessible text stay unchanged, even when empty.
+ * Neither the draft nor the hidden field seeds the comparison baseline. Connect
+ * before focusing if synchronous initialization is needed, and provide initial
+ * submission and accessible values in markup when early focus is possible.
+ *
  * Honest a11y note: a hidden `<input>` is not exposed to assistive tech, so the
  * normalized value is *also* published as text in the `srValue` span referenced
  * by the display's `aria-describedby` — that, not the hidden field, is what a
@@ -118,6 +132,7 @@ declare class CurrencyInputController extends Controller<HTMLElement> {
     static actions: readonly ["format", "onInput"];
     static events: readonly ["change", "reconcile"];
     readonly displayTarget: HTMLInputElement;
+    readonly displayTargets: HTMLInputElement[];
     readonly fieldTarget: HTMLInputElement;
     readonly srValueTarget: HTMLElement;
     readonly hasDisplayTarget: boolean;
@@ -148,8 +163,9 @@ declare class CurrencyInputController extends Controller<HTMLElement> {
     connect(): void;
     /**
      * Releases the composition listeners. A composition still running hears no
-     * `compositionend` once they are gone, so it ends here; a change it held is
-     * taken in on the next `connect()`.
+     * `compositionend` once they are gone, so it ends here; what it held back is
+     * taken in on the next `connect()`. A display that keeps focus through the move
+     * keeps its conversion for the reconnect, and its text is left alone.
      */
     disconnect(): void;
     /**
@@ -159,16 +175,42 @@ declare class CurrencyInputController extends Controller<HTMLElement> {
      * from the committed one is the page's, so it is reported as `reconcile`.
      * A display that arrives behind the one in charge is only tracked: the one
      * ahead may be composing against the declarations in force, and the arrival
-     * is read when that one leaves.
+     * is read when that one leaves. One that arrives in charge while a display
+     * composes is a mid-composition pass: it is read once the conversion ends,
+     * however it ends, because it is not the display rendered last. One moved with
+     * its conversion is the one rendered last, so it owes nothing.
+     *
+     * One that arrives in charge already focused, with no composition the tracker
+     * follows in it, may carry a composition whose start was missed, so it is held
+     * instead of read: another element, or the display rendered last coming back
+     * without that rendering. Its text and selection stay as they are, it is not
+     * rounded, and the hidden field and the accessible text keep the committed value
+     * (the page's own while none was committed); its own `compositionend`, or an
+     * ordinary `input` that releases it, reads it as the user's edit, reported as
+     * `change`. The display rendered last coming back with that rendering is read as
+     * above. The arrival is held by whichever reading notices it first, so a declaration
+     * change, a morph, `format()` or a blur that runs before this callback holds it too:
+     * one that blurs before this callback keeps its rounding for its own `compositionend`.
      */
     displayTargetConnected(target: HTMLInputElement): void;
     /**
      * Stops tracking a display that leaves. A composition running on it hears no
-     * `compositionend` any more, so it ends here; a change it held waits for the
+     * `compositionend` any more, so it ends here — unless the display kept focus
+     * through a move, which keeps the conversion; a change it held waits for the
      * next display to be read. A composition running on another display still hears
      * its own `compositionend`, so its text is left to it. A display that stays is
      * read again as a declaration change reads it, so an amount it holds that
-     * differs from the committed one is the page's and is reported as `reconcile`.
+     * differs from the committed one is the page's and is reported as `reconcile`;
+     * one still composing is read when the conversion ends if it is no longer the
+     * display rendered last, and otherwise has nothing new to read. One left in charge
+     * that is focused, is not the display rendered last and has no composition the
+     * tracker follows in it is held as a focused arrival is: neither read nor rounded,
+     * the hidden field and the accessible text keep the committed value, and its own
+     * `compositionend`, or an ordinary `input` that releases it, reads it as `change`.
+     * The display rendered last that leaves is remembered until it is next classified in
+     * charge, so it comes back as an arrival whichever callback reads it first. One that only
+     * moved within the same mutation batch while the controller stayed connected, already
+     * back in charge, is not remembered; one that leaves with the controller element is.
      */
     displayTargetDisconnected(target: HTMLInputElement): void;
     /** Syncs a late-arriving hidden field without touching the display or events. */
@@ -179,10 +221,32 @@ declare class CurrencyInputController extends Controller<HTMLElement> {
     srValueTargetConnected(): void;
     /** Syncs the screen-reader span that stays when an earlier one leaves, silently. */
     srValueTargetDisconnected(): void;
-    /** Re-groups digits as the user types, preserving the caret position. */
-    onInput(event: Event): void;
-    /** Applies the fixed-precision rounding on blur. */
-    format(): void;
+    /**
+     * Re-groups digits as the user types, preserving the caret position. Only an edit
+     * of the display in charge is the user's: a display behind it is not read, and the
+     * end of a composition its edit shows was settled before this runs. An edit the
+     * event or the tracker reports as composing is the IME's draft, read when the
+     * composition ends. Called without an event, it re-groups the display in charge —
+     * while a composition runs, it leaves the draft and caret alone, since the end of
+     * the composition re-groups what it confirms.
+     */
+    onInput(event?: Event): void;
+    /**
+     * Applies the fixed-precision rounding on blur — of the display in charge only. Called
+     * without an event, it rounds the display in charge. While a composition runs — the
+     * event or the tracker says so — the draft, the caret and the committed outputs stay
+     * as they are, and the rounding is held: the `compositionend` that confirms or
+     * cancels the composition rounds once; a move or disconnect that ends it, or a
+     * composition the user starts in another display, rounds the text it leaves in the
+     * same reading, reported as `reconcile`; any other end no `compositionend` reports
+     * drops the rounding, and the next blur rounds. The rounding is held for the composition
+     * running when it was asked, in the display that composition runs in, and never rounds
+     * another one: it lapses when another display's composition ends, and goes with its
+     * display when that display leaves with no composition the tracker follows going on in
+     * it. A rounding applied at once spends one held for a composition only the event
+     * reported.
+     */
+    format(event?: Event): void;
 }
 
 export { CurrencyInputController };