zabi-components 8.0.0 → 9.0.0

package/dist/molecules/Toaster.svelte.d.ts

@@ -1,6 +1,157 @@
-interface Props {
+import { type ToastDuration, type ToasterMode, type ToasterStrings, type ToastPauseChange } from "../util/toaster.js";
+import type { HTMLAttributes } from "svelte/elements";
+/**
+ * The stack of toasts, fixed to the bottom of the screen: in the corner
+ * from 640px up, across the width with 16px on each side below that.
+ *
+ * It keeps clear of what is at the bottom of a phone screen. The home
+ * indicator and a notch at the side are read from the safe-area insets
+ * (the page has to ask for them with `viewport-fit=cover`). Inside an
+ * `AppShell` the stack sits above the shell's tab bar, which the shell
+ * reports in `--app-shell-bottom-inset`. For anything else fixed to the
+ * bottom (a `BottomTabBar` on its own, a `StickyActionBar`, a
+ * `FloatingActionButton`), say how tall it is with
+ * `--toaster-bottom-offset` on the Toaster or any ancestor:
+ *
+ * ```svelte
+ * <Toaster style="--toaster-bottom-offset: 64px" />
+ * ```
+ *
+ * A `FloatingActionButton` is 56px with 16px under it: `72px` puts the
+ * stack above it.
+ *
+ * That offset is for what is on the page. Over a modal overlay (Modal,
+ * BottomSheet, SlideUp, Drawer) the stack minds the overlay instead: it
+ * never lies on the header, which holds the close button, nor on a
+ * footer pinned to the bottom, and the offset is not added on top. It
+ * sits above the panel when there is more room there, and otherwise
+ * between the header and the footer. Where the on-screen keyboard covers
+ * the page, the stack sits above the keyboard. It is never taller than
+ * the room it has: with more toasts than fit, it scrolls. With an
+ * overlay open, Tab goes from its last control into the toasts and back,
+ * and Escape in a toast returns focus to where it came from.
+ *
+ * A toast shows what it was pushed with: its `title`, its `message`
+ * under it, or the message alone.
+ *
+ * How long it stays is said in words, per toast (`pushToast({ duration:
+ * "short" })`) or for all of them here (`defaultDuration`): `"short"` is
+ * 3 seconds, for a few words that need no reading time ("Saved");
+ * anything a person has to read is `"medium"` (7 seconds) or `"long"`
+ * (14); what they have to act on, and an error, should stay:
+ * `"persistent"`. A number is milliseconds. A toast given no duration
+ * gets medium up to 120 characters of text, long up to 240, and stays
+ * beyond that; an error and a toast with an action stay until they are
+ * dismissed.
+ *
+ * Its timer stops while a mouse is over it, a finger is on it or focus
+ * is inside it, which is what lets a timed toast be read in the reader's
+ * own time (WCAG 2.2.1). A finger that lifts leaves it at least three
+ * seconds, so holding a short toast starts it again.
+ * `data-paused` on the toast says so, and `onpausechange` is called.
+ * A mouse holds the timer once it has moved over the toast, not when the
+ * toast comes up under a pointer that is at rest. A touch or a pen drags
+ * a toast away sideways (`swipeToDismiss`, on by default), and the close
+ * button stays as the way for a keyboard and a screen reader. A toast
+ * pushed with the id of one that is showing replaces it in place, and
+ * `max` limits how many show at once: the oldest toast that is timed
+ * (not an error, not one with an action) is the one that leaves.
+ *
+ * For a phone, `mode="auto"` makes the toast a snackbar below 640px: one
+ * row (two lines at most), one at a time, with its action beside its text
+ * and no stack. It sits directly above what is docked at the bottom, which
+ * it finds by itself: a `BottomTabBar`, a `StickyActionBar`, a
+ * `FloatingActionButton` and an `UnsavedChangesBar` that lie under it, and
+ * anything you name in `avoid` (the button a screen ends in). It comes out
+ * from behind that edge and goes back into it, on `--ease-standard`, with
+ * no movement under reduced motion, and lies over the page without moving
+ * it. Push a short confirmation with `closable: false` and it has no
+ * control and takes no taps.
+ *
+ * ```svelte
+ * <Toaster mode="auto" avoid="[data-primary-action]" />
+ * ```
+ *
+ * Every word the toaster says by itself is in `strings`:
+ *
+ * ```svelte
+ * <Toaster
+ *     strings={{
+ *         regionLabel: "Aviseringar",
+ *         dismiss: "Stäng aviseringen",
+ *         closesIn: (seconds) => `Stängs om ${seconds} sekunder.`,
+ *     }}
+ * />
+ * ```
+ */
+type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "role" | "aria-label"> & {
+    /**
+     * The words the toaster says by itself, for an app in another
+     * language: the region's name, the buttons' names, the sentence about
+     * the time left. What is left out keeps its English default.
+     */
+    strings?: Partial<ToasterStrings>;
+    /** Accessible name of the region. Wins over `strings.regionLabel`. */
+    "aria-label"?: string;
+    /**
+     * Shows the time a toast has left as a sentence under it, with a
+     * button that stops the timer. Without it the bar along the bottom of
+     * the toast shows the time, and the sentence is there for a screen
+     * reader only.
+     */
+    showCountdown?: boolean;
+    /**
+     * How long a toast stays when it was pushed without a `duration`, in
+     * place of `"medium"`: `"short"`, `"medium"`, `"long"`,
+     * `"persistent"` or milliseconds. An error and a toast with an action
+     * still stay until dismissed, a text of 121 to 240 characters still
+     * gets at least `"long"`, and a longer one still stays. A `duration`
+     * on the toast wins.
+     */
+    defaultDuration?: ToastDuration;
+    /**
+     * `"stack"` (default): the stack of toasts. `"snackbar"`: the compact
+     * form for a phone, at every width. `"auto"`: the snackbar below
+     * 640px, the stack from there up.
+     */
+    mode?: ToasterMode;
+    /**
+     * How many toasts show at once. The oldest one that is timed leaves
+     * when a newer one arrives; a toast that has to stay (an error, one
+     * with an action, `"persistent"`) is not dropped, so there can be more
+     * than this while they are showing. Default: no limit, and 1 in the
+     * snackbar.
+     */
+    max?: number;
+    /**
+     * A CSS selector for elements the stack must not lie on, in addition
+     * to the docked bars it finds by itself: the button a screen ends in.
+     * When one lies under the stack, the stack sits above it.
+     */
+    avoid?: string;
+    /**
+     * Draws the thin bar along the bottom of a toast that empties over its
+     * time. Unset: drawn, except under a confirmation in the snackbar that
+     * has nothing to press (pushed with `closable: false`), where it is
+     * left out. `false` leaves it out everywhere, `true` draws it
+     * everywhere; a toast's own `timeLine` wins. The sentence for a screen
+     * reader about the time left stays.
+     */
+    timeLine?: boolean;
+    /**
+     * Touch and pen drag a toast away sideways (and down, in the
+     * snackbar). Default `true`. A mouse does not drag; the close button
+     * is the way for a keyboard and a screen reader.
+     */
+    swipeToDismiss?: boolean;
+    /**
+     * Called when a pointer, a finger or focus starts or stops holding a
+     * toast's timer, with the toast's id. The same state is `data-paused`
+     * on the toast.
+     */
+    onpausechange?: (detail: ToastPauseChange) => void;
     class?: string;
-}
+};
 declare const Toaster: import("svelte").Component<Props, {}, "">;
 type Toaster = ReturnType<typeof Toaster>;
 export default Toaster;