@enigmax/primitives 0.20.0 → 0.22.0

package/src/react/toast/types.ts

@@ -0,0 +1,193 @@
+import React from "react";
+
+export type ToastTypes = "normal" | "action" | "success" | "info" | "warning" | "error" | "loading" | "default";
+
+export type PromiseT<Data = any> = Promise<Data> | (() => Promise<Data>);
+
+export type PromiseTResult<Data = any> = string | React.ReactNode | ((data: Data) => React.ReactNode | string | Promise<React.ReactNode | string>);
+
+export type PromiseExternalToast = Omit<ExternalToast, "description">;
+
+export type PromiseData<ToastData = any> = PromiseExternalToast & {
+    loading?: string | React.ReactNode;
+    success?: PromiseTResult<ToastData>;
+    error?: PromiseTResult;
+    description?: PromiseTResult;
+    finally?: () => void | Promise<void>;
+};
+
+export interface ToastClassnames {
+    toast?: string;
+    title?: string;
+    description?: string;
+    loader?: string;
+    closeButton?: string;
+    cancelButton?: string;
+    actionButton?: string;
+    success?: string;
+    error?: string;
+    info?: string;
+    warning?: string;
+    loading?: string;
+    default?: string;
+    content?: string;
+    icon?: string;
+}
+
+export interface ToastIcons {
+    success?: React.ReactNode;
+    info?: React.ReactNode;
+    warning?: React.ReactNode;
+    error?: React.ReactNode;
+    loading?: React.ReactNode;
+    close?: React.ReactNode;
+}
+
+export interface Action {
+    label: React.ReactNode;
+    onClick: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
+    actionButtonStyle?: React.CSSProperties;
+}
+
+export interface ToastT {
+    id: number | string;
+    title?: (() => React.ReactNode) | React.ReactNode;
+    type?: ToastTypes;
+    icon?: React.ReactNode;
+    jsx?: React.ReactNode;
+    richColors?: boolean;
+    invert?: boolean;
+    closeButton?: boolean;
+    dismissible?: boolean;
+    description?: (() => React.ReactNode) | React.ReactNode;
+    duration?: number;
+    delete?: boolean;
+    action?: Action | React.ReactNode;
+    cancel?: Action | React.ReactNode;
+    onDismiss?: (toast: ToastT) => void;
+    onAutoClose?: (toast: ToastT) => void;
+    promise?: PromiseT;
+    cancelButtonStyle?: React.CSSProperties;
+    actionButtonStyle?: React.CSSProperties;
+    style?: React.CSSProperties;
+    unstyled?: boolean;
+    className?: string;
+    classNames?: ToastClassnames;
+    descriptionClassName?: string;
+    position?: Position;
+}
+
+export function isAction(action: Action | React.ReactNode): action is Action {
+    return (action as Action).label !== undefined;
+}
+
+export type Position = "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center";
+export interface HeightT {
+    height: number;
+    toastId: number | string;
+    position: Position;
+}
+
+interface ToastOptions {
+    className?: string;
+    closeButton?: boolean;
+    descriptionClassName?: string;
+    style?: React.CSSProperties;
+    cancelButtonStyle?: React.CSSProperties;
+    actionButtonStyle?: React.CSSProperties;
+    duration?: number;
+    unstyled?: boolean;
+    classNames?: ToastClassnames;
+}
+
+type Offset =
+    | {
+        top?: string | number;
+        right?: string | number;
+        bottom?: string | number;
+        left?: string | number;
+    }
+    | string
+    | number;
+
+export interface ToasterProps {
+    invert?: boolean;
+    theme?: "light" | "dark" | "system";
+    position?: Position;
+    hotkey?: string[];
+    richColors?: boolean;
+    expand?: boolean;
+    duration?: number;
+    gap?: number;
+    visibleToasts?: number;
+    closeButton?: boolean;
+    toastOptions?: ToastOptions;
+    className?: string;
+    style?: React.CSSProperties;
+    offset?: Offset;
+    mobileOffset?: Offset;
+    dir?: "rtl" | "ltr" | "auto";
+    swipeDirections?: SwipeDirection[];
+    /**
+     * @deprecated Please use the `icons` prop instead:
+     * ```jsx
+     * <Toaster
+     *   icons={{ loading: <LoadingIcon /> }}
+     * />
+     * ```
+     */
+    loadingIcon?: React.ReactNode;
+    icons?: ToastIcons;
+    containerAriaLabel?: string;
+    pauseWhenPageIsHidden?: boolean;
+}
+
+export type SwipeDirection = "top" | "right" | "bottom" | "left";
+
+export interface ToastProps {
+    toast: ToastT;
+    toasts: ToastT[];
+    index: number;
+    swipeDirections?: SwipeDirection[];
+    expanded: boolean;
+    invert: boolean;
+    heights: HeightT[];
+    setHeights: React.Dispatch<React.SetStateAction<HeightT[]>>;
+    removeToast: (toast: ToastT) => void;
+    gap?: number;
+    position: Position;
+    visibleToasts: number;
+    expandByDefault: boolean;
+    closeButton: boolean;
+    interacting: boolean;
+    style?: React.CSSProperties;
+    cancelButtonStyle?: React.CSSProperties;
+    actionButtonStyle?: React.CSSProperties;
+    duration?: number;
+    className?: string;
+    unstyled?: boolean;
+    descriptionClassName?: string;
+    loadingIcon?: React.ReactNode;
+    classNames?: ToastClassnames;
+    icons?: ToastIcons;
+    closeButtonAriaLabel?: string;
+    pauseWhenPageIsHidden: boolean;
+    defaultRichColors?: boolean;
+}
+
+export enum SwipeStateTypes {
+    SwipedOut = "SwipedOut",
+    SwipedBack = "SwipedBack",
+    NotSwiped = "NotSwiped"
+}
+
+export type Theme = "light" | "dark";
+
+export interface ToastToDismiss {
+    id: number | string;
+    dismiss: boolean;
+}
+
+export type ExternalToast = Omit<ToastT, "id" | "type" | "title" | "jsx" | "delete" | "promise"> & {
+    id?: number | string;
+};

