@wello-dev/notifications 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+import * as react from 'react';
+import { ReactNode, MouseEvent, CSSProperties, SVGProps } from 'react';
+
+/** `'blue-600'`, `'blue'` (= 500), or any CSS color. */
+type ToastColor = string;
+/** Resolves a Tailwind name (`'blue-600'`) to its hex value; any other CSS color is returned as is. */
+declare function resolveColor(color: ToastColor): string;
+
+type ToastType = "default" | "success" | "error" | "warning" | "info" | "loading";
+type ToastId = string | number;
+/** `start` / `end` follow the toaster direction: `bottom-start` is bottom-left in LTR, bottom-right in RTL. */
+type ToastPosition = "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+type ToastStylesNames = "toast" | "icon" | "content" | "title" | "description" | "actions" | "action" | "cancel" | "closeButton" | "progress";
+type ToastClassNames = Partial<Record<ToastStylesNames, string>>;
+type ToastStyles = Partial<Record<ToastStylesNames, CSSProperties>>;
+interface ToastAction {
+    label: ReactNode;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /** Close the toast after the click. Default: true */
+    closeOnClick?: boolean;
+}
+interface ToastOptions {
+    /** Pass an existing id to replace that toast in place */
+    id?: ToastId;
+    /** Bold first line; defaults to the message */
+    title?: ReactNode;
+    /** Second line under the title */
+    description?: ReactNode;
+    /** Milliseconds before it closes, or `false` to stay until closed. Default: per type (toaster `duration`) */
+    duration?: number | false;
+    /** Alias of `duration` */
+    autoClose?: number | false;
+    /** Custom icon, or `false` for none */
+    icon?: ReactNode | false;
+    /** Accent color: Tailwind name (`'violet-600'`) or any CSS color. Default: per type */
+    color?: ToastColor;
+    /** Main button, e.g. Undo */
+    action?: ToastAction;
+    /** Secondary button */
+    cancel?: ToastAction;
+    /** Close button and swipe to dismiss. Default: true (false for loading toasts) */
+    dismissible?: boolean;
+    /** Shows the remaining time as a bar. Default: toaster `progress` */
+    progress?: boolean;
+    /** Announced right away by screen readers (`role="alert"`). Default: true for errors */
+    important?: boolean;
+    /**
+     * Plays a sound when shown (and when a loading toast settles): `true` for the built-in sound
+     * of its type, a built-in name (`'message'`, `'critical'`, …) or a sound file URL
+     */
+    sound?: boolean | string;
+    /** Overrides the toaster position for this toast */
+    position?: ToastPosition;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: ToastClassNames;
+    styles?: ToastStyles;
+    /** Called when it closes for any reason */
+    onClose?: (toast: ToastRecord) => void;
+    /** Called when it closes because its time ran out */
+    onAutoClose?: (toast: ToastRecord) => void;
+    /** Called when it appears */
+    onOpen?: (toast: ToastRecord) => void;
+}
+interface ToastRecord extends Omit<ToastOptions, "id" | "autoClose"> {
+    id: ToastId;
+    type: ToastType;
+    /** Fully custom content (`toast.custom`); replaces the built-in layout */
+    render?: (toast: ToastRecord) => ReactNode;
+    /** Changes on every update, so timers restart */
+    version: number;
+    createdAt: number;
+    /** `false` while it animates out */
+    open: boolean;
+}
+type ToastContent = ReactNode;
+
+/** A promise, or a function that starts one (so it runs only when the toast is shown). */
+type PromiseSource<T> = Promise<T> | (() => Promise<T>);
+interface PromiseMessages<T> {
+    loading: ToastContent;
+    success: ToastContent | ((data: T) => ToastContent);
+    error: ToastContent | ((error: unknown) => ToastContent);
+    /** Called after success or error */
+    finally?: () => void;
+}
+declare function promise<T>(source: PromiseSource<T>, messages: PromiseMessages<T>, options?: ToastOptions): Promise<T>;
+/**
+ * Changes an open toast. Pass a message to replace its text, options to change anything else
+ * (including `type` through `toast.success(…, { id })`). Returns false when it is already gone.
+ */
+declare function update(id: ToastId, changes: ToastContent | (ToastOptions & {
+    type?: ToastType;
+})): boolean;
+/**
+ * Shows a toast. Needs one `<Toaster />` somewhere in the app.
+ *
+ * @example
+ * toast.success("Saved");
+ * toast.error("Upload failed", { description: "The file is too large" });
+ * const id = toast.loading("Sending…"); toast.success("Sent", { id });
+ * await toast.promise(save(), { loading: "Saving…", success: "Saved", error: "Could not save" });
+ */
+declare const toast: ((message: ToastContent, options?: ToastOptions) => ToastId) & {
+    success: (message: ToastContent, options?: ToastOptions) => ToastId;
+    error: (message: ToastContent, options?: ToastOptions) => ToastId;
+    /** Same as `error` */
+    danger: (message: ToastContent, options?: ToastOptions) => ToastId;
+    warning: (message: ToastContent, options?: ToastOptions) => ToastId;
+    info: (message: ToastContent, options?: ToastOptions) => ToastId;
+    loading: (message: ToastContent, options?: ToastOptions) => ToastId;
+    /** Same as `toast()` */
+    message: (message: ToastContent, options?: ToastOptions) => ToastId;
+    /** Fully custom content; `render` gets the toast (use `toast.dismiss(t.id)` to close it). */
+    custom: (render: (toast: ToastRecord) => ReactNode, options?: ToastOptions) => ToastId;
+    promise: typeof promise;
+    update: typeof update;
+    /** Closes one toast, or all of them without an id */
+    dismiss: (id?: ToastId) => void;
+    /** Same as `dismiss` */
+    close: (id?: ToastId) => void;
+    /** Closes every toast */
+    clear: () => void;
+    /** Stops every timer, e.g. while a dialog is open */
+    pauseAll: () => void;
+    resumeAll: () => void;
+    /** `true` while the toast is open */
+    isActive: (id: ToastId) => boolean;
+};
+
+type Listener = () => void;
+interface ToastState {
+    /** Newest first; closed toasts stay until their exit animation ends */
+    toasts: ToastRecord[];
+    /** Set by `toast.pauseAll()` */
+    paused: boolean;
+}
+/** Shared toast state, readable with `useSyncExternalStore`. */
+declare const toastStore: {
+    getState: () => ToastState;
+    subscribe(listener: Listener): () => void;
+    /** `true` when at least one `<Toaster>` is mounted */
+    hasToaster: () => boolean;
+    nextId: () => string;
+    /** Adds a toast, or replaces the open one with the same id. */
+    upsert(record: Omit<ToastRecord, "version" | "createdAt" | "open">): ToastId;
+    /** Merges changes into an open toast. Returns false when there is none with this id. */
+    patch(id: ToastId, changes: Partial<ToastRecord>): boolean;
+    /** Starts closing one toast, or all of them. */
+    dismiss(id?: ToastId, reason?: "close" | "auto"): void;
+    /** Removes a toast right away (after its exit animation). */
+    remove(id: ToastId): void;
+    setPaused(paused: boolean): void;
+    /** Test helper: forget every toast. */
+    reset(): void;
+};
+
+/** Open toasts, newest first; for badges or your own notification UI. */
+declare function useToasts(): ToastRecord[];
+
+interface ToasterLabels {
+    /** Name of the notifications region for screen readers */
+    region: string;
+    close: string;
+}
+type ToasterLocale = "en" | "ar";
+declare function resolveLabels(locale?: ToasterLocale, overrides?: Partial<ToasterLabels>): ToasterLabels;
+
+type ToasterTheme = "light" | "dark" | "system";
+interface ToasterProps {
+    /** Default: 'bottom-start' (bottom-left in LTR, bottom-right in RTL) */
+    position?: ToastPosition;
+    /** `'auto'` follows `<html dir>`. Default: 'auto' */
+    dir?: "ltr" | "rtl" | "auto";
+    /** Toasts shown at once per position; the rest wait their turn. Default: 4 */
+    limit?: number;
+    /** Default time on screen in ms. Default: 4000 */
+    duration?: number;
+    /** Per-type time on screen. Default: error 5500, warning 5000, loading until closed */
+    durations?: Partial<Record<ToastType, number | false>>;
+    /** Per-type accent colors: Tailwind names (`'emerald-600'`) or CSS colors */
+    colors?: Partial<Record<ToastType, ToastColor>>;
+    /** Per-type icons; `null` hides one */
+    icons?: Partial<Record<ToastType, ReactNode>>;
+    /** Close button on dismissible toasts. Default: true */
+    closeButton?: boolean;
+    /** Remaining-time bar on every toast. Default: false */
+    progress?: boolean;
+    /** Swipe sideways to dismiss. Default: true */
+    swipe?: boolean;
+    /** Stop timers while hovered or focused. Default: true */
+    pauseOnHover?: boolean;
+    /** Stop timers while the tab is hidden. Default: true */
+    pauseWhenPageHidden?: boolean;
+    /** Sound for every toast: `true` for the built-in sound of each type, a built-in name or a URL. Default: false */
+    sound?: boolean | string;
+    /**
+     * Default: light, switching to dark under a `.dark` / `[data-theme="dark"]` ancestor.
+     * `'system'` follows the OS setting
+     */
+    theme?: ToasterTheme;
+    /** Toast width. Default: 390 */
+    width?: number | string;
+    /** Space between toasts. Default: 12 */
+    gap?: number;
+    /** Distance from the screen edges. Default: 16 */
+    offset?: number | string;
+    /** Default: 11000 */
+    zIndex?: number;
+    /** Built-in texts. Default: 'en' */
+    locale?: ToasterLocale;
+    labels?: Partial<ToasterLabels>;
+    /** Classes and styles for the parts of every toast */
+    classNames?: ToastClassNames & {
+        toaster?: string;
+    };
+    styles?: ToastStyles & {
+        toaster?: CSSProperties;
+    };
+    /** Class on each list of toasts */
+    className?: string;
+    style?: CSSProperties;
+    /** Where to render. Default: document.body */
+    container?: Element | null;
+}
+/**
+ * Renders the toasts. Mount it once, near the root of the app.
+ *
+ * @example
+ * <Toaster />
+ * <Toaster position="top-center" locale="ar" progress />
+ */
+declare function Toaster(props: ToasterProps): react.ReactPortal | null;
+
+type IconProps = SVGProps<SVGSVGElement>;
+declare const SuccessIcon: (props: IconProps) => react.JSX.Element;
+declare const ErrorIcon: (props: IconProps) => react.JSX.Element;
+declare const WarningIcon: (props: IconProps) => react.JSX.Element;
+declare const InfoIcon: (props: IconProps) => react.JSX.Element;
+declare const LoadingIcon: (props: IconProps) => react.JSX.Element;
+declare const CloseIcon: (props: IconProps) => react.JSX.Element;
+
+interface TabNotificationsOptions {
+    /** Title with unread items. Default: `(count) title`, `(99+) title` above 99 */
+    formatTitle?: (count: number, title: string) => string;
+    /** Color of the favicon dot. Default: red-500 */
+    dotColor?: string;
+    /** Add the dot to the favicon while there are unread items. Default: true */
+    favicon?: boolean;
+}
+interface FlashTitleOptions {
+    /** Milliseconds between swaps. Default: 1500 */
+    interval?: number;
+    /** Stop when the user comes back to the tab. Default: true */
+    stopOnFocus?: boolean;
+}
+interface TabNotifications {
+    /** Shows the count in the title and a dot on the favicon; 0 clears both */
+    setUnreadCount(count: number): void;
+    getUnreadCount(): number;
+    /** Alternates the title with a message until `stopFlashing` (or the tab is focused) */
+    flashTitle(message: string, options?: FlashTitleOptions | number): void;
+    stopFlashing(): void;
+    isFlashing(): boolean;
+    /** Restores the original title and favicon */
+    reset(): void;
+}
+/**
+ * Unread count in the tab title, a dot on the favicon, and a flashing title for urgent alerts.
+ * Safe to create on the server; it touches `document` only when used.
+ *
+ * @example
+ * const tab = createTabNotifications();
+ * tab.setUnreadCount(5);          // "(5) My app" + red dot
+ * tab.flashTitle("🔴 New order"); // until the user looks at the tab
+ */
+declare function createTabNotifications(options?: TabNotificationsOptions): TabNotifications;
+/** Shared instance with the default options. */
+declare const tabNotifications: TabNotifications;
+
+type NotificationPriority = "critical" | "high" | "normal" | "low";
+/** Built-in sounds, synthesized in the browser (no files to host). */
+type NotificationSoundName = "success" | "error" | "warning" | "info" | "message" | "critical" | "pop";
+interface PlaySoundOptions {
+    /** 0–1. Default: 0.7 */
+    volume?: number;
+    /**
+     * Built-in sound played when there is no URL or it can't play (missing file, autoplay
+     * blocked before the first click). `false` for silence. Default: 'info'
+     */
+    fallback?: NotificationSoundName | NotificationPriority | false;
+}
+/**
+ * Schedules a built-in sound on any audio context (also an `OfflineAudioContext`, to render it).
+ * Returns its length in seconds.
+ */
+declare function scheduleSound(ctx: BaseAudioContext, name: NotificationSoundName | NotificationPriority, volume?: number, when?: number): number;
+/**
+ * Plays a built-in sound. Silent where audio isn't available.
+ *
+ * @example
+ * playSound("success");
+ * playSound("critical", { volume: 1 });
+ */
+declare function playSound(name?: NotificationSoundName | NotificationPriority, options?: {
+    volume?: number;
+}): void;
+/** Plays the built-in sound for a priority (`critical`, `high`, `normal`, `low`) or a sound name. */
+declare function playTone(priority?: NotificationPriority | NotificationSoundName, volume?: number): void;
+/** Names of the built-in sounds. */
+declare const NOTIFICATION_SOUNDS: NotificationSoundName[];
+/**
+ * Plays a sound file (decoded once, then cached) or a built-in sound by name, falling back
+ * to a built-in sound. Never throws.
+ *
+ * @example
+ * playNotificationSound("/sounds/notification.mp3");
+ * playNotificationSound("message");
+ * playNotificationSound(undefined, { fallback: "critical" }); // built-in only
+ */
+declare function playNotificationSound(url?: string, options?: PlaySoundOptions): Promise<void>;
+
+export { CloseIcon, ErrorIcon, type FlashTitleOptions, InfoIcon, LoadingIcon, NOTIFICATION_SOUNDS, type NotificationPriority, type NotificationSoundName, type PlaySoundOptions, type PromiseMessages, type PromiseSource, SuccessIcon, type TabNotifications, type TabNotificationsOptions, type ToastAction, type ToastClassNames, type ToastColor, type ToastContent, type ToastId, type ToastOptions, type ToastPosition, type ToastRecord, type ToastState, type ToastStyles, type ToastStylesNames, type ToastType, Toaster, type ToasterLabels, type ToasterLocale, type ToasterProps, type ToasterTheme, WarningIcon, createTabNotifications, playNotificationSound, playSound, playTone, resolveColor, resolveLabels, scheduleSound, tabNotifications, toast, toastStore, useToasts };