77 lines
2.3 KiB
Markdown
77 lines
2.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**Directory MapView** - A reimagined file picker dialog that displays the filesystem like a road map.
|
|
|
|
### Vision
|
|
|
|
Traditional file dialogs show directories as indented trees or lists. You never see what's beside you or the broader context. Directory MapView changes this:
|
|
|
|
- Directories appear as connected pathways/roads with labels
|
|
- Current path highlighted like a navigation route
|
|
- "You are here" marker at current location
|
|
- Zoom out to see the big picture, zoom in for details
|
|
- Pan around to explore like Google Maps
|
|
|
|
### Interaction Model
|
|
|
|
- **Mouse wheel**: Zoom in/out
|
|
- **Left-click + drag**: Pan the view
|
|
- **Click on directory**: Navigate there
|
|
- **Hover**: Show directory info
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# Install for development
|
|
pip install -e ".[dev]"
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Run the demo
|
|
python -m dir_mapview.demo
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Technical Approach
|
|
|
|
- **PyQt6/PySide6** for the widget
|
|
- **QGraphicsScene** for zoomable/pannable canvas
|
|
- **Tree layout algorithm** for positioning directories
|
|
- Lazy loading for large filesystems
|
|
- Caching for performance
|
|
|
|
### Key Modules
|
|
|
|
- `src/dir_mapview/widget.py` - Main MapView widget (QGraphicsView subclass)
|
|
- `src/dir_mapview/scene.py` - Scene management and directory rendering
|
|
- `src/dir_mapview/layout.py` - Directory tree layout algorithm
|
|
- `src/dir_mapview/scanner.py` - Filesystem scanning with lazy loading
|
|
- `src/dir_mapview/dialog.py` - Drop-in file picker dialog replacement
|
|
|
|
### Key Paths
|
|
|
|
- **Source code**: `src/dir_mapview/`
|
|
- **Tests**: `tests/`
|
|
- **Documentation**: `docs/` (symlink to project-docs)
|
|
|
|
## Documentation
|
|
|
|
Documentation for this project lives in the centralized docs system:
|
|
|
|
- **Source**: `~/PycharmProjects/project-docs/docs/projects/dir-mapview/`
|
|
- **Public URL**: `https://pages.brrd.tech/rob/dir-mapview/`
|
|
|
|
When updating documentation:
|
|
1. Edit files in `docs/` (the symlink) or the full path above
|
|
2. Use `public: true` frontmatter for public-facing docs
|
|
3. Use `<!-- PRIVATE_START -->` / `<!-- PRIVATE_END -->` to hide sections
|
|
4. Run `~/PycharmProjects/project-docs/scripts/build-public-docs.sh dir-mapview --deploy` to publish
|
|
|
|
Do NOT create documentation files directly in this repository.
|