# gunnartorfis/sonner-native architecture

> Architecture diagram of the GitHub repository gunnartorfis/sonner-native, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gunnartorfis/sonner-native
- Repository: https://github.com/gunnartorfis/sonner-native

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components
    subgraph "Core Components"
        Public_API("Public API (index.tsx)"):::core
        Toast_Context("Toast Context (context.tsx)"):::logic
        Toaster("Toast Container (toaster.tsx)"):::ui
        Toast("Toast Component (toast.tsx)"):::ui
    end

    %% Behavior Modules
    subgraph "Behavior Modules"
        Animation("Animation Handling (animations.ts)"):::behavior
        Gesture("Gesture Handling (gestures.tsx)"):::behavior
        Positioner("Positioning & Layout (positioner.tsx)"):::behavior
    end

    %% Utility Modules
    subgraph "Utility Modules"
        Comparator("Utility: toast-comparator.ts"):::utility
        ToastFns("Utility: toast-fns.ts"):::utility
        Hook_AppState("Hook: use-app-state.ts"):::utility
        Hook_DefaultStyles("Hook: use-default-styles.ts"):::utility
        Hook_Colors("Hook: use-colors.ts"):::utility
    end

    %% External Dependencies
    subgraph "External Dependencies"
        RN("React Native"):::external
        Reanimated("Reanimated 3"):::external
        GestureLib("Gesture Handler"):::external
        Expo("Expo"):::external
        NativeWind("NativeWind"):::external
        TypeScript("TypeScript"):::external
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        Docs("Docs: Toaster Guide"):::docs
        Docs_toast("Docs: Toast Guide"):::docs
        Examples("Example App (App.tsx)"):::docs
        ToastDemo("Example: ToastDemo"):::docs
    end

    %% Connections between Core Components
    Public_API -->|"trigger"| Toast_Context
    Toast_Context -->|"update"| Toaster
    Toaster -->|"render"| Toast

    %% Connections from Toast Component to Behavior Modules
    Toast -->|"animate"| Animation
    Toast -->|"gesture"| Gesture
    Toast -->|"layout"| Positioner

    %% Connections from Utility Modules to Core Components
    Comparator -->|"support"| Toast_Context
    ToastFns -->|"support"| Toast_Context
    Comparator -->|"assist"| Toast
    ToastFns -->|"assist"| Toast

    %% Connections from Custom Hooks to Core Components
    Hook_AppState -->|"provide_state"| Toast_Context
    Hook_DefaultStyles -->|"provide_styles"| Toast
    Hook_Colors -->|"provide_colors"| Toast

    %% External Dependencies supporting Behavior and Core Modules
    RN -->|"platform"| Public_API
    Expo -->|"integrates"| Public_API
    Reanimated -->|"supports"| Animation
    GestureLib -->|"supports"| Gesture
    NativeWind -->|"styling"| Hook_DefaultStyles
    TypeScript -->|"types"| Public_API

    %% Documentation & Examples links
    Docs -->|"documents"| Public_API
    Docs_toast -->|"documents"| Toast
    Examples -->|"demonstrates"| Public_API
    Examples -->|"demonstrates"| Toaster
    ToastDemo -->|"demonstrates"| Toast

    %% Click Events for Core Components
    click Public_API "https://github.com/gunnartorfis/sonner-native/blob/main/src/index.tsx"
    click Toast_Context "https://github.com/gunnartorfis/sonner-native/blob/main/src/context.tsx"
    click Toaster "https://github.com/gunnartorfis/sonner-native/blob/main/src/toaster.tsx"
    click Toast "https://github.com/gunnartorfis/sonner-native/blob/main/src/toast.tsx"

    %% Click Events for Behavior Modules
    click Animation "https://github.com/gunnartorfis/sonner-native/blob/main/src/animations.ts"
    click Gesture "https://github.com/gunnartorfis/sonner-native/blob/main/src/gestures.tsx"
    click Positioner "https://github.com/gunnartorfis/sonner-native/blob/main/src/positioner.tsx"

    %% Click Events for Utility Modules
    click Comparator "https://github.com/gunnartorfis/sonner-native/blob/main/src/toast-comparator.ts"
    click ToastFns "https://github.com/gunnartorfis/sonner-native/blob/main/src/toast-fns.ts"
    click Hook_AppState "https://github.com/gunnartorfis/sonner-native/blob/main/src/use-app-state.ts"
    click Hook_DefaultStyles "https://github.com/gunnartorfis/sonner-native/blob/main/src/use-default-styles.ts"
    click Hook_Colors "https://github.com/gunnartorfis/sonner-native/blob/main/src/use-colors.ts"

    %% Click Events for Documentation & Examples
    click Docs "https://github.com/gunnartorfis/sonner-native/blob/main/docs/docs/Toaster.md"
    click Docs_toast "https://github.com/gunnartorfis/sonner-native/blob/main/docs/docs/toast.md"
    click Examples "https://github.com/gunnartorfis/sonner-native/blob/main/example/src/App.tsx"
    click ToastDemo "https://github.com/gunnartorfis/sonner-native/blob/main/example/ToastDemo.tsx"

    %% Styles
    classDef core fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef logic fill:#A9DFBF,stroke:#333,stroke-width:2px;
    classDef ui fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef behavior fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef utility fill:#D7BDE2,stroke:#333,stroke-width:2px;
    classDef external fill:#D6EAF8,stroke:#333,stroke-width:2px;
    classDef docs fill:#FAD7A0,stroke:#333,stroke-width:2px;
```
