@jxsuite/ui 0.0.0 → 0.2.0

package/src/behaviors/textfield.ts

@@ -0,0 +1,164 @@
+/**
+ * The field family's behaviour sidecar: focus and selection on `jx-textfield`'s inner native
+ * control, the clear button's own three steps, and the id stems neither `jx-textfield` nor
+ * `jx-field` may let two instances share. Each of them is something a document body cannot express
+ * — it can neither move focus, nor dispatch from an element other than the one whose handler is
+ * running, nor count.
+ *
+ * `jx-field` reaches into this module rather than shipping one of its own because the two elements
+ * are one contract: the row names the control, the control names its own sentences, and a single
+ * module is what keeps their two id stems provably distinct.
+ *
+ * @docs extending/ui-kit
+ */
+
+/** The element's own native control. */
+function controlOf(host: HTMLElement): HTMLInputElement | HTMLTextAreaElement | null {
+  return host.querySelector<HTMLInputElement | HTMLTextAreaElement>('[part="input"]');
+}
+
+/**
+ * Focus the field and select its value: all of it, the stem before the last dot (a filename with
+ * its extension left alone), or nothing.
+ *
+ * @param host The `jx-textfield` element.
+ * @param mode What to select once focused.
+ */
+export function selectValue(host: HTMLElement, mode: "all" | "stem" | "none" = "all"): void {
+  const control = controlOf(host);
+  if (!control) {
+    return;
+  }
+  control.focus();
+  if (mode === "none") {
+    return;
+  }
+  if (mode === "stem") {
+    const dot = control.value.lastIndexOf(".");
+    control.setSelectionRange(0, dot > 0 ? dot : control.value.length);
+    return;
+  }
+  control.select();
+}
+
+/** Focus the field without touching its selection. */
+export function focusField(host: HTMLElement): void {
+  controlOf(host)?.focus();
+}
+
+/** The `jx-textfield` an event inside one came from. */
+function hostOf(event: Event): HTMLElement | null {
+  const target = event.currentTarget;
+  return target instanceof Element ? target.closest<HTMLElement>("jx-textfield") : null;
+}
+
+/**
+ * Empty a clearable field: write "" into its value, put focus back on the control the reader was
+ * in, and say so with `input` and then `change`.
+ *
+ * Both events come from the ELEMENT rather than from the clear button, because every host reads
+ * `e.target.value` and the button's own `value` is not the field's. The platform fires nothing for
+ * a value the element wrote itself, so the pair is dispatched here.
+ *
+ * @param state The element's reactive scope, whose `value` this empties.
+ * @param event The click on the clear button.
+ */
+export function clearField(state: Record<string, unknown>, event: Event): void {
+  const host = hostOf(event);
+  if (!host) {
+    return;
+  }
+  state["value"] = "";
+  focusField(host);
+  host.dispatchEvent(new Event("input", { bubbles: true }));
+  host.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
+let minted = 0;
+
+/**
+ * Give the instance an id stem no other field in the document shares, so its error and help
+ * sentences can carry ids the control names in `aria-describedby`.
+ *
+ * A document cannot mint one: the closed operator set has no counter and no identity, and two
+ * fields on one surface must not collide. This is the sidecar case specs/ui.md §3.2 sanctions.
+ *
+ * @param state The element's reactive scope, whose `uid` this writes.
+ */
+export function mintFieldId(state: Record<string, unknown>): void {
+  minted += 1;
+  state["uid"] = `jx-tf-${minted}`;
+}
+
+let namedRows = 0;
+
+/** Whether an element's DEFINITION says it can be named — that it observes `labelledby`. */
+function observesNaming(el: Element): boolean {
+  const def = customElements.get(el.localName) as
+    | { observedAttributes?: readonly string[] }
+    | undefined;
+  return def?.observedAttributes?.includes("labelledby") === true;
+}
+
+/**
+ * Give a `jx-field` an id stem, and hand that stem to the control slotted into it.
+ *
+ * This is the whole reason the row is an element rather than four classes. The four classes could
+ * not name anything, so every call site hand-wrote an `id` on the label, a second one on the help
+ * sentence, and `labelledby` and `describedby` on the control repeating both — four strings a
+ * consumer had to keep in step, in a document where nothing checks that they are.
+ *
+ * The stem is written into `state.uid`, which the row's own `id` bindings read. The control is
+ * named through PROPERTIES rather than through `aria-labelledby` written onto it: every kit control
+ * observes `labelledby` and `describedby` and folds them into whatever else it has to say about
+ * itself (`jx-textfield` puts its own error and help sentences in front of the row's), so writing
+ * the ARIA attribute directly would silently overwrite that. A property write also needs no
+ * mutation observer and no upgrade timing: set on an element the runtime has not initialised yet,
+ * it is an own property, and `connectedCallback` reads own properties into state before it defines
+ * its accessors.
+ *
+ * A control is named when its DEFINITION says it can be — `observedAttributes` carries
+ * `labelledby`. A hyphen in the tag name says only that the element is custom, and the row would
+ * then write a dead expando onto whatever a consumer slotted first, an inner `jx-field` included.
+ * The definition is readable before the instance upgrades, so a control the runtime has not
+ * initialised yet is still named; an element whose definition is not registered when the row mounts
+ * is left alone, exactly as a native control is.
+ *
+ * A NATIVE control — a bare `<input>`, `<select>` or `<textarea>` — has no definition to ask, so
+ * the same rule leaves it alone: a write would be a dead expando rather than a name. Give one its
+ * own `aria-labelledby` pointing at the row's label, or wrap it in a kit element.
+ *
+ * `describedby` is written only when the help line HAS something in it — a sentence from
+ * `description`, or an element slotted into `help`. A row with nothing to say would otherwise point
+ * its control at an empty paragraph, which the class form never did and which `jx-textfield` would
+ * carry as a dead trailing id in its merged list. The presence of a slotted help element is enough,
+ * so a sentence whose text arrives later should be SLOTTED rather than passed as a `description`
+ * that starts empty: the row reads the help line once, here.
+ *
+ * Both are read once, at mount, over the control slotted then. A control appended to the row
+ * afterwards is neither placed in the control part nor named — see the `onMount` prop's own note.
+ *
+ * @param state The row's reactive scope, whose `uid` this writes.
+ * @param host The `jx-field` element, whose slotted control this names.
+ */
+export function nameFieldControl(state: Record<string, unknown>, host: HTMLElement): void {
+  namedRows += 1;
+  const uid = `jx-field-${namedRows}`;
+  state["uid"] = uid;
+
+  /* The row's OWN parts, found among its children rather than by a descendant query. Both spellings
+     return the same node for a rendered row — the row's own parts precede everything slotted, so
+     nothing in the suite can tell them apart — but a `[part]` lookup that may descend is one
+     refactor away from reaching into a nested row's parts. */
+  const own = (name: string) => [...host.children].find((el) => el.getAttribute("part") === name);
+  const control = own("control")?.firstElementChild;
+  if (!control || !observesNaming(control)) {
+    return;
+  }
+  const target = control as unknown as Record<string, unknown>;
+  target["labelledby"] ||= `${uid}-label`;
+  const help = own("help");
+  if (help && (help.firstElementChild !== null || help.textContent !== "")) {
+    target["describedby"] ||= `${uid}-help`;
+  }
+}

package/src/behaviors/toast-host.ts

@@ -0,0 +1,241 @@
+/**
+ * `jx-toast-host`'s behaviour sidecar: the stack's clock policy, and the one gesture that puts the
+ * keyboard into a toast.
+ *
+ * **A toast must not steal focus, and its recovery control must still be reachable before it
+ * expires.** Those two sentences are in tension, and this module is where the tension is resolved
+ * rather than picked. Three things do it together, and none of them is enough alone.
+ *
+ * 1. **The stack is read where it stands.** Nothing here moves focus when a toast arrives; the element
+ *    appears beside the reader's work and the reader's caret does not move.
+ * 2. **Attention suspends every clock in the stack, not only the one under it.** Pointer or focus
+ *    anywhere in the host pauses every toast in it, so an older toast cannot vanish out from under
+ *    a reader who is answering a newer one — which would move the very control they were reaching
+ *    for. `toast.ts` holds the clocks; this module tells them when.
+ * 3. **A key press is the door in.** `hotkey` (`F8` by default, and the same key Radix and Sonner's
+ *    stacks settled on) moves focus to the first control in the stack and REMEMBERS where it came
+ *    from; Escape puts it back, and so does a toast closing under the reader's hand. That is the
+ *    reader asking for the toast rather than the toast taking the reader, which is the distinction
+ *    "must not steal focus" is actually about. `hotkey=""` turns it off for a host whose
+ *    application already owns a key for it — Studio's command registry, say.
+ *
+ * The reader reaches the stack in one press, and the moment they do, nothing in it is on a clock.
+ *
+ * **The one document listener is registered here and released at unmount**, which is the opposite
+ * of `select.ts`'s decision and for the opposite reason: that observer watches the element's own
+ * subtree and dies with it, while this one is on the document and would outlive a removed host — a
+ * dead stack answering a key press, holding the element it can no longer show. A re-parented host
+ * loses its hotkey (the runtime initialises an element once, so nothing re-binds it); a host that
+ * leaks one steals a key from the whole page, and of the two that is the worse.
+ *
+ * @docs extending/ui-kit
+ */
+
+import { TOAST_PAUSE, TOAST_RESUME, staysInside } from "./toast.ts";
+
+/** The tag this sidecar belongs to. */
+const HOST = "jx-toast-host";
+
+/** What a reader can put the keyboard on, before the stack's own state is consulted. */
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/** The reactive scope a `jx-toast-host` document hands its handlers. */
+export interface ToastHostState {
+  /** The key that moves focus into the stack. Empty turns the gesture off. */
+  hotkey: string;
+  /** `polite`, `assertive` or `off`. */
+  live: string;
+  [key: string]: unknown;
+}
+
+/** Where focus was when the reader entered the stack, so it can be given back. */
+const origins = new WeakMap<HTMLElement, HTMLElement>();
+
+/** Each mounted host's document listener, so unmounting can take it off again. */
+const listeners = new WeakMap<object, () => void>();
+
+/** The `jx-toast-host` a listener bound at the host's root belongs to. */
+function hostOf(event: Event): HTMLElement | null {
+  const target = event.currentTarget ?? event.target;
+  return target instanceof Element ? target.closest<HTMLElement>(HOST) : null;
+}
+
+/**
+ * The controls a reader can reach in this stack, in DOM order.
+ *
+ * DOM order and nothing else: the stack is drawn in the order it is written, never reversed, so the
+ * order a reader hears, the order they tab through and the order they see are one order. A closed
+ * toast contributes nothing, because a control inside a `display: none` toast is a stop on the way
+ * to nowhere.
+ *
+ * @param host The `jx-toast-host` element.
+ * @returns The focusable controls of every open toast in it.
+ */
+export function focusablesIn(host: HTMLElement): HTMLElement[] {
+  return [...host.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(
+    (control) => control.closest<HTMLElement>("jx-toast")?.dataset["open"] !== undefined,
+  );
+}
+
+/** Whether the keyboard is currently somewhere inside the stack. */
+function holdsFocus(host: HTMLElement): boolean {
+  const active = host.ownerDocument.activeElement;
+  return active instanceof Node && host.contains(active);
+}
+
+/**
+ * Put the keyboard on the first control in the stack, remembering where it came from.
+ *
+ * The host door as well as the hotkey's: an application with its own command for "go to
+ * notifications" calls this and gets the same round trip, Escape included.
+ *
+ * @param host The `jx-toast-host` element.
+ * @returns True when there was something to focus.
+ */
+export function focusStack(host: HTMLElement): boolean {
+  const [first] = focusablesIn(host);
+  if (!first) {
+    return false;
+  }
+  const active = host.ownerDocument.activeElement;
+  if (active instanceof HTMLElement && !host.contains(active)) {
+    origins.set(host, active);
+  }
+  first.focus();
+  return true;
+}
+
+/**
+ * Give the keyboard back to whatever the reader left to come here.
+ *
+ * When there is nothing to give it back to — the stack was never entered by the hotkey, or the
+ * element that had focus has since left the document — the caret is only let go of, never moved
+ * somewhere of this module's choosing. Focus lands on the document, which is where the platform
+ * puts it when an element holding it is hidden, and the reader's next Tab starts from the top
+ * rather than from a toast that is no longer there.
+ *
+ * @param host The `jx-toast-host` element.
+ * @returns True when focus was returned to a remembered element.
+ */
+export function returnFocus(host: HTMLElement): boolean {
+  const origin = origins.get(host);
+  origins.delete(host);
+  if (origin?.isConnected === true) {
+    origin.focus();
+    return true;
+  }
+  const active = host.ownerDocument.activeElement;
+  if (active instanceof HTMLElement && host.contains(active)) {
+    active.blur();
+  }
+  return false;
+}
+
+/** Say the same thing to every toast in the stack. */
+function tell(host: HTMLElement, name: string): void {
+  for (const toast of host.querySelectorAll("jx-toast")) {
+    toast.dispatchEvent(new Event(name));
+  }
+}
+
+/**
+ * The reader's attention arrived: suspend every clock in the stack.
+ *
+ * `pointerover` rather than `pointerenter`, because the host is `pointer-events: none` — the toasts
+ * are what the pointer can land on, and only a bubbling event carries the news up to the stack that
+ * owns them.
+ *
+ * @param state The host's reactive state.
+ * @param event The `pointerover` or `focusin`.
+ */
+export function onStackHold(_state: ToastHostState, event: Event): void {
+  const host = hostOf(event);
+  if (host) {
+    tell(host, TOAST_PAUSE);
+  }
+}
+
+/**
+ * The reader's attention left: let the clocks run again.
+ *
+ * A move between two toasts of one stack is not a departure, which is what {@link staysInside}
+ * settles — without it, crossing the stack with the pointer would restart every clock in it once
+ * per toast.
+ *
+ * @param state The host's reactive state.
+ * @param event The `pointerout` or `focusout`.
+ */
+export function onStackRelease(_state: ToastHostState, event: Event): void {
+  const host = hostOf(event);
+  if (host && !staysInside(event)) {
+    tell(host, TOAST_RESUME);
+  }
+}
+
+/**
+ * A toast closed. If it took the reader's focus with it, hand focus back.
+ *
+ * Only when the caret was inside the toast that closed, or has already fallen to the document:
+ * closing an older toast while the reader is answering a newer one must not move them at all.
+ *
+ * @param state The host's reactive state.
+ * @param event The `close` bubbling up from a toast.
+ */
+export function onStackClose(_state: ToastHostState, event: Event): void {
+  const host = hostOf(event);
+  if (!host) {
+    return;
+  }
+  const active = host.ownerDocument.activeElement;
+  const closed = event.target;
+  const lost = active === null || active === host.ownerDocument.body;
+  const inClosed = closed instanceof Node && active instanceof Node && closed.contains(active);
+  if (lost || inClosed) {
+    returnFocus(host);
+  }
+}
+
+/**
+ * Register the stack's key: the one that brings the keyboard here, and the one that takes it back.
+ *
+ * It is on the document rather than on the host, and it has to be: a key that only worked once
+ * focus was already in the stack would answer the question it exists to answer with itself. A press
+ * carrying a modifier is left alone, so a host may claim `F8` without taking `Ctrl+F8` from the
+ * browser or the reader's own assistive software.
+ *
+ * @param state The host's reactive state.
+ * @param host The element itself.
+ */
+export function onHostMount(state: ToastHostState, host: HTMLElement): void {
+  const root = host.getRootNode() as Document | ShadowRoot;
+  const onKeydown = (event: Event): void => {
+    const press = event as KeyboardEvent;
+    if (press.altKey || press.ctrlKey || press.metaKey) {
+      return;
+    }
+    const wanted = typeof state.hotkey === "string" ? state.hotkey : "";
+    if (wanted !== "" && press.key === wanted) {
+      if (focusStack(host)) {
+        press.preventDefault();
+      }
+      return;
+    }
+    if (press.key === "Escape" && holdsFocus(host)) {
+      returnFocus(host);
+      press.preventDefault();
+    }
+  };
+  root.addEventListener("keydown", onKeydown);
+  listeners.set(state, () => root.removeEventListener("keydown", onKeydown));
+}
+
+/**
+ * Take the key back when the stack leaves the document.
+ *
+ * @param state The host's reactive state.
+ */
+export function onHostUnmount(state: ToastHostState): void {
+  listeners.get(state)?.();
+  listeners.delete(state);
+}

package/src/behaviors/toast.ts

@@ -0,0 +1,261 @@
+/**
+ * `jx-toast`'s behaviour sidecar: the timer that retires a toast, the holds that suspend it, and
+ * the one function that closes a toast and says why.
+ *
+ * A toast is the only element in the kit whose lifetime is a CLOCK rather than a state, and every
+ * decision here follows from that.
+ *
+ * **The timer is suspended, never merely restarted.** While the pointer rests on a toast, while
+ * focus is inside it, and while the stack it belongs to is being read, its clock does not run — and
+ * it resumes with the time that was LEFT rather than from the top. That is WCAG 2.2.1's "pause" as
+ * an author can honour it without a dialog, and it is what makes the element's other promise true:
+ * a recovery control the reader has reached cannot expire under their hand, because reaching it is
+ * itself what stopped the clock. A hold is a NAMED reason — `pointer`, `focus`, `stack` — held in a
+ * set rather than a boolean, because the three overlap: a pointer leaving a toast the reader has
+ * tabbed into must not restart a clock the focus is still holding.
+ *
+ * **Nothing here calls `focus()`.** A toast is a status message: it appears beside the reader's
+ * work and never takes the keyboard from it. Moving focus INTO a stack is the reader's own gesture
+ * and lives in `toast-host.ts`, behind a key they press.
+ *
+ * **A toast the host closes is silent.** `close` is dispatched only when the element itself decided
+ * — the clock ran out, the dismiss button was pressed, the recovery control was used — so a host
+ * writing `open = false` hears nothing back about a thing it just did.
+ *
+ * @docs extending/ui-kit
+ */
+
+/** The tag this sidecar belongs to. */
+const HOST = "jx-toast";
+
+/** Why a toast closed, as the `close` event's `detail.reason`. */
+export type ToastCloseReason = "timeout" | "dismissed" | "action";
+
+/** The event a `jx-toast-host` dispatches at each toast to suspend its clock. */
+export const TOAST_PAUSE = "jx-toast-pause";
+
+/** The event a `jx-toast-host` dispatches at each toast to let its clock run again. */
+export const TOAST_RESUME = "jx-toast-resume";
+
+/** The reactive scope a `jx-toast` document hands its handlers. */
+export interface ToastState {
+  /** Whether the toast is showing. The host writes it; the clock reads it. */
+  open: boolean;
+  /** How long the toast rests before retiring itself, in ms. `0` never retires. */
+  timeout: number;
+  /** `info`, `positive`, `negative` or `warning`. */
+  variant: string;
+  [key: string]: unknown;
+}
+
+/** One toast's clock: what is left of it, when this run started, and what is holding it. */
+interface Clock {
+  timer: ReturnType<typeof setTimeout> | null;
+  /** Milliseconds still to run. Recomputed every time the clock is suspended. */
+  remaining: number;
+  /** When the current run began, for the subtraction that suspending does. */
+  startedAt: number;
+  /** The reasons the clock is suspended. Empty means it may run. */
+  holds: Set<string>;
+}
+
+/** Which hold an event asks for. Three channels, because they overlap and must not cancel. */
+const HOLD_REASON: Readonly<Record<string, string>> = {
+  focusin: "focus",
+  focusout: "focus",
+  [TOAST_PAUSE]: "stack",
+  [TOAST_RESUME]: "stack",
+  pointerenter: "pointer",
+  pointerleave: "pointer",
+  pointerout: "pointer",
+  pointerover: "pointer",
+};
+
+/** Each scope's clock. */
+const clocks = new WeakMap<object, Clock>();
+
+/** The element each scope belongs to, learned at mount. */
+const hosts = new WeakMap<object, HTMLElement>();
+
+/** This scope's clock, minted on first sight. */
+function clockOf(state: object): Clock {
+  const found = clocks.get(state);
+  if (found) {
+    return found;
+  }
+  const fresh: Clock = { holds: new Set(), remaining: 0, startedAt: 0, timer: null };
+  clocks.set(state, fresh);
+  return fresh;
+}
+
+/** The `jx-toast` a listener bound anywhere inside the element belongs to. */
+function ownerOf(event: Event): HTMLElement | null {
+  const target = event.currentTarget ?? event.target;
+  return target instanceof Element ? target.closest<HTMLElement>(HOST) : null;
+}
+
+/**
+ * Whether a leaving event is really leaving.
+ *
+ * `focusout` fires when focus moves from a toast's recovery control to its dismiss button, and
+ * `pointerout` fires crossing between two toasts in one stack — both of them a departure only if
+ * you do not ask where the pointer or the focus WENT. Without this, a reader tabbing along a
+ * toast's own controls restarts the clock they are standing on at every step.
+ *
+ * @param event A `focusout` or `pointerout`, whose `relatedTarget` says where it went.
+ * @returns True when the destination is still inside the element the listener is bound to.
+ */
+export function staysInside(event: Event): boolean {
+  const to = (event as { relatedTarget?: unknown }).relatedTarget;
+  const from = event.currentTarget;
+  return to instanceof Node && from instanceof Node && from.contains(to);
+}
+
+/** Stop the clock's timer without touching what is left of it. */
+function park(clock: Clock): void {
+  if (clock.timer !== null) {
+    clearTimeout(clock.timer);
+    clock.timer = null;
+  }
+}
+
+/** Run the clock for whatever is left, unless it is held, closed or sticky. */
+function schedule(state: ToastState): void {
+  const clock = clockOf(state);
+  park(clock);
+  if (state.open !== true || clock.holds.size > 0 || clock.remaining <= 0) {
+    return;
+  }
+  clock.startedAt = Date.now();
+  clock.timer = setTimeout(() => {
+    clock.timer = null;
+    const host = hosts.get(state);
+    if (host) {
+      closeToast(host, "timeout");
+    }
+  }, clock.remaining);
+}
+
+/**
+ * Close a toast and say why.
+ *
+ * The host door as well as the element's own: a host that retires a toast from its own code closes
+ * it through here, and the `close` its listeners hear is the same event the dismiss button raises.
+ * Closing a closed toast says nothing, so a dismiss that races the clock is one event rather than
+ * two.
+ *
+ * @param host The `jx-toast` element.
+ * @param reason Why it closed.
+ */
+export function closeToast(host: HTMLElement, reason: ToastCloseReason): void {
+  const el = host as HTMLElement & { open?: boolean };
+  if (el.open !== true) {
+    return;
+  }
+  el.open = false;
+  host.dispatchEvent(new CustomEvent("close", { bubbles: true, detail: { reason } }));
+}
+
+/**
+ * Learn the element, start the clock, and follow `open` for the rest of the toast's life.
+ *
+ * `data-open` is what moves when anything writes `open` — the attribute, the property, or the
+ * element's own retirement — so one observer on it is the whole subscription. The same idiom
+ * `jx-color-field` uses for `data-value`, and for the same reason: a sidecar cannot watch reactive
+ * state, but it can watch the attribute that state writes.
+ *
+ * @param state The toast's reactive state.
+ * @param host The element itself.
+ */
+export function onToastMount(state: ToastState, host: HTMLElement): void {
+  hosts.set(state, host);
+  const clock = clockOf(state);
+  clock.remaining = Number(state.timeout) || 0;
+  schedule(state);
+  const observer = new MutationObserver(() => {
+    if (state.open === true) {
+      clock.remaining = Number(state.timeout) || 0;
+      schedule(state);
+      return;
+    }
+    park(clock);
+  });
+  observer.observe(host, { attributeFilter: ["data-open"], attributes: true });
+}
+
+/**
+ * Stop the clock when the toast leaves the document.
+ *
+ * The element initialises ONCE — `connectedCallback` returns early on an element it has already
+ * built — so a re-parented toast comes back with its observer intact and its clock stopped, which
+ * is to say sticky. That is the safe direction and it is chosen rather than tolerated: a sticky
+ * toast still carries its dismiss button, whereas a timer that survived removal would retire a
+ * toast the host had already taken away and put back, dispatching `close` for a toast the reader
+ * never saw expire.
+ *
+ * @param state The toast's reactive state.
+ */
+export function onToastUnmount(state: ToastState): void {
+  park(clockOf(state));
+}
+
+/**
+ * Suspend the clock: the pointer arrived, focus arrived, or the stack asked.
+ *
+ * @param state The toast's reactive state.
+ * @param event The `pointerenter`, `focusin` or `jx-toast-pause` that asked.
+ */
+export function onToastHold(state: ToastState, event: Event): void {
+  const clock = clockOf(state);
+  const reason = HOLD_REASON[event.type] ?? event.type;
+  if (clock.timer !== null) {
+    clock.remaining = Math.max(1, clock.remaining - (Date.now() - clock.startedAt));
+  }
+  clock.holds.add(reason);
+  park(clock);
+}
+
+/**
+ * Let the clock run again, if nothing else is holding it.
+ *
+ * @param state The toast's reactive state.
+ * @param event The `pointerleave`, `focusout` or `jx-toast-resume` that released it.
+ */
+export function onToastRelease(state: ToastState, event: Event): void {
+  if (staysInside(event)) {
+    return;
+  }
+  clockOf(state).holds.delete(HOLD_REASON[event.type] ?? event.type);
+  schedule(state);
+}
+
+/**
+ * The dismiss button.
+ *
+ * @param state The toast's reactive state.
+ * @param event The button's click.
+ */
+export function onToastDismiss(_state: ToastState, event: Event): void {
+  const host = ownerOf(event);
+  if (host) {
+    closeToast(host, "dismissed");
+  }
+}
+
+/**
+ * A click on the recovery control the consumer slotted in.
+ *
+ * The click is NOT stopped: the control is the event's target, so its own handler has already run,
+ * and a host listening above the toast is entitled to hear it. What the element adds is the
+ * retirement — an answer that has been given is not still being asked, and a toast that stayed
+ * after its one recovery control was used would be a second thing to dismiss.
+ *
+ * @param state The toast's reactive state.
+ * @param event The click, from inside the `action` slot.
+ */
+export function onToastAction(_state: ToastState, event: Event): void {
+  const host = ownerOf(event);
+  if (host) {
+    closeToast(host, "action");
+  }
+}