robot-toast 1.0.0-beta.0

package/README.md

@@ -0,0 +1,200 @@
+# 🤖 robot-toast
+
+A lightweight, zero-dependency, framework-agnostic toast notification library featuring an animated robot companion. Fully draggable, typewriter-style messages, multiple themes, rich transitions, and a cast of **16 built-in robots** — or bring your own.
+
+<p align="center">
+  <img src="public/lightmode.png" alt="Light mode" width="320" />
+  <img src="public/darkmode.png" alt="Dark mode" width="320" />
+  <img src="public/custom.png" alt="Custom styled" width="320" />
+</p>
+
+---
+
+## Features
+
+| Category | Details |
+|---|---|
+| **Themes** | `light` · `dark` · `colored` |
+| **Types** | `default` · `info` · `success` · `warning` · `error` |
+| **Transitions** | `bounce` · `flip` · `zoom` · `slide` |
+| **Positions** | `top-left` · `top-center` · `top-right` · `bottom-left` · `bottom-center` · `bottom-right` |
+| **Robots** | 16 built-in variants — or supply any image path (svg, png, jpg, gif, webp) |
+| **Custom styles** | Pass a `style` object to customize the message bubble however you like |
+| **Drag & drop** | Full XY drag with viewport clamping; snaps to nearest screen edge on release |
+| **Typewriter effect** | Characters appear one by one — configurable speed or instant |
+| **Multi-toast** | Configurable `limit` for simultaneous toasts; excess is auto-queued |
+| **Progress bar** | Countdown bar — show or hide it |
+| **Pause on hover** | Timer pauses when you hover over the toast |
+| **Pause on focus loss** | Timer pauses when the browser tab loses focus |
+| **Robot side** | `nearScreen` flips the robot to the screen-edge side or the inner side |
+| **RTL** | Right-to-left layout support |
+| **Newest on top** | Stack new toasts above existing ones |
+| **Auto-close** | Configurable duration, or disable entirely |
+| **SSR-safe** | All DOM access is guarded — safe for Next.js, Nuxt, etc. |
+| **Zero dependencies** | Pure TypeScript — ESM + CJS builds, tree-shakable |
+
+---
+
+## Installation
+
+```bash
+npm install robot-toast
+```
+
+## Quick Start
+
+```ts
+import { toast } from 'robot-toast';
+
+// Simple string
+toast('Hello 🤖');
+
+// With options
+toast({
+  message: 'Operation successful!',
+  type: 'success',
+  theme: 'dark',
+  position: 'top-right',
+});
+```
+
+## Type Shorthands
+
+```ts
+toast.success('Saved!');
+toast.error('Something went wrong');
+toast.info('Did you know…');
+toast.warning('Check your input');
+```
+
+## Close Programmatically
+
+```ts
+// Close a specific toast by id
+const id = toast('Working…');
+toast.closeById(id);
+
+// Close all toasts at once
+toast.closeAll();
+```
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `message` | `string` | *required* | The text to display |
+| `autoClose` | `number \| false` | `5000` | Auto-close after ms. `false` = stays until dismissed |
+| `position` | `string` | `'bottom-right'` | One of the 6 position presets (see above) |
+| `type` | `string` | `'default'` | `default` · `info` · `success` · `warning` · `error` |
+| `theme` | `string` | `'light'` | `light` · `dark` · `colored` |
+| `transition` | `string` | `'bounce'` | `bounce` · `flip` · `zoom` · `slide` |
+| `style` | `Record<string, string \| number>` | — | Inline styles applied directly to the message bubble for full customization |
+| `typeSpeed` | `number` | `30` | Typing speed in ms per character. `0` = instant |
+| `robotVariant` | `string` | `''` | Built-in name (e.g. `'wave'`) or a custom image path (e.g. `'/my-robot.png'`). `'none'` hides the robot |
+| `hideProgressBar` | `boolean` | `false` | Hide the countdown progress bar |
+| `draggable` | `boolean` | `true` | Allow the user to drag the toast around the screen |
+| `nearScreen` | `boolean` | `true` | `true` = robot near screen edge; `false` = robot on the inner side |
+| `pauseOnHover` | `boolean` | `true` | Pause countdown while the cursor is over the toast |
+| `pauseOnFocusLoss` | `boolean` | `true` | Pause countdown when the browser tab loses focus |
+| `rtl` | `boolean` | `false` | Right-to-left layout |
+| `limit` | `number` | `0` | Max toasts visible at once. `0` = unlimited. Excess is queued |
+| `newestOnTop` | `boolean` | `false` | Stack newest toasts above older ones |
+| `onOpen` | `() => void` | — | Callback fired when the toast finishes its entrance |
+| `onClose` | `() => void` | — | Callback fired after the toast fully exits |
+
+---
+
+## Built-in Robots
+
+Use any of the following names as `robotVariant` — no external files needed:
+
+`wave` · `base` · `base2` · `success` · `error` · `angry` · `angry2` · `shock` · `think` · `search` · `loading` · `sleep` · `head-palm` · `type` · `validation` · `validation2`
+
+```ts
+toast({ message: 'Thinking…', robotVariant: 'think' });
+toast({ message: 'All good!', robotVariant: 'success', type: 'success' });
+```
+
+### Custom Robot Image
+
+Point to any image accessible in your app:
+
+```ts
+toast({
+  message: 'Custom bot!',
+  robotVariant: '/images/my-robot.png',
+});
+```
+
+Supported formats: **svg, png, jpg, jpeg, gif, webp**.
+Set `robotVariant: 'none'` to hide the robot entirely.
+
+---
+
+## Themes & Custom Styles
+
+### Built-in Themes
+
+```ts
+toast({ message: 'Light mode',  theme: 'light' });
+toast({ message: 'Dark mode',   theme: 'dark' });
+toast({ message: 'Colored',     theme: 'colored', type: 'success' });
+```
+
+### Custom Inline Styles
+
+Use the `style` option to fully customize the message bubble:
+
+```ts
+toast({
+  message: 'Fully custom look',
+  style: {
+    background: 'linear-gradient(135deg, #667eea, #764ba2)',
+    color: '#fff',
+    borderRadius: '16px',
+    fontFamily: 'monospace',
+  },
+});
+```
+
+---
+
+## Transitions
+
+```ts
+toast({ message: 'Bounce!', transition: 'bounce' });
+toast({ message: 'Flip!',   transition: 'flip' });
+toast({ message: 'Zoom!',   transition: 'zoom' });
+toast({ message: 'Slide!',  transition: 'slide' });
+```
+
+---
+
+## Framework Examples
+
+### React / Next.js
+
+```tsx
+'use client';
+import { toast } from 'robot-toast';
+import { useEffect, useRef } from 'react';
+
+export default function App() {
+  const shown = useRef(false);
+
+  useEffect(() => {
+    toast({
+      message: 'Welcome!',
+      type: 'success',
+      theme: 'dark',
+      position: 'top-right',
+      robotVariant: 'wave',
+      transition: 'bounce',
+    });
+  }, []);
+
+  return <div>My App</div>;
+}
+```

