# react-grid-layout/react-draggable architecture

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

- Interactive diagram: https://gitdiagram.com/react-grid-layout/react-draggable
- Repository: https://github.com/react-grid-layout/react-draggable

## Overview

##### Project Type & Purpose
- This project is an open-source React library that adds draggable functionalities to DOM elements. Its primary purpose is to enable developers to wrap any existing element with draggable capabilities.
- Key usage patterns are explained in the README. The library supports “controlled” vs. “uncontrolled” behavior and offers two APIs: a higher-level <Draggable> (with state management) and a lower-level <DraggableCore> (for absolute control).

##### File Structure & Architectural Insights
- Top-Level Directories and Key Files:
- The root directory contains configuration and build-related files (.babelrc.js, webpack.config.js, Makefile, etc.), suggesting a well-set-up build and test infrastructure.
- The “lib” directory holds the core library source files (Draggable.js, DraggableCore.js) with supporting utility functions (under lib/utils). These files implement the essential draggable behaviors, event handing, and CSS transform management.
- The “example” folder provides usage examples (example.js, index.html), demonstrating how the library is integrated into a React project.
- The “specs” folder houses test files that ensure the correct behavior of the draggable components. Its inclusion emphasizes a strong testing strategy.
- “typings” contains TypeScript definitions, which indicate support and enforce type safety for consumers.

##### Main Components and Their Relationships
a. Draggable Component:
- Acts as a higher-level component that wraps the user’s content.
- Manages state (position) internally unless controlled via props (position and defaultPosition).
- Enhances the child component with event-handling and CSS transform updates.
b. DraggableCore Component:
- Provides basic drag event abstractions without managing visual state.
- Serves as the lower-level building block for both the <Draggable> component and other potential libraries.
c. Utility Modules:
- Located in lib/utils, these assist with DOM manipulation, logging, event normalization, applying CSS transforms, etc.
d. Build & Configuration:
- Tools such as Babel and Webpack coordinate the building of the distributable library.
- Configuration files (e.g., .eslintrc, Makefile) ensure uniform code quality and build processes.
e. Tests & Type Definitions:
- “typings” show TypeScript support.

##### Relationships and Interaction Flow
- How the user's interactions (mouse/touch events) traverse from the DOM to the library:
- The user interacts with an element wrapped by <Draggable> or <DraggableCore>.
- Event listeners (defined within these components) capture the actions (mousedown, touchstart, etc.).
- Utility functions in lib/utils assist in handling these events, calculating position deltas, and applying CSS transforms.
- The system then updates the component’s position and, if controlled externally, triggers the provided callbacks (onStart, onDrag, onStop).

##### Architectural Patterns & Design Principles
- The separation between <Draggable> (which manages internal state by default) and <DraggableCore> (which is stateless) indicates a separation of concerns, a common design principle in React libraries.
- The modular organization (clearly separated utility functions, core components, and tests) showcases good layering and maintainability.
- The support for both ES6 and CommonJS usage demonstrates an emphasis on compatibility and extensibility.

##### Technologies & Frameworks
- React and ReactDOM are core external dependencies.
- The build configuration leverages Babel and Webpack.
- Testing is set up using a combination of Karma and PhantomJS (as inferred from karma.conf.js) alongside JSX tests.
- TypeScript support is provided via typings while the core library is written in JavaScript.

