vacuum-card/AGENTS.md

Vacuum cleaner card for Home Assistant Lovelace UI

# Repository Guidelines

## Instructions

- Always refer to `home-assistant-js-websocket` library for types and functions to interact with the Home Assistant API.
- When interaction with Home Assistant API is needed, use `custom-card-helpers` library for helper utilities for the card lifecycle and events.

## Project Structure & Module Organization

- `src/`: TypeScript source for the custom Lovelace card (entry: `src/vacuum-card.ts`).
- `dist/`: Build output (bundled card JS). This is generated by Rollup.
- `rollup.config.mjs`: Build pipeline and asset handling.
- `eslint.config.mjs`: Lint configuration.
- `package.json`: Scripts, dependencies, and release config.

## Build, Test, and Development Commands

- `npm install`: Install dependencies.
- `npm run start`: Watch mode build (Rollup) for local development.
- `npm run build`: Production bundle to `dist/`.
- `npm run lint`: Run ESLint on `src/`.
- `npm run lint:fix`: Auto-fix lint issues in `src/`.
- `npm run format`: Format with Prettier (respects `.prettier` settings in `package.json`).
- `npm test`: Runs `lint` then `build` (no separate test suite).

## Coding Style & Naming Conventions

- Language: TypeScript, ES modules (`"type": "module"`).
- Formatting: Prettier with single quotes (`"singleQuote": true`).
- Linting: ESLint (see `eslint.config.mjs`) using `@typescript-eslint` and `eslint-plugin-import`.
- Match existing patterns in `src/` for file naming and exports; prefer descriptive, kebab-case filenames for components.

## Technologies Used

- UI is a Home Assistant Lovelace custom card implemented as a Web Component with Lit (`LitElement`, decorators, `html` templates).
- Home Assistant integrations use `custom-card-helpers` for card lifecycle/events and `home-assistant-js-websocket` types for entities/services.
- Template rendering uses `ha-template` for dynamic text in the card.
- Localization is handled via JSON translation files in `src/translations/` and the `localize` helper.
- Build tooling is Rollup with TypeScript (`rollup-plugin-typescript2`), Babel transforms, and asset handling for JSON, images, CSS, and SVG.
- Styling uses PostCSS (`postcss-preset-env`) and `rollup-plugin-postcss-lit` to process component CSS.
- Production optimizations include HTML literal minification and Terser.
- Utility helpers include Lodash (`get`).
- Developer tooling includes ESLint, Prettier, Husky, and lint-staged.

## Documentations

- This card uses the [custom-card-helpers](https://custom-cards.github.io/custom-card-helpers/modules.html) library with helper utilities for the card lifecycle and events. Always refer to the documentation for useful functions and utilities.
- Use the [home-assistant-js-websocket](https://www.npmjs.com/package/home-assistant-js-websocket) library for types and functions to interact with the Home Assistant API.

## Testing Guidelines

- No dedicated test framework is configured.
- Use `npm test` to validate linting and the production build.
- Keep changes buildable; avoid introducing new build-time warnings.

## Commit & Pull Request Guidelines

- Commit messages follow Conventional Commits (Angular preset), e.g. `feat: ...`, `fix: ...`, `chore(deps): ...`.
- Dependency updates should use `chore(deps): ...` to align with release rules.
- PRs should include: a concise description, what changed, and how it was validated (commands run). If UI changes are visible, include a screenshot or GIF.

## Release & Automation Notes

- Releases are handled by semantic-release on `main` with assets from `dist/vacuum-card.js`.
- Ensure build output remains stable when changing dependencies or build config.