@samline/notify 0.1.10 → 0.2.0

package/docs/vanilla.md

@@ -1,63 +1,226 @@
-# Vanilla
 
-## Quick Start
+# Vanilla JS (Bundler/Import)
 
-Import and initialize the vanilla (DOM) renderer:
+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.
 
-```ts
-import { notify, sileo, initToasters } from '@samline/notify/vanilla';
+## Quick start (ESM / npm)
 
-// Mount the containers (defaults to document.body)
+```js
+import { notify, initToasters } from '@samline/notify/vanilla';
 initToasters(document.body, ['top-right']);
+notify.success({ title: 'Saved', description: 'Your changes have been saved' });
+```
+
+## 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');
+```
+
+## Advanced Toaster Options
+
+You can pass advanced options to `initToasters`:
 
-// Show a notification (use `notify(...)` as the recommended API)
-notify({ title: 'Saved', description: 'Your changes have been saved', type: 'success' });
+```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
+});
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `options` | object | Toast creation options (see Options below) |
+// Autopilot off (manual expand/collapse)
+notify.success({
+	title: 'Manual',
+	autopilot: false
+});
 
-### Returns
+// Custom duration (sticky)
+notify.info({
+	title: 'Sticky',
+	duration: null
+});
 
-`string | void` — `show` returns a toast id when created.
+// Custom position
+notify.success({
+	title: 'Bottom left',
+	position: 'bottom-left'
+});
+```
 
-## Options
+### 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                 |
+
+---
+
+# Browser / CDN (No Bundler)
+
+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>
+<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 |
 
-## Examples
+## Tips
 
-### Basic
+- Always include the stylesheet for correct appearance.
+- Use the ESM build for modern projects, or the UMD build for legacy/static sites.
 
-```ts
-import { notify, initToasters } from '@samline/notify/vanilla';
-initToasters();
-notify.success({ title: 'Saved' });
+## 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
@@ -67,7 +230,7 @@ notify.promise(fetch('/api/save'), {
 	loading: { title: 'Saving...' },
 	success: { title: 'Done', type: 'success' },
 	error: { title: 'Failed', type: 'error' }
-});
+import { notify, initToasters } from '@samline/notify/vanilla'; // Import from '@samline/notify/vanilla'
 ```
 
 ## When to use

package/docs/vue.md

@@ -1,41 +1,294 @@
 # Vue 3
 
-Quick start
+## Quick start
+
+Install the package:
+
+```bash
+npm install @samline/notify vue
+```
+
+Register the `Toaster` component in your app:
 
 ```js
 import { createApp } from 'vue';
 import App from './App.vue';
-import Notifications from '@samline/notify/vue';
+import { Toaster } from '@samline/notify/vue';
 
 const app = createApp(App);
-app.use(Notifications);
+app.component('Toaster', Toaster);
 app.mount('#app');
 ```
 
-Usage
+## 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:
+
+```js
+import { notify } from '@samline/notify/vue';
+notify.show({ title: 'Hello from Vue' });
+```
+
+Or access it globally in any component via `this.$notify` (if you use the plugin install):
 
-- The plugin registers a `Toaster` component and provides a `useSileo()` composable to access the controller.
+```js
+this.$notify.show({ title: 'From global' });
+```
 
-Example in a single-file component:
+In your template:
 
 ```vue
 <template>
-  <Toaster />
-  <button @click="show">Show</button>
+	<Toaster />
+	<button @click="show">Show</button>
 </template>
 
 <script setup>
-import { notify, sileo } from '@samline/notify';
+import { notify } from '@samline/notify/vue';
 function show(){ notify.show({ title: 'Hello from Vue' }); }
 </script>
- 
+```
+
+> **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
 
-- `Notifications` plugin: registers a global component `SileoToaster` and exposes `app.config.globalProperties.$sileo`.
-- `useSileo()` (composable): returns the `sileo` controller instance for programmatic use.
+- `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.
+
+### Methods
+
+```ts
+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.dismiss(id)
+notify.clear()
+```
+
+### Options
+
+| 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` | One of toast positions                      |
+| `duration`    | number                                 | `4000`      | Auto-dismiss timeout in ms (0 = persistent) |
+| `button`      | { title: string, onClick: () => void } | —           | Optional action button                      |
 
-## Notes
+## Tips
 
 - The Vue adapter integrates with the Vue lifecycle and works with Vue 3's Composition API.
-- To customize appearance, import `dist/styles.css` or override the CSS variables.
+- You can customize appearance by importing the stylesheet or overriding CSS variables.
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samline/notify",
-  "version": "0.1.10",
+  "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",