WebMap - Mind Mapping App

A keyboard-first, offline-capable mind mapping application built with React, TypeScript, and Tauri.

🌐 Live Demo | 📦 GitHub Repository

Status: ✅ Production-ready v1.0 (Phase 18 complete - All tests passing, >80% coverage)

✨ Features

Core Functionality

• 🎯 Keyboard-First Navigation: Navigate and edit mind maps entirely with keyboard shortcuts (arrows, Tab, Enter, Space)
• 📱 Progressive Web App: Installable on mobile and desktop, works offline
• 🖥️ Desktop Application: Native app for macOS, Windows, and Linux via Tauri
• ✍️ Rich Text Editing: Markdown-based editing with Lexical (bold, italic, colors, emojis)
• 🎨 Visual Customization: Color picker for text and backgrounds, emoji icons
• 📐 Automatic Layout: Horizontal tree layout with manual repositioning via drag-and-drop
• 💾 Autosave: Automatic saving to IndexedDB to prevent data loss
• ⏪ Undo/Redo: Full history support with keyboard shortcuts
• 📋 Copy/Paste: Copy nodes with entire subtrees
• 🌐 Offline First: Full functionality without internet connection
• 📦 File Management: Save/load mind maps as JSON files

Technical Highlights

• ⚡ High Performance: Handles 100+ nodes efficiently with throttled layout calculations
• 🧪 Well-Tested: 148 unit tests, 36+ E2E scenarios, >80% code coverage
• 🎨 Modern UI: Clean interface with React Flow canvas and Lexical editor
• 🔒 Type-Safe: Built with TypeScript for reliability
• 📱 Responsive: Works on desktop and mobile browsers

Tech Stack

• Framework: React 18 + TypeScript + Vite
• Mind Map Rendering: React Flow
• Rich Text Editor: Lexical
• State Management: Zustand
• Desktop App: Tauri v2
• PWA: Vite PWA Plugin + Workbox
• Testing: Vitest (unit/component) + Playwright (E2E)
• Storage: IndexedDB (idb library)

🚀 Quick Start

Try It Online

Visit https://ankurokok.github.io/webmap/ to use the app immediately - no installation required.

Install as PWA

1. Visit the live demo link above
2. Click the install icon (⊕) in your browser's address bar
3. The app will be installed and work offline

Local Development

Prerequisites

• Node.js 18+
• npm or pnpm

Installation

# Clone the repository
git clone https://github.com/ankurokok/webmap.git
cd webmap

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm run test           # Unit tests
npm run test:e2e       # E2E tests
npm run test:coverage  # Coverage report

# Build for production
npm run build

Development Scripts

npm run dev          # Start dev server
npm run build        # Build for production
npm run preview      # Preview production build
npm run test         # Run unit/component tests
npm run test:ui      # Run tests with UI
npm run test:coverage # Generate coverage report
npm run test:e2e     # Run E2E tests
npm run test:e2e:ui  # Run E2E tests with UI
npm run lint         # Lint code
npm run lint:fix     # Fix linting issues
npm run format       # Format code with Prettier
npm run type-check   # Check TypeScript types

📖 How to Use

Creating Your First Mind Map

1. Start with the root node: When you first open the app, you'll see a single node ready for editing
2. Add text: Type directly to replace the node text, or press Cmd/Ctrl+Enter to edit existing text
3. Create child nodes: Press Tab to create a child node (extends the branch rightward)
4. Create sibling nodes: Press Enter to create a sibling node (same level)
5. Navigate: Use arrow keys to move between nodes:
   • → (Right): Move to first child
   • ← (Left): Move to parent
   • ↑ (Up): Move to previous sibling
   • ↓ (Down): Move to next sibling

Editing Nodes

• Enter edit mode: Press Cmd/Ctrl+Enter or type any character to start editing
• Exit edit mode: Press Escape to save and return to navigation mode
• Markdown formatting: Use **bold** or *italic* for formatting
• Add emojis: Use the emoji picker in the toolbar or type emojis directly

Organizing Your Map

