@editora/toast 2.1.2 → 2.2.0

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/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # Change Log
2
2
 
3
+ ## 2.2.0
4
+
5
+ ### Minor Changes
6
+
7
+ - adb41b4: No CSS to import, JSX in React, and a smaller bundle.
8
+
9
+ - **The styles are built in.** The first toast puts them in a `<style>` at the start of `<head>` (so the app's own CSS still wins), unless `toast.css` is already on the page. Importing `toast.css` keeps working. Under a content security policy, `configure({ nonce })` or `<meta property="csp-nonce">` gives the `<style>` its nonce; `configure({ injectStyles: false })` turns it off.
10
+ - **`@editora/toast/lite`**: the same API without the built-in stylesheet, for apps that load `toast.css` themselves (about 5 KB gzipped smaller).
11
+ - **`@editora/toast/react`**: `toast` takes JSX as the title, message, description and icon; `toast.custom(render, options?)` shows your own component in the toast; `<Toaster />` renders that JSX through portals, so it sees the app's context, and takes the settings as props. It is marked `"use client"`. React 16.8 to 20 are supported (optional peer dependencies).
12
+ - **DOM nodes** can be the `title`, `message` and `description` of a toast, as they already could be its `icon`. A toast with node content is a duplicate only by `dedupeKey`, and a ResizeObserver lays the stack out again when a toast's content changes size.
13
+ - **`toast.promise` keeps the loading toast until the promise settles.** Before, a promise slower than `duration` lost its toast and the success or error was never shown. A result can also be a function that returns options: `success: (file) => ({ title: ..., description: ... })`.
14
+ - **Smaller**: the spring, bounce, slide, zoom, flip, fade, elastic and rotate animations are a separate file, loaded the first time one is used. With its styles included, the package is about 15 KB gzipped in an app (it was 12.5 KB plus 5.6 KB of CSS).
15
+ - The `browser` field and export condition are gone: they pointed bundlers that read them (webpack 4) at the UMD build instead of the ES module one. The UMD file is unchanged in place, and now brings its styles too.
16
+ - The stale `.d.ts` files that were committed in `src/` are removed (the published typings are built into `dist/`).
17
+
3
18
  ## 2.1.2
4
19
 
5
20
  ### Patch Changes
package/README.md CHANGED
@@ -1,8 +1,9 @@
1
1
  <h1 align="center">@editora/toast</h1>
2
2
 
3
3
  <p align="center">
4
- Toast notifications with no dependencies and nothing to mount: call <code>toast.success('Saved')</code> from
5
- anywhere. Status icons, a stack that opens on hover, promise toasts, actions, progress, light and dark, keyboard access.
4
+ Toast notifications with no dependencies, nothing to mount and no CSS to import: call <code>toast.success('Saved')</code>
5
+ from anywhere. Status icons, a stack that opens on hover, promise toasts, actions, progress, light and dark, keyboard
6
+ access, and JSX in React.
6
7
  </p>
7
8
 
8
9
  <p align="center">
@@ -24,8 +25,11 @@
24
25
 
25
26
  ## Features
26
27
 
27
- - **Nothing to mount.** No provider, no container element: the first call creates what it needs. It works from React,
28
- Vue, plain JavaScript, a service, or an event handler.
28
+ - **Nothing to mount, no CSS to import.** No provider, no container element, no stylesheet: the first call creates
29
+ what it needs and puts the styles on the page. It works from React, Vue, plain JavaScript, a service, or an event
30
+ handler.
31
+ - **JSX in React.** `@editora/toast/react` takes JSX wherever text goes, and `toast.custom()` shows your own component in
32
+ the toast. `<Toaster />` renders it with your app's context.
29
33
  - **A modern card.** An opaque, neutral surface with a status icon (a different shape for each level, so colour is
30
34
  never the only cue), in light and dark. Dark follows the system, or your app's own `.dark` switch.
31
35
  - **A stack that opens on hover.** Several toasts fold into a deck, the newest in full; hover it or focus it and it
@@ -36,7 +40,8 @@
36
40
  swipe-to-dismiss.
37
41
  - **Keyboard and screen readers.** Alt+T jumps to the toasts, Escape dismisses one, errors are announced as alerts and
38
42
  the rest politely, and `prefers-reduced-motion` is respected.
39
- - **Small.** 15 KB gzipped plus 5 KB of CSS. No dependencies.
43
+ - **Small.** 15 KB gzipped in your app, styles included (11 KB with the [lite entry](#styles) and your own copy of
44
+ toast.css). The spring, bounce and other animations load only if you use one. No dependencies.
40
45
  - **Safe on the server.** The package imports in Node and the calls do nothing there, so a call in shared code does not
41
46
  break server rendering.
42
47
  - Written in TypeScript. A script tag works too (a UMD build).
@@ -51,7 +56,6 @@ npm install @editora/toast
51
56
 
52
57
  ```ts
53
58
  import { toast } from '@editora/toast';
54
- import '@editora/toast/toast.css';
55
59
 
56
60
  toast.success('Document saved');
57
61
  toast.info('A new version is available');
@@ -77,7 +81,6 @@ subscriptions.
77
81
 
78
82
  ```ts
79
83
  import { toast } from '@editora/toast';
80
- import '@editora/toast/toast.css';
81
84
 
82
85
  // A toast with a title, a description, actions and progress. duration: 0 keeps it until it is dismissed.
83
86
  const report = toast.show({
@@ -113,7 +116,6 @@ and closes the toast; give the action `dismissOnClick: false` to keep the toast
113
116
 
114
117
  ```ts
115
118
  import { toast } from '@editora/toast';
116
- import '@editora/toast/toast.css';
117
119
 
118
120
  const saveDocument = new Promise<{ name: string }>((resolve) => {
119
121
  setTimeout(() => resolve({ name: 'Q3-summary.pdf' }), 1500);
@@ -152,7 +154,6 @@ loading text.
152
154
 
153
155
  ```ts
154
156
  import { toast } from '@editora/toast';
155
- import '@editora/toast/toast.css';
156
157
 
157
158
  // By default several toasts fold into a deck: the newest in full, the others as edges behind it.
158
159
  // Hover the deck (or press Alt+T) and it opens into a list; the timers wait while it is open.
@@ -185,7 +186,6 @@ On a touch screen a tap opens the deck; a tap elsewhere closes it.
185
186
 
186
187
  ```ts
187
188
  import { toast } from '@editora/toast';
188
- import '@editora/toast/toast.css';
189
189
 
190
190
  // A list instead of a deck, so all four are visible at once.
191
191
  toast.configure({ maxVisible: 4, stack: false });
@@ -212,7 +212,6 @@ There is nothing to render. Call `toast` from a handler, an effect or a service:
212
212
 
213
213
  ```tsx
214
214
  import { toast } from '@editora/toast';
215
- import '@editora/toast/toast.css';
216
215
 
217
216
  async function saveDraft() {
218
217
  await new Promise((resolve) => setTimeout(resolve, 800));
@@ -237,16 +236,93 @@ export default function SaveButton() {
237
236
  }
238
237
  ```
239
238
 
239
+ ### JSX
240
+
241
+ For React content, import from `@editora/toast/react`. It is the same `toast`, except that the title, the message, the
242
+ description and the icon can be JSX, and `toast.custom()` shows a component of your own:
243
+
244
+ ```tsx
245
+ import { Toaster, toast } from '@editora/toast/react';
246
+
247
+ export default function App() {
248
+ function archive() {
249
+ // JSX goes anywhere text does: the title, the message, the description, the icon.
250
+ toast.success(
251
+ <span>
252
+ Moved <strong>Q3-summary.pdf</strong> to Archive
253
+ </span>,
254
+ { action: { label: 'Undo', onClick: () => toast.info('Moved back') } }
255
+ );
256
+ }
257
+
258
+ function invite() {
259
+ // A toast made of your own JSX, in the toast card, with a function that dismisses it.
260
+ toast.custom(
261
+ ({ dismiss }) => (
262
+ <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
263
+ <span style={{ flex: 1 }}>
264
+ Ana invited you to <strong>Roadmap</strong>
265
+ </span>
266
+ <button onClick={dismiss}>Join</button>
267
+ </div>
268
+ ),
269
+ { duration: 0 }
270
+ );
271
+ }
272
+
273
+ return (
274
+ <>
275
+ {/* Once, inside your providers: it renders the JSX of the toasts, with your app's context. */}
276
+ <Toaster position="bottom-right" />
277
+ <button onClick={archive}>Archive</button>
278
+ <button onClick={invite}>Invite</button>
279
+ </>
280
+ );
281
+ }
282
+ ```
283
+
284
+ <p align="center">
285
+ <img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/react-jsx.png" alt="Two toasts: a success toast that says Moved Q3-summary.pdf to Archive, with the file name in bold and an Undo button, and a custom toast that says Ana invited you to Roadmap, with a Join button" width="440">
286
+ </p>
287
+
288
+ `<Toaster />` renders that JSX into the toasts through portals, so it sees the context of the place it is mounted
289
+ (a theme, a router, a translation provider): mount it once, inside your providers. It renders nothing else, and its props
290
+ are the [settings](#configure-it). Text does not need it; a toast with JSX and no `<Toaster />` says so in the console.
291
+
292
+ The JSX keeps its state while the toast is updated (`toast.update(id, { title: <b>New</b> })` swaps the title in place),
293
+ and goes when the toast does. `toast.promise` takes JSX for each state, or a function that returns it, and keeps the
294
+ loading toast however long the promise takes.
295
+
240
296
  [`@editora/ui-react`](https://www.npmjs.com/package/@editora/ui-react) also has a `ToastProvider` and a `useToast()` hook
241
297
  if you like a provider.
242
298
 
299
+ ## Styles
300
+
301
+ The styles are built in. The first toast puts them in a `<style>` at the start of `<head>`, so your own CSS still wins,
302
+ and only if `toast.css` is not on the page already. Under a content security policy, give it your nonce:
303
+ `configure({ nonce })`, or a `<meta property="csp-nonce" nonce="...">` (which Vite writes for you) is read.
304
+
305
+ To load the stylesheet as a file instead (a CSS pipeline, or a policy that allows no inline styles), import the lite
306
+ entry, which has the same API without the built-in copy, about 5 KB gzipped smaller:
307
+
308
+ ```ts
309
+ import { toast } from '@editora/toast/lite';
310
+ import '@editora/toast/toast.css';
311
+
312
+ // The same API, styled by your copy of toast.css (the lite entry has no built-in one).
313
+ toast.success('Styled by toast.css');
314
+ ```
315
+
316
+ `configure({ injectStyles: false })` does the same with the main entry. Restyle toasts with the `--et-*` variables or by
317
+ overriding `.editora-toast` (see [Themes](#themes)).
318
+
319
+
243
320
  ## From a script tag
244
321
 
245
- The UMD build defines three globals: `toast`, `toastAdvanced` and `toastPro` (the same object as `toastAdvanced`).
246
- Pin a version in production, as here:
322
+ The UMD build defines three globals: `toast`, `toastAdvanced` and `toastPro` (the same object as `toastAdvanced`), and
323
+ brings its styles, as the main entry does. Pin a version in production, as here:
247
324
 
248
325
  ```html
249
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@editora/toast@2/dist/toast.css" />
250
326
  <script src="https://cdn.jsdelivr.net/npm/@editora/toast@2/dist/index.umd.js"></script>
251
327
 
252
328
  <button id="save">Save</button>
@@ -275,7 +351,6 @@ Pin a version in production, as here:
275
351
 
276
352
  ```ts
277
353
  import { toast } from '@editora/toast';
278
- import '@editora/toast/toast.css';
279
354
 
280
355
  // Settings for every toast from now on. A toast can still override them.
281
356
  toast.configure({
@@ -310,6 +385,8 @@ toast.warning('Your plan renews tomorrow', { theme: 'sunset', duration: 0 });
310
385
  | `rtl` | `false` | Right-to-left layout. |
311
386
  | `richColors` | `false` | Tint each toast with the colour of its level. |
312
387
  | `container` | the page body | The element toasts are added to. |
388
+ | `injectStyles` | `true` | Put the built-in styles on the page with the first toast (see [Styles](#styles)). |
389
+ | `nonce` | from `<meta property="csp-nonce">` | The nonce for that `<style>`, under a content security policy. |
313
390
 
314
391
  `toast.getConfig()` (on `toastAdvanced`) returns the current settings.
315
392
 
@@ -320,7 +397,6 @@ toast.warning('Your plan renews tomorrow', { theme: 'sunset', duration: 0 });
320
397
 
321
398
  ```ts
322
399
  import { toast } from '@editora/toast';
323
- import '@editora/toast/toast.css';
324
400
 
325
401
  // A deck would fold these into one; stack: false keeps them in a list.
326
402
  toast.configure({ position: 'top-right', maxVisible: 12, stack: false, gap: 8 });
@@ -360,7 +436,6 @@ A theme is a set of CSS variables, so you can make your own with a few lines (th
360
436
 
361
437
  ```ts
362
438
  import { toast } from '@editora/toast';
363
- import '@editora/toast/toast.css';
364
439
 
365
440
  toast.configure({ maxVisible: 10 });
366
441
 
@@ -385,7 +460,7 @@ Everything `show()` accepts. All of it is optional except a message (or a title)
385
460
 
386
461
  | Option | |
387
462
  | --- | --- |
388
- | `message`, `title`, `description` | The text. |
463
+ | `message`, `title`, `description` | The text, or a DOM node (a link you made, say). With `@editora/toast/react`, JSX. |
389
464
  | `level` | `'info'`, `'success'`, `'warning'`, `'error'` or `'loading'`. |
390
465
  | `icon` | Your own icon: a string (text or an emoji) or a DOM node; `false` for none. Left out, the level's icon. |
391
466
  | `actions`, `action`, `cancel` | Buttons: `{ label, onClick, primary?, dismissOnClick? }`. |
@@ -424,7 +499,7 @@ to where you were. While a toast has keyboard focus, or the pointer is over the
424
499
  | `toast(message, options?)` | A plain toast, with no level and no icon. |
425
500
  | `info`, `success`, `warning`, `error`, `loading` `(message, options?)` | A toast of that level. |
426
501
  | `show(options)` | Show a toast from full options; returns `{ id, options, dismiss(), update(options) }`. |
427
- | `promise(promise, { loading, success, error })` | A toast that follows a promise (also `onSuccess` and `onError`); resolves with the promise's value. |
502
+ | `promise(promise, { loading, success, error })` | A toast that follows a promise (also `onSuccess` and `onError`); resolves with the promise's value. Each state is a message, options, or (for `success` and `error`) a function of the result that returns either. The loading toast stays until the promise settles. |
428
503
  | `update(id, options)` | Change a toast. |
429
504
  | `dismiss(id?)` / `clear()` | Remove one toast, or (with no id) every toast. |
430
505
  | `configure(settings)` | Set the [settings](#configure-it). |
@@ -445,6 +520,29 @@ The classes and types are exported too: `ToastManager`, and `ToastOptions`, `Toa
445
520
  `ToastPosition`, `ToastTheme`, `ToastPromiseOptions` and more. If you are upgrading from 1.x, see the
446
521
  [migration guide](https://github.com/ajaykr089/Editora/blob/main/packages/editora-toast/MIGRATION_GUIDE.md).
447
522
 
523
+ `@editora/toast/react` exports the same `toast` (taking JSX), plus:
524
+
525
+ | Export | |
526
+ | --- | --- |
527
+ | `toast.custom(render, options?)` | A toast made of your JSX. `render` is JSX, or `({ id, dismiss }) => JSX`. |
528
+ | `<Toaster {...settings} />` | Renders the JSX of the toasts; its props are the settings. |
529
+
530
+ The types are exported too: `ReactToastOptions`, `ToasterProps`, `CustomToast`, `ToastNode`.
531
+
532
+ ## Upgrading from 2.1
533
+
534
+ 2.2 adds; nothing was removed or renamed.
535
+
536
+ - **No CSS import.** The styles come with the package. If you import `toast.css`, nothing changes: the built-in copy is
537
+ only used when the stylesheet is not on the page. To keep only your file, import `@editora/toast/lite` instead.
538
+ - **JSX** with `@editora/toast/react` and `<Toaster />`, and DOM nodes as `title`, `message` and `description`.
539
+ - **toast.promise** keeps the loading toast until the promise settles. Before, a promise slower than `duration` lost its
540
+ toast, and the result was never shown. A result can be options returned by a function:
541
+ ``success: (file) => ({ title: `Saved ${file.name}`, description: 'In Drafts' })``.
542
+ - **Smaller**: the named animations (spring, bounce, slide...) are a separate file, loaded the first time one is used.
543
+ - The package no longer sets the `browser` field: bundlers that read it (webpack 4) now get the ES module build rather
544
+ than the UMD one. The UMD file is where it was, for `<script>` tags and CDNs.
545
+
448
546
  ## Upgrading from 2.0
449
547
 
450
548
  2.1 changes how toasts look and where they sit; nothing was removed.
package/dist/api.d.ts ADDED
@@ -0,0 +1,46 @@
1
+ import { ToastOptions, ToastInstance, ToastConfig, ToastPlugin, ToastPromiseOptions, ToastTheme, ToastPosition, ToastSubscriber, ToastText } from "./core/types";
2
+ export type ToastLevel = "info" | "success" | "error" | "warning" | "loading";
3
+ export interface ToastOptionsLegacy extends ToastOptions {
4
+ message: string;
5
+ }
6
+ declare function toastBase(msg: ToastText, optionsOrDuration?: Partial<ToastOptions> | number, theme?: ToastTheme, position?: ToastPosition): ToastInstance;
7
+ export declare const toast: typeof toastBase & {
8
+ info: (msg: ToastText, optionsOrDuration?: Partial<ToastOptions> | number, theme?: ToastTheme, position?: ToastPosition) => ToastInstance;
9
+ success: (msg: ToastText, optionsOrDuration?: Partial<ToastOptions> | number, theme?: ToastTheme, position?: ToastPosition) => ToastInstance;
10
+ error: (msg: ToastText, optionsOrDuration?: Partial<ToastOptions> | number, theme?: ToastTheme, position?: ToastPosition) => ToastInstance;
11
+ warning: (msg: ToastText, optionsOrDuration?: Partial<ToastOptions> | number, theme?: ToastTheme, position?: ToastPosition) => ToastInstance;
12
+ loading: (msg: ToastText, optionsOrDuration?: Partial<ToastOptions> | number, theme?: ToastTheme, position?: ToastPosition) => ToastInstance;
13
+ show: (options: ToastOptions) => ToastInstance;
14
+ promise: <T>(promise: Promise<T>, options: ToastPromiseOptions<T>) => Promise<T>;
15
+ update: (id: string, options: Partial<ToastOptions>) => boolean;
16
+ dismiss: (id?: string) => boolean;
17
+ clear: () => void;
18
+ configure: (config: Partial<ToastConfig>) => void;
19
+ };
20
+ export default toast;
21
+ export { ToastManager } from "./core/ToastManager";
22
+ export type { ToastLevel as ToastLevelAdvanced, ToastPosition, ToastTheme, ToastAction, ToastProgress, ToastContent, ToastOptions as ToastOptionsAdvanced, ToastInstance, ToastConfig, ToastPlugin, ToastPromiseOptions, ToastState, ToastSubscriber, ToastText, SpringConfig, AnimationType, AnimationConfig, SpringAnimation, BounceAnimation, SlideAnimation, ZoomAnimation, FlipAnimation, FadeAnimation, ElasticAnimation, RotateAnimation, CustomAnimation, } from "./core/types";
23
+ export declare const toastAdvanced: {
24
+ show: (options: ToastOptions) => ToastInstance;
25
+ update: (id: string, options: Partial<ToastOptions>) => boolean;
26
+ dismiss: (id: string) => boolean;
27
+ clear: () => void;
28
+ info: (message: ToastText, options?: Partial<ToastOptions>) => ToastInstance;
29
+ success: (message: ToastText, options?: Partial<ToastOptions>) => ToastInstance;
30
+ error: (message: ToastText, options?: Partial<ToastOptions>) => ToastInstance;
31
+ warning: (message: ToastText, options?: Partial<ToastOptions>) => ToastInstance;
32
+ loading: (message: ToastText, options?: Partial<ToastOptions>) => ToastInstance;
33
+ promise: <T>(promise: Promise<T>, options: ToastPromiseOptions<T>) => Promise<T>;
34
+ group: (id: string, options: ToastOptions) => ToastInstance;
35
+ configure: (config: Partial<ToastConfig>) => void;
36
+ use: (plugin: ToastPlugin) => void;
37
+ getToasts: () => ToastInstance[];
38
+ getGroups: () => import("./core/types").ToastGroup[];
39
+ getConfig: () => ToastConfig;
40
+ getState: () => import("./core/types").ToastState;
41
+ subscribe: (listener: ToastSubscriber) => () => void;
42
+ onEditorEvent: (event: string, callback: (toast: ToastInstance, ...args: any[]) => void) => void;
43
+ triggerEditorEvent: (event: string, toast: ToastInstance, ...args: any[]) => void;
44
+ destroy: () => void;
45
+ };
46
+ export { toastAdvanced as toastPro };