Data Flow & Events

Relevant source files

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

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

The @pcstyle/toast notification system utilizes a centralized state management pattern to handle notification lifecycles. Data flows from external API calls through a singleton store, which then triggers UI updates in a React-based provider via an observer pattern.

Sources: package.json:1-5, src/store.ts:47, src/provider.tsx:1-5

Centralized State Management

The core of the system is the ToastStore, a class that maintains an internal array of active notifications and manages a list of subscribers. It serves as the single source of truth for all toast data.

Store Architecture

The store encapsulates state and provides methods for mutation (add, remove, update). It employs a subscription model where React components can listen for state changes.

The diagram above illustrates the relationship between the central store and individual toast objects.
Sources: src/store.ts:18-50

Data Lifecycle & Flow

Data flow begins when a user invokes the toast utility. This utility interacts with the toastStore to create, modify, or destroy notification objects.

Lifecycle of a Notification

1. Creation: A call to toast() generates a unique ID and pushes a new object to the store.
2. Notification: The store executes all registered Observer functions with the updated toast list.
3. Persistence: If the toast is not a "loading" type, a timer is set to automatically call remove() after a specified duration (defaulting to 4000ms).
4. UI Sync: The ToastProvider component, having subscribed on mount, receives the updated list and updates its local state.

The sequence diagram details how a notification request propagates through the system from the initial call to the UI update.
Sources: src/store.ts:32-45, src/index.ts:10-15, src/provider.tsx:16-18

Asynchronous Operations (Promises)

The toast.promise method implements a complex flow where a single toast ID is maintained while its properties (message, type) are updated based on the resolution or rejection of a provided Promise.

State	Action	Type Transition
Initial	toast.loading()	loading
Resolve	toastStore.update()	success
Reject	toastStore.update()	error

Sources: src/index.ts:37-56

UI Integration & Events

The ToastProvider acts as the primary consumer of the store's data. It utilizes React hooks to bridge the non-React store with the React component tree.

Event Handling

• Subscription: The provider uses useEffect to subscribe to the store when the component mounts and cleans up the subscription on unmount.
• Manual Dismissal: Users can trigger the remove event by clicking a dismissal button, which calls toastStore.remove(id).
• Action Callbacks: If a toast contains an action object, the provider renders a button that executes the provided onClick callback.

This flowchart illustrates the interaction between UI components and the underlying store events.
Sources: src/provider.tsx:16-20, src/provider.tsx:55-75, src/store.ts:22-26

Configuration and Constraints

The system includes built-in constraints to manage performance and visual clutter.

Constraint	Value	File Reference
Max Visible Toasts	5	src/store.ts:35
Default Duration	4000ms	src/store.ts:39
Promise Error Duration	5000ms	src/index.ts:52
Target Environment	ES2020 / React 18+	tsconfig.json:3, package.json:20

Sources: src/store.ts:35-39, src/index.ts:52, package.json:20, tsconfig.json:3

The architecture of @pcstyle/toast ensures that data flow is unidirectional (Store -> Provider) while providing a flexible API for event-driven updates. The use of a standalone store class allows for notification management outside of the React lifecycle, while the observer pattern ensures the UI remains synchronized with the current state of active notifications.