Introduction

Relevant source files

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

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

The @pcstyle/toast library is a React-based notification system designed for the PCSTYLE ecosystem, heavily inspired by Sonner. It provides a lightweight, highly performant mechanism for displaying ephemeral messages to users, supporting advanced features like asynchronous promise tracking, manual dismissals, and action buttons. The system is built with a strict emphasis on type safety and ESM standards.
Sources: package.json:1-5, cubic.yaml:12-23

The system distinguishes itself through a dual-theme architecture, offering both a high-fidelity "cyberpunk" aesthetic (characterized by neon glows and monospaced typography) and a "minimal" aesthetic for cleaner interfaces. It utilizes framer-motion for fluid animations and a singleton store pattern for state management outside of the React component tree.
Sources: src/provider.tsx:9-12, src/store.ts:58, package.json:20-24

System Architecture

The notification system is divided into three primary layers: the State Store, the UI Provider, and the Functional API.

State Management (ToastStore)

The core logic resides in a ToastStore class that implements an Observer pattern. This store maintains a private array of active toasts and a list of observers that are notified whenever the state changes. It handles the generation of unique IDs, automatic dismissal via timers, and state updates for complex toast interactions like loading states.

UI Components (ToastProvider)

The ToastProvider is a "client-side only" React component that subscribes to the ToastStore. It is responsible for rendering the toast container at fixed positions on the screen (e.g., bottom-right, top-center) and applying the selected theme styles.

Prop	Type	Default	Description
theme	"cyber" | "minimal"	"cyber"	Determines the visual style and animations.
position	"top-right" | "top-center" | "bottom-right" | "bottom-center"	"bottom-right"	The screen quadrant where toasts appear.
Sources: src/provider.tsx:9-16

Functional API

The library exports a toast object that serves as the primary entry point for developers. It supports various notification types and utility methods.

Basic Notification Types

The API provides shorthand methods for common notification states, each automatically assigning a ToastType that influences the UI styling.

• toast(message, options): Default notification.
• toast.success(message, options): Success state.
• toast.error(message, options): Error state.
• toast.info(message, options): Informational state.
• toast.warning(message, options): Warning state.
• toast.loading(message, options): Persistent loading state that does not auto-dismiss.
  Sources: src/index.ts:11-37, src/store.ts:45-47

Promise Handling

The toast.promise method allows for seamless synchronization between asynchronous operations and the notification UI. It manages the transition from a "loading" state to either a "success" or "error" state based on the promise resolution.

Data Models

The internal data structures ensure that every toast can support rich interactions, such as custom labels and callback actions.

Toast Interface

export interface Toast {
  id: string;
  message: string | React.ReactNode;
  type: ToastType;
  duration?: number;
  action?: {
    label: string;
    onClick: () => void;
  };
}

Sources: src/store.ts:7-17

Technical Specifications

The project is configured for modern web development with the following constraints:

• Target: ES2020 via TypeScript for modern environment compatibility.
• Module System: ESNext with bundler-based resolution.
• Peer Dependencies: Requires React 18+ and Framer Motion 10+.
• Build Output: Generates declarations and source maps in the ./dist directory.
  Sources: tsconfig.json:2-13, package.json:18-24

Conclusion

The @pcstyle/toast module provides a robust, type-safe notification solution that balances aesthetic flexibility with programmatic control. By separating the store logic from the React rendering cycle, it ensures that notifications can be triggered from anywhere in an application without requiring prop-drilling or complex context setups.
Sources: src/store.ts:58, src/index.ts:11