# ssshooter/react-outliner architecture

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

- Interactive diagram: https://gitdiagram.com/ssshooter/react-outliner
- Repository: https://github.com/ssshooter/react-outliner

## Overview

##### Project type and purpose
- This is a standalone, front‑end React component library (“react‑outliner‑neo”) built with TypeScript and Vite. Its purpose is to provide an embeddable Outliner UI component that consumers can drop into any React app, supporting nested items and keyboard interactions.

##### File structure
- Top‑level config files:
- package.json / pnpm‑lock.yaml – project metadata and dependencies
- vite.config.ts, tsconfig*.json – build and compiler configuration
- tailwind.config.js, postcss.config.js, eslint.config.js – styling and linting
- .github/workflows/npm-publish.yml – CI/CD pipeline for publishing to npm
- src/ hierarchy:
- src/components/ — React components (Outliner.tsx, OutlineItem.tsx plus CSS)
- src/utils/ — core outline manipulation logic (moveToOperation.ts, outlineOperations.ts)
- src/types.ts — shared TypeScript interfaces
- src/__tests__/ — unit tests (Vitest)
- src/main.tsx, index.html — development entry for the local demo
- README describes keyboard commands, installation, usage, tech stack.

##### Key insights from the README
- The library offers hierarchical editing with keyboard shortcuts.
- Consumers import `<Outliner data onChange />`.

##### Main components & relationships
a. Consumer Application (any React app)
– Passes in initial `data` prop to Outliner
– Receives updated outline via `onChange` callback
b. Outliner Component (src/components/Outliner.tsx)
– Manages internal state (controlled or uncontrolled)
– Renders a tree of OutlineItem components
– Hooks into keyboard events and dispatches operations
c. OutlineItem Component (src/components/OutlineItem.tsx)
d. Utility Modules (src/utils/)
– outlineOperations.ts: pure functions for insert, delete, indent, move
– moveToOperation.ts: transforms keyboard events into operation calls
e. Build & Dev Tools
– Vite dev server / build pipeline (vite.config.ts)
– TailwindCSS for styling (tailwind.config.js)
– TypeScript compiler (tsconfig.json)
– Vitest for unit tests (vitest.config.ts)
– GitHub Actions for npm publication

##### Architectural patterns & design principles
- Component‑based, unidirectional data flow: props down, callbacks up
- Pure utility functions for outline state manipulation (separation of UI vs logic)
- CSS modularization (per‑component .css files + Tailwind)
- Test‑driven: Vitest ensures core operations remain correct

