Main Exports (Index)

Relevant source files

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

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

The @pcstyle/toast package provides a cyberpunk-inspired notification system for React applications. The main exports from the index file serve as the public API, offering a unified interface for triggering various types of notifications, managing their lifecycle, and integrating the visual container into the application's component tree.

The system is architected around a singleton store pattern that decouples the notification logic from the UI rendering. This allows developers to trigger toasts from anywhere in the application logic while the ToastProvider handles the visual manifestation and animations using framer-motion.

Sources: package.json:1-5, src/index.ts:1-60, src/provider.tsx:1-10

Core API: The toast Object

The primary interface for the library is the toast function and its associated methods. It provides a shorthand for adding notifications to the global state.

Toast Methods

The toast object includes specialized methods for different notification states:

Method	Type	Description
toast(message, options)	default	Standard notification.
toast.success(message, options)	success	Indicates successful completion of an action.
toast.error(message, options)	error	Indicates a failure or critical error.
toast.info(message, options)	info	Provides general information.
toast.warning(message, options)	warning	Warns the user about potential issues.
toast.loading(message, options)	loading	Displays a persistent loading state.
toast.dismiss(id)	N/A	Removes a specific toast by its unique ID.

Sources: src/index.ts:10-38

Asynchronous Operations with toast.promise

The toast.promise method allows for automatic toast state transitions based on the resolution or rejection of a JavaScript Promise. It initially triggers a loading toast and updates it to either success or error once the promise settles.

The diagram above illustrates the state lifecycle of a promise-based notification.
Sources: src/index.ts:40-58

Components and Providers

The index file exports the ToastProvider, which is the essential UI component required to render notifications.

ToastProvider

The ToastProvider must be placed at a high level in the application component tree. It subscribes to the toastStore and renders the list of active toasts.

Properties:

• theme: Determines the visual style. Options are "cyber" (default) or "minimal".
• position: Controls the screen placement. Supports "top-right", "top-center", "bottom-right" (default), and "bottom-center".

Sources: src/provider.tsx:7-12, src/index.ts:60

Data Structures and Types

The library utilizes specific TypeScript interfaces to ensure strict type safety across the API.

Toast Interface

Defines the structure of a single notification object within the system.

Field	Type	Description
id	string	Unique identifier generated on creation.
message	string | React.ReactNode	The content to be displayed.
type	ToastType	The category of toast (e.g., success, error).
duration	number	Time in ms before auto-removal (default 4000ms).
action	object	Optional action button with label and onClick.

Sources: src/store.ts:5-16

Architectural Flow

The following sequence diagram demonstrates the interaction between the public API, the internal store, and the UI Provider when a toast is triggered.

The diagram shows the decoupled nature of the system where the API triggers state changes and the UI reacts via a subscription model.
Sources: src/index.ts:14-16, src/store.ts:25-50, src/provider.tsx:14-20

Project Standards and Configuration

The project adheres to modern ESM standards and strict type safety as defined in the configuration files.

• Module System: Uses ESNext modules with bundler resolution.
• Strictness: strict: true is enabled in tsconfig.json.
• Custom Rules: The project enforces "STRICT_TYPES" (no any types) and "ESM_STANDARDS" for package exports.
• Dependencies: Relies on react (>=18) and framer-motion (>=10).

Sources: tsconfig.json:4-15, cubic.yaml:18-25, package.json:20-24

Summary

The main exports of the @pcstyle/toast package provide a comprehensive toolset for reactive notifications. By exporting a singleton toast utility alongside a ToastProvider, the library enables a simple imperative API for developers while maintaining a declarative, animated UI layer. The system is constrained to show a maximum of 5 toasts simultaneously to ensure UI clarity.

Sources: src/store.ts:39, src/index.ts:1-60