@samline/notify 0.1.15 → 0.2.0

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.
+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.
 
-Inspired by Sileo — see the original project: https://github.com/hiaaryan/sileo
+Powered by Sileo — see the original project: https://github.com/hiaaryan/sileo
 
 Table of Contents
 
@@ -100,18 +101,67 @@ 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:
 
 | 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,13 +1103,17 @@ 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;
     function rerender(items) {
         positions.forEach((pos) => {
             const container = containers[pos];

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,13 +1099,17 @@ 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;
     function rerender(items) {
         positions.forEach((pos) => {
             const container = containers[pos];

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,13 +1105,17 @@
         }
         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;
         function rerender(items) {
             positions.forEach((pos) => {
                 const container = containers[pos];

package/docs/browser.md

@@ -19,13 +19,61 @@ Add the stylesheet and UMD bundle to your HTML:
 </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.
 
+### 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
+api.initToasters(document.body, ['top-right'], {
+  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.

package/docs/react.md

@@ -26,6 +26,50 @@ export function App() {
 }
 ```
 
+## Methods: Full Examples
+
+```tsx
+// Show a generic toast
+notify.show({ title: 'Hello', description: 'Generic toast', type: 'info' });
+
+// Success toast
+notify.success({ title: 'Success!', description: 'Operation completed.' });
+
+// Error toast
+notify.error({ title: 'Error', description: 'Something went wrong.' });
+
+// Info toast
+notify.info({ title: 'Heads up!', description: 'This is an info toast.' });
+
+// Warning toast
+notify.warning({ title: 'Warning!', description: 'Be careful.' });
+
+// Action toast with button
+notify.action({
+  title: 'Action required',
+  description: 'Click the button to proceed.',
+  button: { title: 'Proceed', onClick: () => alert('Action!') }
+});
+
+// Promise toast (loading, success, error, action)
+notify.promise(fetch('/api/save'), {
+  loading: { title: 'Saving...' },
+  success: { title: 'Saved!', description: 'Your data was saved.' },
+  error: { title: 'Failed', description: 'Could not save.' },
+  action: { title: 'Retry?', button: { title: 'Retry', onClick: () => {/* retry logic */} } }
+});
+
+// Dismiss a toast by id
+const id = notify.success({ title: 'Dismiss me' });
+notify.dismiss(id);
+
+// Clear all toasts
+notify.clear();
+
+// Clear only a position
+notify.clear('top-right');
+```
+
 > **Note:**
 > Import `@samline/notify/dist/styles.css` in your main entrypoint or include it in your HTML for correct appearance.
 > CDN: `<link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css">`
@@ -52,12 +96,160 @@ notify.clear()
 
 ### Options
 
+All notification methods accept advanced 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                    | —           | Optional body text (JSX 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 \| ReactNode                    | —           | Custom icon (SVG or JSX)                    |
+| `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 Toasts
+
+```tsx
+// Custom icon (SVG string or JSX)
+notify.success({
+  title: 'With Icon',
+  icon: <svg width="16" height="16" ...>...</svg>
+});
+
+// Custom fill color
+notify.info({
+  title: 'Colored',
+  fill: '#2563eb'
+});
+
+// Custom styles for sub-elements
+notify.success({
+  title: 'Styled',
+  styles: {
+    title: 'my-title-class',
+    badge: 'my-badge-class',
+    button: 'my-btn-class'
+  }
+});
+
+// Custom roundness
+notify.success({
+  title: 'Rounded',
+  roundness: 32
+});
+
+// Autopilot off (manual expand/collapse)
+notify.success({
+  title: 'Manual',
+  autopilot: false
+});
+
+// Custom duration (sticky)
+notify.info({
+  title: 'Sticky',
+  duration: null
+});
+
+// Custom position
+notify.success({
+  title: 'Bottom left',
+  position: 'bottom-left'
+});
+
+// Description as ReactNode
+notify.info({
+  title: 'JSX Description',
+  description: <span style={{ color: 'red' }}>Custom JSX content</span>
+});
+```
+
+#### Example: Advanced Toast
+
+```tsx
+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
+});
+```
+
+#### Promise Toasts
+
+```tsx
+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
+
+The `<Toaster />` component accepts the following props:
+
+| 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)            |
+
+#### Example: Custom Toaster
+
+```tsx
+<Toaster position="bottom-center" offset={24} theme="dark" options={{ fill: '#222', roundness: 20 }} />
+```
+
+## Customizing Styles
+
+- Override CSS variables in your stylesheet or inline:
+
+```css
+:root {
+  --sileo-bg: #18181b;
+  --sileo-success: #22c55e;
+  --sileo-error: #ef4444;
+  --sileo-info: #2563eb;
+  --sileo-warning: #f59e0b;
+}
+```
+
+- Add custom classes via the `styles` option for title, badge, button, description.
+
+## Accessibility
+
+- Toast containers use `role="status"` and `aria-live="polite"`.
+- Respects `prefers-reduced-motion` for users with motion sensitivity.
+
+## Common Errors & Troubleshooting
+
+- **No styles?** Make sure to import or link `dist/styles.css`.
+- **No animation?** Check that the `motion` dependency is installed for ESM/bundler usage.
+- **Button not working?** Ensure your `onClick` is a function and not a string.
+- **Nothing appears?** Confirm you rendered `<Toaster />` and are using the correct import.
+
+## Migration & Best Practices
+
+- If migrating from Sileo, all options and methods are compatible.
+- Prefer using `notify.success`, `notify.error`, etc. for intent clarity.
+- Use `notify.clear()` to remove all toasts, or pass a position to clear only one area.
+
+---
+
+For other frameworks, see the Vue, Svelte, and Vanilla guides.
 | `duration`    | number                                 | `4000`      | Auto-dismiss timeout in ms (0 = persistent) |
 | `button`      | { title: string, onClick: () => void } | —           | Optional action button                      |
 

package/docs/svelte.md

@@ -26,6 +26,50 @@ Import and initialize in your root component:
 <button on:click={show}>Show</button>
 ```
 
+## Methods: Full Examples
+
+```svelte
+// Show a generic toast
+notify.show({ title: 'Hello', description: 'Generic toast', type: 'info' });
+
+// Success toast
+notify.success({ title: 'Success!', description: 'Operation completed.' });
+
+// Error toast
+notify.error({ title: 'Error', description: 'Something went wrong.' });
+
+// Info toast
+notify.info({ title: 'Heads up!', description: 'This is an info toast.' });
+
+// Warning toast
+notify.warning({ title: 'Warning!', description: 'Be careful.' });
+
+// Action toast with button
+notify.action({
+  title: 'Action required',
+  description: 'Click the button to proceed.',
+  button: { title: 'Proceed', onClick: () => alert('Action!') }
+});
+
+// Promise toast (loading, success, error, action)
+notify.promise(fetch('/api/save'), {
+  loading: { title: 'Saving...' },
+  success: { title: 'Saved!', description: 'Your data was saved.' },
+  error: { title: 'Failed', description: 'Could not save.' },
+  action: { title: 'Retry?', button: { title: 'Retry', onClick: () => {/* retry logic */} } }
+});
+
+// Dismiss a toast by id
+const id = notify.success({ title: 'Dismiss me' });
+notify.dismiss(id);
+
+// Clear all toasts
+notify.clear();
+
+// Clear only a position
+notify.clear('top-right');
+```
+
 > **Note:**
 > Import `@samline/notify/dist/styles.css` in your main entrypoint or HTML for correct appearance.
 > CDN: `<link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css">`
@@ -53,12 +97,160 @@ notify.clear()
 
 ### Options
 
+All notification methods accept advanced options:
+
 | Property      | Type                                   | Default     | Description                                 |
 | ------------- | -------------------------------------- | ----------- | ------------------------------------------- |
 | `title`       | string                                 | —           | Toast title                                 |
-| `description` | string                                 | —           | Optional body text                          |
-| `type`        | `info\|success\|error\|warning`        | `info`      | Visual intent                               |
+| `description` | string \| SvelteNode                   | —           | 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 \| SvelteNode                   | —           | Custom icon (SVG 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 Toasts
+
+```svelte
+// Custom icon (SVG string or SvelteNode)
+notify.success({
+  title: 'With Icon',
+  icon: '<svg width="16" height="16" ...>...</svg>'
+});
+
+// Custom fill color
+notify.info({
+  title: 'Colored',
+  fill: '#2563eb'
+});
+
+// Custom styles for sub-elements
+notify.success({
+  title: 'Styled',
+  styles: {
+    title: 'my-title-class',
+    badge: 'my-badge-class',
+    button: 'my-btn-class'
+  }
+});
+
+// Custom roundness
+notify.success({
+  title: 'Rounded',
+  roundness: 32
+});
+
+// Autopilot off (manual expand/collapse)
+notify.success({
+  title: 'Manual',
+  autopilot: false
+});
+
+// Custom duration (sticky)
+notify.info({
+  title: 'Sticky',
+  duration: null
+});
+
+// Custom position
+notify.success({
+  title: 'Bottom left',
+  position: 'bottom-left'
+});
+
+// Description as SvelteNode
+notify.info({
+  title: 'Node Description',
+  description: '<span style="color: red">Custom HTML content</span>'
+});
+```
+
+#### Example: Advanced Toast
+
+```svelte
+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
+});
+```
+
+#### Promise Toasts
+
+```svelte
+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
+
+The `<Toaster />` component accepts the following props:
+
+| 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)            |
+
+#### Example: Custom Toaster
+
+```svelte
+<Toaster position="bottom-center" offset={24} theme="dark" options={{ fill: '#222', roundness: 20 }} />
+```
+
+## Customizing Styles
+
+- Override CSS variables in your stylesheet or inline:
+
+```css
+:root {
+  --sileo-bg: #18181b;
+  --sileo-success: #22c55e;
+  --sileo-error: #ef4444;
+  --sileo-info: #2563eb;
+  --sileo-warning: #f59e0b;
+}
+```
+
+- Add custom classes via the `styles` option for title, badge, button, description.
+
+## Accessibility
+
+- Toast containers use `role="status"` and `aria-live="polite"`.
+- Respects `prefers-reduced-motion` for users with motion sensitivity.
+
+## Common Errors & Troubleshooting
+
+- **No styles?** Make sure to import or link `dist/styles.css`.
+- **No animation?** Check that the `motion` dependency is installed for ESM/bundler usage.
+- **Button not working?** Ensure your `onClick` is a function and not a string.
+- **Nothing appears?** Confirm you rendered `<Toaster />` and are using the correct import.
+
+## Migration & Best Practices
+
+- If migrating from Sileo, all options and methods are compatible.
+- Prefer using `notify.success`, `notify.error`, etc. for intent clarity.
+- Use `notify.clear()` to remove all toasts, o pasar una posición para limpiar solo un área.
+
+---
+
+For other frameworks, see the React, Vue, and Vanilla guides.
 | `duration`    | number                                 | `4000`      | Auto-dismiss timeout in ms (0 = persistent) |
 | `button`      | { title: string, onClick: () => void } | —           | Optional action button                      |
 

package/docs/vanilla.md

@@ -1,69 +1,226 @@
-# Vanilla JS
 
-Use the vanilla adapter for plain JavaScript projects, either with modules or directly via CDN.
+# Vanilla JS (Bundler/Import)
+
+Use the vanilla adapter for plain JavaScript projects with a bundler (Vite, Webpack, etc) or Node.js ESM/CJS. This entrypoint provides full API and advanced options.
 
 ## Quick start (ESM / npm)
 
-```ts
+```js
 import { notify, initToasters } from '@samline/notify/vanilla';
 initToasters(document.body, ['top-right']);
-notify({ title: 'Saved', description: 'Your changes have been saved', type: 'success' });
+notify.success({ title: 'Saved', description: 'Your changes have been saved' });
 ```
 
-## Quick start (CDN / UMD)
+## Methods: Full Examples
 
-```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>
-<script>
-	document.addEventListener('DOMContentLoaded', () => {
-		const api = window.notify;
-		api.initToasters(document.body, ['top-right']);
-		api.notify({ title: 'Saved', description: 'Your changes have been saved', type: 'success' });
-	});
-</script>
+```js
+// Show a generic toast
+notify.show({ title: 'Hello', description: 'Generic toast', type: 'info' });
+
+// Success toast
+notify.success({ title: 'Success!', description: 'Operation completed.' });
+
+// Error toast
+notify.error({ title: 'Error', description: 'Something went wrong.' });
+
+// Info toast
+notify.info({ title: 'Heads up!', description: 'This is an info toast.' });
+
+// Warning toast
+notify.warning({ title: 'Warning!', description: 'Be careful.' });
+
+// Action toast with button
+notify.action({
+	title: 'Action required',
+	description: 'Click the button to proceed.',
+	button: { title: 'Proceed', onClick: () => alert('Action!') }
+});
+
+// Promise toast (loading, success, error, action)
+notify.promise(fetch('/api/save'), {
+	loading: { title: 'Saving...' },
+	success: { title: 'Saved!', description: 'Your data was saved.' },
+	error: { title: 'Failed', description: 'Could not save.' },
+	action: { title: 'Retry?', button: { title: 'Retry', onClick: () => {/* retry logic */} } }
+});
+
+// Dismiss a toast by id
+const id = notify.success({ title: 'Dismiss me' });
+notify.dismiss(id);
+
+// Clear all toasts
+notify.clear();
+
+// Clear only a position
+notify.clear('top-right');
+```
+
+## Advanced Toaster Options
+
+You can pass advanced options to `initToasters`:
+
+```js
+initToasters(document.body, ['top-right'], {
+	offset: { top: 32, right: 16 },
+	options: { fill: '#222', roundness: 20 },
+	theme: 'dark'
+});
+```
+
+### Example: Multiple positions and custom offset
+
+```js
+initToasters(document.body, ['top-right', 'bottom-left'], {
+	offset: { top: 24, right: 24, bottom: 24, left: 24 },
+	theme: 'light',
+	options: { fill: '#0f1724', roundness: 18 }
+});
 ```
 
 ## API
 
-```ts
-// Core controller (primary: `notify`, compatibility alias: `sileo`)
+```js
 notify.show(options)
 notify.success(options)
 notify.error(options)
 notify.info(options)
 notify.warning(options)
 notify.action(options)
-notify.promise(promise, { loading, success, error })
+notify.promise(promise, { loading, success, error, action })
 notify.dismiss(id)
 notify.clear()
 ```
 
-### Parameters
+## Options: Full Examples
+
+```js
+// Custom icon (SVG string)
+notify.success({
+	title: 'With Icon',
+	icon: '<svg width="16" height="16" ...>...</svg>'
+});
+
+// Custom fill color
+notify.info({
+	title: 'Colored',
+	fill: '#2563eb'
+});
+
+// Custom styles for sub-elements
+notify.success({
+	title: 'Styled',
+	styles: {
+		title: 'my-title-class',
+		badge: 'my-badge-class',
+		button: 'my-btn-class'
+	}
+});
+
+// Custom roundness
+notify.success({
+	title: 'Rounded',
+	roundness: 32
+});
+
+// Autopilot off (manual expand/collapse)
+notify.success({
+	title: 'Manual',
+	autopilot: false
+});
+
+// Custom duration (sticky)
+notify.info({
+	title: 'Sticky',
+	duration: null
+});
+
+// Custom position
+notify.success({
+	title: 'Bottom left',
+	position: 'bottom-left'
+});
+```
+
+### Options
+
+| Property      | Type                                   | Default     | Description                                 |
+| ------------- | -------------------------------------- | ----------- | ------------------------------------------- |
+| `title`       | string                                 | —           | Toast title                                 |
+| `description` | string                                 | —           | Optional body text                          |
+| `type`        | `info\|success\|error\|warning\|action`| `info`      | Visual intent                               |
+| `position`    | string                                 | `top-right` | Container position                          |
+| `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                 |
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `options` | object | Toast creation options (see Options below) |
+---
 
-### Returns
+# Browser / CDN (No Bundler)
 
-`string | void` — `show` returns a toast id when created.
+If you are not using a bundler, use the [Browser guide](./browser.md) for CDN usage. Example:
 
-## Options
+```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>
+<script>
+	document.addEventListener('DOMContentLoaded', () => {
+		const api = window.notify;
+		api.initToasters(document.body, ['top-right']);
+		api.notify({ title: 'Saved', description: 'Your changes have been saved', type: 'success' });
+	});
+</script>
+```
 
-| Property | Type | Default | Description |
-| --- | --- | --- | --- |
-| `title` | `string` | — | Toast title |
-| `description` | `string` | — | Optional body text |
-| `type` | `info\|success\|error\|warning` | `info` | Visual intent |
-| `position` | `string` | `top-right` | Container position |
-| `duration` | `number` | `4000` | Auto-dismiss timeout in ms (`null` = sticky) |
+> The CDN/UMD build exposes `window.notify` and only supports string/HTML for icons and content. For advanced options, use the import/bundler version.
 | `button` | `{ title, onClick }` | — | Optional action button |
 
 ## Tips
 
 - Always include the stylesheet for correct appearance.
 - Use the ESM build for modern projects, or the UMD build for legacy/static sites.
+
+## Customizing Styles
+
+- Override CSS variables in your stylesheet or inline:
+
+```css
+:root {
+  --sileo-bg: #18181b;
+  --sileo-success: #22c55e;
+  --sileo-error: #ef4444;
+  --sileo-info: #2563eb;
+  --sileo-warning: #f59e0b;
+}
+```
+
+- Add custom classes via the `styles` option for title, badge, button, description.
+
+## Accessibility
+
+- Toast containers use `role="status"` and `aria-live="polite"`.
+- Respects `prefers-reduced-motion` for users with motion sensitivity.
+
+## Common Errors & Troubleshooting
+
+- **No styles?** Make sure to import or link `dist/styles.css`.
+- **No animation?** Check that the `motion` dependency is installed for ESM/bundler usage.
+- **Button not working?** Ensure your `onClick` is a function and not a string.
+- **Nothing appears?** Confirm you called `initToasters` and are using the correct container.
+
+## Migration & Best Practices
+
+- If migrating from Sileo, all options and methods are compatible.
+- Use the ESM/bundler version for full feature support.
+- Prefer using `notify.success`, `notify.error`, etc. for intent clarity.
+- Use `notify.clear()` to remove all toasts, or pass a position to clear only one area.
+
+---
+
+For framework-specific usage, see the React, Vue, and Svelte guides.
 ```
 
 ### Promise flow

package/docs/vue.md

@@ -20,6 +20,50 @@ app.component('Toaster', Toaster);
 app.mount('#app');
 ```
 
+## Methods: Full Examples
+
+```js
+// Show a generic toast
+notify.show({ title: 'Hello', description: 'Generic toast', type: 'info' });
+
+// Success toast
+notify.success({ title: 'Success!', description: 'Operation completed.' });
+
+// Error toast
+notify.error({ title: 'Error', description: 'Something went wrong.' });
+
+// Info toast
+notify.info({ title: 'Heads up!', description: 'This is an info toast.' });
+
+// Warning toast
+notify.warning({ title: 'Warning!', description: 'Be careful.' });
+
+// Action toast with button
+notify.action({
+	title: 'Action required',
+	description: 'Click the button to proceed.',
+	button: { title: 'Proceed', onClick: () => alert('Action!') }
+});
+
+// Promise toast (loading, success, error, action)
+notify.promise(fetch('/api/save'), {
+	loading: { title: 'Saving...' },
+	success: { title: 'Saved!', description: 'Your data was saved.' },
+	error: { title: 'Failed', description: 'Could not save.' },
+	action: { title: 'Retry?', button: { title: 'Retry', onClick: () => {/* retry logic */} } }
+});
+
+// Dismiss a toast by id
+const id = notify.success({ title: 'Dismiss me' });
+notify.dismiss(id);
+
+// Clear all toasts
+notify.clear();
+
+// Clear only a position
+notify.clear('top-right');
+```
+
 
 
 Use the `notify` controller to show notifications:
@@ -58,6 +102,163 @@ function show(){ notify.show({ title: 'Hello from Vue' }); }
 
 - `Toaster`: Main visual component (same as in React and Svelte).
 - `notify`: Programmatic controller for showing notifications. Import from `@samline/notify/vue` or use `this.$notify` if using the plugin.
+
+### Options
+
+All notification methods accept advanced options:
+
+| Property      | Type                                   | Default     | Description                                 |
+| ------------- | -------------------------------------- | ----------- | ------------------------------------------- |
+| `title`       | string                                 | —           | Toast title                                 |
+| `description` | string \| VNode                        | —           | 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 \| VNode                        | —           | Custom icon (SVG 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 Toasts
+
+```js
+// Custom icon (SVG string or VNode)
+notify.success({
+	title: 'With Icon',
+	icon: '<svg width="16" height="16" ...>...</svg>'
+});
+
+// Custom fill color
+notify.info({
+	title: 'Colored',
+	fill: '#2563eb'
+});
+
+// Custom styles for sub-elements
+notify.success({
+	title: 'Styled',
+	styles: {
+		title: 'my-title-class',
+		badge: 'my-badge-class',
+		button: 'my-btn-class'
+	}
+});
+
+// Custom roundness
+notify.success({
+	title: 'Rounded',
+	roundness: 32
+});
+
+// Autopilot off (manual expand/collapse)
+notify.success({
+	title: 'Manual',
+	autopilot: false
+});
+
+// Custom duration (sticky)
+notify.info({
+	title: 'Sticky',
+	duration: null
+});
+
+// Custom position
+notify.success({
+	title: 'Bottom left',
+	position: 'bottom-left'
+});
+
+// Description as VNode
+notify.info({
+	title: 'VNode Description',
+	description: h('span', { style: 'color: red' }, 'Custom VNode content')
+});
+```
+
+#### 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
+});
+```
+
+#### Promise Toasts
+
+```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
+
+The `<Toaster />` component accepts the following props:
+
+| 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)            |
+
+#### Example: Custom Toaster
+
+```vue
+<Toaster position="bottom-center" :offset="24" theme="dark" :options="{ fill: '#222', roundness: 20 }" />
+```
+
+## Customizing Styles
+
+- Override CSS variables in your stylesheet or inline:
+
+```css
+:root {
+	--sileo-bg: #18181b;
+	--sileo-success: #22c55e;
+	--sileo-error: #ef4444;
+	--sileo-info: #2563eb;
+	--sileo-warning: #f59e0b;
+}
+```
+
+- Add custom classes via the `styles` option for title, badge, button, description.
+
+## Accessibility
+
+- Toast containers use `role="status"` and `aria-live="polite"`.
+- Respects `prefers-reduced-motion` for users with motion sensitivity.
+
+## Common Errors & Troubleshooting
+
+- **No styles?** Make sure to import or link `dist/styles.css`.
+- **No animation?** Check that the `motion` dependency is installed for ESM/bundler usage.
+- **Button not working?** Ensure your `onClick` is a function and not a string.
+- **Nothing appears?** Confirm you rendered `<Toaster />` and are using the correct import.
+
+## Migration & Best Practices
+
+- If migrating from Sileo, all options and methods are compatible.
+- Prefer using `notify.success`, `notify.error`, etc. for intent clarity.
+- Use `notify.clear()` to remove all toasts, o pasar una posición para limpiar solo un área.
+
+---
+
+For other frameworks, see the React, Svelte, and Vanilla guides.
 - Advanced: The `Notifications` plugin is available for global/legacy registration, but direct use of `Toaster` is recommended for most apps.
 - `useSileo()`: Composable that returns the `sileo` controller if you prefer.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samline/notify",
-  "version": "0.1.15",
+  "version": "0.2.0",
   "description": "Notifications engine inspired by Sileo, with adapters for vanilla, React, Vue and Svelte.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",