Quick Start Guide

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

The @pcstyle/toast library is a React-based notification system inspired by Sonner, featuring dual-theme support (Cyberpunk and Minimal) and high-performance animations powered by framer-motion. This guide provides the technical overview and implementation steps to integrate the toast system into a React application.

The system relies on a centralized observer-based store to manage state independently of the UI components, ensuring a clean API for triggering notifications from anywhere in the codebase.

Sources: package.json:2-4, src/store.ts:1-5, src/provider.tsx:1-8

Installation and Environment Setup

The library is built as an ESM module targeting ES2020 and requires React 18+ and Framer Motion 10+.

Sources: package.json:11-25, tsconfig.json:3-14

Dependencies

Package	Version	Role
react	>=18	Core UI Framework
react-dom	>=18	DOM Rendering
framer-motion	>=10	Animation Engine

Sources: package.json:22-26

Core Architecture

The system is split into three primary layers: the Store (state management), the Provider (UI rendering), and the API (triggering functions).

Data Flow Overview

The following diagram illustrates how a toast request flows from the API through the store to the UI provider.

The ToastStore maintains an internal array of active toasts, limited to 5 visible items at a time to prevent UI clutter.

Sources: src/store.ts:25-30, src/store.ts:46-48

Implementation Steps

1. Configure the Provider

The ToastProvider must wrap the application (or a portion of it) to listen for store changes and render the notifications. It supports two themes: cyber and minimal.

import { ToastProvider } from "@pcstyle/toast";

function App() {
  return (
    <>
      <ToastProvider theme="cyber" position="bottom-right" />
      <MainContent />
    </>
  );
}

Sources: src/provider.tsx:11-14, src/index.ts:60

2. Basic Usage

Notifications are triggered via the toast function or its specialized variants.

import { toast } from "@pcstyle/toast";

// Simple message
toast("Operation successful");

// With options and actions
toast.success("File Saved", {
  duration: 5000,
  action: {
    label: "Undo",
    onClick: () => console.log("Undo clicked")
  }
});

Sources: src/index.ts:11-23

API Reference

Toast Methods

The library exports a singleton toast object with the following methods:

Method	Description	Source
toast(msg, opts)	Default notification	src/index.ts:11
toast.success(msg, opts)	Success state notification	src/index.ts:15
toast.error(msg, opts)	Error state notification	src/index.ts:19
toast.info(msg, opts)	Informational notification	src/index.ts:23
toast.warning(msg, opts)	Warning notification	src/index.ts:27
toast.loading(msg, opts)	Loading state (no auto-dismiss)	src/index.ts:31
toast.dismiss(id)	Removes a specific toast	src/index.ts:35

Promise Handling

The toast.promise method allows for automatic state transitions based on an asynchronous operation.

Configuration Options

Provider Props

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

Sources: src/provider.tsx:11-14

Toast Options

Option	Type	Description
duration	number	Time in ms before auto-removal (default 4000ms).
action	{ label: string, onClick: () => void }	Optional button within the toast.

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

Summary

The PCSTYLE Toast system provides a type-safe, themeable notification solution. By utilizing a central ToastStore with an observer pattern, it allows for seamless notification management across complex React applications without the need for prop drilling or context-heavy architectures.

Sources: src/store.ts:22-40, cubic.yaml:8-15