@samline/notify 0.1.15 → 0.2.2

package/README.md

@@ -1,8 +1,9 @@
-## @samline/notify
 
-A Sileo-inspired notifications engine providing a framework-agnostic core and lightweight adapters for Vanilla JS, React, Vue and Svelte.
+# Notify
 
-Inspired by Sileo — see the original project: https://github.com/hiaaryan/sileo
+A universal toast notification library powered by Sileo, designed to bring the same beautiful, animated experience to React, Vue, Svelte, and Vanilla JS. Built for teams who need Sileo’s quality and API, but require seamless integration across multiple frameworks.
+
+Powered by Sileo — see the original project: https://github.com/hiaaryan/sileo
 
 Table of Contents
 
@@ -47,20 +48,32 @@ CDN / Browser
 
 Use the browser build when your project loads scripts directly and cannot compile npm modules (Shopify, WordPress, plain HTML). Example CDN usage (replace version):
 
+
 ```html
-<script src="https://unpkg.com/@samline/notify@0.1.15/dist/notify.umd.js"></script>
-<link
-  rel="stylesheet" 
-  href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css"
-/>
+<script src="https://unpkg.com/@samline/notify@0.2.1/dist/notify.umd.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.2.1/dist/styles.css" />
 
 <script>
-  const api = window.notify || window.notifications
-  api.initToasters(document.body, ['top-right'])
-  api.notify({ title: 'Saved', description: 'Changes saved', type: 'success' })
+  // Always use an array of strings as the second argument
+  // Correct usage:
+  const api = window.notify || window.notifications;
+  api.initToasters(document.body, ['top-left']);
+  api.notify({
+    title: 'Saved',
+    description: 'Changes saved',
+    type: 'success'
+    // You can omit position if you only initialized one position
+  });
 </script>
 ```
 
+
+> ⚠️ **Important:**
+> - The second argument to `initToasters` **must be an array of strings** with the positions (e.g. `['top-left']`).
+> - **Do not use** `document.body['top-left']` (this is `undefined` and will not work).
+> - If you initialize only one position, toasts without an explicit position will go there automatically (dynamic fallback).
+> - If you initialize multiple positions, toasts without an explicit position will go to `'top-right'` by default.
+
 Entry Points
 
 Choose the entrypoint matching your stack so you only import what you need.
@@ -68,7 +81,7 @@ Choose the entrypoint matching your stack so you only import what you need.
 | Use case      | Import                                                                                                                                        | Guide                              |
 | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
 | Vanilla JS    | `import { notify, initToasters } from '@samline/notify/vanilla'`                                                                              | [docs/vanilla.md](docs/vanilla.md) |
-| Browser / CDN | `<script src="https://unpkg.com/@samline/notify@0.1.13/dist/notify.umd.js"></script>`<br/>`const api = window.notify; api.initToasters(...);` | [docs/browser.md](docs/browser.md) |
+| Browser / CDN | `<script src="https://unpkg.com/@samline/notify@0.2.1/dist/notify.umd.js"></script>`<br/>`const api = window.notify; api.initToasters(...);` | [docs/browser.md](docs/browser.md) |
 | React         | `import { Toaster, notify } from '@samline/notify/react'`                                                                                      | [docs/react.md](docs/react.md)     |
 | Vue           | `import { Toaster, notify } from '@samline/notify/vue'`                                                                                        | [docs/vue.md](docs/vue.md)         |
 | Svelte        | `import Toaster, { notify } from '@samline/notify/svelte'`                                                                                     | [docs/svelte.md](docs/svelte.md)   |
@@ -100,18 +113,89 @@ notify.clear()
 
 When using the UMD/browser bundle the global is exposed as `window.notify` (preferred). For compatibility the API object also exposes `window.notifications` which maintains the previous shape.
 
-Shared Options
 
