File Structure & Organization

Relevant source files

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

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

The @pcstyle/toast project is a React-based notification system designed with a dual-theme support, specifically featuring a "cyberpunk" aesthetic and a "minimal" aesthetic. The repository is organized as a modern TypeScript library following ECMAScript Module (ESM) standards, prioritizing strict type safety and clean API exports.

The project structure separates logic into a centralized state management store, a React context provider for rendering, and a high-level API for triggering notifications. This architecture ensures that toast notifications can be managed programmatically from anywhere in an application while maintaining a consistent visual presentation through a single provider component.

Sources: package.json:3-5, cubic.yaml:14-15, src/index.ts

Core Directory Structure

The repository follows a standard TypeScript project layout, separating source code from configuration and build artifacts.

Path	Description
src/	Contains the TypeScript source code, including logic and UI components.
dist/	Targeted output directory for compiled JavaScript and type definitions.
package.json	Project metadata, dependencies, and build scripts.
tsconfig.json	TypeScript compiler configuration.
cubic.yaml	Repository configuration for code reviews and architecture standards.

Sources: package.json:7-14, tsconfig.json:9-11, cubic.yaml:1-5

Source Code Organization (src/)

The internal logic is divided into three primary modules that handle state, rendering, and the developer-facing API.

The diagram above illustrates the relationship between the entry point, the state store, and the UI provider.
Sources: src/index.ts:1, src/provider.tsx:4, src/store.ts:60

Component Architecture & State Flow

The system utilizes an observer pattern to manage toast notifications. The ToastStore maintains an internal array of active toasts and notifies subscribers (the ToastProvider) whenever the state changes.

State Management (src/store.ts)

The ToastStore class is the central authority for toast data. It handles adding, removing, and updating toast objects. It also enforces a limit of 5 visible toasts at any given time.

API Surface (src/index.ts)

The library exports a toast object that serves as the primary interface for developers. This object includes helper methods for different notification types (success, error, info, etc.) and a complex promise handler.

Method	Purpose
toast(message, options)	Triggers a default toast notification.
toast.success/error/info/warning/loading	Triggers a type-specific toast.
toast.dismiss(id)	Manually removes a toast by its ID.
toast.promise(promise, data, options)	Handles loading, success, and error states for an async operation.

Sources: src/index.ts:10-53

Build & Module Configuration

The project is configured to produce high-quality library distributions using the TypeScript compiler.

• Compiler Settings: Uses ESNext modules and targets ES2020 for modern environment compatibility. It generates declaration files (.d.ts) for consumers.
• Module Standards: The project adheres to ESM standards, as defined in cubic.yaml, ensuring compatibility across different bundlers.
• Dependencies: Relies on react (>=18) and framer-motion (>=10) for UI rendering and animations.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "jsx": "react-jsx"
  }
}

Sources: tsconfig.json:3-14, package.json:18-22, cubic.yaml:22-23

Summary

The @pcstyle/toast repository is structured to provide a type-safe, themeable notification system. By decoupling the state management (store.ts) from the UI layer (provider.tsx) and providing a simplified API (index.ts), it offers a robust architecture for React applications. The project enforces high standards through cubic.yaml and strict TypeScript configurations to ensure reliability and ease of use for library consumers.