ToastProvider Component

Relevant source files

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

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

The ToastProvider is the central UI component of the @pcstyle/toast library, responsible for rendering and managing the lifecycle of toast notifications within a React application. It acts as a subscriber to the singleton toastStore, which handles the internal state and business logic of notification management.

The component supports two distinct visual themes ("cyber" and "minimal") and various screen positions. It utilizes framer-motion for smooth entry and exit animations, ensuring a high-quality user experience consistent with "PCSTYLE" design principles.

Sources: src/provider.tsx:1-13, package.json:1-15

Architecture and Data Flow

The system follows an observer pattern where the ToastProvider observes changes in the toastStore. When a user invokes the toast() function, a new notification object is added to the store, which then notifies the provider to update its local state and re-render.

State Synchronization

The provider uses the useEffect hook to subscribe to the toastStore upon mounting. This subscription returns a cleanup function to prevent memory leaks.

Logic and Constraints

• Maximum Visible Toasts: The system restricts the number of concurrent visible notifications to 5 to prevent UI clutter.
• Auto-Dismissal: Toasts (excluding those of type "loading") are automatically removed after a duration (defaulting to 4000ms).
• Manual Removal: Users can dismiss toasts manually via an close button [X] or via toast.dismiss(id).

Sources: src/store.ts:40-45, src/index.ts:37-39

Configuration and Props

The ToastProvider accepts specific properties to control the global appearance and placement of notifications.

ToastProviderProps

Property	Type	Default	Description
theme	"cyber" | "minimal"	"cyber"	Visual style of the toast cards.
position	"top-right" | "top-center" | "bottom-right" | "bottom-center"	"bottom-right"	Screen placement.

Sources: src/provider.tsx:7-13

Positioning Classes

The provider applies fixed CSS positioning based on the position prop:

• top-right: top-6 right-6
• top-center: top-6 left-1/2 -translate-x-1/2
• bottom-right: bottom-6 right-6
• bottom-center: bottom-6 left-1/2 -translate-x-1/2

Sources: src/provider.tsx:22-27

Theming and UI Implementation

The component implements two distinct visual styles through conditional class logic and internal sub-elements.

Cyber Theme

The "cyber" theme is characterized by a cyberpunk/high-tech aesthetic:

• Styling: Black background with 90% opacity, #ff00ff (magenta) borders and shadows.
• Typography: Monospace fonts with uppercase tracking.
• Special Effects: Includes a top-aligned animated pulse gradient (bg-gradient-to-r).

Minimal Theme

The "minimal" theme provides a cleaner, standard interface:

• Styling: White background with light zinc borders and high-elevation shadows.
• Typography: Standard sans-serif with bold black text for messages.

Sources: src/provider.tsx:39-65

Animation Logic

Animations are handled by framer-motion using the AnimatePresence component to manage exit transitions.

The entry animation direction is determined by the position prop:

• If position includes "right", toasts slide in from x: 20.
• If position includes "top", toasts slide in from y: -20.
• Otherwise, they slide from y: 20.

Sources: src/provider.tsx:35-38

Integration with API

The ToastProvider works in tandem with the functional API exported from index.ts. This API includes support for standard notification types and complex asynchronous workflows.

Toast API Methods

Method	Description
toast(message)	Fires a default notification.
toast.success(message)	Fires a success notification.
toast.error(message)	Fires an error notification.
toast.promise(promise, data)	Handles loading, success, and error states for a Promise.

Sources: src/index.ts:13-64

Data Structures

The internal Toast interface defines the structure rendered by the provider:

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

Sources: src/store.ts:7-16

Conclusion

The ToastProvider serves as the visual anchor for the @pcstyle/toast system. By decoupling the notification state logic into a ToastStore and using framer-motion for rendering, the component achieves a highly performant and visually distinct notification experience suitable for React applications requiring "cyber" or "minimal" aesthetics.