@samline/notify 0.1.10 → 0.1.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +27 -33
  2. package/docs/browser.md +16 -29
  3. package/docs/react.md +40 -28
  4. package/docs/svelte.md +43 -25
  5. package/docs/vanilla.md +22 -16
  6. package/docs/vue.md +66 -14
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -1,4 +1,5 @@
1
1
  ## @samline/notify
2
+
2
3
  A Sileo-inspired notifications engine providing a framework-agnostic core and lightweight adapters for Vanilla JS, React, Vue and Svelte.
3
4
 
4
5
  Inspired by Sileo — see the original project: https://github.com/hiaaryan/sileo
@@ -47,36 +48,30 @@ CDN / Browser
47
48
  Use the browser build when your project loads scripts directly and cannot compile npm modules (Shopify, WordPress, plain HTML). Example CDN usage (replace version):
48
49
 
49
50
  ```html
50
- <script src="https://unpkg.com/@samline/notify@0.1.10/dist/notify.umd.js"></script>
51
- <link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.10/dist/styles.css">
51
+ <script src="https://unpkg.com/@samline/notify@0.1.15/dist/notify.umd.js"></script>
52
+ <link
53
+ rel="stylesheet"
54
+ href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css"
55
+ />
56
+
57
+ <script>
58
+ const api = window.notify || window.notifications
59
+ api.initToasters(document.body, ['top-right'])
60
+ api.notify({ title: 'Saved', description: 'Changes saved', type: 'success' })
61
+ </script>
52
62
  ```
53
63
 
54
64
  Entry Points
55
65
 
56
66
  Choose the entrypoint matching your stack so you only import what you need.
57
67
 
58
- | Use case | Import | Guide |
59
- | --- | --- | --- |
60
- | Vanilla JS | `import { default as notifications } from '@samline/notify'` | [docs/vanilla.md](docs/vanilla.md) |
61
- | Vanilla explicit subpath | `import { sileo } from '@samline/notify/vanilla'` | [docs/vanilla.md](docs/vanilla.md) |
62
- | Browser / CDN | `<script src="https://unpkg.com/@samline/notify@0.1.9/dist/notify.umd.js"></script>` | [docs/browser.md](docs/browser.md) |
63
- | React | `import { Toaster } from '@samline/notify/react'` | [docs/react.md](docs/react.md) |
64
- | Vue | `import Notifications from '@samline/notify/vue'` | [docs/vue.md](docs/vue.md) |
65
- | Svelte | `import Toaster from '@samline/notify/svelte'` | [docs/svelte.md](docs/svelte.md) |
66
-
67
- Quick Start
68
-
69
- Vanilla example (UMD / modules):
70
-
71
- ```html
72
- <script src="https://unpkg.com/@samline/notify@0.1.10/dist/notify.umd.js"></script>
73
- <link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.10/dist/styles.css">
74
- <script>
75
- const api = window.notify || window.notifications;
76
- api.initToasters(document.body, ['top-right']);
77
- api.notify({ title: 'Saved', description: 'Changes saved', type: 'success' });
78
- </script>
79
- ```
68
+ | Use case | Import | Guide |
69
+ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
70
+ | Vanilla JS | `import { notify, initToasters } from '@samline/notify/vanilla'` | [docs/vanilla.md](docs/vanilla.md) |
71
+ | 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) |
72
+ | React | `import { Toaster, notify } from '@samline/notify/react'` | [docs/react.md](docs/react.md) |
73
+ | Vue | `import { Toaster, notify } from '@samline/notify/vue'` | [docs/vue.md](docs/vue.md) |
74
+ | Svelte | `import Toaster, { notify } from '@samline/notify/svelte'` | [docs/svelte.md](docs/svelte.md) |
80
75
 
81
76
  Documentation Guides
82
77
 
@@ -109,14 +104,14 @@ Shared Options
109
104
 
110
105
  Common `options` across entrypoints:
111
106
 
112
- | Property | Type | Default | Description |
113
- | --- | --- | --- | --- |
114
- | `title` | string | — | Toast title |
115
- | `description` | string | — | Optional body text |
116
- | `type` | `info\|success\|error\|warning` | `info` | Visual intent |
117
- | `position` | string | `top-right` | One of toast positions |
118
- | `duration` | number | `4000` | Auto-dismiss timeout in ms (0 = persistent) |
119
- | `button` | { title: string, onClick: () => void } | — | Optional action button |
107
+ | Property | Type | Default | Description |
108
+ | ------------- | -------------------------------------- | ----------- | ------------------------------------------- |
109
+ | `title` | string | — | Toast title |
110
+ | `description` | string | — | Optional body text |
111
+ | `type` | `info\|success\|error\|warning` | `info` | Visual intent |
112
+ | `position` | string | `top-right` | One of toast positions |
113
+ | `duration` | number | `4000` | Auto-dismiss timeout in ms (0 = persistent) |
114
+ | `button` | { title: string, onClick: () => void } | — | Optional action button |
120
115
 
