Merge pull request #1 from Sub-Dev/feat/visual-token-grid

feat: adds support for configuration files and improvements to the To…

Author: Sub-Dev

.gitignore

@@ -65,6 +65,13 @@ dist/
 build/
 *.zip
 
+# Source maps (if generated)
+*.map
+
+# Development files
+.vscode/settings.json
+*.local.js
+
 # Temporary files
 *.tmp
 *.temp 

README.md

@@ -4,106 +4,178 @@
 ![Version](https://img.shields.io/badge/Version-1.0.0-blue)
 ![License](https://img.shields.io/badge/License-MIT-green)
 
-## 📋 Descrição
+> 🇧🇷 **Portuguese speakers**: Check out [README.pt-BR.md](README.pt-BR.md) for the Portuguese version.
 
-**Token Stack Selector** é um módulo moderno para Foundry VTT que soluciona o problema de tokens empilhados (sobrepostos). Quando múltiplos tokens ocupam a mesma posição no grid, este módulo adiciona uma interface elegante e intuitiva para selecionar facilmente o token desejado.
+## 📋 Description
 
-## ✨ Características
+**Token Stack Selector** is a modern module for Foundry VTT that solves the problem of stacked (overlapping) tokens. When multiple tokens occupy the same position on the grid, this module adds an elegant and intuitive interface to easily select the desired token.
 
-### 🎯 **Interface Moderna**
+## ✨ Features
 
-- **Design Premium**: Interface similar ao painel de condições nativo do Foundry
-- **Ícone Único**: Combinação visual de grupo de usuários + mira para identificação rápida
-- **Animações Suaves**: Transições elegantes e feedback visual
-- **Contador Visual**: Badge mostrando quantos tokens estão empilhados
+### 🎯 **Modern Interface**
 
-### 🖱️ **Funcionalidades Avançadas**
+- **Premium Design**: Interface similar to Foundry's native condition panel
+- **Unique Icon**: Visual combination of user group + crosshairs for quick identification
+- **Smooth Animations**: Elegant transitions and visual feedback
+- **Visual Counter**: Badge showing how many tokens are stacked
 
-- **Seleção Inteligente**: Token selecionado automaticamente vem para frente
-- **Informações Detalhadas**: Mostra nome, tipo de ator e HP quando disponível
-- **Posicionamento Inteligente**: Painel se ajusta automaticamente para não sair da tela
-- **Múltiplas Formas de Fechar**: Clique fora, ESC ou seleção automática
+### 🖱️ **Advanced Features**
 
-### 🔧 **Experiência do Usuário**
+- **Hover Preview**: Shows stacked tokens when hovering over them (800ms delay)
+- **Smart Selection**: Selected token automatically comes to front
+- **Detailed Information**: Shows name, actor type and HP when available
+- **Smart Positioning**: Panel automatically adjusts to not go off screen
+- **Multiple Ways to Close**: Click outside, ESC or automatic selection
 
-- **Drag & Drop Correto**: Token selecionado pode ser movido imediatamente
-- **Feedback Visual**: Notificações confirmando ações
-- **Restauração Automática**: Z-index volta ao normal após desseleção
-- **Scrollbar Customizada**: Design consistente com o tema do Foundry
+### 🔧 **User Experience**
 
-## 🚀 Instalação
+- **Correct Drag & Drop**: Selected token can be moved immediately
+- **Visual Feedback**: Notifications confirming actions
+- **Automatic Restoration**: Z-index returns to normal after deselection
+- **Custom Scrollbar**: Design consistent with Foundry theme
 
-### Método 1: Instalação Automática
+## 🚀 Installation
 
-1. Abra o Foundry VTT
-2. Vá para **Setup** → **Add-on Modules**
-3. Clique em **Install Module**
-4. Cole este manifesto: `https://github.com/Sub-Dev/token-stack-selector/releases/latest/download/module.json`
-5. Clique em **Install**
+### Method 1: Automatic Installation
 
-### Método 2: Instalação Manual
+1. Open Foundry VTT
+2. Go to **Setup** → **Add-on Modules**
+3. Click **Install Module**
+4. Paste this manifest: `https://github.com/Sub-Dev/token-stack-selector/releases/latest/download/module.json`
+5. Click **Install**
 
-1. Baixe o arquivo ZIP da [última release](https://github.com/Sub-Dev/token-stack-selector/releases/latest)
-2. Extraia na pasta `Data/modules/` do seu Foundry VTT
-3. Reinicie o Foundry VTT
-4. Ative o módulo no mundo desejado
+### Method 2: Manual Installation
 
-## 🎮 Como Usar
+1. Download the ZIP file from the [latest release](https://github.com/Sub-Dev/token-stack-selector/releases/latest)
+2. Extract to your Foundry VTT `Data/modules/` folder
+3. Restart Foundry VTT
+4. Enable the module in the desired world
 
-1. **Tokens Empilhados**: Quando dois ou mais tokens ocupam a mesma posição, o botão aparece automaticamente no Token HUD
-2. **Abrir Seletor**: Clique no botão com ícone de mira + grupo de usuários
-3. **Escolher Token**: Clique no token desejado no painel que aparece
-4. **Interagir**: O token selecionado automaticamente vem para frente e pode ser movido normalmente
+## 🎮 How to Use
+
+1. **Hover Preview**: Simply hover your mouse over stacked tokens to see a preview of all tokens (appears after 800ms)
+2. **Stacked Tokens**: When two or more tokens occupy the same position, the button automatically appears in the Token HUD
+3. **Open Selector**: Click the button with crosshairs + user group icon
+4. **Choose Token**: Click the desired token in the panel that appears
+5. **Interact**: The selected token automatically comes to front and can be moved normally
 
 ## 🖼️ Screenshots
 
-_// Adicione aqui screenshots do módulo em ação_
+### 🎬 **Demo in Action**
+
+![Token Stack Selector Demo](https://github.com/Sub-Dev/token-stack-selector/raw/main/screenshots/demo.gif)
+
+_Complete workflow: hover preview → HUD button → selection panel → token selection_
+
+---
+
+### 🖱️ **Hover Preview**
+
+![Hover Preview](https://github.com/Sub-Dev/token-stack-selector/raw/main/screenshots/hover-preview.png)
+
+_Modern preview showing stacked tokens when hovering (800ms delay)_
+
+---
+
+### 🎯 **Selection Panel**
+
+![Selection Panel](https://github.com/Sub-Dev/token-stack-selector/raw/main/screenshots/selection-panel.png)
+
+_Elegant selection interface with token details and smart positioning_
+
+---
+
+### 📚 **Stacked Tokens**
+
+![Stacked Tokens](https://github.com/Sub-Dev/token-stack-selector/raw/main/screenshots/stacked-tokens.png)
+
+_HUD button automatically appears when multiple tokens occupy the same position_
 
-## 🔧 Compatibilidade
+## 🔧 Compatibility
 
-- **Foundry VTT**: v11 - v12
-- **Sistemas**: Compatível com todos os sistemas
-- **Módulos**: Não há conflitos conhecidos
+- **Foundry VTT**: v11 - v13
+- **Systems**: Compatible with all systems
+- **Modules**: No known conflicts
 
-## 📝 Notas de Versão
+## 📝 Release Notes
 
 ### v1.0.0
 
-- ✅ Interface moderna com design premium
-- ✅ Seleção inteligente de tokens empilhados
-- ✅ Sistema de z-index automático
-- ✅ Animações e feedback visual
-- ✅ Suporte a múltiplas formas de interação
+- ✅ Modern interface with premium design
+- ✅ Smart selection of stacked tokens
+- ✅ Automatic z-index system
+- ✅ Animations and visual feedback
+- ✅ Support for multiple interaction methods
+
+## 🏗️ Module Architecture
+
+This module uses a **modular architecture** for better maintainability and scalability:
+
+```
+src/
+├── components/           # UI components
+│   ├── token-hooks-manager.js
+│   ├── token-selection-panel.js
+│   └── token-stack-button.js
+├── utils/               # Utilities and helpers
+│   ├── token-detector.js
+│   └── token-layer-manager.js
+├── styles/              # CSS styles
+│   └── token-stack-styles.js
+└── token-stack-selector.js  # Main orchestrator
+```
+
+### Debug Commands
+
+Open browser console and use:
+
+```javascript
+TokenStackSelector.debug(); // Debug information
+TokenStackSelector.getStats(); // Module statistics
+TokenStackSelector.reload(); // Reload module
+TokenStackSelector.shutdown(); // Shutdown module
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the project
+2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 
-## 🤝 Contribuindo
+### 📸 Contributing Screenshots
 
-Contribuições são bem-vindas! Por favor:
+Help improve the documentation by adding screenshots:
 
-1. Faça um Fork do projeto
-2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
-3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
-4. Push para a branch (`git push origin feature/AmazingFeature`)
-5. Abra um Pull Request
+1. Check [screenshots/README.md](screenshots/README.md) for needed images
+2. Take high-quality screenshots showing the module in action
+3. Follow the naming conventions specified
+4. Submit via Pull Request with descriptive commit messages
 
-## 🐛 Reportar Bugs
+## 🐛 Bug Reports
 
-Encontrou um problema? [Abra uma issue](https://github.com/Sub-Dev/token-stack-selector/issues) com:
+Found a problem? [Open an issue](https://github.com/Sub-Dev/token-stack-selector/issues) with:
 
-- Versão do Foundry VTT
-- Versão do módulo
-- Passos para reproduzir o bug
-- Screenshots (se aplicável)
+- Foundry VTT version
+- Module version
+- Steps to reproduce the bug
+- Screenshots (if applicable)
 
-## 📄 Licença
+## 📄 License
 
-Distribuído sob a Licença MIT. Veja `LICENSE` para mais informações.
+Distributed under the MIT License. See `LICENSE` for more information.
 
-## 🙏 Agradecimentos
+## 🙏 Acknowledgments
 
-- Comunidade Foundry VTT Brasil
-- Desenvolvedores do Foundry VTT
-- Todos os usuários que testaram e forneceram feedback
+- Foundry VTT Brazil Community
+- Foundry VTT Developers
+- All users who tested and provided feedback
 
 ---
 
-**Desenvolvido com ❤️ para a comunidade Foundry VTT**
+**Developed with ❤️ for the Foundry VTT community**