# leoikeh99/use-sortable architecture

> Architecture diagram of the GitHub repository leoikeh99/use-sortable, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leoikeh99/use-sortable
- Repository: https://github.com/leoikeh99/use-sortable

## Overview

##### Overall Project Components
- Library Core (React hook): Central to the project, it encapsulates the logic for managing the state of columns and items, handling drag-end events, and providing helper functions.
- Data Model: The hook expects a data structure with “columns” that contain “tasks” (or generic items) – each with a unique ID and an “order”. This is critical because sorting and persistence rely heavily on the “order” property.
- Integration Layer with DnD Libraries: The hook is designed to work with any React DnD library by standardizing event output (like the “result” parameter with destination, source, and draggableId).
- Optimistic Update & Persistence Functions: When a drag operation occurs, the hook may trigger update functions to persist changes to the backend and handle reversion in case of errors.
- Example Application: The “example” folder demonstrates how various components (Board, Column, Task, forms, UI components) use the hook. Although these are for demo purposes, they reflect how consumers might integrate the hook into a full UI.
- Testing and Configuration: With a “test” directory (and multiple configuration files – tsconfig, postcss, tailwind, vite, etc.), the project is structured as a TypeScript library with an example usage environment and CI workflows.

a. Main Components:
– UseSortable Hook (Core Library): Represent this as a central module.
– DragEndHandler: Illustrate it as the interface between UI events (from a DnD library) and the hook’s internal logic.
– Helper Functions (the “fns” object): Represent individual components like create, update, remove (for both columns and items). These operations modify the state.
– Update Functions for Optimistic Updates: Optionally branch these out from the core hook as they interface with external backend services.
– Integration with UI Components: In the example folder, you have Board.tsx, Column.tsx, Task.tsx, and various forms that consume the hook. Represent these as “Consumer Components” that trigger drag events and receive updated state.

b. Relationships/Interactions:
– UI components fire drag events from an external DnD provider that supplies the “result” parameter.
– The DragEndHandler (provided by the hook) receives these events, using the standardized “result” structure.
– The hook, in turn, uses the helper functions (“fns”) to update the internal state (data structure) reflecting the reordering of items or columns.
– Finally, the consumer UI components reflect the updated state via React re-rendering.

c. Architectural Patterns and Design Principles:
– Separation of Concerns: The hook cleanly decouples the sorting logic from the UI, allowing it to be used with different drag-and-drop libraries and backend implementations.
– Reusability & Composability: The design separates the core logic (data reordering) from presentation, demonstrated by the example components.
– Type-Safe Development: Both the “src” and “example” directories use TypeScript to enforce type safety.

– Include labels for each component: e.g., “UI Components (Board, Column, Task Forms)”, “DragEnd Event”, “useSortable Hook”, “Helper Functions (fns)”, “Optimistic Update Handlers”, and “Backend Persistence Module”.
– Add notes about how the drag result object is structured (source, destination, draggableId) to clarify data flows.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External UI Event Source
    UI_DnD["UI (DnD Library)"]:::external

    %% Core Library Subgraph
    subgraph "Core Library & Logic"
        US["useSortable Hook"]:::hook
        DE["DragEndHandler"]:::hook
        HF["Helper Functions (fns)"]:::util
        DM["Data Model (Columns & Items)"]:::util
        OU["Optimistic Update (Hook)"]:::hook
        OP["Optimistic Persistence (Utils)"]:::util
    end

    %% Example UI Components Subgraph
    subgraph "Example UI Components"
        Board["Board Component"]:::ui
        Column["Column Component"]:::ui
        Task["Task Component"]:::ui
        ACF["AddColumnForm"]:::ui
        ECF["EditColumnForm"]:::ui
        ATF["AddTaskForm"]:::ui
        ETF["EditTaskForm"]:::ui
        Btn["Button Component"]:::ui
        Tabs["Tabs Component"]:::ui
    end

    %% Testing and Configuration Node
    Test["Testing & Config"]:::test

    %% Relationships
    UI_DnD -->|"onDragEnd"| DE
    DE -->|"triggers"| US
    US -->|"invokes"| HF
    HF -->|"updates"| DM
    US -->|"triggers"| OU
    OU <-->|"persist/rollback"| OP
    DM -->|"state renders"| Board
    DM -->|"state renders"| Column
    DM -->|"state renders"| Task

    %% UI Components interaction with DnD (for demo)
    Board -->|"composes"| ACF
    Board -->|"composes"| ECF
    Column -->|"composes"| ATF
    Column -->|"composes"| ETF
    Board -->|"contains"| Btn
    Board -->|"contains"| Tabs

    %% Testing relation (side note)
    US ---|"tested by"| Test

    %% Click Events
    click US "https://github.com/leoikeh99/use-sortable/blob/main/src/index.tsx"
    click DE "https://github.com/leoikeh99/use-sortable/blob/main/src/index.tsx"
    click DM "https://github.com/leoikeh99/use-sortable/blob/main/src/types.ts"
    click HF "https://github.com/leoikeh99/use-sortable/blob/main/src/utils.ts"
    click OU "https://github.com/leoikeh99/use-sortable/blob/main/src/index.tsx"
    click OP "https://github.com/leoikeh99/use-sortable/blob/main/src/utils.ts"
    click Board "https://github.com/leoikeh99/use-sortable/blob/main/example/components/Board.tsx"
    click Column "https://github.com/leoikeh99/use-sortable/blob/main/example/components/Column.tsx"
    click Task "https://github.com/leoikeh99/use-sortable/blob/main/example/components/Task.tsx"
    click ACF "https://github.com/leoikeh99/use-sortable/blob/main/example/components/forms/columns/AddColumnForm.tsx"
    click ECF "https://github.com/leoikeh99/use-sortable/blob/main/example/components/forms/columns/EditColumnForm.tsx"
    click ATF "https://github.com/leoikeh99/use-sortable/blob/main/example/components/forms/tasks/AddTaskForm.tsx"
    click ETF "https://github.com/leoikeh99/use-sortable/blob/main/example/components/forms/tasks/EditTaskForm.tsx"
    click Btn "https://github.com/leoikeh99/use-sortable/blob/main/example/components/ui/button.tsx"
    click Tabs "https://github.com/leoikeh99/use-sortable/blob/main/example/components/ui/tabs.tsx"
    click Test "https://github.com/leoikeh99/use-sortable/blob/main/test/index.test.tsx"

    %% Styles
    classDef hook fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef util fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef ui fill:#577590,stroke:#fff,stroke-width:2px;
    classDef external fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef test fill:#ffcc00,stroke:#333,stroke-width:2px;
```