121
116
  Notes
122
117
 
@@ -127,4 +122,3 @@ Notes
127
122
  License
128
123
 
129
124
  MIT
130
-
package/docs/browser.md CHANGED
@@ -1,44 +1,31 @@
1
- # Browser (UMD / no-bundler)
2
1
 
3
- Quick start
2
+ # Browser / CDN usage
4
3
 
5
- Include the UMD bundle and stylesheet in a static page:
4
+ Use this package directly in the browser when you cannot use npm modules or a bundler (e.g. Shopify, WordPress, static HTML).
6
5
 
7
- ```html
8
- <link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.9/dist/styles.css">
9
- <script src="https://unpkg.com/@samline/notify@0.1.9/dist/notify.umd.js"></script>
10
- <script>
11
- const api = window.notify || window.notifications;
12
- api.initToasters(document.body, ['top-right']);
13
- // convenience: api.notify
14
- api.notify({ title: 'Hello', description: 'No-bundler usage', type: 'info' });
15
- </script>
16
- ```
17
-
18
- Notes
6
+ ## Quick start
19
7
 
20
- - The UMD bundle exposes `window.notify` (preferred). For compatibility it also exposes `window.notifications` with the previous API shape.
21
- - Make sure to load `dist/styles.css` for styles and animations.
22
-
23
- ## CDN / Browser
24
-
25
- Use the browser build when your project loads scripts directly in the page and cannot compile npm modules (Shopify, WordPress, plain HTML templates).
26
-
27
- Example using the UMD build (replace path/version as needed):
8
+ Add the stylesheet and UMD bundle to your HTML:
28
9
 
29
10
  ```html
30
- <link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.9/dist/styles.css">
31
- <script src="https://unpkg.com/@samline/notify@0.1.9/dist/notify.umd.js"></script>
11
+ <link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css">
12
+ <script src="https://unpkg.com/@samline/notify@0.1.15/dist/notify.umd.js"></script>
32
13
  <script>
33
14
  document.addEventListener('DOMContentLoaded', () => {
34
- const api = window.notify || window.notifications;
15
+ const api = window.notify; // or window.notifications for legacy
35
16
  api.initToasters(document.body, ['top-right']);
36
17
  api.notify({ title: 'Hello', description: 'No-bundler usage', type: 'info' });
37
18
  });
38
19
  </script>
39
20
  ```
40
21
 
41
- ### Notes
22
+ ## API
23
+
24
+ - The UMD bundle exposes `window.notify` (recommended) and `window.notifications` (legacy/compatibility).
25
+ - Always include `dist/styles.css` for correct appearance and animations.
26
+ - Use `api.initToasters(container, positions)` to mount containers (usually `document.body`).
27
+ - Use `api.notify({...})` to show a notification.
28
+
29
+ ## Notes
42
30
 
43
- The browser bundle exposes `window.notify` (preferred) and for compatibility also exposes `window.notifications`; if these globals conflict with other scripts use the module builds instead.
44
- Include `dist/styles.css` for styles and animations when using the UMD/browser bundle.
31
+ - If you need more control or want to avoid global variables, use the ESM/CJS builds with a bundler.
package/docs/react.md CHANGED
@@ -1,57 +1,69 @@
1
+
1
2
  # React
2
3
 
3
- Installation
4
+ ## Quick start
5
+
6
+ Install the package and peer dependencies:
4
7
 
5
8
  ```bash
6
9
  npm install @samline/notify react react-dom
7
10
  ```
8
11
 
9
- Basic usage
12
+ Import and render the `Toaster` component in your app root:
10
13
 
11
14
  ```tsx
12
15
  import React from 'react';
13
- import { notify, sileo } from '@samline/notify';
14
- import { Toaster } from '@samline/notify/react';
15
16
 
16
- function App(){
17
+ import { Toaster, notify } from '@samline/notify/react';
18
+
19
+ export function App() {
17
20
  return (
18
21
  <>
19
22
  <Toaster />
20
23
  <button onClick={() => notify.show({ title: 'Done', type: 'success' })}>Show</button>
21
24
  </>
22
- )
25
+ );
23
26
  }
24
27
  ```
