@galaxy-io/dls 1.6.1 → 2.0.0

package/dist/toast/useToast.d.ts

@@ -1,8 +1,142 @@
 /**
- * Returns `{ showToast, hideToast }`. `showToast` returns the new toast's id,
- * which you can pass to `hideToast` to dismiss that one early — call it with no
- * argument to clear them all.
+ * `useToast()`: shows and dismisses toasts from anywhere under `GalaxyProvider` (which mounts
+ * `ToastProvider`). `toast(options | header)` returns the toast's id; `toast.promise` follows a
+ * promise with a loading toast that turns into a success or error toast; `dismiss(id?)` removes
+ * one toast or all of them. Both are stable for the provider's lifetime.
  *
- * Throws when called outside a `ToastProvider`.
+ * This module also owns the provider's context (the `useGalaxyTheme` precedent). Nothing here
+ * touches `window` or `document`; the store is created by `ToastProvider` in render-time state.
  */
-export declare const useToast: () => import("./ToastProvider").ToastContextProps;
+import type { Icon as PhosphorIcon } from "@phosphor-icons/react";
+import { type ReactNode } from "react";
+import type { Placement } from "../theme/enums.js";
+import type { ToastAction, ToastVariant } from "./Toast.js";
+/** Where a toast's region sits on the screen: the six `Placement` members that name an edge and an alignment. */
+export type ToastPlacement = Placement.TOP_START | Placement.TOP | Placement.TOP_END | Placement.BOTTOM_START | Placement.BOTTOM | Placement.BOTTOM_END;
+/** What `toast()` takes. */
+export interface ToastOptions {
+    /** The message. One short line. */
+    header: string;
+    /** Supporting text under the header. */
+    description?: ReactNode;
+    /** Severity. @default ToastVariant.PRIMARY */
+    variant?: ToastVariant;
+    /** Replaces the variant's icon. */
+    icon?: PhosphorIcon;
+    /** One action button; choosing it also dismisses the toast. */
+    action?: ToastAction;
+    /** Spinner in place of the icon; the toast does not time out while loading. @default false */
+    isLoading?: boolean;
+    /** Milliseconds the toast stays, counted while it is not paused. @default 5000 */
+    duration?: number;
+    /** Stay until dismissed; `duration` is ignored. @default false */
+    isPersistent?: boolean;
+    /** Screen region. @default Placement.BOTTOM_END */
+    placement?: ToastPlacement;
+    /** Id of a toast still shown, to update it in place; otherwise the id the new toast gets. */
+    id?: string;
+    /** Called once when the toast leaves for any reason: timer, ×, action, or `dismiss()`. */
+    onDismiss?: () => void;
+}
+/** What each phase of `toast.promise` shows: a header, full options, or (on settle) a function of the result. */
+export interface ToastPromiseOptions<T> {
+    /** Shown while pending, as a loading toast. */
+    loading: string | ToastOptions;
+    /** Shown when the promise fulfils, as `SUCCESS` unless the options say otherwise. */
+    success: string | ToastOptions | ((value: T) => string | ToastOptions);
+    /** Shown when the promise rejects, as `ERROR` unless the options say otherwise. */
+    error: string | ToastOptions | ((reason: unknown) => string | ToastOptions);
+}
+/** `toast()`, with `toast.promise`. */
+export interface ToastFunction {
+    /** Shows a toast and returns its id. */
+    (options: ToastOptions | string): string;
+    /** Shows a loading toast for `promise` and turns it into a success or error toast when it settles. Returns the id. */
+    promise: <T>(promise: Promise<T>, options: ToastPromiseOptions<T>) => string;
+}
+/** What `useToast()` returns. */
+export interface UseToastResult {
+    /** Shows a toast and returns its id; `toast.promise` follows a promise. */
+    toast: ToastFunction;
+    /** Dismisses one toast by id, or every toast when called with no id. */
+    dismiss: (id?: string) => void;
+}
+/** @internal Types the store behind ToastContext; apps use useToast. A toast's options with the defaults applied. */
+export interface ResolvedToastOptions {
+    /** The message. */
+    header: string;
+    /** Supporting text. */
+    description?: ReactNode;
+    /** Severity. */
+    variant: ToastVariant;
+    /** Replaces the variant's icon. */
+    icon?: PhosphorIcon;
+    /** The one action. */
+    action?: ToastAction;
+    /** Spinner in place of the icon; no timeout. */
+    isLoading: boolean;
+    /** Milliseconds the toast stays while not paused. */
+    duration: number;
+    /** Stays until dismissed. */
+    isPersistent: boolean;
+    /** Screen region. */
+    placement: ToastPlacement;
+    /** Called once when the toast leaves. */
+    onDismiss?: () => void;
+}
+/** @internal Types the store behind ToastContext; apps use useToast. One toast in the queue, as the viewport renders it. */
+export interface ToastEntry {
+    /** The toast's id (`toast-<n>` unless the options named one). */
+    id: string;
+    /** Its options, with the defaults applied. */
+    options: ResolvedToastOptions;
+    /** `false` from the moment it is dismissed until it is removed after its exit. */
+    isOpen: boolean;
+    /** Creation order; also the React key with the id, so a reused id remounts. */
+    sequence: number;
+}
+/** @internal Types the store behind ToastContext; apps use useToast. A message for the provider's live regions. */
+export interface ToastAnnouncement {
+    /** Which live region reads it. */
+    politeness: "polite" | "assertive";
+    /** The severity word ("Error"). */
+    label: string;
+    /** The toast's header. */
+    header: string;
+    /** The toast's description, rendered again inside the hidden region. */
+    description?: ReactNode;
+}
+/**
+ * @internal Read by ToastProvider; apps use useToast. The per-root toast store: the public
+ * `toast` / `dismiss` pair plus what the provider and its viewport subscribe to.
+ */
+export interface ToastContextValue extends UseToastResult {
+    /** The stable `{ toast, dismiss }` object `useToast()` returns. */
+    api: UseToastResult;
+    /** Subscribes to queue changes (`useSyncExternalStore`). */
+    subscribe: (listener: () => void) => () => void;
+    /** The current entries, oldest first. Changes identity on every queue change. */
+    getEntries: () => readonly ToastEntry[];
+    /** Whether a toast has ever been shown (the viewport loads with the first one). */
+    getHasHadEntries: () => boolean;
+    /** Subscribes to announcements. */
+    onAnnounce: (listener: (announcement: ToastAnnouncement) => void) => () => void;
+    /** Pauses (`true`) or resumes the timers of one region (pointer over it, focus inside it). */
+    setPlacementPaused: (placement: ToastPlacement, isPaused: boolean) => void;
+    /** Pauses (`true`) or resumes every timer (the tab is hidden). */
+    setHidden: (isHidden: boolean) => void;
+    /** Starts the timers (provider mounted). */
+    start: () => void;
+    /** Stops the timers, keeping each toast's remaining time (provider unmounted). */
+    stop: () => void;
+}
+/**
+ * @internal Read by ToastProvider; apps use useToast. The toast store of the nearest
+ * `ToastProvider`; `null` outside one.
+ */
+export declare const ToastContext: import("react").Context<ToastContextValue | null>;
+/**
+ * Returns `{ toast, dismiss }` for the nearest `ToastProvider` (mounted by `GalaxyProvider`).
+ * Throws when called outside one.
+ */
+export declare function useToast(): UseToastResult;