package/dist/index.d.mts

@@ -0,0 +1,250 @@
+/**
+ * RobotToast Types & Constants
+ * Type definitions and constant arrays for the robot toast notification library
+ */
+/** Array of all valid toast positions */
+declare const TOAST_POSITIONS: readonly ["top-right", "top-left", "top-center", "bottom-right", "bottom-left", "bottom-center"];
+/** Array of all valid toast types */
+declare const TOAST_TYPES: readonly ["default", "info", "success", "warning", "error"];
+/** Array of all valid toast themes */
+declare const TOAST_THEMES: readonly ["light", "dark", "colored"];
+/** Array of all valid transition animations */
+declare const TOAST_TRANSITIONS: readonly ["bounce", "slide", "zoom", "flip"];
+/** Type derived from TOAST_POSITIONS constant */
+type ToastPosition = typeof TOAST_POSITIONS[number];
+/** Type derived from TOAST_TYPES constant */
+type ToastType = typeof TOAST_TYPES[number];
+/** Type derived from TOAST_THEMES constant */
+type ToastTheme = typeof TOAST_THEMES[number];
+/** Type derived from TOAST_TRANSITIONS constant */
+type TransitionType = typeof TOAST_TRANSITIONS[number];
+interface RobotToastOptions {
+    /** The message text to display in the toast */
+    message: string;
+    /** Auto-close duration in ms, or false to disable. Default: 5000 */
+    autoClose?: boolean | number;
+    /** Position of the toast on screen. Default: 'bottom-right' */
+    position?: ToastPosition;
+    /** Toast type/style. Default: 'default' */
+    type?: ToastType;
+    /** Visual theme. Default: 'light' */
+    theme?: ToastTheme;
+    /**
+     * Inline style object to apply directly to the message box element.
+     * This allows runtime customization of colors, fonts, backgrounds, etc.
+     * Example: { color: 'red', backgroundColor: 'blue' }
+     * This takes precedence over className for conflicting properties.
+     */
+    style?: Record<string, string | number>;
+    /** Typing speed in ms per character. 0 = instant. Default: 30 */
+    typeSpeed?: number;
+    /**
+     * Robot image to display.
+     * - Built-in: 'wave', 'error', 'success', 'base', 'base2', 'angry', 'angry2', 'shock',
+     *   'think', 'search', 'loading', 'sleep', 'head-palm', 'type', 'validation', 'validation2'
+     *   (these use embedded data URLs, no external files needed)
+     * - Custom: any path accessible in your app (e.g., 'dxd/bird.jpg', 'public/my-robot.svg')
+     * - None: 'none' to hide the robot entirely
+     * Accepted formats for custom images: svg, png, jpg, jpeg, gif, webp.
+     * Anything unrecognized falls back to the built-in robot.
+     */
+    robotVariant?: string;
+    /** Hide the countdown progress bar. Default: false */
+    hideProgressBar?: boolean;
+    /** Pause the auto-close countdown when the window loses focus. Default: true */
+    pauseOnFocusLoss?: boolean;
+    /** Allow the user to drag the toast around the screen. Default: true */
+    draggable?: boolean;
+    /**
+     * Position the robot near the screen edge (true) or away from it (false).
+     * - true: robot appears between screen edge and message bubble
+     * - false: message bubble appears between screen edge and robot
+     * The position is automatically determined by the toast position and this setting.
+     * Default: true
+     */
+    nearScreen?: boolean;
+    /** Pause the auto-close countdown while the cursor is over the toast. Default: true */
+    pauseOnHover?: boolean;
+    /**
+     * Maximum number of toasts visible simultaneously.
+     * Excess toasts are queued and shown as soon as a slot opens.
+     * 0 = unlimited (queue still works, all show in parallel). Default: 0
+     */
+    limit?: number;
+    /** Stack newest toasts on top of older ones. Default: false */
+    newestOnTop?: boolean;
+    /** Right-to-left layout (message on the right, robot on the left). Default: false */
+    rtl?: boolean;
+    /** Entry / exit transition style. Default: 'bounce' */
+    transition?: TransitionType;
+    /** Called when the toast finishes its enter animation and is fully visible. */
+    onOpen?: () => void;
+    /** Called after the toast has fully exited the screen. */
+    onClose?: () => void;
+}
+/** Internal representation of a queued toast item */
+interface ToastQueueItem {
+    options: RobotToastOptions;
+    id: number;
+}
+interface RobotToastAPI {
+    /** Show a toast notification – queued automatically when limit is reached */
+    show: (options: RobotToastOptions) => number;
+    /** Immediately close all visible toasts and clear the queue */
+    closeAll: () => void;
+    /** Close a specific toast by the id returned from show() */
+    closeById: (id: number) => void;
+    /** Get the RobotToastManager instance */
+    getInstance: () => RobotToastInstance;
+}
+interface RobotToastInstance {
+    show: (options: RobotToastOptions) => number;
+    closeAll: () => void;
+    closeById: (id: number) => void;
+}
+declare global {
+    interface Window {
+        __robotToastLoaded?: boolean;
+        __robotToastUtilsLoaded?: boolean;
+        RobotToast?: RobotToastAPI;
+        RobotToastUtils?: {
+            showRobotToast: (options: RobotToastOptions) => Promise<number>;
+            closeAllRobotToasts: () => Promise<void>;
+            closeRobotToastById: (id: number) => Promise<void>;
+            getRobotToastInstance: () => Promise<RobotToastAPI>;
+            ensureRobotToastReady: (timeout?: number) => Promise<RobotToastAPI>;
+        };
+    }
+}
+
+/**
+ * RobotToast v2
+ * ─────────────────────────────────────────────────────────────────────────────
+ * • Multi-toast support with configurable limit + queue
+ * • Each toast is a self-contained ToastItem instance – no shared mutable state
+ * • Sequenced robot enter → message pop-in, message pop-out → robot exit
+ * • Full XY drag with viewport clamping; on drop the robot snaps to the
+ *   nearest screen edge (left / right) with a personality animation
+ * • Progress bar auto-animates for the countdown; pauses correctly on hover
+ *   and drag; resumes with exact remaining time
+ * • All event listeners are tracked and fully removed on close
+ * • SVG-only enforcement for custom robot images; always renders at fixed size
+ * • SSR-safe (all DOM access is guarded by typeof window / document checks)
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+declare class RobotToastManager {
+    private static _instance;
+    private activeToasts;
+    private queue;
+    private globalLimit;
+    private constructor();
+    static getInstance(): RobotToastManager;
+    show(options: RobotToastOptions): number;
+    closeAll(): void;
+    closeById(id: number): void;
+    private spawnToast;
+    private handleRemoved;
+    /**
+     * Recalculate the vertical position of every active toast so they stack
+     * neatly without overlap. Works for both top-* and bottom-* positions.
+     */
+    private restack;
+}
+
+/**
+ * RobotToast Utilities v2
+ * Helper functions for safer access to the RobotToast API.
+ * Handles async readiness checks, SSR guards, and error boundaries.
+ * Useful when loading robot-toast via a CDN <script> tag.
+ */
+
+/**
+ * Wait for window.RobotToast to be available, up to `timeout` ms.
+ * Resolves immediately if it is already loaded.
+ * Useful when the library is loaded via a <script> tag and you need
+ * to call it from another script that may execute first.
+ */
+declare function ensureRobotToastReady(timeout?: number): Promise<RobotToastAPI>;
+/**
+ * Show a robot toast notification.
+ * Waits for the library to be ready before showing.
+ * Returns the toast id or -1 on failure.
+ */
+declare function showRobotToast(options: RobotToastOptions): Promise<number>;
+/**
+ * Close all visible toasts and clear the queue.
+ */
+declare function closeAllRobotToasts(): Promise<void>;
+/**
+ * Get the RobotToast API instance.
+ */
+declare function getRobotToastInstance(): Promise<RobotToastAPI>;
+
+/**
+ * Built-in robot SVG images as base64 data URLs
+ * These are embedded directly in the package, no external files needed
+ */
+declare const ROBOT_IMAGES: {
+    readonly wave: string;
+    readonly base: string;
+    readonly base2: string;
+    readonly success: string;
+    readonly error: string;
+    readonly angry: string;
+    readonly angry2: string;
+    readonly shock: string;
+    readonly think: string;
+    readonly search: string;
+    readonly loading: string;
+    readonly sleep: string;
+    readonly 'head-palm': string;
+    readonly type: string;
+    readonly validation: string;
+    readonly validation2: string;
+};
+
+/**
+ * robot-toast v2
+ * A lightweight, framework-agnostic toast notification library
+ * with an animated robot character, multi-toast queue, and smooth drag.
+ *
+ * ── Basic usage ──────────────────────────────────────────────────────────────
+ *   import { toast } from 'robot-toast';
+ *   toast('Hello 🤖');
+ *   toast({ message: 'Hello!', position: 'top-right', type: 'success' });
+ *
+ * ── Typed shorthands ─────────────────────────────────────────────────────────
+ *   toast.success('Saved!');
+ *   toast.error('Something went wrong');
+ *   toast.info('Did you know…');
+ *   toast.warning('Check your input');
+ *
+ * ── Class / manager ──────────────────────────────────────────────────────────
+ *   import { RobotToast } from 'robot-toast';
+ *   const manager = RobotToast.getInstance();
+ *   const id = manager.show({ message: 'Hi!' });
+ *   manager.closeById(id);
+ */
+
+type ToastInput = string | RobotToastOptions;
+/**
+ * Show a toast notification.
+ * Accepts either a plain string or a full options object.
+ * Returns the toast id (useful for closeById).
+ *
+ * @example
+ * toast('Hello 🤖');
+ * toast({ message: 'Hello!', type: 'success', position: 'top-right' });
+ */
+declare function toast(input: ToastInput): number;
+declare namespace toast {
+    var success: (input: ToastInput) => number;
+    var error: (input: ToastInput) => number;
+    var info: (input: ToastInput) => number;
+    var warning: (input: ToastInput) => number;
+    var closeAll: () => void;
+    var closeById: (id: number) => void;
+}
+
+export { ROBOT_IMAGES, RobotToastManager as RobotToast, type RobotToastAPI, type RobotToastInstance, RobotToastManager, type RobotToastOptions, TOAST_POSITIONS, TOAST_THEMES, TOAST_TRANSITIONS, TOAST_TYPES, type ToastPosition, type ToastQueueItem, type ToastTheme, type ToastType, type TransitionType, closeAllRobotToasts, ensureRobotToastReady, getRobotToastInstance, showRobotToast, toast };