25
28
 
26
- Notes
29
+ > **Note:**
30
+ > Import `@samline/notify/dist/styles.css` in your main entrypoint or include it in your HTML for correct appearance.
31
+ > CDN: `<link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css">`
27
32
 
28
- - The `Toaster` component subscribes to the core controller and renders toasts.
29
- - You can customize positions and styles by importing `dist/styles.css`.
30
33
 
31
- ## Quick start
32
-
33
- Install:
34
+ ## API
34
35
 
35
- ```bash
36
- npm install @samline/notify react react-dom
36
+ - `<Toaster />` subscribes to the notification controller and renders toasts.
37
+ - Use `notify.show({...})` or shortcut methods (`notify.success`, `notify.error`, `notify.info`, `notify.warning`, `notify.action`, `notify.promise`, `notify.dismiss`, `notify.clear`) to trigger notifications. Import from `@samline/notify/react`.
38
+
39
+ ### Methods
40
+
41
+ ```ts
42
+ notify.show(options)
43
+ notify.success(options)
44
+ notify.error(options)
45
+ notify.info(options)
46
+ notify.warning(options)
47
+ notify.action(options)
48
+ notify.promise(promise, { loading, success, error })
49
+ notify.dismiss(id)
50
+ notify.clear()
37
51
  ```
38
52
 
39
- Import and render the React `Toaster` in your app:
53
+ ### Options
40
54
 
41
- ```tsx
42
- import React from 'react';
43
- import { Toaster } from '@samline/notify/react';
44
- import { notify, sileo } from '@samline/notify';
55
+ | Property | Type | Default | Description |
56
+ | ------------- | -------------------------------------- | ----------- | ------------------------------------------- |
57
+ | `title` | string | — | Toast title |
58
+ | `description` | string | — | Optional body text |
59
+ | `type` | `info\|success\|error\|warning` | `info` | Visual intent |
60
+ | `position` | string | `top-right` | One of toast positions |
61
+ | `duration` | number | `4000` | Auto-dismiss timeout in ms (0 = persistent) |
62
+ | `button` | { title: string, onClick: () => void } | — | Optional action button |
45
63
 
46
- export function App(){
47
- return (
48
- <div>
49
- <Toaster />
50
- <button onClick={() => notify.show({ title: 'Done', type: 'success' })}>Show</button>
51
- </div>
52
- );
53
- }
54
- ```
64
+ ## Tips
65
+
66
+ - You can customize positions and styles by overriding CSS variables or importing the stylesheet in your preferred way.
55
67
 
56
68
  ## API
57
69
 
package/docs/svelte.md CHANGED
@@ -1,50 +1,68 @@
1
- # Svelte
2
1
 
3
- Quick start
4
2
  # Svelte
5
3
 
6
- Quick start
4
+ ## Quick start
5
+
6
+ Install the package:
7
7
 
8
8
  ```bash
9
9
  npm install @samline/notify svelte
10
10
  ```
11
11
 
12
- Usage
12
+ Import and initialize in your root component:
13
13
 
14
14
  ```svelte
15
15
  <script>
16
16
  import Toaster, { initSileoStore } from '@samline/notify/svelte';
17
- initSileoStore();
17
+ initSileoStore(); // Call once in your app root
18
+
19
+ import { notify } from '@samline/notify/svelte';
20
+ function show() {
21
+ notify.show({ title: 'From Svelte' });
22
+ }
18
23
  </script>
19
24
 
20
25
  <Toaster />
21
-
22
- <button on:click={() => import('@samline/notify').then(m => m.notify.show({ title: 'Svelte' }))}>Show</button>
26
+ <button on:click={show}>Show</button>
23
27
  ```
24
28
 
25
- TypeScript
29
+ > **Note:**
30
+ > Import `@samline/notify/dist/styles.css` in your main entrypoint or HTML for correct appearance.
31
+ > CDN: `<link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css">`
26
32
 
27
- If you use TypeScript, run `npm run typecheck` and `npx svelte-check` during development.
28
33
 
29
34
  ## API
30
35
 
31
- - `Toaster.svelte` — component that renders toasts and subscribes to the core controller.
32
- - `initSileoStore()` — helper to wire the core `notify`/`sileo` controller to a Svelte store.
33
-
34
- ## Examples
36
+ - `Toaster.svelte`: Renders notifications and subscribes to the core controller.
37
+ - `initSileoStore()`: Wires the notification controller to a Svelte store (call once in your app root).
38
+ - Use `notify.show({...})` or shortcut methods to trigger notifications. Import from `@samline/notify/svelte` (now available directly).
39
+
40
+ ### Methods
41
+
42
+ ```ts
43
+ notify.show(options)
44
+ notify.success(options)
45
+ notify.error(options)
46
+ notify.info(options)
47
+ notify.warning(options)
48
+ notify.action(options)
49
+ notify.promise(promise, { loading, success, error })
50
+ notify.dismiss(id)
51
+ notify.clear()
52
+ ```
35
53
 
