@lapp-studio/react-toast-engine 0.0.1 → 0.0.3

package/README.md

@@ -1,33 +1,40 @@
 # React Toast Engine 🍞
 
+[![npm version](https://img.shields.io/npm/v/@lapp-studio/react-toast-engine.svg?style=flat-square)](https://www.npmjs.com/package/@lapp-studio/react-toast-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
 **React Toast Engine** is a high-performance, headless toast management library for **React** and **React Native**.
 
-It separates state logic (powered by Zustand) from the UI layer, allowing you to share the same notification logic across Web and Mobile while maintaining 60FPS native animations using **Reanimated**.
+It separates state logic (powered by [Zustand](https://github.com/pmndrs/zustand)) from the UI layer, allowing you to share the exact same notification logic across Web and Mobile. For React Native, it maintains flawless 60FPS animations natively using **Reanimated** and **Gesture Handler**, without locking the JS thread.
 
 ## ✨ Key Features
 
-- 🚀 **Zero-Lag State:** Atomic updates via Zustand to prevent unnecessary re-renders.
-- 📱 **Native First:** Deep integration with `react-native-reanimated` and `gesture-handler`.
-- 🌐 **Truly Hybrid:** Multiple entry points to ensure Web builds don't bundle Native code.
-- 🏗️ **Headless & Flexible:** You provide the components; we handle the stack, queue, and lifecycle.
+- 🚀 **Zero-Lag State:** Atomic updates via Zustand to prevent unnecessary re-renders across your app.
+- 📱 **Native First:** Deep, out-of-the-box integration with `react-native-reanimated`, `react-native-gesture-handler`, and `react-native-worklets`.
+- 🌐 **Truly Hybrid (Tree-Shakeable):** Separate entry points for Core (`/`) and Native (`/native`) ensure your Web builds never bundle heavy React Native libraries.
+- 🏗️ **100% Headless & Flexible:** You build the UI components; the engine handles the stacking, queuing, lifecycle, and gesture logic.
+- 🛡️ **Smart Provider Stacking:** If multiple providers exist in the DOM/Tree, the engine intelligently routes toasts only to the topmost (active) provider to prevent duplicates.
 
 ---
 
 ## 📦 Installation
 
+Install the core library:
+
 ```bash
 # npm
 npm i @lapp-studio/react-toast-engine
+
 # yarn
 yarn add @lapp-studio/react-toast-engine
 ```
 
-### Peer Dependencies
+### React Native Peer Dependencies
 
-For **React Native** environments, ensure the following are installed:
+If you are using React Native, ensure you have the required animation and gesture libraries installed in your project:
 
 ```bash
-yarn add react-native-reanimated react-native-gesture-handler react-native-safe-area-context
+yarn add react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-worklets
 ```
 
 ---
@@ -36,29 +43,39 @@ yarn add react-native-reanimated react-native-gesture-handler react-native-safe-
 
 ### 1. Initialize the Client
 
-Define your UI components and initialize the engine.
+Create a shared file (e.g., `src/lib/toasts.ts`) to configure your UI components and initialize the engine.
 
 ```typescript
 // src/lib/toasts.ts
-import { createToastsClient } from "@lapp-studio/react-toast-engine";
-import PoolRenderer from "@lapp-studio/react-toast-engine/native"; // For React Native
+import { createToastsClient } from "@lapp-studio/react-toast-engine/core";
+
+// Import the native renderer only in your React Native app
+import { PoolRenderer } from "@lapp-studio/react-toast-engine/native";
 
+import {
+  MySuccessComponent,
+  MyErrorComponent,
+  MyInfoComponent,
+} from "./components";
+
+// Map your custom components to the engine's InfoTypes
 const components = {
   success: MySuccessComponent,
   error: MyErrorComponent,
   info: MyInfoComponent,
 };
 
+// Create and export the client tools
 export const { store, utilities, renderer } = createToastsClient({
   components,
   PoolRenderer,
-  storeSettings: { poolLimit: 5 },
+  storeSettings: { poolLimit: 5 }, // Keep a maximum of 5 toasts in the DOM at once
 });
 ```
 
 ### 2. Setup the Provider
 
-Wrap your application root with the generated `Provider`.
+Wrap your application's root component with the generated `Provider`.
 
 ```tsx
 import { renderer } from "./lib/toasts";
@@ -74,45 +91,63 @@ export function App() {
 
 ### 3. Trigger Toasts
 
-Use hooks inside components or helpers for business logic (e.g., API interceptors).
+You can stack toasts from anywhere in your app—either via React hooks inside your components or via helper functions in standard TypeScript files.
+
+**Inside a React Component (Using Hooks):**
 
 ```tsx
+import { Button } from "react-native";
 import { utilities } from "./lib/toasts";
 
-// Inside a React Component
-const stack = utilities.hooks.useStackToast();
+export const SaveButton = () => {
+  const stack = utilities.hooks.useStackToast();
 
-// Outside React (e.g., inside an Axios Interceptor)
-utilities.helpers.stack({
-  title: "Success!",
-  description: "Changes saved successfully.",
-  infoType: "success",
-  durationInMs: 3000,
-});
-```
+  const handlePress = () => {
+    stack({
+      title: "Success!",
+      description: "Profile updated.",
+      infoType: "success",
+      durationInMs: 3000,
+    });
+  };
 
----
-
-## 🛠️ Architecture
+  return <Button title="Save" onPress={handlePress} />;
+};
+```
 
-The library follows a **Decoupled Provider-Consumer** pattern:
+**Outside React (Using Helpers - Great for API Interceptors):**
 
-1.  **Store (Zustand):** Manages the global toast pool and provider stack.
-2.  **Utilities:** Provides a clean API via `hooks` for UI and `helpers` for logic.
-3.  **Renderer:** Handles priority. If multiple providers are present, only the topmost (latest) one renders the active toasts to prevent duplicates.
+```typescript
+import { utilities } from "./lib/toasts";
+import api from "./api";
+
+api.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    utilities.helpers.stack({
+      title: "Connection Error",
+      description: error.message,
+      infoType: "error",
+      durationInMs: 5000,
+    });
+    return Promise.reject(error);
+  },
+);
+```
 
 ---
 
-## 📱 React Native Specifics
+## 📱 React Native Architecture
 
-The native build uses **Shared Values** and **Worklets** for maximum performance:
+The native implementation uses **Shared Values** and **Worklets** to achieve native-level performance:
 
-- **Swipe to Dismiss:** Fully interactive gestures to clear notifications.
-- **Safe Area Aware:** Automatically calculates offsets using `react-native-safe-area-context`.
-- **Z-Index Management:** Smart stacking logic that works across different navigation screens.
+- **Swipe to Dismiss:** Fully interactive, physics-based gestures to clear notifications. Swipe velocities are calculated in real-time.
+- **UI Thread Operations:** Dismissing a toast uses `scheduleOnRN` to bypass the JS thread entirely, avoiding stutters during heavy computations.
+- **Safe Area Aware:** Automatically shifts offsets using `react-native-safe-area-context` to prevent overlapping with notches or dynamic islands.
+- **Dynamic Z-Index:** Smart stacking logic that recalculates layer priorities smoothly as new toasts arrive or leave.
 
 ---
 
 ## 📄 License
 
-MIT © LApp
+MIT © L'App Studio

package/dist/core.d.cts

@@ -1,7 +1,7 @@
-import { a as ToastsStoreSettings, c as ToastAction, i as ToastsStore, l as ToastActions, n as ToastsPoolRendererProps, o as NewToast, r as ToastsProviderProps, s as Toast, t as ToastsComponentsByInfoType, u as ToastInfoType } from "./toasts-renderer-DsSfXdUq.cjs";
+import { a as ToastsStore, c as NewToast, d as ToastActions, f as ToastInfoType, i as ToastsRendererContextProps, l as Toast, n as ToastsPoolRendererProps, o as ToastsStoreSettings, r as ToastsProviderProps, s as ToastComponentProps, t as ToastsComponentsByInfoType, u as ToastAction } from "./toasts-renderer-CoN_jkgy.cjs";
 import * as zustand from "zustand";
-import { ElementType } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { ElementType } from "react";
 
 //#region src/core/createToastsClient.d.ts
 type Parameters = {
@@ -34,5 +34,5 @@ declare const createToastsClient: ({
   };
 };
 //#endregion
-export { NewToast, Toast, ToastAction, ToastActions, ToastInfoType, ToastsStore, ToastsStoreSettings, createToastsClient };
+export { NewToast, Toast, ToastAction, ToastActions, ToastComponentProps, ToastInfoType, ToastsComponentsByInfoType, ToastsPoolRendererProps, ToastsProviderProps, ToastsRendererContextProps, ToastsStore, ToastsStoreSettings, createToastsClient };
 //# sourceMappingURL=core.d.cts.map

package/dist/core.d.ts

@@ -1,4 +1,4 @@
-import { a as ToastsStoreSettings, c as ToastAction, i as ToastsStore, l as ToastActions, n as ToastsPoolRendererProps, o as NewToast, r as ToastsProviderProps, s as Toast, t as ToastsComponentsByInfoType, u as ToastInfoType } from "./toasts-renderer-vMIJr1FV.js";
+import { a as ToastsStore, c as NewToast, d as ToastActions, f as ToastInfoType, i as ToastsRendererContextProps, l as Toast, n as ToastsPoolRendererProps, o as ToastsStoreSettings, r as ToastsProviderProps, s as ToastComponentProps, t as ToastsComponentsByInfoType, u as ToastAction } from "./toasts-renderer-Ad20ipzA.js";
 import { ElementType } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 import * as zustand from "zustand";
@@ -34,5 +34,5 @@ declare const createToastsClient: ({
   };
 };
 //#endregion
-export { NewToast, Toast, ToastAction, ToastActions, ToastInfoType, ToastsStore, ToastsStoreSettings, createToastsClient };
+export { NewToast, Toast, ToastAction, ToastActions, ToastComponentProps, ToastInfoType, ToastsComponentsByInfoType, ToastsPoolRendererProps, ToastsProviderProps, ToastsRendererContextProps, ToastsStore, ToastsStoreSettings, createToastsClient };
 //# sourceMappingURL=core.d.ts.map

package/dist/native.d.cts

@@ -1,4 +1,4 @@
-import { n as ToastsPoolRendererProps } from "./toasts-renderer-DsSfXdUq.cjs";
+import { n as ToastsPoolRendererProps } from "./toasts-renderer-CoN_jkgy.cjs";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/native/pool-renderer.d.ts

package/dist/native.d.ts

@@ -1,4 +1,4 @@
-import { n as ToastsPoolRendererProps } from "./toasts-renderer-vMIJr1FV.js";
+import { n as ToastsPoolRendererProps } from "./toasts-renderer-Ad20ipzA.js";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/native/pool-renderer.d.ts

package/dist/{toasts-renderer-DsSfXdUq.d.cts → toasts-renderer-Ad20ipzA.d.ts}

@@ -1,4 +1,5 @@
 import { ElementType } from "react";
+import { StoreApi, UseBoundStore } from "zustand";
 
 //#region src/core/types/toast.d.ts
 declare enum ToastInfoType {
@@ -42,6 +43,11 @@ type ToastsStoreSettings = {
 //#endregion
 //#region src/core/types/toasts-renderer.d.ts
 type ToastsComponentsByInfoType = Record<ToastInfoType, ElementType<ToastComponentProps>>;
+type ToastsRendererContextProps = {
+  children: React.ReactNode;
+  components: ToastsComponentsByInfoType;
+  store: UseBoundStore<StoreApi<ToastsStore>>;
+};
 type ToastsPoolRendererProps = {
   children: React.ReactNode;
 };
@@ -49,5 +55,5 @@ type ToastsProviderProps = {
   children: React.ReactNode;
 };
 //#endregion
-export { ToastsStoreSettings as a, ToastAction as c, ToastsStore as i, ToastActions as l, ToastsPoolRendererProps as n, NewToast as o, ToastsProviderProps as r, Toast as s, ToastsComponentsByInfoType as t, ToastInfoType as u };
-//# sourceMappingURL=toasts-renderer-DsSfXdUq.d.cts.map
+export { ToastsStore as a, NewToast as c, ToastActions as d, ToastInfoType as f, ToastsRendererContextProps as i, Toast as l, ToastsPoolRendererProps as n, ToastsStoreSettings as o, ToastsProviderProps as r, ToastComponentProps as s, ToastsComponentsByInfoType as t, ToastAction as u };
+//# sourceMappingURL=toasts-renderer-Ad20ipzA.d.ts.map

package/dist/{toasts-renderer-DsSfXdUq.d.cts.map → toasts-renderer-Ad20ipzA.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"toasts-renderer-DsSfXdUq.d.cts","names":[],"sources":["../src/core/types/toast.ts","../src/core/types/toast-component.ts","../src/core/types/toasts-store.ts","../src/core/types/toasts-renderer.ts"],"mappings":";;;aAAY,aAAA;EACV,IAAA;EACA,KAAA;EACA,OAAA;AAAA;AAAA,KAGU,KAAA;EACV,EAAA;EACA,KAAA;EACA,WAAA;EACA,YAAA;EACA,QAAA,KAAa,aAAA;AAAA;AAAA,KAGH,QAAA,GAAW,IAAA,CAAK,KAAA;AAAA,KAEhB,WAAA,IAAe,KAAA,EAAO,KAAA;AAAA,KAEtB,YAAA;EACV,SAAA,GAAY,WAAA;EACZ,OAAA,GAAU,WAAA;AAAA;;;KClBA,mBAAA;EACV,KAAA,EAAO,KAAA;EACP,OAAA,EAAS,YAAA;AAAA;;;KCFC,WAAA;EACV,IAAA,EAAM,KAAA;EACN,SAAA;EAEA,KAAA,GAAQ,KAAA,EAAO,QAAA;EACf,MAAA,GAAS,KAAA,EAAO,KAAA;EAChB,GAAA;EAEA,WAAA,GAAc,UAAA;EACd,cAAA,GAAiB,UAAA;AAAA;AAAA,KAGP,mBAAA;EACV,SAAA;AAAA;;;KCRU,0BAAA,GAA6B,MAAA,CACvC,aAAA,EACA,WAAA,CAAY,mBAAA;AAAA,KASF,uBAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA;AAAA,KAGN,mBAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA"}
+{"version":3,"file":"toasts-renderer-Ad20ipzA.d.ts","names":[],"sources":["../src/core/types/toast.ts","../src/core/types/toast-component.ts","../src/core/types/toasts-store.ts","../src/core/types/toasts-renderer.ts"],"mappings":";;;;aAAY,aAAA;EACV,IAAA;EACA,KAAA;EACA,OAAA;AAAA;AAAA,KAGU,KAAA;EACV,EAAA;EACA,KAAA;EACA,WAAA;EACA,YAAA;EACA,QAAA,KAAa,aAAA;AAAA;AAAA,KAGH,QAAA,GAAW,IAAA,CAAK,KAAA;AAAA,KAEhB,WAAA,IAAe,KAAA,EAAO,KAAA;AAAA,KAEtB,YAAA;EACV,SAAA,GAAY,WAAA;EACZ,OAAA,GAAU,WAAA;AAAA;;;KClBA,mBAAA;EACV,KAAA,EAAO,KAAA;EACP,OAAA,EAAS,YAAA;AAAA;;;KCFC,WAAA;EACV,IAAA,EAAM,KAAA;EACN,SAAA;EAEA,KAAA,GAAQ,KAAA,EAAO,QAAA;EACf,MAAA,GAAS,KAAA,EAAO,KAAA;EAChB,GAAA;EAEA,WAAA,GAAc,UAAA;EACd,cAAA,GAAiB,UAAA;AAAA;AAAA,KAGP,mBAAA;EACV,SAAA;AAAA;;;KCRU,0BAAA,GAA6B,MAAA,CACvC,aAAA,EACA,WAAA,CAAY,mBAAA;AAAA,KAGF,0BAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;EAChB,UAAA,EAAY,0BAAA;EACZ,KAAA,EAAO,aAAA,CAAc,QAAA,CAAS,WAAA;AAAA;AAAA,KAGpB,uBAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA;AAAA,KAGN,mBAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA"}

package/dist/{toasts-renderer-vMIJr1FV.d.ts → toasts-renderer-CoN_jkgy.d.cts}

@@ -1,4 +1,6 @@
+import { StoreApi, UseBoundStore } from "zustand";
 import { ElementType } from "react";
+
 //#region src/core/types/toast.d.ts
 declare enum ToastInfoType {
   info = "info",
@@ -41,6 +43,11 @@ type ToastsStoreSettings = {
 //#endregion
 //#region src/core/types/toasts-renderer.d.ts
 type ToastsComponentsByInfoType = Record<ToastInfoType, ElementType<ToastComponentProps>>;
+type ToastsRendererContextProps = {
+  children: React.ReactNode;
+  components: ToastsComponentsByInfoType;
+  store: UseBoundStore<StoreApi<ToastsStore>>;
+};
 type ToastsPoolRendererProps = {
   children: React.ReactNode;
 };
@@ -48,5 +55,5 @@ type ToastsProviderProps = {
   children: React.ReactNode;
 };
 //#endregion
-export { ToastsStoreSettings as a, ToastAction as c, ToastsStore as i, ToastActions as l, ToastsPoolRendererProps as n, NewToast as o, ToastsProviderProps as r, Toast as s, ToastsComponentsByInfoType as t, ToastInfoType as u };
-//# sourceMappingURL=toasts-renderer-vMIJr1FV.d.ts.map
+export { ToastsStore as a, NewToast as c, ToastActions as d, ToastInfoType as f, ToastsRendererContextProps as i, Toast as l, ToastsPoolRendererProps as n, ToastsStoreSettings as o, ToastsProviderProps as r, ToastComponentProps as s, ToastsComponentsByInfoType as t, ToastAction as u };
+//# sourceMappingURL=toasts-renderer-CoN_jkgy.d.cts.map

package/dist/toasts-renderer-CoN_jkgy.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toasts-renderer-CoN_jkgy.d.cts","names":[],"sources":["../src/core/types/toast.ts","../src/core/types/toast-component.ts","../src/core/types/toasts-store.ts","../src/core/types/toasts-renderer.ts"],"mappings":";;;;aAAY,aAAA;EACV,IAAA;EACA,KAAA;EACA,OAAA;AAAA;AAAA,KAGU,KAAA;EACV,EAAA;EACA,KAAA;EACA,WAAA;EACA,YAAA;EACA,QAAA,KAAa,aAAA;AAAA;AAAA,KAGH,QAAA,GAAW,IAAA,CAAK,KAAA;AAAA,KAEhB,WAAA,IAAe,KAAA,EAAO,KAAA;AAAA,KAEtB,YAAA;EACV,SAAA,GAAY,WAAA;EACZ,OAAA,GAAU,WAAA;AAAA;;;KClBA,mBAAA;EACV,KAAA,EAAO,KAAA;EACP,OAAA,EAAS,YAAA;AAAA;;;KCFC,WAAA;EACV,IAAA,EAAM,KAAA;EACN,SAAA;EAEA,KAAA,GAAQ,KAAA,EAAO,QAAA;EACf,MAAA,GAAS,KAAA,EAAO,KAAA;EAChB,GAAA;EAEA,WAAA,GAAc,UAAA;EACd,cAAA,GAAiB,UAAA;AAAA;AAAA,KAGP,mBAAA;EACV,SAAA;AAAA;;;KCRU,0BAAA,GAA6B,MAAA,CACvC,aAAA,EACA,WAAA,CAAY,mBAAA;AAAA,KAGF,0BAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;EAChB,UAAA,EAAY,0BAAA;EACZ,KAAA,EAAO,aAAA,CAAc,QAAA,CAAS,WAAA;AAAA;AAAA,KAGpB,uBAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA;AAAA,KAGN,mBAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lapp-studio/react-toast-engine",
-  "version": "0.00.1",
+  "version": "0.0.3",
   "private": false,
   "type": "module",
   "main": "dist/core.js",
@@ -58,5 +58,19 @@
   "maintainers": [
     "giovanninp"
   ],
+  "keywords": [
+    "react",
+    "react-native",
+    "toast",
+    "notification",
+    "snackbar",
+    "alert",
+    "headless",
+    "zustand",
+    "reanimated",
+    "gesture-handler",
+    "ui",
+    "hybrid"
+  ],
   "license": "MIT"
 }

package/dist/toasts-renderer-vMIJr1FV.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"toasts-renderer-vMIJr1FV.d.ts","names":[],"sources":["../src/core/types/toast.ts","../src/core/types/toast-component.ts","../src/core/types/toasts-store.ts","../src/core/types/toasts-renderer.ts"],"mappings":";;aAAY,aAAA;EACV,IAAA;EACA,KAAA;EACA,OAAA;AAAA;AAAA,KAGU,KAAA;EACV,EAAA;EACA,KAAA;EACA,WAAA;EACA,YAAA;EACA,QAAA,KAAa,aAAA;AAAA;AAAA,KAGH,QAAA,GAAW,IAAA,CAAK,KAAA;AAAA,KAEhB,WAAA,IAAe,KAAA,EAAO,KAAA;AAAA,KAEtB,YAAA;EACV,SAAA,GAAY,WAAA;EACZ,OAAA,GAAU,WAAA;AAAA;;;KClBA,mBAAA;EACV,KAAA,EAAO,KAAA;EACP,OAAA,EAAS,YAAA;AAAA;;;KCFC,WAAA;EACV,IAAA,EAAM,KAAA;EACN,SAAA;EAEA,KAAA,GAAQ,KAAA,EAAO,QAAA;EACf,MAAA,GAAS,KAAA,EAAO,KAAA;EAChB,GAAA;EAEA,WAAA,GAAc,UAAA;EACd,cAAA,GAAiB,UAAA;AAAA;AAAA,KAGP,mBAAA;EACV,SAAA;AAAA;;;KCRU,0BAAA,GAA6B,MAAA,CACvC,aAAA,EACA,WAAA,CAAY,mBAAA;AAAA,KASF,uBAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA;AAAA,KAGN,mBAAA;EACV,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA"}