##### Guidance on diagramming this library
- Use a layered approach:
- Top layer: Consumer App
- Middle layer: Outliner Component + OutlineItem Component
- Logic layer: Utility modules
- External layer: React, TypeScript, TailwindCSS, Lucide, Vite, Vitest, GitHub Actions
- Blue = UI components
- Green = business logic (utils)
- Gray = build & CI/CD
- Orange = external dependencies
- From Consumer → Outliner: “data” prop
- From Outliner → Consumer: “onChange” callback
- Between Outliner & OutlineItem: “render tree” and “keyboard events”
- From keyboard events → utils: “operation functions”
- Important keyboard shortcuts and how they map to utilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Application Layer
    subgraph "Consumer Application"
        direction TB
        App["App.tsx"]:::ui
        Main["main.tsx"]:::ui
        HTML["index.html"]:::ui
    end

    %% UI Components Layer
    subgraph "UI Layer (Components)"
        direction TB
        Outliner["Outliner.tsx"]:::ui
        OutlinerCSS["Outliner.css"]:::ui
        OutlineItem["OutlineItem.tsx"]:::ui
        OutlineCSS["OutlineItem.css"]:::ui
    end

    %% Logic Layer
    subgraph "Logic Layer (Business Logic)"
        direction TB
        Ops["outlineOperations.ts"]:::logic
        MoveOp["moveToOperation.ts"]:::logic
        Types["types.ts"]:::logic
    end

    %% Unit Tests
    subgraph "Unit Tests (Vitest)"
        direction TB
        Tests["Outliner.test.tsx"]:::infra
    end

    %% Build & Tooling
    subgraph "Build & Tooling"
        direction TB
        ViteCfg["vite.config.ts"]:::infra
        TSConfig["tsconfig*.json"]:::infra
        TailwindCfg["tailwind.config.js"]:::infra
        PostCSS["postcss.config.js"]:::infra
        ESLint["eslint.config.js"]:::infra
        VitestCfg["vitest.config.ts"]:::infra
        VitestSetup["vitest.setup.ts"]:::infra
        IndexCSS["src/index.css"]:::infra
    end

    GitHubActions[".github/workflows/npm-publish.yml"]:::infra
    PackageJSON["package.json"]:::infra

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        React["React 18"]:::external
        TS["TypeScript"]:::external
        Tailwind["TailwindCSS"]:::external
        Lucide["Lucide Icons"]:::external
        Vite["Vite"]:::external
        VitestExt["Vitest"]:::external
    end

    %% Connections
    App -->|"data prop"| Outliner
    Outliner -->|"onChange callback"| App
    Outliner -->|"renders tree"| OutlineItem
    OutlineItem -->|"keyboard events"| Outliner
    OutlineItem -->|"event payload"| MoveOp
    MoveOp -->|"calls operations"| Ops
    Types --> Ops
    Types --> Outliner
    React --> Outliner
    React --> OutlineItem
    TS --> Outliner
    TS --> OutlineItem
    TS --> Ops
    Tailwind --> OutlinerCSS
    Tailwind --> OutlineCSS
    Lucide --> OutlineItem
    Vite --> ViteCfg
    VitestExt --> Tests
    GitHubActions --> PackageJSON

    %% Click Events
    click App "https://github.com/ssshooter/react-outliner/blob/master/src/App.tsx"
    click Main "https://github.com/ssshooter/react-outliner/blob/master/src/main.tsx"
    click HTML "https://github.com/ssshooter/react-outliner/blob/master/index.html"
    click Outliner "https://github.com/ssshooter/react-outliner/blob/master/src/components/Outliner.tsx"
    click OutlinerCSS "https://github.com/ssshooter/react-outliner/blob/master/src/components/Outliner.css"
    click OutlineItem "https://github.com/ssshooter/react-outliner/blob/master/src/components/OutlineItem.tsx"
    click OutlineCSS "https://github.com/ssshooter/react-outliner/blob/master/src/components/OutlineItem.css"
    click Ops "https://github.com/ssshooter/react-outliner/blob/master/src/utils/outlineOperations.ts"
    click MoveOp "https://github.com/ssshooter/react-outliner/blob/master/src/utils/moveToOperation.ts"
    click Types "https://github.com/ssshooter/react-outliner/blob/master/src/types.ts"
    click Tests "https://github.com/ssshooter/react-outliner/blob/master/src/__tests__/Outliner.test.tsx"
    click ViteCfg "https://github.com/ssshooter/react-outliner/blob/master/vite.config.ts"
    click TSConfig "https://github.com/ssshooter/react-outliner/blob/master/tsconfig.json"
    click TailwindCfg "https://github.com/ssshooter/react-outliner/blob/master/tailwind.config.js"
    click PostCSS "https://github.com/ssshooter/react-outliner/blob/master/postcss.config.js"
    click ESLint "https://github.com/ssshooter/react-outliner/blob/master/eslint.config.js"
    click VitestCfg "https://github.com/ssshooter/react-outliner/blob/master/vitest.config.ts"
    click VitestSetup "https://github.com/ssshooter/react-outliner/blob/master/vitest.setup.ts"
    click IndexCSS "https://github.com/ssshooter/react-outliner/blob/master/src/index.css"
    click GitHubActions "https://github.com/ssshooter/react-outliner/blob/master/.github/workflows/npm-publish.yml"
    click PackageJSON "https://github.com/ssshooter/react-outliner/blob/master/package.json"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef logic fill:#d4edda,stroke:#155724,color:#155724
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
```