-Common `options` across entrypoints:
+
+Shared Options (All Entrypoints)
+
+All notification methods accept a rich set of options for full customization. **Position fallback note:**
+
+- If you initialize only one position with `initToasters`, toasts without an explicit `position` will go there (dynamic fallback).
+- If you initialize multiple positions, the fallback will be `'top-right'`.
+- If you notify to a position that was not initialized, a warning will appear in the console and the toast will not be shown. This warning is now always triggered, incluso si la posición no existe en el DOM.
+
+Example:
+
+```js
+// Only one position (dynamic fallback)
+api.initToasters(document.body, ['bottom-left']);
+api.notify({ title: 'Will go to bottom-left' });
+
+// Multiple positions (classic fallback)
+api.initToasters(document.body, ['top-right', 'bottom-left']);
+api.notify({ title: 'Will go to top-right' });
+api.notify({ title: 'Will go to bottom-left', position: 'bottom-left' });
+```
+
+---
+
+All options:
 
 | Property      | Type                                   | Default     | Description                                 |
 | ------------- | -------------------------------------- | ----------- | ------------------------------------------- |
 | `title`       | string                                 | —           | Toast title                                 |
-| `description` | string                                 | —           | Optional body text                          |
-| `type`        | `info\|success\|error\|warning`        | `info`      | Visual intent                               |
+| `description` | string \| ReactNode \| SvelteNode      | —           | Optional body text (JSX, HTML, or string)   |
+| `type`        | `info\|success\|error\|warning\|action`| `info`      | Visual intent                               |
 | `position`    | string                                 | `top-right` | One of toast positions                      |
-| `duration`    | number                                 | `4000`      | Auto-dismiss timeout in ms (0 = persistent) |
+| `duration`    | number \| null                         | `4000`      | Auto-dismiss timeout in ms (null = sticky)  |
 | `button`      | { title: string, onClick: () => void } | —           | Optional action button                      |
+| `icon`        | string \| ReactNode \| SvelteNode      | —           | Custom icon (SVG, JSX, or node)             |
+| `fill`        | string                                 | —           | Custom background color (SVG or badge)      |
+| `styles`      | { title, description, badge, button }  | —           | Custom class overrides for sub-elements     |
+| `roundness`   | number                                 | 16          | Border radius in pixels                     |
+| `autopilot`   | boolean \| object                      | true        | Auto expand/collapse timing                 |
+
+#### Example: Advanced Toast
+
+```js
+notify.success({
+  title: "Styled!",
+  fill: "#222",
+  icon: '<svg>...</svg>',
+  styles: {
+    title: "text-white!",
+    badge: "bg-white/20!",
+    button: "bg-white/10!"
+  },
+  roundness: 24,
+  autopilot: false
+});
+```
+
+#### SileoPromiseOptions
+
+The `promise` method supports advanced flows:
+
+```js
+notify.promise(fetchData(), {
+  loading: { title: "Loading..." },
+  success: (data) => ({ title: `Loaded ${data.name}` }),
+  error: (err) => ({ title: "Error", description: err.message }),
+  action: (data) => ({ title: "Action required", button: { title: "Retry", onClick: () => retry() } })
+});
+```
+
+#### Toaster Component Props (React, Svelte, Vue, Vanilla)
+
+All Toaster components accept the following props for global control:
+
+| Prop      | Type                                      | Default      | Description                                 |
+| --------- | ----------------------------------------- | ------------ | ------------------------------------------- |
+| `position`| string                                    | top-right    | Default toast position                      |
+| `offset`  | number \| string \| {top,right,bottom,left}| 0            | Distance from viewport edges                |
+| `options` | Partial<Options>                          | —            | Default options for all toasts              |
+| `theme`   | "light" \| "dark" \| "system"            | system       | Color scheme (auto, light, dark)            |
+
+See framework-specific guides for more examples.
 
 Notes
 

package/dist/index.cjs.js