• Collapse/expand: Press Space to hide/show children of a node
• Drag nodes: Click and drag any node to reposition it manually
• Reset layout: Use the Reset Layout button in the toolbar to return to automatic positioning
• Copy/paste: Select a node and press Cmd/Ctrl+C to copy (includes all children), then Cmd/Ctrl+V to paste

Styling

• Text color: Click the color picker in the toolbar and select a text color
• Background color: Click the background tab in the color picker
• Emoji icons: Use the emoji picker to add an icon to the node (will appear before text)

Saving and Loading

• Autosave: Your mind map is automatically saved to your browser's IndexedDB every 500ms
• Export JSON: Press Cmd/Ctrl+S to download your mind map as a JSON file
• Open file: Press Cmd/Ctrl+O or drag-and-drop a JSON file to load it

⌨️ Keyboard Shortcuts Reference

Navigation Mode (Default)

Shortcut	Action	Details
→ ↑ ↓ ←	Navigate between nodes	Right: child, Left: parent, Up/Down: siblings
Enter	Create sibling node	New node at same level as current
Tab	Create child node	New node extends branch rightward
Space	Collapse/expand children	Toggle visibility of child nodes
Delete or Backspace	Delete node	Removes node and all children (except root)
Type any character	Edit mode (overwrite)	Replaces text and enters edit mode
Cmd/Ctrl + Enter	Edit mode (append)	Enters edit mode with existing text
Cmd/Ctrl + C	Copy node	Copies node and all children
Cmd/Ctrl + V	Paste node	Pastes as child of selected node
Cmd/Ctrl + Z	Undo	Revert last change
Cmd/Ctrl + Shift + Z	Redo	Reapply undone change
Cmd/Ctrl + S	Save/Export	Download mind map as JSON
Cmd/Ctrl + O	Open file	Open file picker to load JSON

Edit Mode

Shortcut	Action	Details
Escape	Exit edit mode	Saves changes and returns to navigation
Cmd/Ctrl + Z	Undo (exits edit mode)	Reverts changes, returns to navigation
Cmd/Ctrl + Shift + Z	Redo (exits edit mode)	Reapplies changes, returns to navigation
Cmd/Ctrl + B	Toggle bold	Markdown: **text**
Cmd/Ctrl + I	Toggle italic	Markdown: *text*
Arrow Keys	Move cursor	Navigate within text

Toolbar Actions (Mouse/Touch)

• Color Picker: Change text or background color
• Emoji Picker: Add emoji icon or inline emoji (searchable)
• Reset Layout: Return all nodes to automatic positioning

Project Structure

webmap/
├── src/
│   ├── components/      # React components
│   │   ├── MindMap/     # Mind map canvas and nodes
│   │   ├── Toolbar/     # Color picker, emoji picker
│   │   ├── Menu/        # Top menu bar
│   │   └── common/      # Shared components
│   ├── hooks/           # Custom React hooks
│   ├── store/           # Zustand state management
│   ├── utils/           # Utility functions
│   ├── types/           # TypeScript type definitions
│   ├── constants/       # Constants (keyboard, colors)
│   └── styles/          # Global styles
├── tests/
│   ├── unit/            # Unit tests
│   ├── component/       # Component tests
│   └── e2e/             # E2E tests (Playwright)
├── planning/            # Project planning docs
│   ├── spec.md          # Technical specification
│   ├── todo.md          # Task breakdown
│   └── plan.md          # Implementation plan
└── public/              # Static assets

Development Workflow

1. Create a feature branch: git checkout -b feature/my-feature
2. Make changes: Implement your feature with tests
3. Run tests: npm run test && npm run test:e2e
4. Lint and format: npm run lint:fix && npm run format
5. Commit: Use conventional commit format (e.g., feat: add node deletion)
6. Push and create PR

Testing

Unit Tests (Vitest)

npm run test

E2E Tests (Playwright)

npm run test:e2e

Coverage Report

npm run test:coverage

Building for Desktop (Tauri)

The app is configured to run as a native desktop application using Tauri.

Prerequisites

You need to install Rust to build the desktop app. See TAURI_SETUP.md for detailed instructions.

Quick start:

# Install Rust (macOS/Linux)
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

# Install Rust (Windows)
# Download from https://rustup.rs/