36
- ```svelte
37
- <script>
38
- import Toaster, { initSileoStore } from '@samline/notify/svelte';
39
- initSileoStore();
40
- function show(){ import('@samline/notify').then(m => m.notify.show({ title: 'From Svelte' })); }
41
- </script>
54
+ ### Options
42
55
 
43
- <Toaster />
44
- <button on:click={show}>Show</button>
45
- ```
56
+ | Property | Type | Default | Description |
57
+ | ------------- | -------------------------------------- | ----------- | ------------------------------------------- |
58
+ | `title` | string | — | Toast title |
59
+ | `description` | string | — | Optional body text |
60
+ | `type` | `info\|success\|error\|warning` | `info` | Visual intent |
61
+ | `position` | string | `top-right` | One of toast positions |
62
+ | `duration` | number | `4000` | Auto-dismiss timeout in ms (0 = persistent) |
63
+ | `button` | { title: string, onClick: () => void } | — | Optional action button |
46
64
 
47
- ## Notes
65
+ ## Tips
48
66
 
49
- - Use `npx svelte-check` and `npm run typecheck` when developing with TypeScript.
50
- - The Svelte adapter is lightweight and subscribes to the shared core controller; use `initSileoStore()` in your app root to wire the store.
67
+ - For TypeScript, use `npx svelte-check` and `npm run typecheck` during development.
68
+ - You can customize styles by overriding CSS variables or importing the stylesheet as needed.
package/docs/vanilla.md CHANGED
@@ -1,19 +1,29 @@
1
- # Vanilla
1
+ # Vanilla JS
2
2
 
3
- ## Quick Start
3
+ Use the vanilla adapter for plain JavaScript projects, either with modules or directly via CDN.
4
4
 
5
- Import and initialize the vanilla (DOM) renderer:
5
+ ## Quick start (ESM / npm)
6
6
 
7
7
  ```ts
8
- import { notify, sileo, initToasters } from '@samline/notify/vanilla';
9
-
10
- // Mount the containers (defaults to document.body)
8
+ import { notify, initToasters } from '@samline/notify/vanilla';
11
9
  initToasters(document.body, ['top-right']);
12
-
13
- // Show a notification (use `notify(...)` as the recommended API)
14
10
  notify({ title: 'Saved', description: 'Your changes have been saved', type: 'success' });
15
11
  ```
16
12
 
13
+ ## Quick start (CDN / UMD)
14
+
15
+ ```html
16
+ <link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css">
17
+ <script src="https://unpkg.com/@samline/notify@0.1.15/dist/notify.umd.js"></script>
18
+ <script>
19
+ document.addEventListener('DOMContentLoaded', () => {
20
+ const api = window.notify;
21
+ api.initToasters(document.body, ['top-right']);
22
+ api.notify({ title: 'Saved', description: 'Your changes have been saved', type: 'success' });
23
+ });
24
+ </script>
25
+ ```
26
+
17
27
  ## API
18
28
 
19
29
  ```ts
@@ -50,14 +60,10 @@ notify.clear()
50
60
  | `duration` | `number` | `4000` | Auto-dismiss timeout in ms (`null` = sticky) |
51
61
  | `button` | `{ title, onClick }` | — | Optional action button |
52
62
 
53
- ## Examples
54
-
55
- ### Basic
63
+ ## Tips
56
64
 
57
- ```ts
58
- import { notify, initToasters } from '@samline/notify/vanilla';
59
- initToasters();
60
- notify.success({ title: 'Saved' });
65
+ - Always include the stylesheet for correct appearance.
66
+ - Use the ESM build for modern projects, or the UMD build for legacy/static sites.
61
67
  ```
62
68
 
63
69
  ### Promise flow
@@ -67,7 +73,7 @@ notify.promise(fetch('/api/save'), {
67
73
  loading: { title: 'Saving...' },
68
74
  success: { title: 'Done', type: 'success' },
69
75
  error: { title: 'Failed', type: 'error' }
70
- });
76
+ import { notify, initToasters } from '@samline/notify/vanilla'; // Import from '@samline/notify/vanilla'
71
77
  ```
72
78
 
73
79
  ## When to use