package/src/react/toaster.tsx

@@ -1,238 +1,126 @@
 "use client";
 
+import { TOAST_STYLES } from "@/react/toast/styles";
 import { defaultQueue } from "@/react/use-notifications";
+import { toast as vendorToast } from "@/react/toast/state";
+import { Toaster as VendorToaster } from "@/react/toast/index";
 import type { Notification, Notifications } from "@/core/notifications";
-import { useCallback, useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { useEffect, useLayoutEffect, useRef, type ReactNode } from "react";
+import type { ToasterProps as VendorToasterProps } from "@/react/toast/types";
 
 /**
- * `<Toaster />` - the stack, the movement and the gestures. No colours.
+ * `<Toaster />` - the toast stack, and the one component in this package that ships a look.
  *
- * The queue underneath already owns ordering, dedupe by key, sticky errors and timers that
- * HOLD while the tab is hidden. What this adds is everything you cannot express in a queue:
- * a toast that is on its way out is still on screen, a pointer resting on the stack must
- * stop the clock, and a swipe has to follow the finger before it decides anything.
+ * The implementation under `react/toast/` is vendored and deliberately unedited: it is the
+ * toast these projects already use, and a second one that merely resembled it would be a
+ * different thing on every screen. Two mechanical changes were unavoidable to make it a
+ * library - the `cn` helper became a local file rather than a path alias, and the
+ * `import "./styles.css"` became the injection below, because a package cannot assume its
+ * consumer has a CSS-capable bundler.
  *
- * Every part carries a data attribute, so the theme is a stylesheet you own. `enigma add
- * toast --copy` writes one.
+ * WHY IT SHIPS STYLES. Everywhere else here a missing stylesheet gives you an unstyled
+ * component you can see and fix. A toast renders at the edge of the screen, stacked and
+ * animated, so the same omission gives you a pile of text in a corner - and "remember to
+ * import the CSS" is a footgun for something that appears once every few minutes. The sheet
+ * is injected once and PREPENDED to `<head>`, so anything the document already has outranks
+ * it by source order without a single `!important`; `styles={false}` turns it off, and
+ * `@enigmax/primitives/toast.css` is the same sheet for anyone who prefers the import.
  */
 
-export type ToastPosition =
-    | "top-left" | "top-center" | "top-right"
-    | "bottom-left" | "bottom-center" | "bottom-right";
+let injected = false;
 
-export interface ToasterProps {
-    /** Which queue to render. The shared one by default. */
-    queue?: Notifications;
-    position?: ToastPosition;
-    /**
-     * How long the exit animation lasts, in ms. The node stays mounted for exactly this
-     * long after it leaves the queue - a toast that vanishes the instant it is dismissed
-     * cannot animate out, and that is the only reason this component keeps its own list.
-     */
-    exitDuration?: number;
-    /** Px a toast must travel before the release dismisses it. */
-    swipeThreshold?: number;
-    /** Render a toast yourself. The default renders title, body and the action. */
-    children?: (notification: Notification, controls: ToastControls) => ReactNode;
-    /** Accessible name for the region. */
-    label?: string;
-    className?: string;
-    style?: CSSProperties;
-}
-
-export interface ToastControls {
-    dismiss: () => void;
+function injectStyles(): void {
+    if (injected || typeof document === "undefined") return;
+    injected = true;
+    if (document.querySelector("[data-enigma-toast-styles]")) return;
+    const element = document.createElement("style");
+    element.setAttribute("data-enigma-toast-styles", "");
+    element.textContent = TOAST_STYLES;
+    document.head.prepend(element);
 }
 
-interface Rendered {
-    notification: Notification;
-    /** Set once it has left the queue and is animating out. */
-    leaving: boolean;
+export interface ToasterProps extends VendorToasterProps {
+    /**
+     * Inject the stylesheet. On by default - see the note above. `false` leaves the markup
+     * bare for a theme of your own.
+     */
+    styles?: boolean;
+    /**
+     * A notification QUEUE to render, alongside anything raised with `toast()`.
+     *
+     * This is the bridge for `useNotifications().notify()`, which predates the vendored
+     * component: everything already written against the queue keeps working, and both APIs
+     * end up in one stack rather than in two competing ones. `null` unsubscribes.
+     */
+    queue?: Notifications | null;
 }
 
-/** Swipe follows the edge the stack is pinned to, so a toast never slides across the page. */
-function swipeAxis(position: ToastPosition): { axis: "x" | "y"; sign: number; } {
-    if (position.endsWith("-center")) return { axis: "y", sign: position.startsWith("top") ? -1 : 1 };
-    return { axis: "x", sign: position.endsWith("-left") ? -1 : 1 };
-}
+export function Toaster({ styles = true, queue = defaultQueue, ...props }: ToasterProps): ReactNode {
+    // Before paint: a sheet applied after the first frame shows the toast unstyled first.
+    useLayoutEffect(() => { if (styles) injectStyles(); }, [styles]);
 
-export function Toaster({
-    queue = defaultQueue,
-    position = "bottom-right",
-    exitDuration = 200,
-    swipeThreshold = 60,
-    children,
-    label = "Notifications",
-    className,
-    style
-}: ToasterProps): ReactNode {
-    // Seeded from the queue rather than empty: a notify() that happened before this mounted
-    // - during a redirect, or from a module that runs early - would otherwise be invisible
-    // for a frame. On a server the queue is empty, so this still renders nothing there.
-    const [rendered, setRendered] = useState<Rendered[]>(
-        () => queue.items.map((notification) => ({ notification, leaving: false }))
-    );
-    const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>());
+    /** Queue id -> the toast raised for it, so a dismissal reaches the right one. */
+    const forwarded = useRef(new Map<string, string | number>());
 
     useEffect(() => {
+        if (!queue) return;
         const sync = (items: readonly Notification[]): void => {
-            setRendered((current) => {
-                const live = new Map(items.map((item) => [item.id, item]));
-                const kept = current.map((entry) => {
-                    const still = live.get(entry.notification.id);
-                    if (still) return { notification: still, leaving: false };
-                    if (entry.leaving) return entry;
-
-                    // It has just left the queue: hold the node for the exit animation, and
-                    // only then drop it. Without this the stack jumps.
-                    const timer = setTimeout(() => {
-                        timers.current.delete(entry.notification.id);
-                        setRendered((later) => later.filter((row) => row.notification.id !== entry.notification.id));
-                    }, exitDuration);
-                    timers.current.set(entry.notification.id, timer);
-                    return { ...entry, leaving: true };
-                });
-
-                const seen = new Set(kept.map((entry) => entry.notification.id));
-                const added = items.filter((item) => !seen.has(item.id)).map((item) => ({ notification: item, leaving: false }));
-                return [...kept, ...added];
-            });
+            const live = new Set(items.map((item) => item.id));
+
+            for (const item of items) {
+                if (forwarded.current.has(item.id)) continue;
+                forwarded.current.set(item.id, raise(item));
+            }
+            // Dismissed in the queue is dismissed on screen: the queue owns its own timers,
+            // and a toast that outlived the item behind it would be showing a state that no
+            // longer exists.
+            for (const [id, toastId] of forwarded.current) {
+                if (live.has(id)) continue;
+                vendorToast.dismiss(toastId);
+                forwarded.current.delete(id);
+            }
         };
 
         sync(queue.items);
         return queue.subscribe(sync);
-    }, [queue, exitDuration]);
+    }, [queue]);
 
-    // Clearing on unmount only: a timer per exiting toast is cheap, and clearing them on
-    // every render would cancel the exit that is currently running.
-    useEffect(() => {
-        const pending = timers.current;
-        return () => {
-            for (const timer of pending.values()) clearTimeout(timer);
-            pending.clear();
-        };
-    }, []);
-
-    if (!rendered.length) return null;
-
-    return (
-        <section
-            aria-label={label}
-            data-enigma-toaster=""
-            data-position={position}
-            className={className}
-            style={style}
-            // A pointer resting on the stack stops every clock, so a message cannot expire
-            // while it is being read. Focus counts too, for anyone using a keyboard.
-            onPointerEnter={() => queue.pause()}
-            onPointerLeave={() => queue.resume()}
-            onFocusCapture={() => queue.pause()}
-            onBlurCapture={() => queue.resume()}
-        >
-            {rendered.map((entry, index) => (
-                <Toast
-                    key={entry.notification.id}
-                    entry={entry}
-                    index={rendered.length - 1 - index}
-                    position={position}
-                    swipeThreshold={swipeThreshold}
-                    onDismiss={() => queue.dismiss(entry.notification.id)}
-                    render={children}
-                />
-            ))}
-        </section>
-    );
+    return <VendorToaster {...props} />;
 }
 
-interface ToastProps {
-    entry: Rendered;
-    /** 0 is the front of the stack. Drives the offset and scale in the theme. */
-    index: number;
-    position: ToastPosition;
-    swipeThreshold: number;
-    onDismiss: () => void;
-    render?: (notification: Notification, controls: ToastControls) => ReactNode;
+/** One queue item, as the vendored toast API expects it. */
+function raise(item: Notification): string | number {
+    const options = {
+        description: item.body,
+        // The queue already counts down and removes the item; leaving the toast's own timer
+        // running as well would race it, and the shorter of the two would win at random.
+        duration: Infinity,
+        action: item.action
+            ? { label: item.action.label, onClick: () => item.action?.onSelect() }
+            : undefined
+    };
+
+    switch (item.tone) {
+        case "success": return vendorToast.success(item.title, options);
+        case "error": return vendorToast.error(item.title, options);
+        case "warning": return vendorToast.warning(item.title, options);
+        case "info": return vendorToast.info(item.title, options);
+        case "loading": return vendorToast.loading(item.title, options);
+        default: return vendorToast(item.title, options);
+    }
 }
 
-function Toast({ entry, index, position, swipeThreshold, onDismiss, render }: ToastProps): ReactNode {
-    const { notification, leaving } = entry;
-    const [offset, setOffset] = useState(0);
-    const [swiping, setSwiping] = useState(false);
-    const start = useRef(0);
-    const { axis, sign } = swipeAxis(position);
-
-    const onPointerDown = useCallback((event: React.PointerEvent<HTMLElement>) => {
-        // Not on the buttons: a press on "Undo" is a press, not the start of a drag.
-        if ((event.target as HTMLElement).closest("button")) return;
-        if (event.pointerType === "mouse" && event.button !== 0) return;
-        (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
-        start.current = axis === "x" ? event.clientX : event.clientY;
-        setSwiping(true);
-    }, [axis]);
-
-    const onPointerMove = useCallback((event: React.PointerEvent<HTMLElement>) => {
-        if (!swiping) return;
-        const delta = (axis === "x" ? event.clientX : event.clientY) - start.current;
-        // Only towards the edge it is pinned to. Dragging the other way does nothing, so a
-        // scroll or a misread gesture cannot pull the toast into the middle of the page.
-        setOffset(sign > 0 ? Math.max(0, delta) : Math.min(0, delta));
-    }, [swiping, axis, sign]);
-
-    const onPointerUp = useCallback(() => {
-        if (!swiping) return;
-        setSwiping(false);
-        if (Math.abs(offset) >= swipeThreshold) {
-            onDismiss();
-            return;
-        }
-        setOffset(0);   // Under the threshold it springs back, so nothing is lost by accident.
-    }, [swiping, offset, swipeThreshold, onDismiss]);
+/** The vendored API, which is the direct way to raise one. */
+export { toast } from "@/react/toast/state";
+export { useSonner } from "@/react/toast/index";
+export type { ToastT, ExternalToast, ToastClassnames, Action } from "@/react/toast/types";
 
-    const controls: ToastControls = { dismiss: onDismiss };
-
-    return (
-        <article
-            data-enigma-toast=""
-            data-tone={notification.tone}
-            data-state={leaving ? "leaving" : "open"}
-            data-index={index}
-            data-front={index === 0 ? "" : undefined}
-            data-swiping={swiping ? "" : undefined}
-            // An error interrupts; anything else waits its turn rather than talking over
-            // whatever a screen reader is in the middle of.
-            role={notification.tone === "error" ? "alert" : "status"}
-            aria-live={notification.tone === "error" ? "assertive" : "polite"}
-            tabIndex={0}
-            onKeyDown={(event) => { if (event.key === "Escape") onDismiss(); }}
-            onPointerDown={onPointerDown}
-            onPointerMove={onPointerMove}
-            onPointerUp={onPointerUp}
-            onPointerCancel={onPointerUp}
-            style={{
-                // Read by the theme, so the transform stays the stylesheet's decision.
-                "--enigma-toast-swipe": `${offset}px`,
-                "--enigma-toast-index": index
-            } as CSSProperties}
-        >
-            {render
-                ? render(notification, controls)
-                : (
-                    <>
-                        <p data-enigma-toast-title="">{notification.title}</p>
-                        {notification.body && <p data-enigma-toast-body="">{notification.body}</p>}
-                        {notification.action && (
-                            <button
-                                type="button"
-                                data-enigma-toast-action=""
-                                onClick={() => {
-                                    notification.action?.onSelect();
-                                    if (notification.action?.dismiss !== false) onDismiss();
-                                }}
-                            >{notification.action.label}</button>
-                        )}
-                        <button type="button" data-enigma-toast-close="" aria-label="Dismiss" onClick={onDismiss}>&times;</button>
-                    </>
-                )}
-        </article>
-    );
-}
+/**
+ * The queue, from the entry that renders it.
+ *
+ * `@enigmax/primitives/react/toast` is where somebody looks for both halves - mounting the
+ * stack and telling it something - and sending them to a second subpath for the second half
+ * is the kind of split that makes an import line something to look up.
+ */
+export { useNotifications, createNotificationQueue, defaultQueue } from "@/react/use-notifications";
+export type { Notification, NotificationInput, NotificationTone, NotificationAction, Notifications } from "@/core/notifications";