@r01al/simple-toast 1.0.9 β 1.0.10
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.
- package/README.md +182 -184
- package/dist/toast.d.ts +12 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,248 +1,246 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @r01al/simple-toast
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Lightweight, framework-agnostic toast notifications with zero dependencies.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
- π **Theming** - Light, dark themes built-in
|
|
14
|
-
- β¨ **Smooth animations** - Opacity and margin transitions
|
|
15
|
-
- βΏ **Accessibility** - ARIA labels and keyboard support
|
|
16
|
-
- π§Ή **Clean DOM** - Container and styles removed when no toasts visible
|
|
17
|
-
- π¦ **Tiny footprint** - ~13KB unminified (includes all styles)
|
|
9
|
+
## Benefits (why you'll like it) π
|
|
10
|
+
- β‘ **Tiny & fast**: no dependencies, minimal runtime overhead.
|
|
11
|
+
- 𧩠**Framework-agnostic**: use with vanilla JS, React, Vue, Svelte, or anything.
|
|
12
|
+
- π§Ό **Zero setup CSS**: styles are injected automatically.
|
|
13
|
+
- ποΈ **Flexible config**: global defaults + per-toast overrides.
|
|
14
|
+
- βΏ **Accessible by default**: ARIA roles and polite announcements included.
|
|
18
15
|
|
|
19
|
-
##
|
|
16
|
+
## Install π¦
|
|
20
17
|
|
|
21
18
|
```bash
|
|
22
|
-
npm install simple-toast
|
|
19
|
+
npm install @r01al/simple-toast
|
|
23
20
|
```
|
|
24
21
|
|
|
25
|
-
|
|
22
|
+
## Quick start π
|
|
26
23
|
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
|
|
24
|
+
```js
|
|
25
|
+
import toast from '@r01al/simple-toast';
|
|
26
|
+
|
|
27
|
+
toast('Hello there!');
|
|
28
|
+
toast.success('Saved successfully');
|
|
29
|
+
toast.error('Something went wrong');
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Examples π§ͺ
|
|
33
|
+
|
|
34
|
+
Run the demo pages locally:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npm run build
|
|
30
38
|
```
|
|
31
39
|
|
|
32
|
-
|
|
40
|
+
- Full demo page: open `example/index.html` in your browser.
|
|
41
|
+
- Minimal demo page: open `example/minimal.html` in your browser.
|
|
42
|
+
- Scripted usage sample: see `example/usage.js`.
|
|
33
43
|
|
|
34
|
-
|
|
44
|
+
## Usage (detailed) π§
|
|
35
45
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
import { toast } from 'simple-toast';
|
|
39
|
-
// No CSS import needed - styles are auto-injected on first use!
|
|
46
|
+
### 1) Import styles (you donβt have to)
|
|
47
|
+
`simple-toast` injects styles automatically the first time you show a toast.
|
|
40
48
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
toast
|
|
44
|
-
|
|
45
|
-
toast
|
|
49
|
+
### 2) Show a toast
|
|
50
|
+
```js
|
|
51
|
+
import toast from '@r01al/simple-toast';
|
|
52
|
+
|
|
53
|
+
toast('I am a basic toast');
|
|
46
54
|
```
|
|
47
55
|
|
|
48
|
-
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
<body>
|
|
56
|
-
<button onclick="showToast()">Show Toast</button>
|
|
57
|
-
|
|
58
|
-
<script src="simple-toast.umd.js"></script>
|
|
59
|
-
<script>
|
|
60
|
-
function showToast() {
|
|
61
|
-
SimpleToast.toast.success('Hello World!');
|
|
62
|
-
}
|
|
63
|
-
</script>
|
|
64
|
-
</body>
|
|
65
|
-
</html>
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
**CommonJS:**
|
|
69
|
-
```javascript
|
|
70
|
-
const { toast } = require('simple-toast');
|
|
71
|
-
toast.info('This works in Node too!');
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### Advanced Configuration
|
|
75
|
-
|
|
76
|
-
```javascript
|
|
77
|
-
import { toast, configure } from 'simple-toast';
|
|
78
|
-
|
|
79
|
-
// Global configuration
|
|
80
|
-
configure({
|
|
81
|
-
position: 'top-right',
|
|
82
|
-
duration: 3000,
|
|
83
|
-
theme: 'dark',
|
|
84
|
-
maxToasts: 5
|
|
85
|
-
});
|
|
56
|
+
### 3) Use a type helper
|
|
57
|
+
```js
|
|
58
|
+
toast.success('Payment received');
|
|
59
|
+
toast.info('New message');
|
|
60
|
+
toast.warning('Storage almost full');
|
|
61
|
+
toast.error('Upload failed');
|
|
62
|
+
```
|
|
86
63
|
|
|
87
|
-
|
|
88
|
-
|
|
64
|
+
### 4) Customize per-toast
|
|
65
|
+
```js
|
|
66
|
+
toast('Custom toast', {
|
|
67
|
+
type: 'success',
|
|
89
68
|
duration: 5000,
|
|
90
|
-
position: '
|
|
91
|
-
dismissible: true
|
|
69
|
+
position: 'tr',
|
|
70
|
+
dismissible: true,
|
|
71
|
+
theme: 'l',
|
|
72
|
+
className: 'my-toast'
|
|
92
73
|
});
|
|
93
74
|
```
|
|
94
75
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
Display a toast notification.
|
|
76
|
+
### 5) Configure global defaults
|
|
77
|
+
```js
|
|
78
|
+
import { configure } from '@r01al/simple-toast';
|
|
100
79
|
|
|
101
|
-
|
|
80
|
+
configure({
|
|
81
|
+
position: 'bc',
|
|
82
|
+
duration: 4000,
|
|
83
|
+
theme: 'l',
|
|
84
|
+
dismissible: true,
|
|
85
|
+
maxToasts: 6
|
|
86
|
+
});
|
|
87
|
+
```
|
|
102
88
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
| `duration` | number | `3000` | Auto-dismiss duration in ms (0 = no auto-dismiss) |
|
|
107
|
-
| `position` | string | `'top-right'` | Position: `'top-left'`, `'top-center'`, `'top-right'`, `'bottom-left'`, `'bottom-center'`, `'bottom-right'`, `'middle-left'`, `'middle-center'`, `'middle-right'` |
|
|
108
|
-
| `dismissible` | boolean | `true` | Show close button |
|
|
109
|
-
| `theme` | string | `'light'` | Theme: `'light'`, `'dark'`, `'custom'` |
|
|
110
|
-
| `className` | string | `''` | Custom CSS class |
|
|
89
|
+
### 6) Dismiss toasts
|
|
90
|
+
```js
|
|
91
|
+
const id = toast('I will be removed');
|
|
111
92
|
|
|
112
|
-
|
|
93
|
+
// Later...
|
|
94
|
+
toast.dismiss(id);
|
|
113
95
|
|
|
114
|
-
|
|
115
|
-
toast.success(message, options)
|
|
116
|
-
toast.error(message, options)
|
|
117
|
-
toast.info(message, options)
|
|
118
|
-
toast.warning(message, options)
|
|
96
|
+
toast.dismissAll();
|
|
119
97
|
```
|
|
120
98
|
|
|
121
|
-
|
|
99
|
+
## API Reference π
|
|
122
100
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
101
|
+
### `toast(message, options?)`
|
|
102
|
+
- **message**: `string`
|
|
103
|
+
- **options**: `ToastOptions`
|
|
104
|
+
- **returns**: `number` (toast id)
|
|
126
105
|
|
|
127
|
-
###
|
|
106
|
+
### `toast.success(message, options?)`
|
|
107
|
+
### `toast.error(message, options?)`
|
|
108
|
+
### `toast.info(message, options?)`
|
|
109
|
+
### `toast.warning(message, options?)`
|
|
110
|
+
Same as `toast()` but forces the `type`.
|
|
128
111
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
toast.dismiss(toastId); // Dismiss specific toast
|
|
132
|
-
toast.dismissAll(); // Dismiss all toasts
|
|
133
|
-
```
|
|
112
|
+
### `toast.dismiss(id)`
|
|
113
|
+
Dismiss a specific toast by id.
|
|
134
114
|
|
|
135
|
-
|
|
115
|
+
### `toast.dismissAll()`
|
|
116
|
+
Dismiss all active toasts.
|
|
136
117
|
|
|
137
|
-
###
|
|
118
|
+
### `configure(config)`
|
|
119
|
+
Set global defaults for all future toasts.
|
|
138
120
|
|
|
139
|
-
|
|
140
|
-
// Light theme (default)
|
|
141
|
-
configure({ theme: 'light' });
|
|
121
|
+
## Options π§
|
|
142
122
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
123
|
+
### `ToastOptions`
|
|
124
|
+
| Option | Type | Default | Description |
|
|
125
|
+
| --- | --- | --- | --- |
|
|
126
|
+
| `type` | `'success' | 'error' | 'info' | 'warning'` | `'info'` | Visual style + icon. |
|
|
127
|
+
| `duration` | `number` | `3000` | Auto-dismiss after N ms. Use `0` to disable. |
|
|
128
|
+
| `position` | `'tl' | 'tc' | 'tr' | 'ml' | 'mc' | 'mr' | 'bl' | 'bc' | 'br'` | `'bc'` | Screen position (see map below). |
|
|
129
|
+
| `dismissible` | `boolean` | `true` | Show a close button. |
|
|
130
|
+
| `theme` | `'l' | 'd' | string` | `'l'` | `l` = light, `d` = dark, or a custom theme key. |
|
|
131
|
+
| `className` | `string` | `undefined` | Extra class added to the toast element. |
|
|
146
132
|
|
|
147
|
-
|
|
133
|
+
Note: built-in styles use the short position codes and the `l`/`d` theme keys shown above.
|
|
148
134
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
- Error: `#ef4444` (red)
|
|
152
|
-
- Info: `#3b82f6` (blue)
|
|
153
|
-
- Warning: `#f59e0b` (orange)
|
|
135
|
+
### `ToastConfig`
|
|
136
|
+
Includes all `ToastOptions`, plus:
|
|
154
137
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
138
|
+
| Option | Type | Default | Description |
|
|
139
|
+
| --- | --- | --- | --- |
|
|
140
|
+
| `maxToasts` | `number` | `10` | Maximum toasts shown at once. Oldest is dismissed first. |
|
|
141
|
+
|
|
142
|
+
## Position map πΊοΈ
|
|
143
|
+
Short codes map to screen locations:
|
|
160
144
|
|
|
161
|
-
|
|
145
|
+
- `tl` = top-left
|
|
146
|
+
- `tc` = top-center
|
|
147
|
+
- `tr` = top-right
|
|
148
|
+
- `ml` = middle-left
|
|
149
|
+
- `mc` = middle-center
|
|
150
|
+
- `mr` = middle-right
|
|
151
|
+
- `bl` = bottom-left
|
|
152
|
+
- `bc` = bottom-center
|
|
153
|
+
- `br` = bottom-right
|
|
162
154
|
|
|
163
|
-
|
|
155
|
+
## Themes π¨
|
|
156
|
+
Built-in themes are `l` (light) and `d` (dark). To create your own theme:
|
|
164
157
|
|
|
165
158
|
```css
|
|
166
|
-
/*
|
|
167
|
-
.
|
|
168
|
-
background
|
|
159
|
+
/* Example: theme = 'custom' */
|
|
160
|
+
.r01st-container[data-theme="custom"] .r01st-success {
|
|
161
|
+
background: #16a34a;
|
|
169
162
|
}
|
|
170
163
|
|
|
171
|
-
.
|
|
172
|
-
|
|
173
|
-
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.3) !important;
|
|
164
|
+
.r01st-container[data-theme="custom"] .r01st-error {
|
|
165
|
+
background: #dc2626;
|
|
174
166
|
}
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
Or modify the injected styles programmatically before first use.
|
|
178
|
-
|
|
179
|
-
## Architecture
|
|
180
|
-
|
|
181
|
-
Simple Toast uses a modular architecture with separate concerns:
|
|
182
167
|
|
|
183
|
-
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
- **`toast-manager.js`** - Toast state and lifecycle management
|
|
187
|
-
- **`toast-creator.js`** - DOM element creation
|
|
188
|
-
- **`animations.js`** - Show/hide animations
|
|
189
|
-
- **`icons.js`** - SVG icon definitions
|
|
190
|
-
- **`styles.js`** - CSS injection (auto-injected on first use)
|
|
168
|
+
.r01st-container[data-theme="custom"] .r01st-info {
|
|
169
|
+
background: #2563eb;
|
|
170
|
+
}
|
|
191
171
|
|
|
192
|
-
|
|
172
|
+
.r01st-container[data-theme="custom"] .r01st-warning {
|
|
173
|
+
background: #f59e0b;
|
|
174
|
+
}
|
|
175
|
+
```
|
|
193
176
|
|
|
194
|
-
|
|
177
|
+
Then use:
|
|
178
|
+
```js
|
|
179
|
+
toast('Custom theme', { theme: 'custom' });
|
|
180
|
+
```
|
|
195
181
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
3. On first toast, styles are injected into `<head>` via `<style>` tag
|
|
199
|
-
4. Container div is added to `<body>`
|
|
200
|
-
5. Toast element is created and animated in
|
|
201
|
-
6. After duration, toast animates out and is removed
|
|
202
|
-
7. When no toasts remain, container is removed from DOM
|
|
203
|
-
8. **Zero DOM footprint when inactive!**
|
|
182
|
+
## Custom styling β¨
|
|
183
|
+
Add a `className` and style it yourself:
|
|
204
184
|
|
|
205
|
-
|
|
185
|
+
```js
|
|
186
|
+
toast('Styled toast', { className: 'my-toast' });
|
|
187
|
+
```
|
|
206
188
|
|
|
207
|
-
|
|
208
|
-
-
|
|
209
|
-
|
|
210
|
-
-
|
|
211
|
-
|
|
212
|
-
|
|
189
|
+
```css
|
|
190
|
+
.my-toast {
|
|
191
|
+
border: 2px solid #fff;
|
|
192
|
+
backdrop-filter: blur(6px);
|
|
193
|
+
}
|
|
194
|
+
```
|
|
213
195
|
|
|
214
|
-
|
|
196
|
+
## Accessibility βΏ
|
|
197
|
+
- Container uses `role="region"` and `aria-live="polite"`.
|
|
198
|
+
- Each toast uses `role="alert"`.
|
|
199
|
+
- Close button has `aria-label="Close notification"`.
|
|
215
200
|
|
|
216
|
-
##
|
|
201
|
+
## Browser build (UMD) π
|
|
202
|
+
If you prefer a direct script tag, use the UMD build (global name: `SimpleToast`).
|
|
217
203
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
204
|
+
```html
|
|
205
|
+
<script src="https://unpkg.com/@r01al/simple-toast/dist/simple-toast.min.js"></script>
|
|
206
|
+
<script>
|
|
207
|
+
SimpleToast.toast('Hello from the browser build');
|
|
208
|
+
SimpleToast.toast.success('It works!');
|
|
209
|
+
</script>
|
|
210
|
+
```
|
|
221
211
|
|
|
222
|
-
|
|
212
|
+
## TypeScript β
|
|
213
|
+
Type definitions are included. If you need them directly:
|
|
223
214
|
|
|
224
|
-
|
|
215
|
+
```ts
|
|
216
|
+
import toast, { configure, ToastOptions } from '@r01al/simple-toast';
|
|
217
|
+
```
|
|
225
218
|
|
|
226
|
-
|
|
219
|
+
## Common patterns π§
|
|
227
220
|
|
|
228
|
-
|
|
229
|
-
|
|
221
|
+
### Keep it on screen until the user dismisses it
|
|
222
|
+
```js
|
|
223
|
+
toast('Please confirm this action', { duration: 0 });
|
|
224
|
+
```
|
|
230
225
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
position: 'top-center',
|
|
235
|
-
dismissible: true,
|
|
236
|
-
theme: 'dark'
|
|
237
|
-
};
|
|
226
|
+
### Override global config for one toast
|
|
227
|
+
```js
|
|
228
|
+
configure({ duration: 5000, position: 'tr' });
|
|
238
229
|
|
|
239
|
-
toast('
|
|
230
|
+
toast('Overrides only this toast', { duration: 1000, position: 'bl' });
|
|
240
231
|
```
|
|
241
232
|
|
|
242
|
-
|
|
233
|
+
### Limit spammy notifications
|
|
234
|
+
```js
|
|
235
|
+
configure({ maxToasts: 3 });
|
|
236
|
+
```
|
|
243
237
|
|
|
244
|
-
|
|
238
|
+
## Development (for contributors) π οΈ
|
|
239
|
+
```bash
|
|
240
|
+
npm run build
|
|
241
|
+
npm run dev
|
|
242
|
+
```
|
|
245
243
|
|
|
246
|
-
|
|
244
|
+
---
|
|
247
245
|
|
|
248
|
-
MIT
|
|
246
|
+
MIT Β© r01al
|
package/dist/toast.d.ts
CHANGED
|
@@ -13,18 +13,18 @@ export interface ToastOptions {
|
|
|
13
13
|
|
|
14
14
|
/**
|
|
15
15
|
* Position of the toast on screen
|
|
16
|
-
* @default '
|
|
16
|
+
* @default 'bc'
|
|
17
17
|
*/
|
|
18
18
|
position?:
|
|
19
|
-
| '
|
|
20
|
-
| '
|
|
21
|
-
| '
|
|
22
|
-
| '
|
|
23
|
-
| '
|
|
24
|
-
| '
|
|
25
|
-
| '
|
|
26
|
-
| '
|
|
27
|
-
| '
|
|
19
|
+
| 'tl'
|
|
20
|
+
| 'tc'
|
|
21
|
+
| 'tr'
|
|
22
|
+
| 'ml'
|
|
23
|
+
| 'mc'
|
|
24
|
+
| 'mr'
|
|
25
|
+
| 'bl'
|
|
26
|
+
| 'bc'
|
|
27
|
+
| 'br';
|
|
28
28
|
|
|
29
29
|
/**
|
|
30
30
|
* Whether to show a close button
|
|
@@ -34,9 +34,9 @@ export interface ToastOptions {
|
|
|
34
34
|
|
|
35
35
|
/**
|
|
36
36
|
* Theme to apply
|
|
37
|
-
* @default '
|
|
37
|
+
* @default 'l'
|
|
38
38
|
*/
|
|
39
|
-
theme?: '
|
|
39
|
+
theme?: 'l' | 'd' | string;
|
|
40
40
|
|
|
41
41
|
/**
|
|
42
42
|
* Custom CSS class to add to the toast
|