lumatoast 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,366 @@
+type ToastType = "success" | "error" | "warning" | "info" | "loading" | "custom";
+type ToastTheme = "linear" | "aurora" | "vision" | "minimal" | "cupertino" | "material" | "terminal" | "github" | "cyberpunk";
+type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+/** Where the progress bar is rendered inside the card. */
+type ToastProgressPosition = "top" | "bottom";
+/** Enter animation style. */
+type ToastAnimationEnter = "slide" | "fade" | "scale" | "bounce" | "none";
+/** Exit animation style. */
+type ToastAnimationExit = "slide" | "fade" | "none";
+/** Global animation speed preset. */
+type ToastAnimationSpeed = "slow" | "normal" | "fast";
+/** Action button visual variant. */
+type ToastActionVariant = "solid" | "outline" | "ghost";
+interface ToastAction {
+    label: string;
+    onClick: () => void;
+    /** Visual style of the action button. Default: "solid" */
+    variant?: ToastActionVariant;
+}
+interface ToastOptions {
+    /** Stable id — useful for `toast.update()`. Auto-generated if omitted. */
+    id?: string;
+    /** Bold title text rendered above the description. */
+    title?: string;
+    /** Body text of the toast. */
+    description?: string;
+    /** Auto-dismiss delay in ms. Use `Infinity` to never auto-dismiss. Default: 4000 */
+    duration?: number;
+    /** Show the × close button. Default: true */
+    dismissible?: boolean;
+    /** Screen position of the toast. Default: "top-right" */
+    position?: ToastPosition;
+    /** Visual theme preset. Default: "linear" */
+    theme?: ToastTheme;
+    /** Action button shown inside the toast. */
+    action?: ToastAction;
+    /** Extra CSS class(es) added to the toast wrapper element. */
+    className?: string;
+    /**
+     * Inline styles applied to the toast card.
+     * Supports both regular CSS properties and CSS custom properties.
+     *
+     * @example
+     * style: { "--luma-bg": "#1a1a2e", borderRadius: "24px" }
+     */
+    style?: Record<string, string>;
+    /** Show the type icon. Default: true */
+    showIcon?: boolean;
+    /**
+     * Dismiss the toast when the user clicks anywhere on the card body.
+     * Default: false
+     */
+    closeOnClick?: boolean;
+    /** Where the progress bar is placed inside the card. Default: "bottom" */
+    progressPosition?: ToastProgressPosition;
+    /** Enter animation style. Default: "slide" */
+    animationEnter?: ToastAnimationEnter;
+    /** Exit animation style. Default: "slide" */
+    animationExit?: ToastAnimationExit;
+}
+interface ToastItem extends ToastOptions {
+    id: string;
+    type: ToastType;
+    title?: string;
+    description?: string;
+    action?: ToastAction;
+    duration: number;
+    dismissible: boolean;
+    position: ToastPosition;
+    theme: ToastTheme;
+    showIcon: boolean;
+    closeOnClick: boolean;
+    progressPosition: ToastProgressPosition;
+    animationEnter: ToastAnimationEnter;
+    animationExit: ToastAnimationExit;
+    createdAt: number;
+    visible: boolean;
+}
+interface ToastUpdateOptions {
+    type?: ToastType;
+    title?: string;
+    description?: string;
+    duration?: number;
+    dismissible?: boolean;
+    action?: ToastAction;
+    theme?: ToastTheme;
+    className?: string;
+    style?: Record<string, string>;
+    showIcon?: boolean;
+    progressPosition?: ToastProgressPosition;
+}
+interface PromiseToastOptions {
+    loading: ToastOptions;
+    success: ToastOptions;
+    error: ToastOptions;
+}
+
+type Listener<T> = (payload: T) => void;
+/**
+ * Tiny event emitter used internally by LumaToast.
+ */
+declare class EventEmitter<T> {
+    private listeners;
+    subscribe(listener: Listener<T>): () => void;
+    emit(payload: T): void;
+    clear(): void;
+}
+
+interface ToastConfig {
+    /** Default auto-dismiss duration in ms. Default: 4000 */
+    duration?: number;
+    /** Default screen position. Default: "top-right" */
+    position?: ToastPosition;
+    /** Default visual theme. Default: "linear" */
+    theme?: ToastTheme;
+    /** Default dismissible flag. Default: true */
+    dismissible?: boolean;
+    /** Maximum number of toasts visible at once. Default: 5 */
+    maxVisible?: number;
+    /** Show the type icon by default. Default: true */
+    showIcon?: boolean;
+    /** Dismiss on card body click by default. Default: false */
+    closeOnClick?: boolean;
+    /** Default progress bar placement. Default: "bottom" */
+    progressPosition?: ToastProgressPosition;
+    /** Default enter animation. Default: "slide" */
+    animationEnter?: ToastAnimationEnter;
+    /** Default exit animation. Default: "slide" */
+    animationExit?: ToastAnimationExit;
+    /**
+     * Global animation speed preset.
+     * Applies `--luma-duration-enter/exit/stack` CSS variables on <html>.
+     * Default: "normal"
+     */
+    animationSpeed?: ToastAnimationSpeed;
+}
+/**
+ * Set global defaults for all toasts.
+ * Per-toast options always override these.
+ *
+ * @example
+ * configure({
+ *   position: "bottom-right",
+ *   theme: "minimal",
+ *   duration: 3000,
+ *   progressPosition: "top",
+ *   animationEnter: "scale",
+ *   animationSpeed: "fast",
+ * });
+ */
+declare function configure(config: ToastConfig): void;
+declare class ToastManager {
+    private visible;
+    private queue;
+    readonly changes: EventEmitter<ToastItem[]>;
+    /**
+     * Returns all visible toasts.
+     */
+    getToasts(): ToastItem[];
+    /**
+     * Create a new toast.
+     */
+    create(type: ToastType, options?: ToastOptions): ToastItem;
+    /**
+     * Remove a toast by id.
+     */
+    dismiss(id: string): void;
+    /**
+     * Remove all visible and queued toasts.
+     */
+    dismissAll(): void;
+    /**
+     * Remove the most recently added visible toast.
+     */
+    dismissLatest(): void;
+    /**
+     * Update an existing toast by id.
+     * Works on both visible and queued toasts.
+     */
+    update(id: string, updates: ToastUpdateOptions): ToastItem | null;
+}
+declare const toastManager: ToastManager;
+
+declare const toast: {
+    /**
+     * Show a success toast.
+     */
+    success(message: string, options?: ToastOptions): ToastItem;
+    /**
+     * Show an error toast.
+     */
+    error(message: string, options?: ToastOptions): ToastItem;
+    /**
+     * Show a warning toast.
+     */
+    warning(message: string, options?: ToastOptions): ToastItem;
+    /**
+     * Show an info toast.
+     */
+    info(message: string, options?: ToastOptions): ToastItem;
+    /**
+     * Show a persistent loading toast that must be dismissed manually
+     * or converted via `toast.update()` / `toast.promise()`.
+     */
+    loading(message: string, options?: ToastOptions): ToastItem;
+    /**
+     * Show a fully custom toast.
+     * You control the title, description, action, theme, and position.
+     *
+     * @example
+     * toast.custom("Custom notification", { title: "Hey!", theme: "cyberpunk" });
+     */
+    custom(message: string, options?: ToastOptions): ToastItem;
+    /**
+     * Dismiss a toast by id.
+     */
+    dismiss(id: string): void;
+    /**
+     * Dismiss all visible and queued toasts.
+     */
+    dismissAll(): void;
+    /**
+     * Dismiss the most recently added visible toast.
+     */
+    dismissLatest(): void;
+    /**
+     * Update an existing toast's properties.
+     * Useful for transitioning a loading toast to success or error.
+     */
+    update(id: string, updates: ToastUpdateOptions): ToastItem | null;
+    /**
+     * Track a promise: show a loading toast, then auto-transition to
+     * success or error based on the promise outcome.
+     *
+     * @example
+     * toast.promise(fetch("/api/save"), {
+     *   loading: { description: "Saving..." },
+     *   success: { description: "Saved!" },
+     *   error:   { description: "Failed to save." }
+     * });
+     */
+    promise<T>(promise: Promise<T>, options: PromiseToastOptions): Promise<T>;
+    /**
+     * Subscribe to toast state changes.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * const unsub = toast.subscribe((toasts) => console.log(toasts));
+     * // later:
+     * unsub();
+     */
+    subscribe(listener: (toasts: ReturnType<typeof toastManager.getToasts>) => void): () => void;
+    /**
+     * Set global defaults for all toasts.
+     * Per-toast options always override these.
+     *
+     * @example
+     * toast.configure({ position: "bottom-right", theme: "minimal", duration: 3000 });
+     */
+    configure: typeof configure;
+};
+
+/**
+ * LumaToast design tokens.
+ *
+ * These constants map to CSS custom properties used by the themes.
+ * Override any of these in your CSS to customise LumaToast globally
+ * or per-theme without writing extra class selectors.
+ *
+ * @example
+ * ```css
+ * :root {
+ *   --luma-bg: #1a1a2e;
+ *   --luma-radius: 24px;
+ *   --luma-font: "Inter", sans-serif;
+ * }
+ * ```
+ */
+declare const DURATION_SHORT = 2000;
+declare const DURATION_DEFAULT = 4000;
+declare const DURATION_LONG = 6000;
+declare const DURATION_INFINITE: number;
+declare const ANIMATION_ENTER_MS = 320;
+declare const ANIMATION_EXIT_MS = 300;
+declare const ANIMATION_STACK_MS = 280;
+declare const TOAST_WIDTH_PX = 340;
+declare const TOAST_GAP_PX = 12;
+declare const Z_INDEX_BASE = 1000;
+declare const CSS_VARS: {
+    readonly WIDTH: "--luma-width";
+    readonly RADIUS: "--luma-radius";
+    readonly PADDING: "--luma-padding";
+    readonly GAP: "--luma-gap";
+    readonly BG: "--luma-bg";
+    readonly BORDER_COLOR: "--luma-border-color";
+    readonly BORDER_WIDTH: "--luma-border-width";
+    readonly SHADOW: "--luma-shadow";
+    readonly BACKDROP: "--luma-backdrop";
+    readonly FONT: "--luma-font";
+    readonly TITLE_SIZE: "--luma-title-size";
+    readonly TITLE_WEIGHT: "--luma-title-weight";
+    readonly TITLE_COLOR: "--luma-title-color";
+    readonly DESC_SIZE: "--luma-desc-size";
+    readonly DESC_COLOR: "--luma-desc-color";
+    readonly LINE_HEIGHT: "--luma-line-height";
+    readonly LETTER_SPACING: "--luma-letter-spacing";
+    readonly ICON_SIZE: "--luma-icon-size";
+    readonly CLOSE_COLOR: "--luma-close-color";
+    readonly CLOSE_SIZE: "--luma-close-size";
+    readonly ACTION_BG: "--luma-action-bg";
+    readonly ACTION_COLOR: "--luma-action-color";
+    readonly ACTION_HOVER_BG: "--luma-action-hover-bg";
+    readonly ACTION_RADIUS: "--luma-action-radius";
+    readonly ACTION_PADDING: "--luma-action-padding";
+    readonly ACTION_SIZE: "--luma-action-size";
+    readonly ACTION_WEIGHT: "--luma-action-weight";
+    readonly ACTION_BORDER: "--luma-action-border";
+    readonly ACTION_HOVER_BORDER: "--luma-action-hover-border";
+    readonly PROGRESS_HEIGHT: "--luma-progress-height";
+    readonly PROGRESS_RADIUS: "--luma-progress-radius";
+    readonly PROGRESS_SUCCESS: "--luma-progress-success";
+    readonly PROGRESS_ERROR: "--luma-progress-error";
+    readonly PROGRESS_WARNING: "--luma-progress-warning";
+    readonly PROGRESS_INFO: "--luma-progress-info";
+    readonly PROGRESS_LOADING: "--luma-progress-loading";
+    readonly PROGRESS_CUSTOM: "--luma-progress-custom";
+    readonly ACCENT_SUCCESS: "--luma-accent-success";
+    readonly ACCENT_ERROR: "--luma-accent-error";
+    readonly ACCENT_WARNING: "--luma-accent-warning";
+    readonly ACCENT_INFO: "--luma-accent-info";
+    readonly DURATION_ENTER: "--luma-duration-enter";
+    readonly DURATION_EXIT: "--luma-duration-exit";
+    readonly DURATION_STACK: "--luma-duration-stack";
+};
+declare const CLASS_CONTAINER = "luma-toast-container";
+declare const CLASS_TOAST = "luma-toast";
+declare const CLASS_CARD = "luma-toast-card";
+declare const CLASS_ICON = "luma-toast-icon";
+declare const CLASS_CONTENT = "luma-toast-content";
+declare const CLASS_TITLE = "luma-toast-title";
+declare const CLASS_DESCRIPTION = "luma-toast-description";
+declare const CLASS_ACTION = "luma-toast-action";
+declare const CLASS_CLOSE = "luma-toast-close";
+declare const CLASS_PROGRESS = "luma-progress";
+declare const CLASS_EXIT = "luma-toast-exit";
+
+declare const DEFAULT_DURATION = 4000;
+declare const DEFAULT_POSITION: "top-right";
+declare const DEFAULT_THEME: "linear";
+declare const DEFAULT_DISMISSIBLE = true;
+declare const DEFAULT_SHOW_ICON = true;
+declare const DEFAULT_CLOSE_ON_CLICK = false;
+declare const DEFAULT_PROGRESS_POS: "bottom";
+declare const DEFAULT_ANIMATION_ENTER: "slide";
+declare const DEFAULT_ANIMATION_EXIT: "slide";
+declare const DEFAULT_ANIMATION_SPEED: "normal";
+declare const MAX_VISIBLE_TOASTS = 5;
+declare const STACK_GAP = 12;
+
+/**
+ * Initialize the DOM renderer. Must be called once before showing toasts.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ */
+declare function initializeRenderer(): void;
+
+export { ANIMATION_ENTER_MS, ANIMATION_EXIT_MS, ANIMATION_STACK_MS, CLASS_ACTION, CLASS_CARD, CLASS_CLOSE, CLASS_CONTAINER, CLASS_CONTENT, CLASS_DESCRIPTION, CLASS_EXIT, CLASS_ICON, CLASS_PROGRESS, CLASS_TITLE, CLASS_TOAST, CSS_VARS, DEFAULT_ANIMATION_ENTER, DEFAULT_ANIMATION_EXIT, DEFAULT_ANIMATION_SPEED, DEFAULT_CLOSE_ON_CLICK, DEFAULT_DISMISSIBLE, DEFAULT_DURATION, DEFAULT_POSITION, DEFAULT_PROGRESS_POS, DEFAULT_SHOW_ICON, DEFAULT_THEME, DURATION_DEFAULT, DURATION_INFINITE, DURATION_LONG, DURATION_SHORT, MAX_VISIBLE_TOASTS, type PromiseToastOptions, STACK_GAP, TOAST_GAP_PX, TOAST_WIDTH_PX, type ToastAction, type ToastActionVariant, type ToastAnimationEnter, type ToastAnimationExit, type ToastAnimationSpeed, type ToastItem, type ToastOptions, type ToastPosition, type ToastProgressPosition, type ToastTheme, type ToastType, type ToastUpdateOptions, Z_INDEX_BASE, configure, initializeRenderer, toast, toastManager };