package/docs/vue.md CHANGED
@@ -1,41 +1,93 @@
1
1
  # Vue 3
2
2
 
3
- Quick start
3
+ ## Quick start
4
+
5
+ Install the package:
6
+
7
+ ```bash
8
+ npm install @samline/notify vue
9
+ ```
10
+
11
+ Register the `Toaster` component in your app:
4
12
 
5
13
  ```js
6
14
  import { createApp } from 'vue';
7
15
  import App from './App.vue';
8
- import Notifications from '@samline/notify/vue';
16
+ import { Toaster } from '@samline/notify/vue';
9
17
 
10
18
  const app = createApp(App);
11
- app.use(Notifications);
19
+ app.component('Toaster', Toaster);
12
20
  app.mount('#app');
13
21
  ```
14
22
 
15
- Usage
16
23
 
17
- - The plugin registers a `Toaster` component and provides a `useSileo()` composable to access the controller.
18
24
 
19
- Example in a single-file component:
25
+ Use the `notify` controller to show notifications:
26
+
27
+ ```js
28
+ import { notify } from '@samline/notify/vue';
29
+ notify.show({ title: 'Hello from Vue' });
30
+ ```
31
+
32
+ Or access it globally in any component via `this.$notify` (if you use the plugin install):
33
+
34
+ ```js
35
+ this.$notify.show({ title: 'From global' });
36
+ ```
37
+
38
+ In your template:
20
39
 
21
40
  ```vue
22
41
  <template>
23
- <Toaster />
24
- <button @click="show">Show</button>
42
+ <Toaster />
43
+ <button @click="show">Show</button>
25
44
  </template>
26
45
 
27
46
  <script setup>
28
- import { notify, sileo } from '@samline/notify';
47
+ import { notify } from '@samline/notify/vue';
29
48
  function show(){ notify.show({ title: 'Hello from Vue' }); }
30
49
  </script>
31
-
50
+ ```
51
+
52
+ > **Note:**
53
+ > Import `@samline/notify/dist/styles.css` in your main entrypoint or HTML for correct appearance.
54
+ > CDN: `<link rel="stylesheet" href="https://unpkg.com/@samline/notify@0.1.15/dist/styles.css">`
55
+
56
+
32
57
  ## API
33
58
 
34
- - `Notifications` plugin: registers a global component `SileoToaster` and exposes `app.config.globalProperties.$sileo`.
35
- - `useSileo()` (composable): returns the `sileo` controller instance for programmatic use.
59
+ - `Toaster`: Main visual component (same as in React and Svelte).
60
+ - `notify`: Programmatic controller for showing notifications. Import from `@samline/notify/vue` or use `this.$notify` if using the plugin.
61
+ - Advanced: The `Notifications` plugin is available for global/legacy registration, but direct use of `Toaster` is recommended for most apps.
62
+ - `useSileo()`: Composable that returns the `sileo` controller if you prefer.
63
+
64
+ ### Methods
65
+
66
+ ```ts
67
+ notify.show(options)
68
+ notify.success(options)
69
+ notify.error(options)
70
+ notify.info(options)
71
+ notify.warning(options)
72
+ notify.action(options)
73
+ notify.promise(promise, { loading, success, error })
74
+ notify.dismiss(id)
75
+ notify.clear()
76
+ ```
77
+
78
+ ### Options
79
+
80
+ | Property | Type | Default | Description |
81
+ | ------------- | -------------------------------------- | ----------- | ------------------------------------------- |
82
+ | `title` | string | — | Toast title |
83
+ | `description` | string | — | Optional body text |
84
+ | `type` | `info\|success\|error\|warning` | `info` | Visual intent |
85
+ | `position` | string | `top-right` | One of toast positions |
86
+ | `duration` | number | `4000` | Auto-dismiss timeout in ms (0 = persistent) |
87
+ | `button` | { title: string, onClick: () => void } | — | Optional action button |
36
88
 
37
- ## Notes
89
+ ## Tips
38
90
 
39
91
  - The Vue adapter integrates with the Vue lifecycle and works with Vue 3's Composition API.
40
- - To customize appearance, import `dist/styles.css` or override the CSS variables.
92
+ - You can customize appearance by importing the stylesheet or overriding CSS variables.
41
93
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@samline/notify",
3
- "version": "0.1.10",
3
+ "version": "0.1.15",
4
4
  "description": "Notifications engine inspired by Sileo, with adapters for vanilla, React, Vue and Svelte.",
5
5
  "main": "dist/index.cjs.js",
6
6
  "module": "dist/index.esm.js",