Desktop Development

# Development mode (with hot reload)
npm run tauri:dev

# Build production desktop app
npm run tauri:build

# Regenerate app icons
npm run tauri:icon src-tauri/icons/icon.svg

Platform-Specific Builds

The tauri:build command creates installers for your platform:

• macOS: .app bundle and .dmg installer
• Windows: .exe and .msi installer
• Linux: .deb, .AppImage, and others

See TAURI_SETUP.md for complete setup and build instructions.

Progressive Web App (PWA)

The app is configured as a PWA and can be installed on mobile and desktop browsers.

Installation

Desktop (Chrome/Edge):

• Look for the install icon (⊕) in the address bar
• Or use the browser menu → "Install WebMap"

Mobile (iOS Safari):

• Tap Share (□↑) → "Add to Home Screen"

Mobile (Android Chrome):

• Tap Menu (⋮) → "Add to Home screen"

PWA Features

✅ Installable app icon on home screen/desktop ✅ Standalone window (no browser UI) ✅ Works offline with full functionality ✅ Automatic updates ✅ Fast loading from cache

See PWA_GUIDE.md for complete PWA documentation.

Contributing

See planning/plan.md for the implementation roadmap and contribution guidelines.

License

MIT

🏗️ Architecture

State Management

• Zustand Store: Centralized state management with actions for all operations
• History Stack: Undo/redo functionality with 50-state limit
• Selective Subscriptions: Components only re-render when relevant state changes

Layout System

• Horizontal Tree Algorithm: Automatic positioning with D3-hierarchy concepts
• Throttled Calculations: 150ms throttle to optimize performance during rapid operations
• Manual Override: Nodes can be dragged; manual positions preserved across operations

Performance Optimizations

• React.memo: CustomNode and CustomEdge components memoized
• Throttled Layout: Layout calculations throttled to ~6-7/sec during rapid operations
• Debounced Autosave: 500ms debounce on autosave operations
• Efficient Rendering: Only affected nodes re-render on state changes

Testing Strategy

• Unit Tests (148): Store, utilities, hooks, algorithms
• E2E Tests (36+ scenarios): Critical user flows across 3 browsers (Chromium, Firefox, WebKit)
• Performance Tests (5): Large mind maps (100+ nodes, 50-level nesting)
• Coverage: >80% across all modules (Store 98.69%, Layout 98.83%, Navigation 97.22%)

Tech Stack Details

• React Flow: Canvas rendering with custom nodes/edges
• Lexical: Rich text editing with markdown shortcuts
• Zustand: State management with devtools integration
• IndexedDB: Browser storage via idb wrapper
• Vite: Fast build tool with PWA plugin
• TypeScript: Full type safety throughout codebase

🗺️ Roadmap

Completed (v1.0)

• Phase 1: Project setup and infrastructure ✅
• Phase 2: State management (Zustand store) ✅
• Phase 3: Layout and navigation algorithms ✅
• Phase 4: React Flow canvas ✅
• Phase 5: Keyboard navigation ✅
• Phase 5.5: Layout improvement (horizontal tree) ✅
• Phase 6: Rich text editing (Lexical) ✅
• Phase 6.5: Copy/paste with keyboard shortcuts ✅
• Phase 7: Toolbar and styling ✅
• Phase 8: Undo/redo keyboard shortcuts ✅
• Phase 8.5: Edit mode UX improvements ✅
• Phase 9: File management (browser) ✅
• Phase 16: Performance optimization ✅
• Phase 17: Testing and QA ✅
• Phase 18: Testing & quality assurance ✅
• Phase 20: Deployment (GitHub Pages) ✅

Planned (Future Releases)

• Phase 10: Top menu bar (File, Edit, View, Help)
• Phase 11: Export features (PDF, PNG, SVG)
• Phase 12: Tauri desktop app packaging
• Phase 13: PWA testing and optimization
• Phase 15: UI polish and accessibility improvements
• Phase 19: Extended documentation
• v1.1: Images and links in nodes
• v1.2: Multiple mind maps (library view)
• v2.0: Cloud sync and collaboration

See planning/plan.md and planning/todo.md for detailed implementation notes.