Imported from denysdovhan/vacuum-card (AGENTS.md). Install upstream with npx skills add denysdovhan/vacuum-card. Copyright stays with the author.

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