How gunnartorfis/sonner-native works
Project Type and Purpose
• The README further clarifies that the library is optimized for performance (using Reanimated 3) and supports Expo and NativeWind styling. It is intended for integration by developers in their own React Native apps.
File Structure
• Top-level directories and files include:
• “example”: Provides a sample integration with an App demonstrating usage, illustrating the public API (showing how to import, render, and interact with toasts).
• “docs”: Offers documentation content and configuration (for Docusaurus), which can give hints on intended usage and architectural organization.
• Others (tests, configuration files, GitHub workflows, etc.) support development and CI/CD but are less central to the runtime architecture.
• Within “src”, crucial modules include:
• index.tsx: Likely the public API entry point, re-exporting the main components and functions.
• toaster.tsx and toast.tsx: Represent the main UI components – the “Toaster” which acts as the container, and individual “Toast” components.
• context.tsx: Manages the global state or context for toasts – the engine that holds and orchestrates toast notifications.
• Additional utilities such as animations.ts, gestures.tsx, positioner.tsx, and toast-comparator.ts define the behavior for animations (touch and gesture responses), positioning strategies, and ordering or comparison logic for concurrent notifications.
a. Main Components:
• Public API & Entry Point: index.tsx that exposes the “Toaster” component and “toast” function.
• Toast Container (Toaster): Manages displaying active toasts.
• Toast Component: Defines the visual representation, including support for variants (success, error, warning, etc.) and handling custom JSX.
• Context/State Management: (context.tsx) to maintain the state of active and dismissed toasts.
• Animation & Gestures: (animations.ts, gestures.tsx) illustrating how toast appearance, cancellation, and swipe actions are achieved using Reanimated 3 and Gesture Handler.
• Positioning and Layout: (positioner.tsx, use-default-styles.ts) dictating the alignment (top, bottom) and placement logic.
• Utility Functions: Helper functions like those in toast-fns.ts and toast-comparator.ts for toast ordering and styling logic.
• External Dependencies: Highlight the peer dependencies such as React Native Reanimated, Gesture Handler, Safe Area Context, and React Native SVG.
b. Relationships and Interactions:
• A directional data flow starting with the API call (via the toast function) – when a component triggers a toast, it will dispatch the event to the global Context.
• The Context then updates the state, prompting the “Toaster” component to render a new “Toast” instance.
• Each “Toast” uses the Animation and Gesture modules to animate its entry, provide swipable dismissal, and respond to user interactions.
• Utility modules (like positioner, comparator, and default styles) are used by the UI components to maintain consistency in layout and behavior.
• External libraries (Reanimated, Gesture Handler, etc.) should be noted as supporting the animations and responsive interactions.
c. Architectural Patterns and Principles:
• Separation of Concerns: The project clearly separates the API layer (public index, toast function), UI components (toaster, toast), state management (context), and behavioral logic (animations, gestures).
• Modular Design: Each file/module handles one aspect of the functionality (e.g., animations, positioning), making it easy to extend or modify parts of the library.
• React Hooks and Context: The usage of hooks (e.g., useAppState, useDefaultStyles) and Context implies that the state flows and updates are handled reactively.
d. Relevant Technologies/Frameworks:
• React Native – for the component structure.
• Reanimated 3 – to support high-performance animations.
• React Native Gesture Handler – for detecting swipe/dismiss gestures.
• Expo – as indicated in the installation and example setup.
• NativeWind – for styling support with Tailwind CSS.
• TypeScript – throughout the source (.tsx, .ts files) indicates strong type checking.
Elements
• Annotations: You might want to include notes that explain that gesture events, for instance, are managed via the separate “gestures.tsx” module and integrated with the toast component for swipe-to-dismiss functionality.