Trigger API Methods
Relevant source files
The following files were used as context for generating this wiki page:
The Trigger API Methods represent the primary interface for developers to interact with the @pcstyle/toast notification system. These methods allow for the creation, management, and dismissal of toast notifications through a centralized singleton store. The API is designed to be highly typed and flexible, supporting various notification states including success, error, info, warning, and asynchronous loading states.
Architecturally, the trigger methods act as a functional wrapper around the ToastStore. When a trigger method is called, it generates a unique identifier, pushes the notification data into the store, and triggers a state update that is consumed by the ToastProvider component.
Core Trigger API
The main toast function and its properties provide the primary means of creating notifications. Each method accepts a message (string or React node) and an optional ToastOptions object.
Standard Notification Methods
The API provides specialized methods for different semantic types of notifications. All methods return a unique id string which can be used for manual dismissal or updates.
| Method | Type | Description |
|---|---|---|
toast(message, options) | default | Creates a generic notification. |
toast.success(message, options) | success | Creates a success notification. |
toast.error(message, options) | error | Creates an error notification. |
toast.info(message, options) | info | Creates an informational notification. |
toast.warning(message, options) | warning | Creates a warning notification. |
toast.loading(message, options) | loading | Creates a persistent loading notification. |
Sources: src/index.ts:11-35, src/store.ts:7-16
Configuration Options
The ToastOptions interface allows for customization of individual notifications.
| Property | Type | Description |
|---|---|---|
duration | number | Time in milliseconds before auto-dismissal (default: 4000ms). |
action | object | Optional action button with a label and onClick handler. |
Sources: src/index.ts:3-10, src/store.ts:40
Asynchronous Promise Handling
The toast.promise method provides a streamlined way to handle asynchronous operations. It automatically manages a loading state and transitions to either a success or error state based on the resolution of the provided Promise.
The diagram above illustrates the lifecycle of a promise-based toast notification from initial trigger to final resolution.
Sources: src/index.ts:41-59
Store Interaction and State Management
The Trigger API methods are thin wrappers that communicate with the ToastStore. The store maintains an internal array of active toasts, limited to a maximum of 5 visible items.
Data Flow Architecture
This flowchart describes how a notification flows from the initial API call through the store's logic and into the UI.
Sources: src/store.ts:28-44, src/provider.tsx:14-17
Manual Dismissal
Notifications can be manually removed using the toast.dismiss method, which takes the id returned by the creation methods. Internally, this calls the ToastStore.remove method, filtering the toast out of the active list and notifying observers.
Sources: src/index.ts:37-39, src/store.ts:49-52
Technical Specifications
The system is built with strict TypeScript configurations to ensure type safety across the public API.
| Feature | Specification |
|---|---|
| Language | TypeScript (ES2020) |
| Module System | ESM (ESNext) |
| React Support | >= 18 |
| Animation | Framer Motion (>= 10) |
| Maximum Toasts | 5 visible notifications |
| Default Duration | 4000ms (unless type is 'loading') |
Sources: package.json:2-30, tsconfig.json:3-15, src/store.ts:34-40, cubic.yaml:14-23
Dependency Context
The project utilizes framer-motion for exit and entry transitions, while the store implementation uses a custom observer pattern to bridge the vanilla TypeScript logic with the React-based ToastProvider.
Sources: package.json:22-26, src/provider.tsx:4-7, src/store.ts:19-26
Conclusion
The Trigger API Methods provide a robust, type-safe interface for managing application notifications. By abstracting the complex state management of the ToastStore into simple functional calls like toast.success and toast.promise, the library enables developers to implement sophisticated notification behaviors with minimal boilerplate.