Store Implementation

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 Store Implementation within the @pcstyle/toast library provides a centralized, framework-agnostic state management system for handling notifications. It utilizes an Observer pattern to decouple the logic of toast creation and lifecycle management from the React-based UI rendering components. Sources: src/store.ts, package.json:2

The system is designed to support multiple notification types (success, error, loading, etc.) and provides a strictly typed API for both synchronous and asynchronous (promise-based) operations. Sources: src/index.ts, cubic.yaml:23-24

Core Architecture

The architecture revolves around the ToastStore class, which maintains an internal array of active toasts and a list of subscribers. The store acts as a singleton instance exported for global use. Sources: src/store.ts:18-62

Data Structures

The state is defined by the Toast interface and the ToastType union.

Field	Type	Description
id	string	Unique identifier generated upon creation.
message	string | React.ReactNode	The content to display in the notification.
type	ToastType	Category: success, error, info, warning, loading, or default.
duration	number	Time in milliseconds before auto-dismissal (default 4000ms).
action	object	Optional action button with label and onClick callback.

Sources: src/store.ts:5-14, src/store.ts:43

State Management Flow

The following diagram illustrates how the store handles a new toast request and notifies the UI provider.

Store Operations

The ToastStore class implements several methods to manage the toast lifecycle. Sources: src/store.ts:22-60

Subscription Mechanism

The store uses a subscribe method that allows the ToastProvider to listen for state changes. It returns a cleanup function to prevent memory leaks.
Sources: src/store.ts:22-27, src/provider.tsx:18-20

Toast Lifecycle Methods

• add(toast): Generates a random alphanumeric ID, adds the toast to the beginning of the list, and enforces a maximum limit of 5 visible notifications. Sources: src/store.ts:34-38
• remove(id): Filters out the toast with the matching ID and triggers a notification to observers. Sources: src/store.ts:51-54
• update(id, updates): Performs a partial update on an existing toast's properties (e.g., changing a loading message to a success message). Sources: src/store.ts:56-59

API Integration

The toast utility functions wrap the toastStore to provide a developer-friendly interface. Sources: src/index.ts:11-37

Promise Handling

The implementation includes a specific handler for asynchronous operations via toast.promise.

Implementation Details

Build and Configuration

The project is configured as a TypeScript ESM module, ensuring strict type safety as mandated by the project's custom rules. Sources: package.json:6, cubic.yaml:23-24, tsconfig.json:11

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "declaration": true
  }
}

Sources: tsconfig.json:3-13

UI Synchronization

The ToastProvider uses the useEffect hook to synchronize its local React state with the toastStore singleton upon mounting. Sources: src/provider.tsx:17-21

  useEffect(() => {
    return toastStore.subscribe(setToasts);
  }, []);

Sources: src/provider.tsx:18-20

Summary

The Store Implementation provides a robust foundation for the PCSTYLE toast system. By using an internal observer-based store, the library ensures that notification logic remains separated from presentation, allowing for efficient updates, automatic dismissal timers, and complex asynchronous state transitions (promises) while maintaining a strict 5-toast visibility limit.