@@ -24,8 +24,21 @@ class NotifyController {
         return this.toasts.slice();
     }
     show(opts) {
+        // Normalizar props avanzadas
+        const { icon, fill, styles, roundness, autopilot, ...rest } = opts;
         const id = this.nextId();
-        const item = { id, options: { ...opts }, createdAt: Date.now() };
+        const item = {
+            id,
+            options: {
+                ...rest,
+                ...(icon !== undefined ? { icon } : {}),
+                ...(fill !== undefined ? { fill } : {}),
+                ...(styles !== undefined ? { styles } : {}),
+                ...(roundness !== undefined ? { roundness } : {}),
+                ...(autopilot !== undefined ? { autopilot } : {}),
+            },
+            createdAt: Date.now(),
+        };
         this.toasts.push(item);
         this.notify();
         return id;
@@ -65,6 +78,13 @@ class NotifyController {
         const loadingId = this.show({ ...(opts.loading || {}), type: 'loading', position: opts.position });
         p.then((res) => {
             this.dismiss(loadingId);
+            if (opts.action) {
+                const actionOpt = typeof opts.action === 'function' ? opts.action(res) : opts.action;
+                if (actionOpt) {
+                    this.show({ ...(actionOpt || {}), type: 'action', position: opts.position });
+                    return;
+                }
+            }
             const successOpt = typeof opts.success === 'function' ? opts.success(res) : opts.success;
             if (successOpt)
                 this.show({ ...(successOpt || {}), type: 'success', position: opts.position });
@@ -1006,12 +1026,30 @@ const POSITIONS = [
     'bottom-center',
     'bottom-right'
 ];
-function createContainer(position, root) {
+function createContainer(position, root, opts) {
     const c = document.createElement('div');
     c.className = 'sileo-toaster';
     c.setAttribute('data-position', position);
     c.setAttribute('role', 'status');
     c.setAttribute('aria-live', 'polite');
+    if (opts === null || opts === void 0 ? void 0 : opts.theme)
+        c.setAttribute('data-theme', opts.theme);
+    // offset
+    if ((opts === null || opts === void 0 ? void 0 : opts.offset) !== undefined) {
+        if (typeof opts.offset === 'number' || typeof opts.offset === 'string') {
+            c.style.margin = typeof opts.offset === 'number' ? `${opts.offset}px` : opts.offset;
+        }
+        else if (typeof opts.offset === 'object') {
+            if (opts.offset.top !== undefined)
+                c.style.marginTop = `${opts.offset.top}px`;
+            if (opts.offset.right !== undefined)
+                c.style.marginRight = `${opts.offset.right}px`;
+            if (opts.offset.bottom !== undefined)
+                c.style.marginBottom = `${opts.offset.bottom}px`;
+            if (opts.offset.left !== undefined)
+                c.style.marginLeft = `${opts.offset.left}px`;
+        }
+    }
     return c;
 }
 function renderToast(item) {
@@ -1065,33 +1103,46 @@ function renderToast(item) {
     }
     return el;
 }
-function initToasters(root = document.body, positions = ['top-right']) {
+function initToasters(root = document.body, positions = ['top-right'], opts) {
     const containers = {};
     positions.forEach((pos) => {
-        const c = createContainer(pos);
+        const c = createContainer(pos, root, opts);
         root.appendChild(c);
         containers[pos] = c;
     });
+    if (opts === null || opts === void 0 ? void 0 : opts.options)
+        window.sileo._globalOptions = opts.options;
+    if (opts === null || opts === void 0 ? void 0 : opts.theme)
+        window.sileo._theme = opts.theme;
+    // fallback dinámico: si solo hay una posición, usarla como default
+    const fallbackPosition = positions.length === 1 ? positions[0] : 'top-right';
     function rerender(items) {
+        // Lanzar advertencia para todos los toasts con posición no inicializada
+        items.forEach((t) => {
+            if (t.options.position && !containers[t.options.position]) {
+                console.warn(`[sileo] Toast con posición "${t.options.position}" pero no se inicializó ningún contenedor para esa posición. Inicializa con initToasters(..., ['${t.options.position}']) para mostrarlo.`);
+            }
+        });
         positions.forEach((pos) => {
             const container = containers[pos];
-            const visible = items.filter((t) => (t.options.position || 'top-right') === pos);
-            // Diff existing children and animate out removed toasts
+            // fallback dinámico
+            const visible = items.filter((t) => (t.options.position || fallbackPosition) === pos);
+            // Diff existing children y animar salida de toasts removidos
             const visibleIds = new Set(visible.map((v) => v.id));
             const existing = Array.from(container.children);
             existing.forEach((child) => {
                 const id = child.dataset.id;
                 if (!id || !visibleIds.has(id)) {
-                    // animate out then remove
+                    // animar salida y luego remover
                     animate(child, { opacity: 0, y: -8 }, { duration: 0.18 }).finished.then(() => child.remove());
                 }
             });
-            // Add new items
+            // Añadir nuevos toasts
             visible.forEach((t) => {
                 if (!container.querySelector(`[data-id="${t.id}"]`)) {
                     const node = renderToast(t);
                     container.appendChild(node);
-                    // animate in
+                    // animar entrada
                     requestAnimationFrame(() => {
                         animate(node, { opacity: [0, 1], y: [-6, 0] }, { duration: 0.24 });
                     });

package/dist/index.esm.js

@@ -20,8 +20,21 @@ class NotifyController {
         return this.toasts.slice();
     }
     show(opts) {
+        // Normalizar props avanzadas
+        const { icon, fill, styles, roundness, autopilot, ...rest } = opts;
         const id = this.nextId();
-        const item = { id, options: { ...opts }, createdAt: Date.now() };
+        const item = {
+            id,
+            options: {
+                ...rest,
+                ...(icon !== undefined ? { icon } : {}),
+                ...(fill !== undefined ? { fill } : {}),
+                ...(styles !== undefined ? { styles } : {}),
+                ...(roundness !== undefined ? { roundness } : {}),
+                ...(autopilot !== undefined ? { autopilot } : {}),
+            },
+            createdAt: Date.now(),
+        };
         this.toasts.push(item);
         this.notify();
         return id;
@@ -61,6 +74,13 @@ class NotifyController {
         const loadingId = this.show({ ...(opts.loading || {}), type: 'loading', position: opts.position });
         p.then((res) => {
             this.dismiss(loadingId);
+            if (opts.action) {
+                const actionOpt = typeof opts.action === 'function' ? opts.action(res) : opts.action;
+                if (actionOpt) {
+                    this.show({ ...(actionOpt || {}), type: 'action', position: opts.position });
+                    return;
+                }
+            }
             const successOpt = typeof opts.success === 'function' ? opts.success(res) : opts.success;
             if (successOpt)
                 this.show({ ...(successOpt || {}), type: 'success', position: opts.position });
@@ -1002,12 +1022,30 @@ const POSITIONS = [
     'bottom-center',
     'bottom-right'
 ];
-function createContainer(position, root) {
+function createContainer(position, root, opts) {
     const c = document.createElement('div');
     c.className = 'sileo-toaster';
     c.setAttribute('data-position', position);
     c.setAttribute('role', 'status');
     c.setAttribute('aria-live', 'polite');
+    if (opts === null || opts === void 0 ? void 0 : opts.theme)
+        c.setAttribute('data-theme', opts.theme);
+    // offset
+    if ((opts === null || opts === void 0 ? void 0 : opts.offset) !== undefined) {
+        if (typeof opts.offset === 'number' || typeof opts.offset === 'string') {
+            c.style.margin = typeof opts.offset === 'number' ? `${opts.offset}px` : opts.offset;
+        }
+        else if (typeof opts.offset === 'object') {
+            if (opts.offset.top !== undefined)
+                c.style.marginTop = `${opts.offset.top}px`;
+            if (opts.offset.right !== undefined)
+                c.style.marginRight = `${opts.offset.right}px`;
+            if (opts.offset.bottom !== undefined)
+                c.style.marginBottom = `${opts.offset.bottom}px`;
+            if (opts.offset.left !== undefined)
+                c.style.marginLeft = `${opts.offset.left}px`;
+        }
+    }
     return c;
 }
 function renderToast(item) {
@@ -1061,33 +1099,46 @@ function renderToast(item) {
     }
     return el;
 }
-function initToasters(root = document.body, positions = ['top-right']) {
+function initToasters(root = document.body, positions = ['top-right'], opts) {
     const containers = {};
     positions.forEach((pos) => {
-        const c = createContainer(pos);
+        const c = createContainer(pos, root, opts);
         root.appendChild(c);
         containers[pos] = c;
     });
+    if (opts === null || opts === void 0 ? void 0 : opts.options)
+        window.sileo._globalOptions = opts.options;
+    if (opts === null || opts === void 0 ? void 0 : opts.theme)
+        window.sileo._theme = opts.theme;
+    // fallback dinámico: si solo hay una posición, usarla como default
+    const fallbackPosition = positions.length === 1 ? positions[0] : 'top-right';
     function rerender(items) {
+        // Lanzar advertencia para todos los toasts con posición no inicializada
+        items.forEach((t) => {
+            if (t.options.position && !containers[t.options.position]) {
+                console.warn(`[sileo] Toast con posición "${t.options.position}" pero no se inicializó ningún contenedor para esa posición. Inicializa con initToasters(..., ['${t.options.position}']) para mostrarlo.`);
+            }
+        });
         positions.forEach((pos) => {
             const container = containers[pos];
-            const visible = items.filter((t) => (t.options.position || 'top-right') === pos);
-            // Diff existing children and animate out removed toasts
+            // fallback dinámico
+            const visible = items.filter((t) => (t.options.position || fallbackPosition) === pos);
+            // Diff existing children y animar salida de toasts removidos
             const visibleIds = new Set(visible.map((v) => v.id));
             const existing = Array.from(container.children);
             existing.forEach((child) => {
                 const id = child.dataset.id;
                 if (!id || !visibleIds.has(id)) {
-                    // animate out then remove
+                    // animar salida y luego remover
                     animate(child, { opacity: 0, y: -8 }, { duration: 0.18 }).finished.then(() => child.remove());
                 }
             });
-            // Add new items
+            // Añadir nuevos toasts
             visible.forEach((t) => {
                 if (!container.querySelector(`[data-id="${t.id}"]`)) {
                     const node = renderToast(t);
                     container.appendChild(node);
-                    // animate in
+                    // animar entrada
                     requestAnimationFrame(() => {
                         animate(node, { opacity: [0, 1], y: [-6, 0] }, { duration: 0.24 });
                     });

package/dist/notify.umd.js

@@ -26,8 +26,21 @@
             return this.toasts.slice();
         }
         show(opts) {
+            // Normalizar props avanzadas
+            const { icon, fill, styles, roundness, autopilot, ...rest } = opts;
             const id = this.nextId();
-            const item = { id, options: { ...opts }, createdAt: Date.now() };
+            const item = {
+                id,
+                options: {
+                    ...rest,
+                    ...(icon !== undefined ? { icon } : {}),
+                    ...(fill !== undefined ? { fill } : {}),
+                    ...(styles !== undefined ? { styles } : {}),
+                    ...(roundness !== undefined ? { roundness } : {}),
+                    ...(autopilot !== undefined ? { autopilot } : {}),
+                },
+                createdAt: Date.now(),
+            };
             this.toasts.push(item);
             this.notify();
             return id;
@@ -67,6 +80,13 @@
             const loadingId = this.show({ ...(opts.loading || {}), type: 'loading', position: opts.position });
             p.then((res) => {
                 this.dismiss(loadingId);
+                if (opts.action) {
+                    const actionOpt = typeof opts.action === 'function' ? opts.action(res) : opts.action;
+                    if (actionOpt) {
+                        this.show({ ...(actionOpt || {}), type: 'action', position: opts.position });
+                        return;
+                    }
+                }
                 const successOpt = typeof opts.success === 'function' ? opts.success(res) : opts.success;
                 if (successOpt)
                     this.show({ ...(successOpt || {}), type: 'success', position: opts.position });
@@ -1008,12 +1028,30 @@
         'bottom-center',
         'bottom-right'
     ];
-    function createContainer(position, root) {
+    function createContainer(position, root, opts) {
         const c = document.createElement('div');
         c.className = 'sileo-toaster';
         c.setAttribute('data-position', position);
         c.setAttribute('role', 'status');
         c.setAttribute('aria-live', 'polite');
+        if (opts === null || opts === void 0 ? void 0 : opts.theme)
+            c.setAttribute('data-theme', opts.theme);
+        // offset
+        if ((opts === null || opts === void 0 ? void 0 : opts.offset) !== undefined) {
+            if (typeof opts.offset === 'number' || typeof opts.offset === 'string') {
+                c.style.margin = typeof opts.offset === 'number' ? `${opts.offset}px` : opts.offset;
+            }
+            else if (typeof opts.offset === 'object') {
+                if (opts.offset.top !== undefined)
+                    c.style.marginTop = `${opts.offset.top}px`;
+                if (opts.offset.right !== undefined)
+                    c.style.marginRight = `${opts.offset.right}px`;
+                if (opts.offset.bottom !== undefined)
+                    c.style.marginBottom = `${opts.offset.bottom}px`;
+                if (opts.offset.left !== undefined)
+                    c.style.marginLeft = `${opts.offset.left}px`;
+            }
+        }
         return c;
     }
     function renderToast(item) {
@@ -1067,33 +1105,46 @@
         }
         return el;
     }
-    function initToasters(root = document.body, positions = ['top-right']) {
+    function initToasters(root = document.body, positions = ['top-right'], opts) {
         const containers = {};
         positions.forEach((pos) => {
-            const c = createContainer(pos);
+            const c = createContainer(pos, root, opts);
             root.appendChild(c);
             containers[pos] = c;
         });
+        if (opts === null || opts === void 0 ? void 0 : opts.options)
+            window.sileo._globalOptions = opts.options;
+        if (opts === null || opts === void 0 ? void 0 : opts.theme)
+            window.sileo._theme = opts.theme;
+        // fallback dinámico: si solo hay una posición, usarla como default
+        const fallbackPosition = positions.length === 1 ? positions[0] : 'top-right';
         function rerender(items) {
+            // Lanzar advertencia para todos los toasts con posición no inicializada
+            items.forEach((t) => {
+                if (t.options.position && !containers[t.options.position]) {
+                    console.warn(`[sileo] Toast con posición "${t.options.position}" pero no se inicializó ningún contenedor para esa posición. Inicializa con initToasters(..., ['${t.options.position}']) para mostrarlo.`);
+                }
+            });
             positions.forEach((pos) => {
                 const container = containers[pos];
-                const visible = items.filter((t) => (t.options.position || 'top-right') === pos);
-                // Diff existing children and animate out removed toasts
+                // fallback dinámico
+                const visible = items.filter((t) => (t.options.position || fallbackPosition) === pos);
+                // Diff existing children y animar salida de toasts removidos
                 const visibleIds = new Set(visible.map((v) => v.id));
                 const existing = Array.from(container.children);
                 existing.forEach((child) => {
                     const id = child.dataset.id;
                     if (!id || !visibleIds.has(id)) {
-                        // animate out then remove
+                        // animar salida y luego remover
                         animate(child, { opacity: 0, y: -8 }, { duration: 0.18 }).finished.then(() => child.remove());
                     }
                 });
-                // Add new items
+                // Añadir nuevos toasts
                 visible.forEach((t) => {
                     if (!container.querySelector(`[data-id="${t.id}"]`)) {
                         const node = renderToast(t);
                         container.appendChild(node);
-                        // animate in
+                        // animar entrada
                         requestAnimationFrame(() => {
                             animate(node, { opacity: [0, 1], y: [-6, 0] }, { duration: 0.24 });
                         });

package/docs/browser.md

@@ -8,24 +8,85 @@ Use this package directly in the browser when you cannot use npm modules or a bu
 Add the stylesheet and UMD bundle to your HTML:
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css">
-<script src="https://unpkg.com/@samline/notify@0.1.15/dist/notify.umd.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.2.1/dist/styles.css">
+<script src="https://unpkg.com/@samline/notify@0.2.1/dist/notify.umd.js"></script>
 <script>
   document.addEventListener('DOMContentLoaded', () => {
     const api = window.notify; // or window.notifications for legacy
-    api.initToasters(document.body, ['top-right']);
+    // Always use an array of strings as the second argument
+    // Correct usage:
+    api.initToasters(document.body, ['top-left']);
     api.notify({ title: 'Hello', description: 'No-bundler usage', type: 'info' });
   });
 </script>
 ```
 
+
+
 ## API
 
 - The UMD bundle exposes `window.notify` (recommended) and `window.notifications` (legacy/compatibility).
 - Always include `dist/styles.css` for correct appearance and animations.
-- Use `api.initToasters(container, positions)` to mount containers (usually `document.body`).
+- Use `api.initToasters(container, positions, { offset, options, theme })` to mount containers (usually `document.body`).
 - Use `api.notify({...})` to show a notification.
 
+### ⚠️ Warnings and Best Practices
+
+- The second argument to `initToasters` **must be an array of strings** (e.g. `['top-left']`).
+- **Do not use** `document.body['top-left']` (this is `undefined` and will not work).
+- If you initialize only one position, toasts without an explicit position will go there automatically (dynamic fallback).
+- If you initialize multiple positions, toasts without an explicit position will go to `'top-right'` by default.
+- If you notify to a position that was not initialized, you will see a warning in the console and the toast will not be shown.
+
+### Advanced Options
+
+All notification methods accept advanced options:
+
+| Property      | Type                                   | Default     | Description                                 |
+| ------------- | -------------------------------------- | ----------- | ------------------------------------------- |
+| `title`       | string                                 | —           | Toast title                                 |
+| `description` | string                                 | —           | Optional body text (HTML or string)         |
+| `type`        | `info\|success\|error\|warning\|action`| `info`      | Visual intent                               |
+| `position`    | string                                 | `top-right` | One of toast positions                      |
+| `duration`    | number \| null                         | `4000`      | Auto-dismiss timeout in ms (null = sticky)  |
+| `button`      | { title: string, onClick: () => void } | —           | Optional action button                      |
+| `icon`        | string                                 | —           | Custom icon (SVG or HTML)                   |
+| `fill`        | string                                 | —           | Custom background color (SVG or badge)      |
+| `styles`      | { title, description, badge, button }  | —           | Custom class overrides for sub-elements     |
+| `roundness`   | number                                 | 16          | Border radius in pixels                     |
+| `autopilot`   | boolean \| object                      | true        | Auto expand/collapse timing                 |
+
+#### Example: Advanced Toast
+
+```js
+api.success({
+  title: "Styled!",
+  fill: "#222",
+  icon: '<svg>...</svg>',
+  styles: {
+    title: "text-white!",
+    badge: "bg-white/20!",
+    button: "bg-white/10!"
+  },
+  roundness: 24,
+  autopilot: false
+});
+```
+
+### Toaster Options
+
+
+You can pass advanced options to `initToasters`:
+
+```js
+// Correct example with multiple positions
+api.initToasters(document.body, ['top-right', 'bottom-left'], {
+  offset: { top: 32, right: 16 },
+  options: { fill: '#222', roundness: 20 },
+  theme: 'dark'
+});
+```
+
 ## Notes
 
 - If you need more control or want to avoid global variables, use the ESM/CJS builds with a bundler.