Toast Lifecycle

Relevant source files

The following files were used as context for generating this wiki page:

• src/store.ts
• src/provider.tsx
• src/index.ts
• package.json
• tsconfig.json

The Toast Lifecycle in the @pcstyle/toast library defines the complete progression of a notification from its initial trigger to its removal from the DOM. This lifecycle is managed through a centralized state management system that coordinates between user-facing API calls, an internal observable store, and a React-based provider component.

The system is designed with a "Sonner-inspired" architecture, utilizing framer-motion for visual transitions and supporting a dual-theme approach ("cyber" and "minimal"). The lifecycle ensures that notifications are displayed, auto-dismissed after a specific duration, or manually closed via user interaction.

Sources: package.json:3-5, src/provider.tsx:4, src/store.ts:25-54

1. Initialization and Subscription

The lifecycle begins with the registration of the ToastProvider. This component acts as the visual host for all toasts and establishes a connection with the ToastStore.

The Store-Provider Connection

Upon mounting, the ToastProvider subscribes to the toastStore. This subscription uses an observer pattern where the provider's local state is updated whenever the store's data changes.

2. Creation Phase (Triggering)

Toasts are created through the toast utility functions. These functions act as wrappers around the toastStore.add method.

Toast Types and Options

The system supports several specific toast types, each influencing the visual style and lifecycle behavior (e.g., loading toasts do not auto-dismiss).

Type	Function	Auto-dismiss	Default Duration
default	toast()	Yes	4000ms
success	toast.success()	Yes	4000ms
error	toast.error()	Yes	4000ms
info	toast.info()	Yes	4000ms
warning	toast.warning()	Yes	4000ms
loading	toast.loading()	No	N/A

Sources: src/index.ts:11-35, src/store.ts:39-50

Generation Logic

When a toast is added, the store performs the following steps:

1. ID Generation: Creates a unique alphanumeric ID (e.g., Math.random().toString(36)).
2. Stack Limitation: Adds the new toast to the top of the array but limits the total visible toasts to 5.
3. Notification: Calls all registered observers to trigger a re-render in the UI.

Sources: src/store.ts:40-43

3. Active State and Updates

Once a toast is active, its state can be modified. This is most prominent in the toast.promise workflow, where a single toast transitions through multiple statuses.

Promise Lifecycle

The toast.promise helper manages a toast's lifecycle based on the resolution of an asynchronous operation.

Data Structure

A toast object during its active lifecycle consists of the following properties:

• id: Unique identifier (string).
• message: Content (string or React node).
• type: The ToastType category.
• duration: Optional override for auto-dismissal.
• action: Optional object containing a label and onClick callback.

Sources: src/store.ts:7-17

4. Dismissal and Removal

The final phase of the lifecycle is the removal of the toast from the state and the DOM. Removal can occur through three different triggers.

Dismissal Triggers

1. Auto-dismiss: For non-loading toasts, a setTimeout is triggered upon creation.
2. Manual Close: User clicks the [X] button in the UI, invoking toastStore.remove(id).
3. Programmatic Dismiss: Calling toast.dismiss(id) directly.

Visual Exit

When a toast is removed from the store array, the ToastProvider uses AnimatePresence and motion.div to handle the exit animation, scaling the element down to 0.95 and fading its opacity.

Summary

The Toast Lifecycle is a tightly coupled flow between the ToastStore (logic/state) and ToastProvider (presentation). By centralizing state, the system ensures consistent behavior across different notification types while allowing for complex interactions like promise tracking and manual overrides. The use of an observer pattern allows any part of the application to trigger notifications without needing direct access to the UI components.