High-Level Architecture

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
• cubic.yaml

The @pcstyle/toast library is a React-based notification system designed with a focus on dual-theme support (cyberpunk and minimal) and strict type safety. It follows a decoupled architecture where the notification state management is separated from the UI rendering layer, allowing for programmatic control of toasts from any part of an application without requiring direct access to React context or hooks.

The system is built as a Modern ESM package, leveraging framer-motion for animations and TypeScript for comprehensive type definitions. It utilizes an observer pattern to synchronize a singleton state store with a UI provider component.

Sources: package.json:1-15, src/store.ts:1-5, cubic.yaml:10-15

Core Components

The architecture consists of three primary layers: the State Store, the API Interface, and the React Provider.

State Store (ToastStore)

The central hub of the system is a ToastStore class. It maintains an internal array of active toasts and a list of subscribers. It implements a basic Pub/Sub model where UI components can subscribe to state changes. The store enforces a maximum limit of 5 visible toasts at any given time to maintain UI cleanliness.

Sources: src/store.ts:19-35

API Interface (toast)

The library exports a toast function and several specialized methods (e.g., toast.success, toast.error). These serve as the public API for developers. Internally, these methods call toastStore.add(), which generates a unique ID, manages auto-dismissal timers (defaulting to 4000ms), and notifies observers.

Sources: src/index.ts:10-40, src/store.ts:37-50

React Provider (ToastProvider)

The ToastProvider is a client-side React component that listens to the ToastStore. It uses the useEffect hook to subscribe to the store on mount and updates its local state whenever the store changes. It handles the visual layout, positioning, and theme-specific styling.

Sources: src/provider.tsx:12-20

Data Flow and Interaction

The following diagram illustrates the flow of a notification from the initial API call to the final UI rendering.

Data Structures and Types

The system relies on a central Toast interface to ensure consistency across the store and the UI.

Field	Type	Description
id	string	Unique identifier generated by Math.random().toString(36).
message	string | React.ReactNode	The content of the notification.
type	ToastType	Categories: success, error, info, warning, loading, default.
duration	number	Time in ms before auto-removal (Optional).
action	object	Optional button with label and onClick callback.

Sources: src/store.ts:5-15, src/store.ts:38-39

Thematic Design and Positioning

The ToastProvider supports two primary visual styles and four screen positions. Styling is handled via Tailwind CSS classes and conditional logic based on the theme prop.

Advanced Logic: Promise Handling

The architecture includes a specialized toast.promise wrapper. This method manages the lifecycle of an asynchronous operation by transitioning a single toast through different states (loading -> success/error).

// src/index.ts:51-71
toast.promise = async <T,>(
  promise: Promise<T>,
  data: {
    loading: string;
    success: (data: T) => string;
    error: (err: any) => string;
  },
  options?: ToastOptions
) => {
  const id = toast.loading(data.loading, options);
  try {
    const result = await promise;
    toastStore.update(id, { message: data.success(result), type: "success", duration: 4000 });
    return result;
  } catch (err) {
    toastStore.update(id, { message: data.error(err), type: "error", duration: 5000 });
    throw err;
  }
};

Sources: src/index.ts:51-71

Summary

The @pcstyle/toast high-level architecture provides a robust, type-safe notification system by decoupling state from UI. By using a singleton store with an observer pattern, it ensures that notifications can be triggered from anywhere in the codebase while maintaining a centralized, animated display controlled by the ToastProvider. The inclusion of specialized themes and promise-handling logic makes it a versatile solution for modern React applications.