How maetzi87/lovelace-mushroom-50px works
1. What this repo is
- Mushroom is a Home Assistant Lovelace custom card library packaged as a single browser-side JavaScript module.
- It is not a backend service; it runs inside the Home Assistant frontend and plugs into the dashboard editor/runtime.
2. Top-level packaging boundary
- The deliverable is the compiled asset in dist/mushroomic.js.
- Source is TypeScript under src/, bundled via Rollup and validated/released by GitHub Actions.
- hacs.json and the README installation flow show that distribution is centered on HACS and manual local resource loading.
3. Core product shape: cards and badges
- The main features are Lovelace cards in src/cards/ and a Lovelace badge in src/badges/.
- Each feature follows the same split: a runtime component, an editor component, and a config type.
- This makes the repo an extensible UI component system rather than a single monolithic dashboard widget.
4. Card subsystem
- src/cards/* contains the user-facing UI blocks, with domain-oriented cards for entities like alarm control panel, climate, cover, light, lock, media player, update, vacuum, etc.
- There is also a more generic template family and an empty/title/chips style of structural cards.
- The card layer is where entity state is turned into visual controls and actions.
5. Badge subsystem
- src/badges/template/* provides the badge implementation.
- The README notes this badge is intended for newer Home Assistant versions, so the badge boundary is version-sensitive and tied to the Lovelace badge API.
6. Home Assistant adapter layer
- src/ha/ is the main integration boundary with Home Assistant frontend internals.
- It contains wrappers for entity metadata/state, domain-specific data, translations, themes, main window access, and Lovelace panel utilities.
- This layer isolates Mushroom from direct coupling to raw Home Assistant APIs and centralizes compatibility logic.
7. How data flows through the system
- Home Assistant provides entity state, registries, translations, themes, and Lovelace config.
- Mushroom’s HA layer computes derived values such as display names, domain/object IDs, color/state representations, and feature support.
- Those computed values flow into card and badge renderers, which then emit user interactions back to Lovelace/HA services.
8. Editor and form pipeline
- src/utils/lovelace/ and src/ha/panels/lovelace/ hold the editor plumbing for configuring cards from the UI.
- src/utils/form/ and shared config models define reusable form fields, selectors, and config schemas.
- The architecture is strongly editor-driven: the same component family supports both rendering and configuration.
9. Shared visual primitives
- src/shared/ contains reusable building blocks such as buttons, chips, sliders, state labels, badge icons, avatars, and config fragments.
- These are the design system layer used across many cards to keep styling and behavior consistent.
- This reduces duplication and keeps entity cards visually uniform.
10. Cross-cutting utilities
- src/utils/ handles the non-domain infrastructure: appearance, colors, layout, caching, loading, theming, keyframes, icons, weather helpers, and custom element registration helpers.
- It also includes generic Lovelace helpers and error handling around sub-editors and GUI support.
- These utilities sit underneath both the card runtime and the editor runtime.
11. Localization and theming
- src/translations/ plus src/localize.ts provide internationalization across many languages.
- src/utils/theme.ts, src/utils/colors.ts, and related helpers define the theme-aware styling model, with explicit support for light/dark modes and Material-style colors.
- The README’s theme notes and the file layout show theming is a first-class architectural concern, not an afterthought.
12. Development and demo environment
- .hass_dev/ is a self-contained Home Assistant demo configuration used to exercise cards, views, and packages during development.
- This repo therefore has a two-part workflow: build the library, then test it inside a real Home Assistant instance.
- That makes the browser/HA integration boundary the main integration test surface.
13. Documentation and release boundary
- docs/cards/* and docs/badges/* document each user-facing component separately, matching the architecture of individual card modules.
- GitHub Actions (build, validate, release) and the HACS metadata support the operational lifecycle: verify, bundle, publish, and distribute.
- The repo is thus structured around a frontend component library + Home Assistant compatibility layer + packaging/release pipeline.
Main entry points: cards Cards · template Badge · mushroomic.ts Entrypoint · shared Primitives
Components 19
Packaging
Build, bundle, distribution, and release boundary.
- Bundle · Compiled browser module distributed to Home Assistant.
dist/mushroomic.js - Rollup · Bundles the TypeScript sources into the distributable asset.
rollup.config.mjs - CI/CD · Build, validate, and release automation.
.github/workflows - HACS · Marketplace metadata for Home Assistant community install flow.
hacs.json
Core UI
Runtime custom card and badge entrypoints.
- Cards · Main Lovelace card family for entity control and display.
src/cards - Badge · Template badge implementation for Lovelace badge API.
src/badges/template - Entrypoint · Top-level Mushroom registration and export surface.
src/mushroomic.ts
Home Assistant
Integration layer for HA frontend APIs, entity data, and Lovelace panel/editor support.
- HA Bridge · Main Home Assistant integration surface and compatibility layer.
src/ha/index.ts - Entity Data · Entity, registry, domain, and support-feature computation.
src/ha/data - Lovelace Panel · Lovelace-specific panel utilities, action handling, and editor plumbing.
src/ha/panels/lovelace - HA Common · Low-level Home Assistant helpers for colors, strings, numbers, DOM, and translations.
src/ha/common
Shared UI
Reusable visual primitives and config fragments.
- Primitives · Reusable buttons, chips, state visuals, icons, and config fragments.
src/shared - Config Models · Shared Lovelace card and badge config types and fragments.
src/shared/config
Utilities
Cross-cutting helpers for styling, forms, Lovelace editing, and generic runtime behavior.
- Appearance · Theme-aware styling, colors, layout, and card/entity presentation helpers.
src/utils - Forms · Reusable HA form and selector helpers for card configuration.
src/utils/form - Lovelace Utils · Generic Lovelace editor and chip-element helpers.
src/utils/lovelace - Localization · Translation loading and localized label resolution.
src/localize.ts
Connections 30
- Rollup → Bundle: builds · Bundles source into the published browser asset.
- Entrypoint → Cards: registers · Wires card modules into the custom element surface.
- Entrypoint → Badge: registers · Exposes the badge implementation for Lovelace usage.
- Entrypoint → HA Bridge: uses · Initializes the Home Assistant integration layer.
- Entrypoint → Primitives: composes · Builds the UI from reusable shared components.
- Entrypoint → Appearance: styles · Applies theming and layout helpers across components.
- Cards → Entity Data: reads · Consumes derived entity state and feature data.
- Cards → Primitives: composes · Uses shared buttons, chips, sliders, and state elements.
- Cards → Config Models: typed by · Uses shared card config models and fragments.
- Badge → Entity Data: reads · Consumes entity state and display metadata.
- Badge → Primitives: composes · Uses the shared badge icon and state display primitives.
- Badge → Config Models: typed by · Uses shared badge config models.
- HA Bridge → HA Common: wraps · Centralizes compatibility helpers around Home Assistant internals.
- HA Bridge → Entity Data: provides · Supplies entity/domain/state derivations to the UI layer.
- HA Bridge → Lovelace Panel: supports · Connects Lovelace editor/runtime utilities to HA panel APIs.
- Entity Data → Localization: localizes · Resolves translated names and state text.
- HA Common → Localization: localizes · Shared translation helpers used across HA-facing code.
- Lovelace Panel → Forms: configures · Feeds configuration forms and selectors for editors.
- Lovelace Panel → Lovelace Utils: orchestrates · Coordinates editor plumbing and custom sub-editors.
- Primitives → Config Models: follows · Implements the shared config-driven UI model.
- Appearance → Primitives: styles · Provides theme-aware visual tokens and layout helpers.
- Forms → Config Models: binds · Maps config models into editable form fields.
- Lovelace Utils → Forms: supports · Provides Lovelace-specific editor helpers and wrappers.
- Docs → Cards: documents · Documents each user-facing card family.
- Docs → Badge: documents · Documents the badge component.
- Demo HA → Cards: exercises · Showcases card behavior in a real Home Assistant instance.
- Demo HA → Badge: exercises · Provides demo coverage for badge behavior.
- CI/CD → Rollup: runs · Build workflow validates the bundle pipeline.
- CI/CD → Bundle: publishes · Release workflow ships the compiled asset.
- HACS → Bundle: references · Points Home Assistant install flows at the distributable module.