@samline/notify 0.1.15 → 0.2.2

package/docs/vanilla.md

@@ -1,69 +1,240 @@
-# 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' });
+// 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' });
 ```
 
-## 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');
 ```
 
-## API
+## Advanced Toaster Options
 
-```ts
-// Core controller (primary: `notify`, compatibility alias: `sileo`)
-notify.show(options)
-notify.success(options)
+You can pass advanced options to `initToasters`:
+
+```js
+// Correct example with one position (dynamic fallback)
+initToasters(document.body, ['bottom-left'], {
+	offset: { top: 32, right: 16 },
+	options: { fill: '#222', roundness: 20 },
+	theme: 'dark'
+});
+```
+
+### 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'
+});
+```
+
+---
+
+## ⚠️ 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.
 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
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `options` | object | Toast creation options (see Options below) |
+| 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                 |
 
-### Returns
+---
 
-`string | void` — `show` returns a toast id when created.
+# Browser / CDN (No Bundler)
 
-## Options
+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.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;
+		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:
@@ -51,13 +95,177 @@ 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
 
 - `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 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)                   |
+| `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 (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({
+	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.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",