npm - @t007/toast - Versions diffs - 0.0.23 → 0.0.25 - Mend

@t007/toast 0.0.23 → 0.0.25

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 (6) hide show

package/README.md CHANGED Viewed

@@ -53,7 +53,7 @@ Features built-in SVG icons, custom actions, and smooth hardware-accelerated ani
 - **9 Positioning Zones**: Anchor toasts anywhere on the screen (e.g., `top-right`, `bottom-center`, `center-center`).
 - **Dynamic Updating**: Update the text, icon, or type of an active toast without breaking its animation loop.
-- **Queue Management**: Strict enforcement of `maxToasts` and `renotify` to keep the UI clean.
+- **Queue Management**: Strict enforcement of `limit` and `renotify` to keep the UI clean.
 - **Custom Hardware Vibrations**: Unique vibration patterns for different alert types (`success`, `error`, `warning`).
 ---
@@ -120,7 +120,7 @@ toast.promise(myFetch, {
 ### CDN / Browser (Global)
-If you are not using a bundler, the library automatically injects itself into the global `t007` object and provides the convenient `window.Toast` fallback.
+If you are not using a bundler, the library automatically injects itself into the global `t007` object and provides the convenient `window.toast` fallback.
 ```html
 <!DOCTYPE html>
@@ -129,17 +129,12 @@ If you are not using a bundler, the library automatically injects itself into th
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@t007/toast@latest/dist/index.min.css">
 </head>
 <body>
   <button id="notifyBtn">Show Toast</button>
   <script src="https://cdn.jsdelivr.net/npm/@t007/toast@latest"></script>
   <script>
     document.getElementById('notifyBtn').addEventListener('click', () => {
-      Toast.info("System running smoothly.", {
-        pauseOnHover: true,
-        dragToClose: true
-      }); // or use `t007.toast -> t007.toast.info()`
+      toast.info("System running smoothly.", { pauseOnHover: true, dragToClose: true }); // or `t007.toast -> t007.toast.info()`
     });
   </script>
 </body>
@@ -152,20 +147,20 @@ If you are not using a bundler, the library automatically injects itself into th
 ### Basic Toasts
-Trigger toasts based on their severity. Returns the unique `id` of the generated toast.
+Trigger toasts based on their severity. Returns the unique `id` of the generated toast. If first argument is an id, don't put `id` in options; it will be taken as a fallback `render`.
   - `toast(render, options)` (Default / Info)
-  - `toast.info(render, options)`
-  - `toast.success(render, options)`
-  - `toast.warn(render, options)`
-  - `toast.error(render, options)`
+  - `toast.info(renderOrId, options)`
+  - `toast.success(renderOrId, options)`
+  - `toast.warn(renderOrId, options)`
+  - `toast.error(renderOrId, options)`
 ### Toast Updating
 You can dynamically update a toast that is currently on the screen.
 ```javascript
-const toastId = toast.loading("Processing...");
+const toastId = toast.loading("Processing..."); // id is auto-generated reliably
 // Later in your code...
 toast.update(toastId, {
@@ -176,6 +171,18 @@ toast.update(toastId, {
 });
 ```
+### `id` Upsert vs `tag` + `renotify`
+- `id` controls in-place replacement: if a toast with that same active id exists, the call updates it instead of creating a new one.
+- `toast.update(id, options)` is explicit update; helper calls (`success`, `info`, etc.) also upsert when `options.id` matches an active toast.
+- `tag` is a grouping key, not an update key.
+- `renotify: true` + same `tag` removes other active toasts with that tag before showing the new one.
+```javascript
+toast.success("Added to favorites", { id: `${tipId} favorite` }); // upsert by id, only if you can handle management
+toast.info("Sync started", { tag: "sync", renotify: true }); // one active toast per tag
+```
 ### Promise Handling
 Automatically maps a JavaScript Promise to the lifecycle of a toast.
@@ -221,10 +228,68 @@ window.t007.TOAST_DEFAULT_OPTIONS.vibrate = true;
 window.t007.TOAST_DURATIONS.error = 10000; // Leave errors up for 10 seconds
 ```
-### CSS Variables
+### CSS Selectors & Variables
 You can easily override the progress bar, animations, and container spacing by targeting `.t007-toast` in your stylesheet.
+#### Corporate Override Starter (Google-like)
+Use generic brand tokens first, then map them to toast variables. This keeps your theme portable across projects.
+```css
+/* 1) Brand/system tokens (generic names) */
+:root {
+  --app-surface: #ffffff;
+  --app-text: #202124;
+  --app-muted: #5f6368;
+  --app-muted-2: #9aa0a6;
+}
+/* 2) Map tokens to toast variables (theme layer) */
+.t007-toast {
+  --t007-toast-type-color: var(--app-text);
+  --t007-toast-background: var(--app-surface);
+  --t007-toast-text-shadow: none;
+  --t007-toast-text-stroke: 0;
+  --t007-toast-x-color: var(--app-muted-2);
+  /* ...check source code for all variables... */
+}
+/* 3) Container sizing/layout layer */
+.t007-toast-container {
+  --t007-toast-unit: 0.9rem;
+  --t007-toast-width: calc(var(--t007-toast-unit) * 25);
+  --t007-toast-min-height: 3.25rem;
+  --t007-toast-progress-height: calc(var(--t007-toast-unit) / 6);
+  --t007-toast-icon-width: calc(var(--t007-toast-unit) * 1.25);
+  --t007-toast-icon-height: calc(var(--t007-toast-unit) * 1.25);
+  --t007-toast-x-size: calc(var(--t007-toast-unit) * 1.5);
+}
+@media (max-width: 40rem) {
+  .t007-toast-container {
+    --t007-toast-unit: 0.95rem;
+    --t007-toast-container-margin: 16px;
+  }
+}
+```
+#### Specificity Note (Important)
+- Start with `:root` for shared tokens.
+- If a token does not apply, override directly on `.t007-toast` (visuals/colors).
+- For sizing/layout variables, override `.t007-toast-container` (unit, width, icon size, margins).
+- For strong app themes (e.g. `html[data-theme="dark"]`), use equal/stronger selectors on both `.t007-toast` and `.t007-toast-container`.
+- Check source code for more details.
+### Runtime Data Attributes
+The library writes useful data attributes to toast DOM nodes at runtime:
+- Toast root (`.t007-toast`): `data-group-id`, `data-animation`, `data-tag`, `data-drag-to-close`
+- Container (`.t007-toast-container`): `data-position`
+- Body text (`.t007-toast-body-text`): `data-render`
+- Icon (`.t007-toast-icon`): `data-icon`
+- Image (`.t007-toast-image`): `data-loaded`
+-
 -----
 ## Author

package/dist/index.css CHANGED Viewed

@@ -35,11 +35,12 @@
 }
 :where(:root, .t007-toast-container) {
   --t007-toast-unit: 1rem;
-  --t007-toast-container-margin-top: calc(var(--t007-toast-unit) / 2);
-  --t007-toast-container-margin-bottom: calc(var(--t007-toast-unit) / 2);
-  --t007-toast-container-margin-left: calc(var(--t007-toast-unit) / 2);
-  --t007-toast-container-margin-right: calc(var(--t007-toast-unit) / 2);
-  --t007-toast-container-gap: calc(var(--t007-toast-unit) / 2);
+  --t007-toast-container-margin: calc(var(--t007-toast-unit) / 2);
+  --t007-toast-container-margin-top: var(--t007-toast-container-margin);
+  --t007-toast-container-margin-bottom: var(--t007-toast-container-margin);
+  --t007-toast-container-margin-left: var(--t007-toast-container-margin);
+  --t007-toast-container-margin-right: var(--t007-toast-container-margin);
+  --t007-toast-container-gap: var(--t007-toast-container-margin);
   --t007-toast-min-width: unset;
   --t007-toast-width: calc(var(--t007-toast-unit) * 20);
   --t007-toast-max-width: 100%;
@@ -203,6 +204,10 @@
   outline: var(--t007-toast-focus-visible-outline);
   outline-offset: calc(var(--t007-toast-unit) / 7.5);
 }
+*:where(:has(> .t007-toast-container .t007-toast.t007-toast-scoped)) {
+  position: relative;
+  overflow: hidden;
+}
 .t007-toast-container {
   position: var(--t007-toast-container-position);
   margin-top: var(--t007-toast-container-margin-top);
@@ -330,21 +335,21 @@
 .t007-toast[data-animation=zoom].t007-toast-show {
   animation-name: t007-zoom-in;
 }
-.t007-toast:is(.info, .success, .error, .warning) {
+.t007-toast-container .t007-toast:is(.info, .success, .error, .warning) {
   --t007-toast-font-color: var(--t007-toast-type-color);
   --t007-toast-progress-background: var(--t007-toast-type-color);
   --t007-toast-progress-backdrop-background: rgb(from var(--t007-toast-type-color) r g b/0);
 }
-.t007-toast.info {
+.t007-toast-container .t007-toast.info {
   --t007-toast-type-color: var(--t007-toast-info-color);
 }
-.t007-toast.success {
+.t007-toast-container .t007-toast.success {
   --t007-toast-type-color: var(--t007-toast-success-color);
 }
-.t007-toast.error {
+.t007-toast-container .t007-toast.error {
   --t007-toast-type-color: var(--t007-toast-error-color);
 }
-.t007-toast.warning {
+.t007-toast-container .t007-toast.warning {
   --t007-toast-type-color: var(--t007-toast-warning-color);
 }
 .t007-toast.progress::before,

package/dist/index.d.ts CHANGED Viewed

@@ -3,50 +3,18 @@ import "@t007/utils";
 /** Toast severity level. */
 export type ToastType = "info" | "success" | "error" | "warning";
 /** Screen anchor for toast placement. */
-export type ToastPosition =
-  | "top-left"
-  | "top-center"
-  | "top-right"
-  | "bottom-left"
-  | "bottom-center"
-  | "bottom-right"
-  | "center-left"
-  | "center-center"
-  | "center-right";
+export type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "center-left" | "center-center" | "center-right";
 /** Motion preset used when a toast enters or leaves the screen. */
-export type ToastAnimation =
-  | "fade"
-  | "zoom"
-  | "slide"
-  | "slide-left"
-  | "slide-right"
-  | "slide-up"
-  | "slide-down"
-  | boolean;
+export type ToastAnimation = "fade" | "zoom" | "slide" | "slide-left" | "slide-right" | "slide-up" | "slide-down" | boolean;
 /** Allowed drag directions for dismiss gestures. */
-export type ToastDragDir =
-  | "x"
-  | "y"
-  | "xy"
-  | "x|y"
-  | "x||y"
-  | "x+"
-  | "x-"
-  | "y+"
-  | "y-"
-  | "xy+"
-  | "xy-"
-  | "x|y+"
-  | "x|y-"
-  | "x||y+"
-  | "x||y-";
+export type ToastDragDir = "x" | "y" | "xy" | "x|y" | "x||y" | "x+" | "x-" | "y+" | "y-" | "xy+" | "xy-" | "x|y+" | "x|y-" | "x||y+" | "x||y-";
 /** Configuration object for creating and updating a toast. */
 export interface ToastOptions {
-  /** Explicit toast id. */
+  /** Explicit toast id. Reusing an active id updates that toast in place (upsert-style), preserving position/animation state. */
   id?: string;
   /** Prefix used when ids are generated automatically. */
-  idPrefix?: string;
+  groupId?: string;
   /** Delay before the toast is initialized. */
   delay?: number | null;
   /** Container element used to host toast stacks. */
@@ -73,6 +41,8 @@ export interface ToastOptions {
   closeOnClick?: boolean;
   /** Hide the progress bar. */
   hideProgressBar?: boolean;
+  /** Manual progress value (0-1) used by the progress bar when set directly. */
+  nprogress?: number;
   /** Pause auto-close while the pointer is over the toast. */
   pauseOnHover?: boolean;
   /** Pause auto-close while the document is hidden. */
@@ -83,9 +53,9 @@ export interface ToastOptions {
   dragToClosePercent?: number | { x?: number; y?: number };
   /** Axis or direction filter used by the drag gesture system. */
   dragToCloseDir?: ToastDragDir;
-  /** Remove other toasts with the same tag before showing this one. */
+  /** When true and `tag` is provided, any other active toast with the same tag is removed before this toast renders. */
   renotify?: boolean;
-  /** Arbitrary tag used for grouping, filtering, and renotify matching. */
+  /** Arbitrary tag used for grouping and renotify matching. Does not update by itself; pair with `renotify` to enforce one-toast-per-tag behavior. */
   tag?: string | number;
   /** Trigger vibration when the toast appears. */
   vibrate?: boolean | number[];
@@ -94,7 +64,7 @@ export interface ToastOptions {
   /** Put new toasts at the front of the stack. */
   newestOnTop?: boolean;
   /** Maximum number of toasts allowed in a container. */
-  maxToasts?: number;
+  limit?: number;
   /** Action buttons rendered under the message body. */
   actions?: Record<string, (e: MouseEvent, toast: ToastInstance) => void> | false;
   /** Callback fired when the toast closes. */
@@ -106,18 +76,19 @@ export interface ToastOptions {
 /** Live toast instance returned by the runtime. */
 export interface ToastInstance {
-  /** Unique toast id. */
-  id: string;
   /** Current option bag applied to the instance. */
   opts: ToastOptions;
   /** Pending timeouts waiting to apply queued updates. */
   queue: number[];
-  /** Whether the toast has been removed from the DOM. */
-  destroyed: boolean;
-  /** Root DOM node for the toast. */
+  /** Whether the toast is active and in the DOM. */
+  inactive: boolean;
+  /** Root DOM node for the toast.
+   * Runtime datasets written here: `data-group-id`, `data-animation`, `data-tag`, `data-drag-to-close`.
+   * Related runtime datasets: container `data-position`, body text `data-render`, icon `data-icon`, image `data-loaded`.
+   */
   toastElement: HTMLElement;
-  /** Build the DOM node and attach it to the stack. */
-  init(): void;
+  /** Build the DOM node and setup its lifecycle. */
+  activate(): void;
   /** Apply new options and return the toast id.
    * @param options Options to apply.
    * @returns Toast id.
@@ -131,7 +102,7 @@ export interface ToastInstance {
    * @param manner Removal mode.
    * @param timeElapsed Whether the auto-close timer already elapsed.
    */
-  _remove(manner?: "smooth" | "instant", timeElapsed?: boolean): void;
+  remove(manner?: "smooth" | "instant", timeElapsed?: boolean): void;
 }
 /** Promise state configuration used by toast.promise. */
@@ -141,7 +112,6 @@ export interface ToastPromiseState<T = any> extends Omit<ToastOptions, "render"
   /** Render HTML for the promise state. */
   bodyHTML?: string | ((response: T) => string);
 }
 /** Configuration object accepted by toast.promise. */
 export interface ToastPromiseConfig<T = any> {
   /** Pending-state text or options. */
@@ -157,140 +127,102 @@ export interface Toast {
   /** Create a default toast.
    * @param render Body text for the toast.
    * @param options Toast configuration.
-   * @returns Toast id.
+   * @returns Toast `id`.
    */
   (render?: string, options?: ToastOptions): string;
-  /** Update an existing toast by id.
-   * @param id Toast id.
+  /** Check if a toast is currently active with the id or any toast if no `id` provided.
+   * @param id Toast `id`.
+   * @returns True if the toast is visibly active, i.e, not delayed; false otherwise.
+   */
+  isActive(id: string): boolean;
+  /** Update an existing toast by `id`.
+   * @param id Toast `id`.
    * @param options Options to apply.
    * @returns Updated toast id or false when no toast was found.
    */
   update(id: string, options: ToastOptions): string | false;
   /** Show an info toast.
-   * @param render Body text.
+   * @param renderOrId Body text or toast id.
    * @param options Toast configuration.
-   * @returns Toast id.
+   * @returns Toast `id`.
    */
-  info(render?: string, options?: ToastOptions): string;
+  info(renderOrId?: string, options?: ToastOptions): string;
   /** Show a success toast.
-   * @param render Body text.
+   * @param renderOrId Body text or toast id.
    * @param options Toast configuration.
-   * @returns Toast id.
+   * @returns Toast `id`.
    */
-  success(render?: string, options?: ToastOptions): string;
+  success(renderOrId?: string, options?: ToastOptions): string;
   /** Show a warning toast.
-   * @param render Body text.
+   * @param renderOrId Body text or toast id.
    * @param options Toast configuration.
-   * @returns Toast id.
+   * @returns Toast `id`.
    */
-  warn(render?: string, options?: ToastOptions): string;
+  warn(renderOrId?: string, options?: ToastOptions): string;
   /** Show an error toast.
-   * @param render Body text.
+   * @param renderOrId Body text or toast id.
    * @param options Toast configuration.
-   * @returns Toast id.
+   * @returns Toast `id`.
    */
-  error(render?: string, options?: ToastOptions): string;
+  error(renderOrId?: string, options?: ToastOptions): string;
   /** Show a loading toast.
-   * @param render Body text.
+   * @param renderOrId Body text or toast id.
    * @param options Toast configuration.
-   * @returns Toast id.
+   * @returns Toast `id`.
    */
-  loading(render?: string, options?: ToastOptions): string;
+  loading(renderOrId?: string, options?: ToastOptions): string;
   /** Bind a promise to the toast lifecycle.
    * @param promise Promise to observe.
    * @param options Pending, success, and error states.
    * @returns The original promise.
    */
-  promise<T>(promise: Promise<T>, options?: ToastPromiseConfig<T>): Promise<T>;
+  promise<T>(promise: Promise<T>, config?: ToastPromiseConfig<T>): Promise<T>;
   /** Dismiss a single toast or the whole stack.
-   * @param id Toast id to dismiss.
+   * @param id Toast `id` to dismiss.
    * @param manner Removal mode.
    * @param timeElapsed Whether the auto-close timer already elapsed.
    */
   dismiss(id?: string, manner?: "smooth" | "instant", timeElapsed?: boolean): void;
-  /** Dismiss every toast that matches an optional prefix.
-   * @param idPrefix Optional id prefix filter.
+  /** Dismiss every toast that matches an optional group id or the whole stack.
+   * @param groupId Optional group id filter.
    */
-  dismissAll(idPrefix?: string): void;
+  dismissAll(groupId?: string): void;
   /** Run an action against every matching toast instance.
    * @param action Instance method to invoke.
    * @param options Options forwarded to the instance method.
-   * @param idPrefix Optional id prefix filter.
+   * @param groupId Optional group id filter.
    */
-  doForAll(action: string, options?: any, idPrefix?: string): void;
+  doForAll(action: string, options?: any, groupId?: string): void;
   /** Return every matching toast instance.
-   * @param idPrefix Optional id prefix filter.
+   * @param groupId Optional group id filter.
    * @returns Matching toast instances.
    */
-  getAll(idPrefix?: string): ToastInstance[];
+  getAll(groupId?: string): ToastInstance[];
 }
 /** Helper methods used internally by toaster() and promise flows. */
 export interface Toasting {
-  /** Update an existing toast or recreate it if needed.
-   * @param base Toast factory to use.
-   * @param id Toast id.
-   * @param options Options to apply.
-   * @returns Updated id or false when no toast exists.
-   */
+  isActive(base: Toast, id: string): boolean;
   update(base: Toast, id: string, options: ToastOptions): boolean | string;
-  /** Attach a helper like info/success/warn/error to the base toast function.
-   * @param base Toast factory to extend.
-   * @param defaults Default option factory.
-   * @param action Helper name to create.
-   */
-  message(base: Toast, defaults: () => ToastOptions, action: string): void;
-  /** Create a loading toast from an id or a message.
-   * @param base Toast factory to use.
-   * @param renderOrId Toast id or loading text.
-   * @param options Loading options.
-   * @returns Toast id.
-   */
+  message(base: Toast, getDefaults: () => ToastOptions, action: string, renderOrId: string, options?: ToastOptions): string;
   loading(base: Toast, renderOrId: string, options?: ToastOptions): string;
-  /** Bind promise resolution states to an active toast.
-   * @param base Toast factory to use.
-   * @param promise Promise to observe.
-   * @param config Promise state configuration.
-   * @returns The original promise.
-   */
   promise<T>(base: Toast, promise: Promise<T>, config?: ToastPromiseConfig<T>): Promise<T>;
-  /** Dismiss a toast by id or clear all matching toasts.
-   * @param base Toast factory to use.
-   * @param id Toast id.
-   * @param manner Removal mode.
-   * @param timeElapsed Whether the auto-close timer already elapsed.
-   */
   dismiss(base: Toast, id?: string, manner?: string, timeElapsed?: boolean): void;
-  /** Dismiss all matching toasts.
-   * @param base Toast factory to use.
-   * @param idPrefix Optional id prefix filter.
-   */
-  dismissAll(base: Toast, idPrefix?: string): void;
-  /** Run a method on every matching toast instance.
-   * @param base Toast factory to use.
-   * @param action Instance method to invoke.
-   * @param options Options forwarded to the instance method.
-   * @param idPrefix Optional id prefix filter.
-   */
-  doForAll(base: Toast, action: string, options?: any, idPrefix?: string): void;
-  /** Return every matching toast instance.
-   * @param base Toast factory to use.
-   * @param idPrefix Optional id prefix filter.
-   * @returns Matching toast instances.
-   */
-  getAll(base: Toast, idPrefix?: string): ToastInstance[];
+  dismissAll(base: Toast, groupId?: string): void;
+  doForAll(base: Toast, action: string, options?: any, groupId?: string): void;
+  getAll(base: Toast, groupId?: string): ToastInstance[];
 }
 // BUNDLE EXPORTS & GLOBAL DECLARATIONS
 /** Internal helper methods used by the toast factory. */
 export const toasting: Toasting;
-/** Create a toast factory with custom defaults.
+/** Create a toast factory with custom defaults and a group id.
  * @param defOptions Default options merged into every toast.
- * @param idPrefix Prefix applied to generated ids.
+ * @param groupId Prefix applied to generated ids.
  * @returns Toast factory.
  */
-export function toaster(defOptions?: ToastOptions, idPrefix?: string): Toast;
+export function toaster(defOptions?: ToastOptions, groupId?: string): Toast;
 /** Default toast factory instance attached by the bundle. */
 declare const toast: Toast;
 export default toast;
@@ -315,6 +247,6 @@ declare global {
     TOAST_ICONS: Record<ToastType | "loading", string>;
   }
   interface Window {
-    Toast?: Toast;
+    toast?: Toast;
   }
 }