rob
/
dir-mapview
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dir-mapview/CLAUDE.md

2.3 KiB
Raw Permalink Blame History

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

# 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.