@samline/notify 0.2.0 → 0.2.2

package/README.md

@@ -1,5 +1,5 @@
 
-## @samline/notify
+# Notify
 
 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.
 
@@ -48,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.
@@ -69,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)   |
@@ -102,9 +114,31 @@ 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 (All Entrypoints)
 
-All notification methods accept a rich set of options for full customization:
+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                                 |
 | ------------- | -------------------------------------- | ----------- | ------------------------------------------- |

package/dist/index.cjs.js

@@ -1114,26 +1114,35 @@ function initToasters(root = document.body, positions = ['top-right'], opts) {
         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

@@ -1110,26 +1110,35 @@ function initToasters(root = document.body, positions = ['top-right'], opts) {
         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

@@ -1116,26 +1116,35 @@
             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,18 +8,21 @@ 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).
@@ -27,6 +30,14 @@ Add the stylesheet and UMD bundle to your HTML:
 - 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:
@@ -64,10 +75,12 @@ api.success({
 
 ### Toaster Options
 
+
 You can pass advanced options to `initToasters`:
 
 ```js
-api.initToasters(document.body, ['top-right'], {
+// 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'

package/docs/react.md

@@ -72,7 +72,7 @@ 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">`
+
 
 
 ## API
@@ -103,7 +103,7 @@ All notification methods accept advanced options:
 | `title`       | string                                 | —           | Toast title                                 |
 | `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                      |
+| `position`    | string                                 | `top-right` | One of the valid positions. If you only initialize one position with `<Toaster position="..." />`, toasts without an explicit position will go there (dynamic fallback). If you initialize multiple, the fallback is `top-right`. |
 | `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)                    |
@@ -155,11 +155,18 @@ notify.info({
   duration: null
 });
 
-// Custom position
+// Custom position (make sure you initialized that position with <Toaster position="bottom-left" />)
 notify.success({
   title: 'Bottom left',
   position: 'bottom-left'
 });
+---
+
+## ⚠️ Warnings and Best Practices
+
+- If you only use one `<Toaster position="..." />`, toasts without an explicit position will go there automatically (dynamic fallback).
+- If you use multiple `<Toaster position="..." />`, the fallback will be `top-right`.
+- 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.
 
 // Description as ReactNode
 notify.info({

package/docs/svelte.md

@@ -72,7 +72,7 @@ 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">`
+
 
 
 ## API
@@ -104,7 +104,7 @@ All notification methods accept advanced options:
 | `title`       | string                                 | —           | Toast title                                 |
 | `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                      |
+| `position`    | string                                 | `top-right` | One of the valid positions. If you only initialize one position with `<Toaster position="..." />`, toasts without an explicit position will go there (dynamic fallback). If you initialize multiple, the fallback is `top-right`. |
 | `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)                   |
@@ -156,11 +156,18 @@ notify.info({
   duration: null
 });
 
-// Custom position
+// Custom position (make sure you initialized that position with <Toaster position="bottom-left" />)
 notify.success({
   title: 'Bottom left',
   position: 'bottom-left'
 });
+---
+
+## ⚠️ Warnings and Best Practices
+
+- If you only use one `<Toaster position="..." />`, toasts without an explicit position will go there automatically (dynamic fallback).
+- If you use multiple `<Toaster position="..." />`, the fallback will be `top-right`.
+- 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.
 
 // Description as SvelteNode
 notify.info({

package/docs/vanilla.md

@@ -7,7 +7,8 @@ Use the vanilla adapter for plain JavaScript projects with a bundler (Vite, Webp
 
 ```js
 import { notify, initToasters } from '@samline/notify/vanilla';
-initToasters(document.body, ['top-right']);
+// Always use an array of strings as the second argument
+initToasters(document.body, ['top-left']);
 notify.success({ title: 'Saved', description: 'Your changes have been saved' });
 ```
 
@@ -60,7 +61,8 @@ notify.clear('top-right');
 You can pass advanced options to `initToasters`:
 
 ```js
-initToasters(document.body, ['top-right'], {
+// Correct example with one position (dynamic fallback)
+initToasters(document.body, ['bottom-left'], {
 	offset: { top: 32, right: 16 },
 	options: { fill: '#222', roundness: 20 },
 	theme: 'dark'
@@ -70,18 +72,30 @@ initToasters(document.body, ['top-right'], {
 ### Example: Multiple positions and custom offset
 
 ```js
+// Correct example with multiple positions (classic fallback)
 initToasters(document.body, ['top-right', 'bottom-left'], {
 	offset: { top: 24, right: 24, bottom: 24, left: 24 },
 	theme: 'light',
 	options: { fill: '#0f1724', roundness: 18 }
 });
+
+```js
+// Custom position (make sure you initialized that position)
+notify.success({
+	title: 'Bottom left',
+	position: 'bottom-left'
+});
 ```
 
-## API
+---
+
+## ⚠️ Warnings and Best Practices
 
-```js
-notify.show(options)
-notify.success(options)
+- 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.
 notify.error(options)
 notify.info(options)
 notify.warning(options)
@@ -164,8 +178,8 @@ notify.success({
 If you are not using a bundler, use the [Browser guide](./browser.md) for CDN usage. Example:
 
 ```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.0/dist/styles.css">
+<script src="https://unpkg.com/@samline/notify@0.2.0/dist/notify.umd.js"></script>
 <script>
 	document.addEventListener('DOMContentLoaded', () => {
 		const api = window.notify;

package/docs/vue.md

@@ -95,7 +95,7 @@ function show(){ notify.show({ title: 'Hello from Vue' }); }
 
 > **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">`
+
 
 
 ## API
@@ -112,7 +112,7 @@ All notification methods accept advanced options:
 | `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                      |
+| `position`    | string                                 | `top-right` | One of the valid positions. If you only initialize one position with `<Toaster position="..." />`, toasts without an explicit position will go there (dynamic fallback). If you initialize multiple, the fallback is `top-right`. |
 | `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)                   |
@@ -164,11 +164,18 @@ notify.info({
 	duration: null
 });
 
-// Custom position
+// Custom position (make sure you initialized that position with <Toaster position="bottom-left" />)
 notify.success({
 	title: 'Bottom left',
 	position: 'bottom-left'
 });
+---
+
+## ⚠️ Warnings and Best Practices
+
+- If you only use one `<Toaster position="..." />`, toasts without an explicit position will go there automatically (dynamic fallback).
+- If you use multiple `<Toaster position="..." />`, the fallback will be `top-right`.
+- 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.
 
 // Description as VNode
 notify.info({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samline/notify",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Notifications engine inspired by Sileo, with adapters for vanilla, React, Vue and Svelte.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -37,6 +37,7 @@
     "@types/node": "^20.0.0",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
+    "jsdom": "^29.0.1",
     "rollup": "^3.0.0",
     "rollup-plugin-copy": "^3.4.0",
     "svelte-check": "^3.3.0",