package/dist/toast/useToast.js

@@ -1,17 +1,19 @@
-import { ToastContext } from "./ToastProvider.js";
-import { useContext } from "react";
+import { createContext, useContext } from "react";
 //#region src/toast/useToast.ts
 /**
-* Returns `{ showToast, hideToast }`. `showToast` returns the new toast's id,
-* which you can pass to `hideToast` to dismiss that one early — call it with no
-* argument to clear them all.
-*
-* Throws when called outside a `ToastProvider`.
+* @internal Read by ToastProvider; apps use useToast. The toast store of the nearest
+* `ToastProvider`; `null` outside one.
 */
-var useToast = () => {
-	const context = useContext(ToastContext);
-	if (!context) throw new Error("useToast must be used within a ToastProvider");
-	return context;
-};
+var ToastContext = createContext(null);
+ToastContext.displayName = "ToastContext";
+/**
+* Returns `{ toast, dismiss }` for the nearest `ToastProvider` (mounted by `GalaxyProvider`).
+* Throws when called outside one.
+*/
+function useToast() {
+	const store = useContext(ToastContext);
+	if (store === null) throw new Error("useToast must be used inside GalaxyProvider (or ToastProvider)");
+	return store.api;
+}
 //#endregion
-export { useToast };
+export { ToastContext, useToast };