vacuum-card 2.11.7 → 2.12.0

package/.github/release-drafter.yml

@@ -0,0 +1,58 @@
+name-template: v$RESOLVED_VERSION 🧹
+tag-template: v$RESOLVED_VERSION
+exclude-contributors:
+  - github-actions[bot]
+  - github-actions
+  - dependabot[bot]
+  - dependabot
+categories:
+  - title: ❗️ Breaking Changes
+    labels:
+      - breaking
+  - title: 🚀 Features
+    labels:
+      - feature
+      - enhancement
+  - title: 🐛 Bug Fixes
+    labels:
+      - fix
+      - bug
+  - title: 🧰 Maintenance
+    labels:
+      - chore
+      - dependencies
+      - documentation
+change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
+change-title-escapes: '\\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
+version-resolver:
+  major:
+    labels:
+      - major
+      - breaking
+  minor:
+    labels:
+      - minor
+      - feature
+      - enhancement
+  patch:
+    labels:
+      - patch
+      - dependencies
+  default: patch
+template: |
+  ## What's Changed
+
+  $CHANGES
+
+  ## ⭐️ Contributors
+
+  $CONTRIBUTORS
+
+  ## Sponsorship
+
+  If you like this project, please consider supporting me:
+
+  - 💖 [Sponsor on GitHub](https://github.com/sponsors/denysdovhan)
+  - ☕️ [Buy Me A Coffee](https://buymeacoffee.com/denysdovhan)
+  - Bitcoin: `bc1q7lfx6de8jrqt8mcds974l6nrsguhd6u30c6sg8`
+  - Ethereum: `0x6aF39C917359897ae6969Ad682C14110afe1a0a1`

package/.github/workflows/deps.yml

@@ -0,0 +1,26 @@
+name: Dependencies
+on:
+  pull_request:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependabot-auto-merge:
+    name: Dependabot Auto-merge
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    steps:
+      - name: 💿 Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: ↔️ Merge Dependabot PRs
+        if: steps.metadata.outputs.update-type == 'version-update:semver-minor' || steps.metadata.outputs.update-type == 'version-update:semver-patch'
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/main.yml

@@ -4,7 +4,6 @@ on:
   pull_request:
 
 permissions:
-  id-token: write # Required for OIDC
   contents: write
   pull-requests: write
 
@@ -31,49 +30,3 @@ jobs:
 
       - name: 🧪 Test
         run: npm test
-
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    needs: [validate]
-    if: github.ref_name == 'main' && (github.event_name == 'push' || github.event.pull_request.merged)
-    steps:
-      - name: ⬇️ Checkout Repo
-        uses: actions/checkout@v6
-
-      - name: ⬢ Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          registry-url: https://registry.npmjs.org
-          node-version: latest
-          cache: npm
-
-      - name: 📦 Install Packages
-        run: npm ci
-
-      - name: 🏗 Build
-        run: npm run build
-
-      - name: 🚀 Release
-        run: npx semantic-release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  dependabot:
-    name: Dependabot Auto-merge
-    runs-on: ubuntu-latest
-    needs: [validate]
-    if: github.actor == 'dependabot[bot]' && github.event_name == 'pull_request'
-    steps:
-      - name: 💿 Dependabot metadata
-        id: metadata
-        uses: dependabot/fetch-metadata@v2
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: ↔️ Enable Auto-merge for minor and patch Dependabot PRs
-        run: gh pr merge --auto --squash "$PR_URL"
-        if: steps.metadata.outputs.update-type == 'version-update:semver-minor' || steps.metadata.outputs.update-type == 'version-update:semver-patch'
-        env:
-          PR_URL: ${{ github.event.pull_request.html_url }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/release-drafter.yml

@@ -0,0 +1,20 @@
+name: Release Drafter
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update_release_draft:
+    name: Update Release Draft
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📝 Update draft
+        uses: release-drafter/release-drafter@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⬇️ Checkout Repo
+        uses: actions/checkout@v6
+
+      - name: ⬢ Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          registry-url: https://registry.npmjs.org
+          node-version: latest
+          cache: npm
+
+      - name: 📦 Install Packages
+        run: npm ci
+
+      - name: 🧮 Set version from tag
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          npm version --no-git-tag-version "${TAG#v}"
+
+      - name: 🏗 Build
+        run: npm run build
+
+      - name: 🚀 Publish to npm
+        run: npm publish --provenance --access public
+
+      - name: 📦 Upload release asset
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/vacuum-card.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/AGENTS.md

@@ -1,5 +1,10 @@
 # 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`).
@@ -25,6 +30,23 @@
 - 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.

package/CONTRIBUTING.md

@@ -34,3 +34,10 @@ Only native speaker can translate to specific language.
 5. Add `http://localhost:5000/vacuum-card.js` to your Lovelace resources.
 
 Now you can make changes to files in `src` folder. Development server will automatically rebuild on changes. Lovelace will load resource from development server. Refresh the browser to see changes. Make sure cache is cleared or disabled.
+
+## Release process
+
+1. Merge PRs into `main`. Release Drafter updates the draft release on each `main` push.
+2. Edit the draft release notes if needed.
+3. Publish the release with a tag like `vX.Y.Z`.
+4. Publishing triggers the release workflow to build the project, publish to npm, and upload `dist/vacuum-card.js` to the GitHub release.

package/README.md

@@ -34,7 +34,6 @@ Just search for `Vacuum Card` in plugins tab.
 1. Download `vacuum-card.js` file from the [latest-release].
 2. Put `vacuum-card.js` file into your `config/www` folder.
 3. Add reference to `vacuum-card.js` in Lovelace. There's two way to do that:
-
    1. **Using UI:** _Configuration_ → _Lovelace Dashboards_ → _Resources Tab_ → Click Plus button → Set _Url_ as `/local/vacuum-card.js` → Set _Resource type_ as `JavaScript Module`.
       **Note:** If you do not see the Resources Tab, you will need to enable _Advanced Mode_ in your _User Profile_
    2. **Using YAML:** Add following code to `lovelace` section.
@@ -107,20 +106,21 @@ shortcuts:
 
 Here is what every option means:
 
-| Name           |   Type    | Default      | Description                                                                                               |
-| -------------- | :-------: | ------------ | --------------------------------------------------------------------------------------------------------- |
-| `type`         | `string`  | **Required** | `custom:vacuum-card`                                                                                      |
-| `entity`       | `string`  | **Required** | An entity_id within the `vacuum` domain.                                                                  |
-| `map`          | `string`  | Optional     | An entity_id within the `camera` domain, for streaming live vacuum map.                                   |
-| `map_refresh`  | `integer` | `5`          | Update interval for map camera in seconds                                                                 |
-| `image`        | `string`  | `default`    | Path to image of your vacuum cleaner. Better to have `png` or `svg`.                                      |
-| `show_name`    | `boolean` | `true`       | Show friendly name of the vacuum.                                                                         |
-| `show_status`  | `boolean` | `true`       | Show status of the vacuum.                                                                                |
-| `show_toolbar` | `boolean` | `true`       | Show toolbar with actions.                                                                                |
-| `compact_view` | `boolean` | `false`      | Compact view without image.                                                                               |
-| `stats`        | `object`  | Optional     | Custom per state stats for your vacuum cleaner                                                            |
-| `actions`      | `object`  | Optional     | Override default actions behavior with service invocations.                                               |
-| `shortcuts`    |  `array`  | Optional     | List of shortcuts shown at the right bottom part of the card with custom actions for your vacuum cleaner. |
+| Name             |   Type    | Default      | Description                                                                                               |
+| ---------------- | :-------: | ------------ | --------------------------------------------------------------------------------------------------------- |
+| `type`           | `string`  | **Required** | `custom:vacuum-card`                                                                                      |
+| `entity`         | `string`  | **Required** | An entity_id within the `vacuum` domain.                                                                  |
+| `battery_entity` | `string`  | Optional     | An entity_id within the `sensor` domain to display battery state and icon.                                |
+| `map`            | `string`  | Optional     | An entity_id within the `camera` domain, for streaming live vacuum map.                                   |
+| `map_refresh`    | `integer` | `5`          | Update interval for map camera in seconds                                                                 |
+| `image`          | `string`  | `default`    | Path to image of your vacuum cleaner. Better to have `png` or `svg`.                                      |
+| `show_name`      | `boolean` | `true`       | Show friendly name of the vacuum.                                                                         |
+| `show_status`    | `boolean` | `true`       | Show status of the vacuum.                                                                                |
+| `show_toolbar`   | `boolean` | `true`       | Show toolbar with actions.                                                                                |
+| `compact_view`   | `boolean` | `false`      | Compact view without image.                                                                               |
+| `stats`          | `object`  | Optional     | Custom per state stats for your vacuum cleaner                                                            |
+| `actions`        | `object`  | Optional     | Override default actions behavior with service invocations.                                               |
+| `shortcuts`      |  `array`  | Optional     | List of shortcuts shown at the right bottom part of the card with custom actions for your vacuum cleaner. |
 
 ### `stats` object
 
@@ -138,38 +138,38 @@ You can use any attribute of vacuum or even any entity by `entity_id` to display
 
 You can defined service invocations to override default actions behavior. Available actions to override are `start`, `pause`, `resume`, `stop`, `locate` and `return_to_base`.
 
-| Name           |   Type   | Default                           | Description                                     |
-| -------------- | :------: | --------------------------------- | ----------------------------------------------- |
-| `service`      | `string` | Optional                          | A service to call, i.e. `script.clean_bedroom`. |
-| `service_data` | `object` | `service_data` for `service` call |
+| Name           |   Type   | Default  | Description                                     |
+| -------------- | :------: | -------- | ----------------------------------------------- |
+| `service`      | `string` | Optional | A service to call, i.e. `script.clean_bedroom`. |
+| `service_data` | `object` | Optional | `service_data` for `service` call               |
 
 ### `shortcuts` object
 
 You can defined [custom scripts][ha-scripts] for custom actions i.e cleaning specific room and add them to this card with `shortcuts` option.
 
-| Name           |   Type   | Default                           | Description                                                             |
-| -------------- | :------: | --------------------------------- | ----------------------------------------------------------------------- |
-| `name`         | `string` | Optional                          | Friendly name of the action, i.e. `Clean bedroom`.                      |
-| `service`      | `string` | Optional                          | A service to call, i.e. `script.clean_bedroom`.                         |
-| `target`       | `object` | Optional                          | A `HassServiceTarget`, to define a target for the current service call. |
-| `icon`         | `string` | Optional                          | Any icon for action button.                                             |
-| `service_data` | `object` | `service_data` for `service` call |
+| Name           |   Type   | Default  | Description                                                             |
+| -------------- | :------: | -------- | ----------------------------------------------------------------------- |
+| `name`         | `string` | Optional | Friendly name of the action, i.e. `Clean bedroom`.                      |
+| `service`      | `string` | Optional | A service to call, i.e. `script.clean_bedroom`.                         |
+| `target`       | `object` | Optional | A `HassServiceTarget`, to define a target for the current service call. |
+| `icon`         | `string` | Optional | Any icon for action button.                                             |
+| `service_data` | `object` | Optional | `service_data` for `service` call                                       |
 
 ## Theming
 
 This card can be styled by changing the values of these CSS properties (globally or per-card via [`card-mod`][card-mod]):
 
-| Variable                    | Default value                                         | Description                          |
-| --------------------------- | ----------------------------------------------------- | ------------------------------------ |
-| `--vc-background`           | `transparent`                                         | Background of the card               |
-| `--vc-primary-text-color`   | `var(--primary-text-color)`                           | Vacuum name, stats values, etc       |
-| `--vc-secondary-text-color` | `var(--secondary-text-color)`                         | Status, stats units and titles, etc  |
-| `--vc-icon-color`           | `var(--secondary-text-color)`                         | Colors of icons                      |
-| `--vc-toolbar-background`   | `var(--vc-background)`                                | Background of the toolbar            |
-| `--vc-toolbar-text-color`   | `var(--secondary-text-color)`                         | Color of the toolbar texts           |
-| `--vc-toolbar-icon-color`   | `var(--secondary-text-color)`                         | Color of the toolbar icons           |
-| `--vc-divider-color`        | `var(--entities-divider-color, var(--divider-color))` | Color of dividers                    |
-| `--vc-spacing`              | `10px`                                                | Paddings and margins inside the card |
+| Variable                    | Default value                                                          | Description                                         |
+| --------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------- |
+| `--vc-background`           | `var(--ha-card-background, var(--card-background-color, transparent))` | Card background.                                    |
+| `--vc-primary-text-color`   | `var(--primary-text-color)`                                            | Vacuum name, stats values, etc.                     |
+| `--vc-secondary-text-color` | `var(--secondary-text-color)`                                          | Status, stats units and titles, etc.                |
+| `--vc-icon-color`           | `var(--secondary-text-color)`                                          | Colors of icons.                                    |
+| `--vc-toolbar-background`   | `transparent`                                                          | Toolbar background (transparent to avoid stacking). |
+| `--vc-toolbar-text-color`   | `var(--secondary-text-color)`                                          | Color of the toolbar texts.                         |
+| `--vc-toolbar-icon-color`   | `var(--secondary-text-color)`                                          | Color of the toolbar icons.                         |
+| `--vc-divider-color`        | `var(--entities-divider-color, var(--divider-color))`                  | Color of dividers.                                  |
+| `--vc-spacing`              | `10px`                                                                 | Paddings and margins inside the card.               |
 
 ### Styling via theme