How piotrmachowski/lovelace-xiaomi-vacuum-map-card works
Project type and purpose
• This is a frontend custom card for Home Assistant’s Lovelace UI (“xiaomi-vacuum-map-card”).
• It’s written in TypeScript, built with Rollup, and uses LitElement/web components.
File structure
• Top‐level build/config files:
• rollup.config.js / rollup.config.dev.js
• tsconfig.json
• package.json / package-lock.json
• ESLint / Prettier / .devcontainer / .vscode / GitHub workflows
• Source code under src/:
• xiaomi-vacuum-map-card.ts (entry point module)
• config-validators.ts (parses & validates YAML config)
• action-handler-directive.ts (handles tap/hold events → dispatch custom events)
• localize/ (i18n resources with translation files)
• renderers/ (custom UI renderers like toast)
• polyfills/ (shims for old browsers)
• utils.ts, const.ts, types/
• docs/: extensive Markdown/YAML examples, templates, video demos, migration guides.
Key insights from README
• Purpose: fully‐featured, map‐based vacuum controls (zones, point/goto, room cleaning, follow path).
• Architecture hints: model/generators for presets, service_call_schema, action_handler, UI components, localization.
a. Main components
• Configuration Input (YAML via UI editor or raw Lovelace resources)
• Configuration Validator & Parser (config-validators.ts)
• Model Layer (src/model):
– Map objects (zones, points, room outlines, path)
– Map modes & service-call schema definitions
• Localization (localize/)
• View Layer (src/components + pinch-zoom + renderers):
– Root element (xiaomi-vacuum-map-card) extends LitElement
• Action Handler (action-handler-directive.ts → custom DOM events)
• Home Assistant Integration (calls HA services via custom‐service events)
• Build Pipeline (Rollup → final JS module)
• External dependencies/services: Home Assistant core, HACS, vacuum platform integrations
b. Relationships & interactions
1. User writes or edits YAML config → fed into Configuration Validator
2. Validator outputs a normalized config object → passed to Model Layer
3. Model Layer generates:
– iconList, tileList (based on platform & presets)
– map mode definitions and service_call_schema
– calibration & coordinate conversion modules
4. The entry‐point component (xiaomi-vacuum-map-card) renders:
5. User interacts (click/tap/drag) → Action Handler Directive translates Lit‐events into custom‐DOM events
6. Custom events carry service_call_schema + placeholders → Home Assistant services are invoked
7. Vacuum platform integration handles the actual device API calls
8. Responses/state updates in Home Assistant cause the card to re‐render via Lit’s reactive properties
c. Architectural patterns & principles
• Separation of Concerns:
• Config parsing → Model generation → View rendering → Event handling → Service calls
• MVC‐Like layering: Model (data & behavior), View (LitElement components), Controller (action handler + service dispatcher)
• Plugin/Generator pattern for supporting multiple vacuum platforms via JSON templates + generator wrapper
• Reactive UI using LitElement
• Single‐bundle modularization with Rollup
d. Key technologies/frameworks
• TypeScript for static typing
• Rollup for bundling into a single JS module
• LitElement / web components for UI
• pinch-zoom library for map interactions
• Polyfills for cross-browser support
• Home Assistant’s Lovelace resource API for integration
• JSON templates for vacuum platforms
Essential elements
• Clear component names matching the src/ folder (e.g., config-validators.ts, model/generators, components/tile.ts)
• Build pipeline (Rollup & Polyfills) feeding into the final JS resource