# 🤝 Contribution

Contributions of any kind are warmly welcomed! Whether you're reporting bugs, requesting features, improving documentation, or submitting code, your input helps make the Expander Card better for everyone.

## Feature Requests

Have an idea for a new feature or enhancement? We'd love to hear about it!

To submit a feature request:

1. Check if a similar request already exists in [existing issues](https://github.com/MelleD/lovelace-expander-card/issues)
2. If not, create a new feature request using our template
3. Describe the feature, its use case, and why it would be valuable

[Submit a Feature Request](https://github.com/MelleD/lovelace-expander-card/issues/new?template=feature_request.md)

**Template includes:**

- Feature description
- Use case scenarios
- Proposed implementation (optional)
- Alternative solutions considered

## Bug Reports

Found something that's not working as expected? Please let us know!

When reporting a bug:

1. Search [existing issues](https://github.com/MelleD/lovelace-expander-card/issues) to avoid duplicates
2. Use our bug report template for consistency
3. Include reproduction steps, expected vs actual behavior
4. Add relevant configuration YAML and screenshots if possible
5. Mention your Home Assistant version and browser

[Report a Bug](https://github.com/MelleD/lovelace-expander-card/issues/new?template=bug_report.md)

**What to include:**

- Clear description of the issue
- Steps to reproduce
- Expected behavior vs actual behavior
- YAML configuration (sanitized)
- Screenshots or videos (if applicable)
- Environment details (HA version, browser, etc.)

## Discussions

Want to share ideas, ask questions, or connect with the community? Join our discussions!

Discussion categories:

- **General**: Questions and general discussions
- **Ideas**: Brainstorm new features and improvements
- **Show and Tell**: Share your creative expander card configurations
- **Q&A**: Get help from the community

[Join the Discussion](https://github.com/MelleD/lovelace-expander-card/discussions)

**Perfect for:**

- Asking "how do I..." questions
- Sharing your custom configurations
- Discussing potential features before opening an issue
- Getting feedback on your setup
- Helping other users

## Pull Requests

The ultimate contribution! We appreciate code contributions, documentation improvements, and bug fixes.

### How to Submit a Pull Request

1. **Fork the repository**

   ```bash
   # Fork via GitHub UI, then clone your fork
   git clone https://github.com/YOUR_USERNAME/lovelace-expander-card.git
   cd lovelace-expander-card
   ```

2. **Create a feature branch**

   ```bash
   git checkout -b feature/AmazingFeature
   # or
   git checkout -b fix/BugFix
   ```

3. **Make your changes**
   - Write clear, commented code
   - Follow the existing code style
   - Test your changes thoroughly
   - Update documentation if needed

4. **Commit your changes**

   ```bash
   git add .
   git commit -m 'Add some AmazingFeature'
   ```

   Use clear, descriptive commit messages

5. **Push to your fork**

   ```bash
   git push origin feature/AmazingFeature
   ```

6. **Open a Pull Request**
   - Go to the [original repository](https://github.com/MelleD/lovelace-expander-card)
   - Click "New Pull Request"
   - Select your fork and branch
   - Provide a clear description of your changes
   - Link any related issues

### Pull Request Guidelines

- **One feature per PR**: Keep pull requests focused on a single feature or fix
- **Test thoroughly**: Ensure your changes work in different scenarios
- **Update docs**: If you add features, update the documentation
- **Code style**: Match the existing code formatting and style
- **Commit messages**: Use clear, descriptive messages
- **Be patient**: Maintainers will review your PR as soon as possible

### Local Development Setup

#### Build & Install

```bash
# Install dependencies
npm install
# or
pnpm install

# Start development server
npm run srv

# Build for production
npm run build

# Run es linting
npm run lint

# Fix es linting
npm run lint-fix
```

#### Visual Tests

One-time setup — **VS Code**: open the *Terminal › Run Task* palette and choose *Python: Set up virtual environment*.

One-time setup — **Command line**:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[test]'
playwright install chromium
```

**VS Code** — open the *Terminal › Run Task* palette and choose any `pytest:` task (run all, run single scenario, update snapshots, etc.).

**Command line** — activate the virtual environment first, then:

| Goal | Command |
|---|---|
| All tests | `pytest tests/` |
| All tests — update snapshots & doc images | `SNAPSHOT_UPDATE=1 DOC_IMAGE_UPDATE=1 pytest tests/` |
| Scenario tests only | `pytest tests/visual/test_scenarios.py` |
| Update scenario snapshots | `SNAPSHOT_UPDATE=1 pytest tests/visual/test_scenarios.py` |
| Single scenario | `pytest tests/visual/test_scenarios.py -k expander_collapsed` |
| Single scenario — update snapshot | `SNAPSHOT_UPDATE=1 pytest tests/visual/test_scenarios.py -k expander_collapsed` |
| Doc images — generate / verify | `pytest tests/visual/test_doc_images.py` |
| Doc images — update all | `DOC_IMAGE_UPDATE=1 pytest tests/visual/test_doc_images.py` |
| Doc image audit (no HA needed) | `pytest tests/test_doc_audit.py` |

> **Tip:** Start the persistent HA server (`python -m ha_testcontainer.ha_server` or the *HA: Start persistent server* VS Code task) before running tests to skip the Docker boot wait on every run.

> **Tip (debugging):** When the persistent server is running, its URL is logged in the terminal. You can open that URL in a browser and log in with the ha-testcontainer default credentials — username `testadmin`, password `testpassword123` — to inspect the HA instance manually. **Do not browse to the instance before running tests**; doing so may interfere with the test session. If you have already browsed to it, stop the server and start it again before running tests.

#### Docs

Go to docs folder and install [zensical](https://zensical.org/docs/get-started/)

```bash
# cd docs
cd docs

# Install zensical https://zensical.org/docs/get-started/
...

# build docs
zensical build --clean

# start server to see updates in realtime
zensical serve
```

Open browser on [http://localhost:8000](http://localhost:8000)

## Other Ways to Contribute

- **Documentation**: Help improve or translate documentation
- **Examples**: Share your expander card configurations in discussions
- **Support**: Help answer questions from other users
- **Testing**: Test beta releases and provide feedback
- **Spread the word**: Star the repo and tell others about it

## Code of Conduct

Be respectful, constructive, and welcoming. We're all here to make the Expander Card better together.

## Questions?

Not sure where to start? Feel free to:

- Open a [discussion](https://github.com/MelleD/lovelace-expander-card/discussions)
- Comment on existing issues
- Check the [documentation](https://github.com/MelleD/lovelace-expander-card/blob/main/README.md)

Thank you for contributing! 🎉