##### Final Touch
- Annotations to explain key decisions such as the separation of Draggable and DraggableCore. Outline the testing and build strategy briefly if space permits.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        UE("User DOM Events"):::external
        React("React/ReactDOM"):::external
    end

    %% Core Library Components
    subgraph "Core Library"
        D("Draggable (Stateful)"):::core
        DC("DraggableCore (Stateless)"):::core
        UT("Utils"):::utils
    end

    %% Build & Configuration Files
    subgraph "Build & Config"
        Babel("Babel (.babelrc.js)"):::build
        Webpack("Webpack (webpack.config.js)"):::build
        Make("Makefile"):::build
        ESLint("ESLint (.eslintrc)"):::build
        Package("Package (package.json)"):::build
        Karma("Karma (karma.conf.js)"):::build
    end

    %% Test Suite
    subgraph "Tests"
        T1("draggable-phantom.spec.jsx"):::test
        T2("draggable.spec.jsx"):::test
        T3("ESLint Config Test (.eslintrc)"):::test
    end

    %% Type Definitions
    subgraph "Type Definitions"
        TD1("index.d.ts"):::types
        TD2("test.tsx"):::types
        TD3("tsconfig.json"):::types
    end

    %% Example Usage
    subgraph "Example Usage"
        EX1("example.js"):::example
        EX2("index.html"):::example
    end

    %% Connections from User Layer to Core Library
    UE -->|"initiates"| D
    UE -->|"initiates"| DC
    React -->|"renders"| D
    React -->|"renders"| DC

    %% Internal interactions within Core Library
    D -->|"uses"| DC
    D -->|"utilizes"| UT
    DC -->|"calls"| UT
    D -->|"triggers"| React
    DC -->|"triggers"| React

    %% Build & Config dependencies to Core Library
    Babel --> D
    Babel --> DC
    Webpack --> D
    Webpack --> DC
    Make --> D
    Make --> DC
    ESLint --> D
    ESLint --> DC
    Package --> D
    Package --> DC
    Karma --> D
    Karma --> DC

    %% Test Suite dependencies to Core Library
    T1 --> D
    T1 --> DC
    T2 --> D
    T2 --> DC
    T3 --> D
    T3 --> DC

    %% Type Definitions dependencies to Core Library
    TD1 --> D
    TD1 --> DC
    TD2 --> D
    TD2 --> DC
    TD3 --> D
    TD3 --> DC

    %% Example Usage integration with Core Library
    EX1 --> D
    EX1 --> DC
    EX2 --> D
    EX2 --> DC

    %% Click Events for Core Components
    click D "https://github.com/react-grid-layout/react-draggable/blob/master/lib/Draggable.js"
    click DC "https://github.com/react-grid-layout/react-draggable/blob/master/lib/DraggableCore.js"
    click UT "https://github.com/react-grid-layout/react-draggable/tree/master/lib/utils"

    %% Click Events for Build & Configuration Files
    click Babel "https://github.com/react-grid-layout/react-draggable/blob/master/.babelrc.js"
    click Webpack "https://github.com/react-grid-layout/react-draggable/blob/master/webpack.config.js"
    click Make "https://github.com/react-grid-layout/react-draggable/tree/master/Makefile"
    click ESLint "https://github.com/react-grid-layout/react-draggable/blob/master/.eslintrc"
    click Package "https://github.com/react-grid-layout/react-draggable/blob/master/package.json"
    click Karma "https://github.com/react-grid-layout/react-draggable/blob/master/karma.conf.js"

    %% Click Events for Test Files
    click T1 "https://github.com/react-grid-layout/react-draggable/blob/master/specs/draggable-phantom.spec.jsx"
    click T2 "https://github.com/react-grid-layout/react-draggable/blob/master/specs/draggable.spec.jsx"
    click T3 "https://github.com/react-grid-layout/react-draggable/blob/master/specs/.eslintrc"

    %% Click Events for Type Definitions
    click TD1 "https://github.com/react-grid-layout/react-draggable/blob/master/typings/index.d.ts"
    click TD2 "https://github.com/react-grid-layout/react-draggable/blob/master/typings/test.tsx"
    click TD3 "https://github.com/react-grid-layout/react-draggable/blob/master/typings/tsconfig.json"

    %% Click Events for Example Usage
    click EX1 "https://github.com/react-grid-layout/react-draggable/blob/master/example/example.js"
    click EX2 "https://github.com/react-grid-layout/react-draggable/blob/master/example/index.html"

    %% Styles
    classDef external fill:#fef2c0,stroke:#333,stroke-width:2px;
    classDef core fill:#c0eaff,stroke:#005,stroke-width:2px;
    classDef utils fill:#d0f0c0,stroke:#030,stroke-width:2px;
    classDef build fill:#fab1a0,stroke:#833,stroke-width:2px;
    classDef test fill:#fcd0ff,stroke:#933,stroke-width:2px;
    classDef types fill:#c0ffdf,stroke:#0a3,stroke-width:2px;
    classDef example fill:#e0c0ff,stroke:#603,stroke-width:2px;
```
