stimeo-ui 0.15.0 → 0.16.0

package/dist/controllers/toast_controller.d.ts

@@ -9,7 +9,7 @@ import { Controller } from '@hotwired/stimulus';
  *        data-stimeo--toast-max-value="3">
  *     <!-- Attribute-only trigger: no hand-written JS required. -->
  *     <button data-action="click->stimeo--toast#show"
- *             data-stimeo--toast-body-param="Saved"
+ *             data-stimeo--toast-message-param="Saved"
  *             data-stimeo--toast-type-param="status">Show</button>
  *     <!-- The live region is a descendant; the controller element only needs
  *          to enclose both the trigger(s) and the list/template targets. -->
@@ -17,7 +17,7 @@ import { Controller } from '@hotwired/stimulus';
  *       <ol data-stimeo--toast-target="list"></ol>
  *       <template data-stimeo--toast-target="template">
  *         <li data-stimeo--toast-target="item" tabindex="0">
- *           <span role="status" data-toast-slot="body"></span>
+ *           <span role="status" data-toast-slot="message"></span>
  *           <button type="button" data-toast-dismiss>Dismiss</button>
  *         </li>
  *       </template>
@@ -30,7 +30,14 @@ import { Controller } from '@hotwired/stimulus';
  * once the last of hover and focus is released, so the pointer's target and the
  * focused control stay where they are.
  *
- * `dismiss` dispatches `{ item: HTMLElement, reason: "timeout" | "user" }`.
+ * The `max` limit (`0` or less, or not a finite number, means none) keeps them there too.
+ * Past it the oldest toasts go with reason `limit`, passing over every toast the pointer
+ * is over or focus is inside — whether or not a timer runs — the toast just taken on, and
+ * the one the pointer or focus is moving into. While nothing else can go the list stays
+ * over the limit, and the limit is applied again once hover and focus have both left a
+ * toast, or a toast they held leaves the list.
+ *
+ * `dismiss` dispatches `{ item: HTMLElement, reason: "timeout" | "user" | "limit" }`.
  *
  * `show` dispatches `{ item: HTMLElement }`.
  *
@@ -60,6 +67,11 @@ declare class ToastController extends Controller<HTMLElement> {
     readonly hasTemplateTarget: boolean;
     durationValue: number;
     maxValue: number;
+    /**
+     * Stimulus reports every toast the list already holds before this runs, and each is
+     * taken on then with its holds, meeting no limit. The limit is applied here once, over
+     * all of them, unless the list was already held to the current `max`.
+     */
     connect(): void;
     disconnect(): void;
     /** Rebinds delegated interaction when Turbo replaces the list target in place. */
@@ -67,14 +79,28 @@ declare class ToastController extends Controller<HTMLElement> {
     /** Releases delegation only when the removed target is its current owner. */
     listTargetDisconnected(element: HTMLElement): void;
     durationValueChanged(): void;
+    /**
+     * Holds the list to a changed `max`. Stimulus can also call this ahead of `connect()` —
+     * for an attribute that changed while the controller was away, and on every connect
+     * for an undeclared `max`, with its default; `connect()` decides then.
+     */
     maxValueChanged(): void;
     /**
      * Stimulus lifecycle callback triggered automatically when a new item target
-     * enters the DOM, from a client-side injection or a Turbo Stream append alike. An
-     * item already leaving, or parented outside `list`, is skipped.
+     * enters the DOM, from a client-side injection or a Turbo Stream append alike, and for
+     * every toast the list already holds ahead of `connect()`. An item already leaving,
+     * parented outside `list`, or already taken on (a move within the list) is skipped; any
+     * other is taken on with the holds it already has. On a connected controller the `max`
+     * limit is then applied, never to the arrival itself; the toasts reported ahead of
+     * `connect()` are left to it.
      */
     itemTargetConnected(element: HTMLElement): void;
-    /** Clears any active timer when a toast is removed from the DOM. */
+    /**
+     * Lets go of a toast that left the list or stopped being an item: its timer, holds,
+     * `data-paused` and pending frame. After a move within the list the node is already
+     * back, still an item, when Stimulus reports it, so it keeps all of those, and only the
+     * holds the move may have ended are read again.
+     */
     itemTargetDisconnected(element: HTMLElement): void;
     /**
      * Shows a new toast. Accepts its content from either a Stimulus action param
@@ -82,12 +108,15 @@ declare class ToastController extends Controller<HTMLElement> {
      * (remote / Turbo trigger); the action param wins when both are present.
      *
      *   <button data-action="click->stimeo--toast#show"
-     *           data-stimeo--toast-body-param="Saved"
+     *           data-stimeo--toast-message-param="Saved"
      *           data-stimeo--toast-type-param="status">Show</button>
      *
-     *   element.dispatchEvent(new CustomEvent("show", { detail: { body, type } }))
+     *   element.dispatchEvent(new CustomEvent("show", { detail: { message, type } }))
      *
-     * Clones the template slot, interpolates the body text, and appends to the list.
+     * Clones the template slot, interpolates the message, and appends to the list.
+     * `message` is the wording key the rest of the library dispatches under, so a
+     * part that already carries its own wording — `stimeo--clipboard:copy`,
+     * `stimeo--auto-submit:done` — wires straight into this action.
      */
     show(event: Event): void;
     /** Dismisses the toast that contained the trigger. */
@@ -100,18 +129,26 @@ declare class ToastController extends Controller<HTMLElement> {
      * Hover and focus are tracked as independent reasons: the timer is only
      * snapshotted on the first active reason, and only resumed once *every*
      * reason has been released (see {@link resume}). This keeps a toast paused
-     * while it is still hovered *or* focused, per WCAG 2.2.1.
+     * while it is still hovered *or* focused, per WCAG 2.2.1. The hold is recorded
+     * whether or not a timer runs, so the `max` limit passes over the toast either
+     * way; `data-paused` marks a timer that stopped, and only that.
      */
     pause(event: Event): void;
-    /** Resumes the auto-dismiss timer once both hover and focus have been released. */
+    /**
+     * Resumes the auto-dismiss timer once both hover and focus have been released,
+     * and then applies the `max` limit again, sparing the toast the pointer or focus is
+     * moving into: its own hold only arrives after this event.
+     */
     resume(event: Event): void;
     /**
-     * Removes the oldest toasts when the list exceeds `maxValue`.
+     * Removes the oldest toasts while the list shows more than `maxValue`, passing
+     * over every toast hover or focus holds.
      *
      * Public (not `#private`) as a deterministic seam: enforcement normally runs
-     * from `itemTargetConnected`, a Stimulus callback delivered through a
-     * MutationObserver, which a DOM-only environment does not reliably fire — so
-     * it can also be invoked directly. It is not a user-wired action.
+     * as each toast is taken on in `itemTargetConnected`, a Stimulus callback delivered
+     * through a MutationObserver, which a DOM-only environment does not reliably fire —
+     * so it can also be invoked directly. It counts only the toasts taken on. It is not a
+     * user-wired action.
      */
     enforceMaxLimit(): void;
 }