π οΈ Development Guide¶
This document describes the internal architecture of the Entity Progress Card for contributors and maintainers. It complements the user-facing Configuration Reference and Theme Guide, and the setup/PR-facing Contributing Guide.
- Quick start
- Design principles
- Object architecture
- Card lifecycle
- Home Assistant integration
- Rendering & performance
- Browser compatibility matrix
- Jinja template subscriptions
- Configuration validation
- Security
- Editor components: native HA elements vs. our own
- Editor architecture
- Internationalization
- Adding a new option
- Code quality & tooling
- Considered and deferred
- Release process
- Logging & debugging
Quick start¶
git clone https://github.com/francois-le-ko4la/lovelace-entity-progress-card.git
cd lovelace-entity-progress-card
npm install # Node 24 (see .nvmrc / package.json's engines); also
# installs the husky pre-commit hook (format + lint on
# staged files)
npm run build:test # β dist/entity-progress-card_dev.js (readable, not minified)
src/bootstrap.ts is where execution actually settles: it registers the card/
badge/feature custom elements and prints the console banner β everything else in
src/ is reached from there, directly or transitively. src/index.ts calls it;
the seven visual editors ship in a file of their own, src/editor/entry.ts (see
The editor file).
Tests come in two layers, run by two different gates:
npm testβ pure logic (schema validation, math, formatting), intest/card/,test/editor/andtest/utils/, plustest/docs/: the documentation checked against the schema β YAML examples, documented defaults, compatibility badges, option tables, the demo dashboards, anddocs/option-map.mdagainst what its generator renders today. No DOM, nohass.npm run test:domβ mounts every registered custom element and builds every editor against a real DOM (happy-dom), intest/dom/, split by domain likesrc/(card/,editor/,utils/; the whole bundle at its root). It asserts that things mount and build, never what they look like.test/dom-setup.tsinstalls the browser globals - never bind a constructor to the window, it breaks theHTMLElementprototype chain and the elements silently lose.style.test/ha-stubs.tsstands in for what Home Assistant provides (ha-card,ha-svg-icon,action-handler'sbind()) plus amakeHass()whoseconnectionis a realEventTarget.
Neither covers rendering, real entity state, or the WebSocket Jinja round trip.
To see the card render against real entities, point a Lovelace resource at the
dev build and import docs/demo-dashboard-dev.yaml
into a real Home Assistant instance. Full steps (and the PR checklist) are in
the Contributing Guide.
Three gates, each named for when you run it. Each one contains the previous:
| when | adds | |
|---|---|---|
check:code |
while you code | syntax, format, lint, types, i18n structure, logic tests |
check:github |
every push and the release | release flags, knip, full i18n sync, markdown, test:dom, build:prod, language floor on both files |
check:push |
before pushing | check:chrome92, the dev bundle (build:test + node --check) and its split guard |
check:github deliberately never builds the dev bundle - it bakes in
__EPB_DEV_BUILD__: true and has no business on a release runner.
Design principles¶
- Zero runtime dependency. The card ships as one bundled, dependency-free
JavaScript file (built from the
src/module tree byscripts/build.js, see Release process) β no Lit, no external sanitizer, no CDN request at runtime. This constrains some choices and explains the hand-rolled infrastructure described below. - Vanilla web components. Cards are plain
HTMLElementsubclasses with shadow DOM. The reactive-update machinery a framework would provide (batching, diffing, style sharing) is implemented by dedicated helper classes (DOMHelper,ChangeTracker,ObjStructure). - Progressive enhancement. Modern browser APIs (Constructable Stylesheetsβ¦) are used behind feature detection; older engines covered by the README support table fall back to the legacy behavior.
- Fail soft. A malformed config, a missing attribute or an unavailable entity must degrade into a visible error state or a safe default β never into an uncaught exception (Home Assistant would replace the card with a red error card).
Object architecture¶
src/ is organized in layers, bottom-up:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Custom elements (cards / badges / feature / editors) β HA-facing
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Views (ViewCore β ViewBase β CardView, BadgeView, β¦) β per-card state
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Config helpers + validation (BaseConfigHelper, types, schemas) β config layer
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Domain helpers (EntityHelper, ThemeManager, β¦) β business logic
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Infrastructure (DOMHelper, ResourceManager, Logger, is/has, β¦) β utilities
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Source layout¶
src/card/ is split by what a module is. A part split off one class lives under
it.
| Folder | Holds |
|---|---|
elements/ |
The custom elements: card-base, features, template-base, multi. |
core/ |
HACore (core.ts, its parts in core/) and HABase (base.ts, its parts in base/). |
view/ |
The views and what they resolve: progress-math, watermark-view, bound-value, jinja-state, β¦ |
config/ |
schema.ts + schema/, config-helpers.ts + config-helpers/, factorization, multi-rows. |
dom/ |
dom-helpers, structure, marks, alert, badge-icon, status-label, aligned-bars. |
values/ |
Entity and value helpers: entity-helper, device-probes, formatting, ha-state, unit-helper. |
color/ |
Theme and colour: theme-manager, bar-colors (bar colour and gradients from a view), entity-collection, diverging-gradient. |
history/ |
What changes over time: trend-tracker, peak-tracker, change-tracker, sample-ring, history-seeding, peak-marker-view. |
diagnostics/ |
doctor and card-audit (EPB.doctor). |
- A barrel (
schema.ts,config-helpers.ts,dom-helpers.ts) sits next to its folder and re-exports only that folder. - No other barrel: import a module from the file that defines it.
- Layers, bottom-up:
utils,values,config,color,history,view,dom,core,elements; ESLint (import-x/no-restricted-paths) rejects an import from a higher folder, andcard/never importseditor/. test/card/<folder>/mirrorssrc/card/<folder>/.
src/editor/ follows the same rule: elements/ (base, editors, chips,
list-editors/), form/ (field-builder, dom-helper, select-types),
data/ (multi-cascade, issue-report, config-flow), fields/, groups/;
entry.ts and factory.ts stay at the root.
Two files, one copy of each module¶
Those layers ship in two files. The editors are the only part of the top layer that lives apart:
entity-progress-card.js entity-progress-card-editor.js
ββββββββββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββ
β src/index.ts β bootstrap.ts β import() β src/editor/entry.ts β
β cards, badges, features, Multis β βββββββββΆ β 7 editors, 2 row editors, β
β β on first β chips, list editors, β
β shared: parameters, schema, β opening β EditorFactory β
β config-helpers, hass-provider, β β β
β styles, log, register, β¦ β βββββββββ β reads the shared modules β
β β host table (Symbol.for key) β table β back, never bundles them β
ββββββββββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββ
- The bundle owns every piece of state: one
HassProviderSingleton, oneCARD_CONTEXT, one set of shared stylesheets, one schema. The editor file runs on the same objects the cards do. - The seam is computed, not declared:
scripts/build.jsshares whatever card module the editor's own code imports, and fails the build if any module ends up in both files. - Each side keeps its own job: the bundle registers the cards and answers
getConfigElement(); the editor file defines the editors and nothing else. Neither reads the other's source at runtime - only the table.
Mechanism, key and failure modes: The editor file and Loading the editor.
Custom element hierarchy¶
classDiagram
HTMLElement <|-- HACore
HACore <|-- HABase
HACore <|-- EntityProgressFeatures
HABase <|-- EntityProgressCardBase
HABase <|-- EntityProgressTemplateBase
EntityProgressCardBase <|-- EntityProgressCard
EntityProgressCardBase <|-- EntityProgressBadge
EntityProgressTemplateBase <|-- EntityProgressTemplateCard
EntityProgressTemplateBase <|-- EntityProgressTemplateBadge
HACore <|-- EntityProgressMultiBase
EntityProgressMultiBase <|-- EntityProgressMultiCard
EntityProgressMultiBase <|-- EntityProgressMultiFeature
HTMLElement <|-- EditorBase
EditorBase <|-- EntityProgressCardEditor
EditorBase <|-- EntityProgressBadgeEditor
EditorBase <|-- EntityProgressTemplateEditor
EditorBase <|-- EntityProgressBadgeTemplateEditor
EditorBase <|-- EntityProgressFeatureEditor
EditorBase <|-- MultiEditorBase
MultiEditorBase <|-- EntityProgressMultiCardEditor
MultiEditorBase <|-- EntityProgressMultiFeatureEditor
EditorBase <|-- EntityProgressMultiCardRowEditor
EditorBase <|-- EntityProgressMultiFeatureRowEditor
Everything under HACore ships in the bundle; everything under EditorBase in
the editor file.
| Class | Responsibility |
|---|---|
HACore |
Shadow DOM setup, setConfig/set hass contract, render pipeline, resource lifecycle, WebSocket watching, Jinja subscription management. Abstract. |
HABase |
Entity-driven rendering: icon, badge, shape, trend, hidden components, standard text fields, base Jinja handlers. Abstract. |
EntityProgressCardBase |
Full card behavior (auto-refresh for timers, CSS updates, standard fields). |
EntityProgressCard / EntityProgressBadge |
Concrete card/badge: static metadata (_cardStructure, _baseClass), stub config. |
EntityProgressTemplateBase |
Jinja-first variants: every visible field comes from a template subscription. |
EntityProgressFeatures |
Tile feature (progress bar embedded in a native Tile card), including the row-size fix for top/bottom positions. Extends HACore directly (not EntityProgressCardBase) and has its own _updateCSS() β a separate implementation from Card/Badge's shared one, not a missing one. Its view (FeatureView) still extends ViewBase and its HTML still comes from the same StructureElements.progressBar builder as Card/Badge, so anything ViewBase exposes (theme, watermark, bar_stack, center_zero, peak_marker, β¦) works identically here. entity is optional: set context() falls back to the parent Tile's own entity (LovelaceCardFeatureContext.entity_id) when the feature's own config omits one. Has its own visual editor (EntityProgressFeatureEditor, EditorFactory.buildFeature()) - see below. |
Each concrete class carries static metadata consumed by the shared pipeline:
_cardStructure (an ObjStructure instance), _cardStyle (CSS text),
_baseClass (CSS class / type name), _hiddenComponents,
_hasDisabledIconTap, β¦
View hierarchy¶
Views hold the per-card state derived from config + hass. The custom element
delegates every "what should be displayed" question to its view
(this._cardView) and keeps only DOM concerns for itself.
classDiagram
ViewCore <|-- ViewBase
ViewCore <|-- TemplateViewBase
TemplateViewBase <|-- CardTemplateView
TemplateViewBase <|-- BadgeTemplateView
ViewBase <|-- CardView
ViewBase <|-- BadgeView
ViewBase <|-- FeatureView
ViewCoreβ config storage, the card entity (EntityHelper, unbound withoutentity), watermark values, action helpers, trend memory, the Jinja alert trigger. Reached from the element asentityView(ViewBaseornull).ViewBaseβ adds the full entity pipeline:Progress(min/max/center-zero math and value formatting),ThemeManager,EntityCollectionHelper(bar_stack), max-value entity, alert thresholds (bound-value.ts), color resolution, badge info.TemplateViewBase(CardTemplateView,BadgeTemplateView) intentionally skipsViewBase: content comes from Jinja subscriptions, not from entity state computation. It owns the percent theme and the pushed colors.
Each view owns a matching config helper (CardConfigHelper,
BadgeTemplateConfigHelper, β¦) that validates and negotiates the raw YAML β
this is the diagram's "Config helpers + validation" layer; see
Configuration validation for the full detail
(preProcess/postProcess, schema-derived Config type).
Domain helpers¶
| Helper | Role |
|---|---|
HassProviderSingleton |
Single access point to the hass object: entity props, attributes, names/areas/floors, localization, locale-aware formatting. Shared by all cards on the page. |
ChangeTracker |
Per-card filter deciding whether a hass update concerns this card (reference comparison of watched entities' state objects). |
EntityHelper |
Wraps one entity (unbound when the card has none): its value kind (timer, counter, number, duration, default, from HA_CONTEXT.domains then the device class or a time unit), value extraction, validity/availability, default color (resolved once per refresh). |
hasUsableHistory |
The one rule for what the recorder keeps a usable numeric history of (no attribute, no timer/counter value kind): the card fetches history by it, the editor offers peak_marker by it. |
boundFrom / boundValue / boundUsable |
bound-value.ts: a min_value/max_value/watermark/alert_when end - a number, an EntityHelper or null (unset, or fed by Jinja) - decided once from the config; null and numbers are never in a fault state. |
ha-state.ts |
HA's own reading of a domain/state pair, over the HA_CONTEXT mirrors of HA frontend/core: isStateActive (state_active.ts), stateColor (state_color.ts: the first --state-*-color candidate HA's themes define wins, cached per domain/device class/state, battery and group rules included), isToggleDomain (where the tile card icon toggles by default), domainTraits (our own per-domain value kind, percent attribute, animation). |
EntityCollectionHelper |
The bar_stack feature: proportional mode renormalizes shares against the combined total (a.k.a. "100% stacked"), stacked places each entity at its own position on the min/max scale, net reduces everything to one algebraic total. Width/share math always runs on #magnitude (Math.abs) - a raw negative value must never produce a negative width. An entity counts as negative (net's sign, or the arm it lands in with center_zero) via #isNegative: marked subtract, or its own raw value is already negative - checking both instead of just flipping the sign on subtract avoids double-negating an already-negative value back to positive. With center_zero, stacked/proportional split by that same #isNegative into two independent arm gradients (getDivergingGradients) applied via dedicated CSS variables (--stack-*) instead of the single shared fill. |
resolveProgressInput / progress-display.ts |
Validates what a refresh resolves into a ProgressInput (a refused value falls back to its default); pure functions print it: unit, timer and locale formatting, theme value. The view holds the resulting Progress and rebuilds it on each refresh. |
ProgressMath |
The percentage formulas themselves (min/max, reversed, bar_scale, center-zero), immutable: the whole input comes in through the constructor, so no formula reads what it was not given. resolveProgressInput feeds it. |
UnitHelper |
values/unit-helper.ts: a unit and its display flag, held by the view. |
ThemeManager |
Built-in & custom themes: color/icon per value zone, segment/rainbow gradients, HA color name adaptation. |
NumberFormatter |
Value/unit/duration formatting (Intl.NumberFormat, timedelta parsing). |
ObjStructure + StructureTemplates/StructureElements |
HTML structure factory: pure string builders + per-option <template> cache (see Rendering). |
Infrastructure¶
| Class | Role |
|---|---|
DOMHelper |
Registered-element map + RAF-batched, value-cached DOM writes (setStyle, setHTML, toggleClass, β¦). A write whose value matches the cache is skipped before touching the DOM; pending writes are flushed once per animation frame. Also hosts the HTML sanitizer. setStyle never unsets a value on its own (nullish writes are just skipped) β a CSS custom property that's only conditionally applied (e.g. bar_stack's diverging-arm gradient) needs an explicit removeStyle call when the condition stops holding, or it stays stuck from a stale render. |
ResourceManager |
Ownership of every disposable resource (intervals, timeouts, listeners, WS subscriptions, observers) keyed by id; cleanup() releases everything on disconnect. Also provides throttle / throttleDebounce. |
ActionHelper |
Bridges HA's action-handler (tap/hold/double-tap) to hass-action events, with icon-vs-card hit detection. Idempotent init(). |
Logger |
Per-class leveled logging with optional method wrapping (wrapAll) for call tracing. |
is / has |
Type guards used everywhere (is.number rejects NaN/Infinity, is.strictNumericString vs lax is.numericString, β¦). |
RegistrationHelper |
customElements.define + window.customCards / customBadges / customCardFeatures registration. |
The Multi cards¶
entity-progress-multi-card and entity-progress-multi-feature
(card/elements/multi.ts) render no bar of their own. Each row is a real
entity-progress-card, created with document.createElement (synchronous, no
loadCardHelpers) inside a .multi-item wrapper, and handed its own config and
hass: it watches, refreshes, formats and opens its more-info by itself. The
aggregator only stacks the rows and gives each an equal slice of the height
through the child's own height variable.
- A row's config:
rowConfigsOf(multi-rows.ts) merges the top level into each row (Shared values) andtoRowConfigimposes the row shape βframeless,marginlessand a density β which the row schemas therefore leave out.bar_sizedefaults tosmall. - Rows or columns: the Multi-Card's
layoutandbar_positionare not aggregator fields. They reach the rows like any shared option, androwShapereads them:horizontalmakes each rowdensity: single_line;verticalmakes each onesingle_column, with the card'sbar_position(defaultoroverlay) winning over the row's. Columns sit side by side, each the full height, withoutrowMetrics;rowsdefaults to a vertical card's plus one. The Feature has nolayout: always rows. - Validation: the aggregator's own keys (
AGGREGATOR_FIELDS:entities,rows) by its schema; each row by the full card schema, in its child. A row identity (ROW_IDENTITY_FIELDS:entity,attribute,name,icon) is never shared. - The two variants differ only in two hooks: the card wraps the stack in its
own
ha-cardand lets the Sections grid impose the height (getGridOptions,rows); the feature renders bare in its tile row, takes HA's--feature-heightas its unit, and hides each child's shape throughforceHidden, called beforesetConfig. What a slice of a 42 px row can't hold (icon actions,trend_indicator,status_label, the icon badge,alert_when) its row schema,multiFeatureRow, doesn't accept at all. - Bars line up through
bar_aligned, true by default here: a row knows it is one by its.multi-itemparent (see Rendering & performance). - The editor is a list (
entity-progress-multi-row-editor,list-editors/) whose pencil opens a row editor β the card editor itself, built byEditorFactory.buildMultiRowβ and writes back throughMULTI_ROWS.
Card lifecycle¶
The web component contract¶
Cards are autonomous custom elements. The relevant callbacks and the HA
calls interleave like this β note that Home Assistant sets config and hass
before attaching the element to the DOM:
sequenceDiagram
participant HA as Home Assistant
participant El as Card element
HA->>El: createElement(tag)
Note over El: constructor()<br/>attachShadow, Logger init
HA->>El: setConfig(config)
Note over El: validate config, build DOM structure
HA->>El: hass = β¦
Note over El: guarded: some managers may not exist yet
HA->>El: append to DOM
Note over El: connectedCallback()<br/>resources, render, listeners
loop every state change in the installation
HA->>El: hass = β¦
Note over El: ChangeTracker filters,<br/>refresh only if a watched entity moved
end
HA->>El: remove from DOM
Note over El: disconnectedCallback()<br/>ResourceManager.cleanup()
Two consequences drive the code style:
- Everything reachable from
setConfig/set hassmust tolerate a not-yet-connected element (_resourceManagermay benull, the DOM may not exist). Guards likethis._resourceManager?.β¦are load-bearing, not defensive noise. connectedCallbackcan run many times (view navigation, edit mode, DOM moves). Everything it does must be idempotent: listeners are attached once (ActionHelper.#initialized), the render is guarded by#isRendered, resource re-creation is keyed.
Function chain¶
setConfig(config) (HACore):
setConfig
ββ reset() # if already rendered (editor keystroke)
β ββ remove 'transition-ready' class
β ββ _dom.destroy() # clear element map + caches
β ββ shadowRoot.innerHTML = '' (adoptedStyleSheets survive)
ββ _cardView.config = {β¦} # validation + negotiation (ConfigHelper)
ββ _registerWatchedEntities() # rebuild the ChangeTracker watch set
ββ render()
ββ _handleHassUpdate() # if hass already known
render() (once per connection/config, guarded by #isRendered):
render
ββ _createCardElements()
β ββ adopt shared CSSStyleSheet (or legacy <style> fallback)
β ββ create card element, register it in DOMHelper
β ββ _buildStyle() # base classes, watermark, bar effect
β ββ card.replaceChildren(clone) # <template> cache keyed by structure options
ββ shadowRoot.replaceChildren(β¦)
ββ _storeDOM() # register the few dynamic elements (_domKeys)
ββ RAF β add 'transition-ready' # enables CSS transitions after first paint
The transition-ready class exists so the bar does not animate from 0 on
the very first paint β transitions are only enabled one frame later.
set hass(hass) (every state change in the installation):
set hass
ββ ChangeTracker.hassState = hass # reference-compare watched entities
ββ if first hass or a watched entity changed:
β ββ HassProviderSingleton.hass = hass
β ββ _handleHassUpdate()
β ββ refresh()
β ββ _cardView.refresh(hass) # recompute values/percent/theme
β ββ _manageErrorMessage() # error card state
β ββ _updateDynamicElements()
β ββ _showIcon / _showBadge / _manageShape / _updateTrend
β ββ _updateCSS() # CSS custom properties via DOMHelper
β ββ _processJinjaFields() # throttled; no-op if subscribed
ββ _watchWebSocket() # once
All DOM writes in this chain go through DOMHelper: value-cached (no-op if
unchanged) and RAF-batched (one flush per frame). An idle card whose watched
entities did not change costs one Map lookup and n reference comparisons per
hass update β nothing else. Cards with no watched entity (pure Jinja
template cards) skip the refresh entirely: their content arrives via push
subscriptions.
disconnectedCallback():
disconnectedCallback
ββ ResourceManager.cleanup() # intervals, listeners, WS subscriptions, observers
ββ _resourceManager = null
ββ clear template-subscription signatures # allows resubscription on reconnect
The local tick (auto-refresh)¶
A running timer, a relative last_changed/last_updated and a
peak_marker/trend_indicator window all move with no state change from HA.
_manageAutoRefresh, after every hass update and every tick, arms one
ResourceManager-owned setTimeout (autoRefresh) for the view's
nextTickAt(now): the next instant something shown changes, null when nothing
will. A timer's value turns on its own clock (finishes_at - duration), a
relative time where relativeAge (utils/clock.ts, shared with the formatter)
says its reading changes, a window at most a minute on. An earlier deadline
re-arms at once; a timer firing early waits for its own.
A tick is not a refresh: hass hasn't changed, only time has. The view re-reads
what time moves (refreshClock(): current value, percent, peak marks, theme
value), then the bar, the value text, alerts, the status label and the trend
follow. Tick text goes through setTextNow: synchronous, still skipped when
unchanged.
Home Assistant integration¶
Registration¶
At module load, in src/bootstrap.ts:
RegistrationHelper.registerCard(META.types.card, EntityProgressCard);
RegistrationHelper.registerBadge(META.types.badge, EntityProgressBadge);
RegistrationHelper.registerCardFeature(META.types.feature, EntityProgressFeatures);
β¦
The editors register later, from their own file: src/editor/entry.ts defines
each one under devName(META.types.*.editor) when getConfigElement() imports
it. The bundle only ever holds the tag name.
RegistrationHelper does two things per component:
customElements.define(tag, class)β guarded bycustomElements.getso a double-load (HACS + manual resource) logs a warning instead of throwing.- Pushes a descriptor into
window.customCards/window.customBadges/window.customCardFeatures(deferred by 1 s) so the card appears in HA's card picker with name, description and preview support. Card/Badge only, the descriptor also carriesgetEntitySuggestion(HA 2026.6+ entity-first card picker) β seesrc/utils/entity-suggestions.tsfor the domain/ attribute rules deciding which entities get a suggestion and what config comes back. It resolves off the sameHA_CONTEXT.domains(percent) the card itself reads for a default attribute, so a picked entity and a hand-written one agree. A battery (device_class: battery) gets two: the plain card, then the same one undertheme: battery_adaptive, labelled with that theme's own editor label (HA titles it "- customCardFeaturesentries also needconfigurable: truefor the edit pencil to appear in HA's tile-feature list at all (hui-card-features- editor.ts's_isFeatureTypeEditable) - entirely independent of whethergetConfigElement()/customElements.define()for the editor actually work. With the editor in its own file, that is literally the case: the pencil shows before the editor file was ever fetched.- Features answer both
isSupported(HA 2025.6+) and the oldersupported: HA 2025.6+ only asks the first, and a feature answeringsupportedalone is skipped by any host card without an entity of its own (Mushroom's template card).
The HA β card contract¶
| HA calls | Purpose |
|---|---|
setConfig(config) |
Raw YAML config. Must throw on unusable config (HA shows the error card). Called on every editor keystroke. |
hass setter |
New immutable snapshot on every state change of the whole installation. |
getCardSize() / getLayoutOptions() |
Masonry & sections-grid sizing. Derived from layout/bar options by the view. |
static getConfigElement() |
Returns the visual editor element (document.createElement('<tag>-editor')). |
static getStubConfig(hass) |
Initial config in the card picker; picks a sensible entity from hass. |
Conventions relied upon:
hass.statesobjects are immutable β the frontend replaces the object on change.ChangeTrackerexploits this: change detection is reference equality, exactly like native cards'shouldUpdate.- Actions are delegated to HA: the card binds the global
<action-handler>element (created lazily if absent, as the HA frontend does) and emitshass-actionevents; HA executes more-info/toggle/navigate. - Native components are reused in the editor (
ha-selector,ha-expansion-panel,ha-filter-chip,ha-button,ha-svg-icon) and in the card (ha-card,ha-icon,ha-state-icon,ha-alert). This keeps look & feel aligned with each HA release, at the cost of depending on their (stable) public behavior. - Theming goes through HA CSS custom properties (
--primary-color,--state-icon-color,--ha-card-*) plus the card's public--epb-*API (see Theme Guide); dark-mode switches need no JavaScript. The--epb-*prefix means exactly that: every one of them is a documented, user-settable hook listed in Theme Guide. A variable the card sets programmatically as a render channel (--stack-*,--mark-*,--current-*) never takes it. - State colors and activity mirror HA frontend:
HA_CONTEXTcopies HA's--state-*-colornames,STATE_COLORED_DOMAIN,state_active.tsand the battery steps, each pinned to its source;ha-state.tsreads them. An entity's default color is therefore the one HA's own tiles show, theme included. Re-sync the mirrors from HA's source, never by hand-guessing.
WebSocket¶
Beyond the hass object, the card talks to HA through the shared WebSocket
connection (hass.connection) for Jinja rendering β see next section. The
disconnected / ready connection events are watched to drop and restore
subscriptions across reconnections (HA restart, network loss).
History¶
trend_indicator with a window and peak_marker start from the recorder's
history, then follow the live value.
- Who may ask:
hasUsableHistory(entity-helper.ts) β the same rule the editor uses to offerpeak_marker: no attribute, notimer/counter. A duration's points are converted to the card's working unit. - The request:
HistorySeeding(history-seeding.ts) sends onehistory/history_during_periodover the shared connection. Two features asking for the same window share one in-flight call, andseeddrops a reply whose entity, attribute or window changed while it was in flight. - The samples:
SampleRingkeeps (time, value) pairs in growable typed arrays, not an object per reading β Float32 percents forTrendTracker, Float64 raw values forPeakTracker(min, max, time-weighted average). Both trim to their window, and the window slides with time, not only with new readings.
Rendering & performance¶
Techniques used to keep N cards cheap on a dashboard that updates constantly:
- Shared constructed stylesheets. The ~47 KB CSS is parsed once into a
CSSStyleSheetand adopted by reference by every shadow root (getSharedStyleSheet). Feature-detected; Firefox < 101 / Safari < 16.4 fall back to a per-instance<style>element. <template>cache.ObjStructure.clone(options)builds the HTML string once per unique structure-option set, parses it into a<template>, and every subsequent render clones the tree. The cache key is the JSON of the options object β the DOM structure depends on config options (layout, bar position, center-zeroβ¦), so each distinct combination gets its own template and identical cards share one.- Value-cached, RAF-batched DOM writes (
DOMHelper, shared by the card and byEditorDOMHelper extends DOMHelper). Two independent mechanisms, both keyed${key}:${prop}(the registered element's key + the property being written, e.g.bar_size:style:width):- Value cache (
_appliedValues) β everysetStyle/setText/toggleClass/β¦ checks this map first and returns immediately if the incoming value already equals the last one applied; nothing gets enqueued at all for a no-op change, so an unrelated hass update that recomputes the same values costs a handful of map lookups, not DOM writes. - RAF queue (
enqueue(key, prop, updateFn)β_pendingUpdates) β writes that do need to happen go into aMap<"key:prop", updateFn>instead of touching the DOM synchronously. Enqueuing again under the samekey:propbefore the next frame just overwrites the map entry (last write wins) rather than queuing a second one, so N redundant writes to the same target collapse into the one that actually mattered. A singlerequestAnimationFramecallback flushes the whole map once per frame, however many distinct keys ended up queued. This is also the project's general-purpose debounce building block β seeResourceManager.setTimeout(handler, ms, id)'s own cancel-and-replace- by-id semantics, used the same way for the Jinja render debounce (Jinja template subscriptions).
- Value cache (
- Reference-based change detection (
ChangeTracker), so the per-update cost of an idle card is a few!==. - Compositor-only animations. The bar fill animates with
transform: translateX/Y; gradient/glass effects live on a::beforescaled withtransformtoo. Nowidth/background-sizeanimation β no per-frame repaint.contain: layout paintbounds invalidation to the bar. - Push-based Jinja with subscription dedup (next section) instead of polling or resubscribing.
bar_alignedonly grows at once (card/dom/aligned-bars.ts). The column is a single_line row's text, or the value beside a default-row bar (HAS_EFFECT.barAligned). A row joins its group at render - its Multi fortrue, the name otherwise - and leaves with its other resources. A text change (MutationObserver) measures that row alone: wider than the column, it widens every row at once; narrower, the column shrinks only if the widths already read still say so 30 s later - a timer, no measurement. A resize (ResizeObserver), a leave or a late web font measures the whole group again. OnerequestAnimationFramesettles everything marked - all releases tomax-content, then all reads, then all writes - so one forced layout for the page, never one per row, and ahassupdate that leaves the text alone costs nothing.- The ring is the shape's
::after, not a bar.bar_position: iconbuilds no straight bar (hasStraightBarturnscenter_zero,bar_effect,bar_stackandbar_segmentsinert there). A conic-gradient under a radial mask draws the ring outside the shape (--ring-offset), inside a fixed 44 px envelope, so the icon never shrinks under it. Its fill animates through--entity-progress-ring-value, registered withCSS.registerPropertyinbootstrap.tsso it can transition, and held at 0 untiltransition-ready, as the bar is. Colours come fromThemeManagerwithisRing(a conic gradient over the whole track), and the marks are.ring-*layers driven by the bar's ownshown/wm-*classes: no second mark pipeline.
Browser compatibility matrix¶
The card ships to a wide range of Home Assistant setups β including embedded/kiosk panels running an old, unupdatable browser β so compatibility is handled as two distinct floors, not one:
| Tier | Home Assistant | Chrome/Edge | Firefox | Safari | Opera |
|---|---|---|---|---|---|
| Functional minimum | 2024.0+ |
98+ |
94+ |
15.4+ |
84+ |
| Full visual effects | β | 111+ |
113+ |
16.2+ |
97+ |
(kept in sync with the table in the README β update both when either floor changes.) Below the functional-minimum row, the card may not load at all. Between the two rows, it loads and works completely β every option, every interaction β but a handful of purely decorative touches (a soft tint behind icons, the pulsing alert/ping animations, the bar's gradient sheen) fall back to a plainer look instead of the modern one. This is a deliberate trade-off, not an oversight: full functionality first, full polish where the browser allows it.
How the two floors are enforced¶
- Syntax (does the JS itself parse/run) is handled by the build target,
not by writing fallback code β
scripts/lib/esbuild-settings.jsholdstarget: 'es2021'andNATIVE_CLASS_FEATURES, read bybuild.js's minifier and bytest.js, so the tests compile as the shipped bundle does;npm run check:es-target(part of the release build) re-verifies that language floor on the minified output. This is the direct fix for issue #128 (filed against Chrome 92): the build used to targetes2022, which let esbuild emit classstatic {}blocks β a hardSyntaxErroron Chrome 92, caught by neither dev-mode testing (a modern browser) nornode --checkin CI (Node's own parser is newer than the target), so it shipped broken to exactly the embedded/kiosk browsers this matters most for. Static blocks are the only es2022 syntax Chrome 92 lacks: class fields, private fields and methods, and#x in objall run natively there (Chrome 72-91), soesbuild-settings.jsdeclares them supported (NATIVE_CLASS_FEATURES) and keeps them native instead of lowered toWeakMaphelpers.check:es-targetmirrors that split:es-check es2022for the syntax level, thenscripts/check-no-static-blocks.js, because es-check passes or fails static blocks together with the rest of es2022. The build also avoids esbuild'skeepNames: without static blocks, esbuild can only name a class by lowering all of it, private members included (226WeakMap/WeakSet, ~35 KB) β loggers name themselves instead, see Logging & debugging.eslint-plugin-compatlints the source against the same functional-minimum matrix duringnpm run lint, catching a problem earlier, before it'd otherwise only surface incheck:es-targeton the built output. See Release process for exactly where the build-time check runs. - Runtime APIs (does the method exist at all) are neither syntax nor CSS, so
neither mechanism catches them: esbuild's target rewrites syntax and leaves
Object.hasOwnexactly as written, andes-checkonly parses. Two modules encapsulate the ones this card uses βcommon-checks.ts'shas.ownandbrowser-support.ts'sdeepCloneβ each picking the modern API or a fallback onIN_SUPPORTED_MATRIX; every other module goes through them.npm run check:chrome92(incheck:push, local only β Chrome 92 is best effort, not something a release runner should block on) re-runseslint-plugin-compatagainstChrome >= 92with those two files exempted, so a direct call anywhere else is a finding. It reads source rather than the bundle, and sees globals and static methods but not prototype methods on an untyped receiver β a pass is encouraging, not proof. The worked example:Object.hasOwnsat unguarded informatting.tsfor months, harmless because nothing on a load-time path reached it, until apeak_markerschema default began calling it while the schema was being built β taking the whole card down on Chrome 92, on every dashboard. - Visual/CSS degradation is a separate, manual mechanism β there's no build
target or linter for "does this gradient look right on Safari 15.4". Effects
that use a modern CSS feature (
color-mix(),round(), Constructable Stylesheets) ship a fallback tier picked via@supports(or atry/catcharound the feature-detection itself, for JS APIs like Constructable Stylesheets), and a modern tier for browsers that support the real thing. Both tiers render the same underlying state, just with a plainer technique on the fallback side β never a missing feature.docs/graphic-effects-compatibility.htmlis the living side-by-side reference: every animation/gradient/effect in the card, fallback tier next to modern tier, with a note on exactly what technique change makes each one safe. Read it before adding a new visual effect, and add the new effect to it.
When adding something that needs a newer CSS/JS feature¶
- Check whether it's purely decorative (an animation flourish, a gradient sheen) or functional (the option doesn't work at all without it). Only decorative effects get the two-tier treatment β a functional gap has to be solved a different way (a simpler technique that works everywhere, or the option genuinely requires the floor to move, which needs a deliberate discussion, not a silent regression).
- Write the fallback tier first (the one that works at the functional- minimum
floor), confirm it looks reasonable on its own, then add the modern tier
behind
@supports(or equivalent feature detection). - Add the pair to
docs/graphic-effects-compatibility.htmlso it's visible in the living comparison, not just correct in isolation.
Pushing the floor lower where it's cheap¶
The 98+/94+/15.4+/84+ row is where the project draws the line on
effort, not a hard technical wall. Issue #128's own reporter was on Chrome
92 β an embedded kiosk panel, the kind of device that's often the hardest to get
upgraded. The JS syntax side is already covered for that case (the build target
and static-block check above), so this is really about the CSS fallback
tier: when a tier you're already writing for @supports also happens to work
on something like Chrome 92 at no extra cost, prefer that shape. Don't spend
real effort chasing 92 specifically, and don't let it constrain the modern
tier's implementation β it's "free wins welcome," not a second floor to formally
test against.
Jinja template subscriptions¶
Template-capable options (badge_icon, bar_effect, hide, min_value,
max_value, watermark.low, watermark.high, alert_when.above,
alert_when.below, and all fields of the template cards) are rendered
server-side by HA via render_template WebSocket subscriptions: HA pushes a
new result whenever an entity referenced inside the template changes. The card
never evaluates Jinja itself.
min_value/max_value/watermark.low/watermark.high/alert_when.above/
alert_when.below all share the same explicit shape
(number | { entity, attribute } | { jinja: "..." }) rather than sniffing a
bare string for either the entity or the Jinja case β disambiguating either at
runtime from just the value's shape is exactly what this avoids.
validJinjaFields's rawValueFor resolves both flat keys (min_value) and one
level of nested dot-path keys (watermark.low, alert_when.above) the same way
#resolveValue does for editor fields. The resolved number is cached on the
view (jinjaMinValue, jinjaWatermarkLow, jinjaAlertAbove, β¦) and read with
?? ahead of the static value in #setStdValues/the watermark
getter/isAlertActive β never written directly into a Bound, which only
understands numbers and entity IDs.
Key mechanics (_processJinjaFields / _subscribeToTemplate):
- Signature dedup. Each subscription is identified by
template + '\0' + entity-variable. If an identical subscription is live or in flight, the call is a no-op β refreshes cost zero WS traffic. The signature is reserved before theawait, which also prevents concurrent duplicate subscriptions; a superseded in-flight subscription unsubscribes itself on resolution. - Invalidation. Signatures are cleared when the WS drops (
disconnectedevent), ondisconnectedCallback, and on subscription failure (allowing retry). Orphan subscriptions (field removed from config) are cleaned on the next processing cycle. - Throttling.
_processJinjaFieldsruns throughthrottleDebounce(300 ms): leading execution for responsiveness, trailing execution only for calls rejected by the throttle. - Result handling.
render_templatereturns native types β handlers normalize (listor comma-string forbar_effect/hide, number or numeric string forpercent) and render errors are caught and logged rather than crashing the WS callback. - Per-key render debounce. Every pushed result funnels through
HACore._renderJinja(key, content), which debounces ~80ms perkey(idjinja-render-<key>) viaResourceManager.setTimeoutbefore calling the real handler (#applyJinja) β no new mechanism, just reusingResourceManager's existing cancel-and-replace-by-id semantics for the same id. This exists because a multi-step HA script/automation (e.g. turning on aninput_boolean, then picking aninput_selectoption) makes entities referenced by anandcondition change one at a time, not atomically β HA pushes one intermediaterender_templateresult per entity it touches, not just the final settled one. Without the debounce, a field could visibly render (and stay stuck on) a transient value nothing in the final state actually supports (issue #135). The 300ms throttle above governs how often a subscription gets (re)established; this 80ms debounce governs how often an already-subscribed field's result gets applied to the DOM β different problems, both needed.
Configuration validation¶
BaseConfigHelper subclasses run the raw YAML through a schema built with the
types combinators (YamlSchemaFactory), one helper per variant:
| Helper | Schema | Extends |
|---|---|---|
CardConfigHelper |
card (legacy migrations, defaults) |
BaseConfigHelper |
BadgeConfigHelper / FeatureConfigHelper |
badge / feature |
CardConfigHelper |
TemplateConfigHelper / BadgeTemplateConfigHelper |
template / badgeTemplate |
BaseConfigHelper |
MultiCardConfigHelper / MultiFeatureConfigHelper |
multiCard / multiFeature |
MultiConfigHelper |
MultiRowConfigHelper / MultiFeatureRowConfigHelper |
multiRow / multiFeatureRow (editor) |
MultiConfigHelper |
Principles:
- Negotiation, not rejection: an invalid property is dropped
(
SKIP_PROPERTY) or replaced by its default, and a message is surfaced in the editor preview; the card still renders whenever possible. - The negotiated config (
_configHelper.config) is what views consume; the raw config is what the editor round-trips, so user YAML is never rewritten behind their back. - Deprecated options are detected and logged with a migration hint.
- Migration is per-class, not automatic β
BaseConfigHelper._customizeConfigcalls_migrateLegacyOptionspolymorphically, but onlyCardConfigHelper(Card/Badge/Feature) overrode it with real transformations until #140:TemplateConfigHelper/BadgeTemplateConfigHelperinheritedBaseConfigHelper's no-op, sowatermark.low/.high's legacy forms were silently dropped there despite the shared console warning claiming otherwise. A migration that applies to every variant belongs inBaseConfigHelper._migrateLegacyOptionsitself (see_migrateWatermarkOptions), not bolted ontoCardConfigHelperalone β check which config helpers actually call the override before adding a migration only one subclass will ever run.
preProcess / postProcess (struct(), schema.ts)¶
Every schema's pipeline is
preProcess(rawData) β per-field validator() β postProcess(result):
preProcessruns on the raw, untypedRecord<string, unknown>, before any field validator sees it. It's for reshaping input whose YAML shorthand differs from the internal shape β e.g. a barename: "text"string gets normalized into the real[{type: 'text', text: ...}]array the field validator expects, so the validator itself only has to handle one shape.postProcessruns on the validated, typed result. It's the cross-field safety net for "field B is meaningless without field A":INERT_OPTIONSlists each such option with itsHAS_EFFECTpredicate and its fallback (the schema default), and wherever the option has no effectpostProcessputs the fallback back βbar_color_mode/interpolateonce no theme is active,bar_single_lineoncebar_positionisn'toverlay. This runs for every config, hand-written YAML included, which is what actually protects rendering.
When adding an option gated by another one, give it a HAS_EFFECT predicate
and an INERT_OPTIONS entry. From that one line the schema resets it, and the
editor hides its field and parks its value (see
Editor architecture). Neither is where you'd reject bad
input β that's the field validator's own job (throw ValidationError, or return
SKIP_PROPERTY to drop silently).
Config is derived from the schema, not hand-maintained¶
schema.ts's Validator<T> (and all of its types combinators β string,
object, array, optional, enums, discriminatedUnion, β¦) is generic, so
struct() returns a properly typed { validate, parse, extend } instead of
any. Infer<S> extracts the resulting config type straight from a
YamlSchemaFactory entry:
type Infer<S> = Extract<ReturnType<S['validate']>, { isValid: true }>['config'];
utils/types.ts's Config is
Partial<Infer<Card> & Infer<Badge> & Infer<Template> & Infer<BadgeTemplate> & Infer<Feature>>
β an intersection of all five schemas, then made fully optional. It's an
intersection rather than a union on purpose: shared code (HACore, ViewCore,
β¦) reads config fields without knowing which card family is actually running,
and TypeScript only allows property access on a union when the property exists
on every member. When adding or changing a property, edit the relevant
YamlSchemaFactory schema β Config picks it up automatically, nothing to
update by hand.
Defaults and allowed values are read off the live validators¶
Two more things come from the schema rather than a parallel table, through
struct()'s own introspection methods:
fieldDefault(name)β a field's real default, walking_schemaand reading thedefaultValuethattypes.fallbackToattaches. FeedsSCHEMA_DEFAULTS.fieldOptions(name)β a field's allowed values, reading theallowedValuesthattypes.enums/theme/jinjaOrArrayWithValidatedElemattach, forwarded throughoptional/fallbackTo/unionbywithOptions. Accepts a dot path ('watermark.type'). Feeds the editor's dropdowns (SELECT_TYPES) andhide's chip list, per variant.
Warning
withOptions deliberately forwards a separate _optionsSchema view instead
of _schema itself. _schema carries default semantics too, and widening its
reach through optional turns absent defaults into real ones β measured:
alert_when gains { highlight: 'border' } and bar_stack
{ mode: 'stacked' }, injected into cards that never configured either.
The schema holds every option rule¶
schema.ts (the schema/ folder behind it) started as the validator. It is now
where every rule about an option lives, and the card, the editor, the
diagnostics and the docs all read it there instead of keeping their own copy:
- What each variant accepts: its field list, shared by
.delete()/.extend(). The editor offers exactly those fields (editor-coverage.test). - Types, defaults, allowed values:
Config,SCHEMA_DEFAULTS,fieldOptionsβ the sections above. - Where an option has an effect:
HAS_EFFECTandINERT_OPTIONS(with the fallback an inert option gets back), anddensityOverrides(what a density imposes). A rule reading a raw config (contentShape,HAS_EFFECT) reads it throughdensityOverridesfirst (settled): a rawsingle_columnhas nolayoutyet.postProcessapplies them to the negotiated config, the editor hides and parks a field by them, andcard-audit.tsreports "no effect" by them β inEPB.doctorand the issue report. - Marks:
MARK_FIELDS, which mark has which field and whether it inherits (Shared values). - The Multi's split:
AGGREGATOR_FIELDS(the aggregator's own keys) andROW_IDENTITY_FIELDS(never shared between rows). - The documentation:
test/docs/checksconfiguration.md's defaults, compatibility badges and option tables, and every documented YAML example, against it;docs/option-map.mdis generated from it.
A new rule about an option goes in schema/, exported through schema.ts,
never written in the card or the editor alone β two copies of one rule drift
apart without a line of code in common to give them away.
Security¶
Jinja results rendered as HTML (name, secondary, custom_info, name_info)
pass through the allowlist sanitizer in DOMHelper.setHTML:
- Tags:
b,i,u,span,div,brβ anything else is unwrapped (text preserved);script/style/iframe/object/embedare dropped with their content. - Attributes:
class, plusstylerestricted tocolor/background-color. Event handlers and URLs never survive.
Rationale: templates are authored by the dashboard owner, but they often interpolate strings the owner does not control (media titles, network device names, MQTT payloads). Details in the Supported HTML section.
When adding a new render path, use setText unless HTML is a documented feature
of the field β and never bypass setHTML's sanitizer with a raw innerHTML
assignment.
Editor components: native HA elements vs. our own¶
Why this is a real constraint, not a style preference¶
Home Assistant's own ha-* elements (ha-selector, ha-button, ha-form, β¦)
are internal implementation details of the frontend, not a published, versioned
API for third-party cards. Depending on them directly is a known risk: HA can
rename or restructure any of them without notice, and a change that breaks a
community card is a real, precedented failure mode β HA 0.115 introduced
lazy-loading for these elements specifically, which broke custom card editors
relying on them being already loaded, badly enough that the change was reverted
in 0.115.3 while a real fix was worked out (see
home-assistant/frontend#11294).
That discussion is also where Thomas Loven (of card-mod/layout-card fame)
laid out the community's still-current workaround, quoted directly there: force
an element to load as a side effect of using window.loadCardHelpers() (a
helper HA itself exposes for custom cards, undocumented on the official site but
stable in practice) β e.g.
(await window.loadCardHelpers()).createRowElement({type: "..."}) for a row
type that internally imports the target element β rather than depending on it
directly. His lovelace-card-tools library packages the same idea
as a reusable load_lovelace() helper (loads the whole Lovelace panel, and with
it every native element it registers).
How this project's approach evolved¶
Early on, this project used that same preload trick β it's a genuinely clever
piece of community engineering, and it was the right call at the time: it's what
let this card have a real visual editor at all, years before writing one this
way would even have been an option. As the editor grew, the project moved to a
factory built directly on ha-selector (EditorBase#getSelectorForType, see
below) β ha-selector is itself HA's own dispatcher component: mount it with a
.selector config object and it renders whichever concrete widget HA currently
ships for that selector type. That means this editor picks up HA's own selector
improvements (the WebAwesome-based restyling referenced throughout this
document, for one) automatically, with no maintenance here β less a correction
of the earlier approach than a natural next step once the editor had enough
surface for that to pay off.
No explicit preload step is needed in practice anymore: reaching this editor at
all requires going through HA's own "Edit card" dialog first, which already uses
ha-selector pervasively for its own built-in card editors β by the time our
editor mounts, it's already registered.
Two strategies, side by side¶
ha-selector β for anything HA's own selector system already models¶
EditorBase#getSelectorForType maps this project's own field-type strings to a
native Selector config object β the exact shape HA's own built-in card editors
pass to <ha-selector> (cross-checked against HA's source, e.g. the box-mode
select with tile images mirrors hui-tile-card-editor.ts, linked directly in
the code). This covers most of the field surface:
entity/attribute/action/color/icon/text/number/boolean pickers, and any generic
dropdown.
Check HA's own Selector union type before building anything
custom β if the shape you need already exists there, mapping it in
#getSelectorForType is the whole job, and it stays free of maintenance as HA's
own widget evolves.
Our own components β for anything it doesn't¶
HA's selector system has no public field type for a few things this editor
needs: a fused 2-mode segmented pill, a repeatable-row list editor, a
progressive-disclosure "+" picker (confirmed by checking ha-form's own
LOAD_ELEMENTS registry β see the entity-progress-action-picker note above).
For those, two class families follow the same template-method pattern:
ChipsBase/SingleSelectChipsBase(editor/elements/chips.ts) β chip sets and 2-mode segmented pills.ListEditorBase(editor/elements/list-editors/) β repeatable row editors (bar_stackentities,custom_themezones) andEntityProgressActionPicker.
Construction: plain HTMLElement subclasses, their own shadow DOM, a
build-once/render-on-value-change lifecycle, dispatching a
VALUE_CHANGED_EVENT that bubbles out β the same event contract <ha-selector>
itself uses, so EditorBase#onChanged handles both kinds of field identically
without knowing which one it's talking to.
Reproducing HA's look & feel: styled from HA's own CSS custom properties, not one-off colors, with a fallback chain that keeps working on HA installs still on the pre-WebAwesome theme system:
--chip-accent: var(--wa-color-brand-fill-loud, var(--primary-color));
--chip-accent-text: var(--wa-color-brand-on-loud, var(--text-primary-color, #fff));
--chip-standby: var(--wa-color-brand-fill-normal, var(--secondary-background-color));
--chip-standby-text: var(--wa-color-brand-on-normal, var(--primary-text-color));
(CHIPS_HOST_STYLE, styles.ts) β "loud" = selected/active, "normal" =
standby/inactive, traced directly from ha-button.ts's own
:host([variant="brand"]) block and wa.globals.ts. Every left-hand variable
is HA-owned; every fallback resolves to a pre-WebAwesome HA variable, never a
literal color, so theming keeps working either way.
Where a genuine native element already exists with no selector wrapper around
it, use it directly instead of imitating its look: the "+ Add β¦" buttons
(EntityProgressBarStackEditor, EntityProgressCustomThemeEditor,
EntityProgressActionPicker) are real document.createElement('ha-button')
instances β appearance="filled" size="s", matching how HA's own
ha-form-optional_actions.ts builds its own "+ Add interaction" button β not a
lookalike, so it's theme-reactive automatically and stays visually in sync with
HA for free.
Editor architecture¶
EditorFactory builds the field-def tree¶
EditorFactory.build(template, badge) produces the whole static _fields tree
consumed by EditorBase, one entry per panel: general, content, theme,
markers, layout, interactions. Every section function takes the same two
booleans (template/badge) identifying which of the four editable variants
(Card/Badge/Template/Badge Template) is being built, and returns a plain object
of field definitions β there's no class hierarchy here, just parameterized
functions returning data.
The theme panel in particular is assembled from a dozen small
themeXxxFields(...) helpers (themeModeFields, themeColorModeFields,
themeCardOnlyFields, themeBarSizingFields, β¦) instead of one large function
β this is deliberate, not just tidiness: theme()'s own body would trip
sonarjs/cognitive-complexity's 15-branch cap if every card-type ternary lived
inline. Adding a field to that panel usually means extending the right existing
themeXxxFields helper, not adding to theme() itself.
valueField/nestedValueField are the equivalent factories for the 3-way
(standard/entity/jinja) value fields
(min_value/max_value/watermark.low/.high/alert_when.above/ .below) β
one implementation, five call sites.
- A declarative field map (
static _fields) organized in expansion panels; each field is anha-selector(or a custom element:entity-progress-effect-chips,entity-progress-hide-chips,entity-progress-mode-chips,entity-progress-bar-stack-editor,entity-progress-custom-theme-editor,entity-progress-multi-row-editor,entity-progress-action-picker), ortype: 'section_label'- a non-interactive caption grouping the fields after it (no value, noha-selector; seeEditorFieldsType.sectionLabel).entity-progress-action-pickeris the interactions panel's "+ Add interaction" reveal-one-at-a-time picker (hold_action,icon_hold_action,double_tap_action,icon_double_tap_action) - the same UX asha-form's nativeoptional_actionsfield type, built on this custom engine instead since the editor isn'tha-form-based._visible_actions(ephemeral) tracks manually-revealed keys;interactions()infactory.tsderives the hidden/shown split.
EditorBase runtime conventions¶
- A feature's tile entity: Home Assistant hands a feature's editor its
tile's
context.EditorBasekeepscontext.entity_idunder_context_entity(an ephemeral key, never written), negotiates defaults off it when the feature sets no entity of its own, and an entity-gated field askseffectiveEntity()(factory.ts), neverc.entityalone. The entity field itself shows only what the YAML holds. - Render once, update forever: the DOM is built on first
connectedCallback; every subsequentsetConfigonly pushes values, visibility (showIf) and dynamic selectors throughEditorDOMHelper(same RAF-queue + value-cache batching as the card β see Rendering & performance). - Fields read the negotiated config so entity-driven defaults show up,
except
template/actionfields which read the raw config to avoid flicker while typing Jinja. - An emptied field (
'',null,undefinedβ never0/false) unsets its key instead of saving''; a nested one keeps its parent, whose presence is what turns the section on.onClearonly drops what depended on the key. virtualfields (UI-only toggles),targetremapping,onChange/onClearhooks cover the YAMLβUI mismatches;_-prefixed keys carry ephemeral UI state and are stripped beforeconfig-changedis dispatched (never round-tripped to the saved YAML), but survive across asetConfiground-trip like the rest of#configdoes.- Draft-preservation pattern: when a toggle/mode-switch (
badge_toggle,icon_animation_mode,min_value_mode, β¦) discards a value to switch shape, stash it in a matching_<field>_<mode>_draftkey first (one draft per other mode, e.g._min_value_entity_draft+_min_value_jinja_draftformin_value_mode's 3-way switch) instead of just dropping it. Re-entering that mode later reads the draft back before falling to a blank default, so switching jinja β standard β jinja restores the typed template instead of starting over.valueField/nestedValueFieldinfactory.tsare the reference implementation for the 3-way (standard/ entity/jinja) case; every 2-way jinja toggle (hide_mode,bar_effect_mode,status_label_toggle, β¦) follows the same shape with one draft each way. - Inert options are parked, not kept: on every write, an
OPTIONS_WITHOUT_EFFECTentry (INERT_OPTIONSplusbar_size) that has no effect in the new config moves to_<key>_inert_draftand leaves the YAML; it comes back once it has an effect again, unless the user set it anew meanwhile. Apart fromdraftToggle's_<key>_draft, which holds a value the user switched off and must not return on its own. Migrate config shows for such an option too: its click's own write parks it. Not on a Multi host (_parksInertOptions = false): its shared level is a partial config. - Field
widthcan be a plain string (set once, at build) or a function of config (re-evaluated on every relevant update viaEditorDOMHelper, same as a dynamictype). Two fields meant to sit side by side in the same flex-wrap row must agree on when each goes half vs. full β if field B'sshowIfcan go false while field A stays visible and half-width, A needs a matching conditional width (falling back to100%) or it ends up alone with empty space beside it.EditorFactory.themeBarSizingFieldsis the most elaborate real example (four different pairing rules depending on card type, spelled out in its own header comment) - read it before adding a new field to that same panel. - Custom elements that edit an array of row-objects (
bar_stack's entities,custom_theme's zones) shareListEditorBase: a label, a list container, the build-once/render-on-change lifecycle, and_deleteRow/_updateItemβ the same template-method patternChipsBase/SingleSelectChipsBaseuse for the chip family. A concrete row editor only implements_buildDOM()/_render()/_dispatch()and its own per-field builders.
Shared values: one factorisation¶
card/config/factorization.ts is the one rule for every "set once on top,
exceptions below" level: the mark families (MARK_FACTORIZATION, built from
schema.ts's MARK_FIELDS table) and the Multi's rows (MULTI_ROWS,
editor/data/multi-cascade.ts). A Factorization is stateless, built from a
spec (where the shared values and items live, how an item reads and writes a
key, which keys an item inherits, pins or owns, which items have a say). The
card reads through resolve (an item's own value, else the shared one if it
inherits); the editor writes through setLocal, which calls settle.
settle moves where values are written, never what a shown item uses: the
values in use are read first; a strict majority (at least 2 voters, or the only
one) becomes the shared value; a tie keeps the current one; an item using no
value at all blocks the rule (there is no "nothing" to write as its exception);
a pinned key found on top is pushed back down. Hidden marks don't vote and are
left as they are.
MARK_FIELDS is the single table of which mark has which field and whether it
inherits β the editor's fields, the card's resolution and markIds all derive
from it (mark-cascade.test). The Multi card's own merge (multi-rows.ts,
rowConfigsOf) is checked against MULTI_ROWS.resolve (factorization.test),
and a property test holds the invariant over random configs.
Internationalization¶
All user-visible strings live in two module-level constants β 41 languages, 248 leaf keys:
const TRANSLATION_KEYS = ['card.msg.entityNotFound', 'editor.field.unit', β¦]; // stated once
const TRANSLATIONS_FLAT = {
en: ['β¦', 'β¦', β¦], // one value per TRANSLATION_KEYS entry, same order
fr: ['β¦', 0, β¦], // 0 = "same as English" (untranslated or genuinely identical)
β¦
};
Not a per-language nested tree: the key path (editor.field.unit) used to be
repeated in full 39 times, once per language object β restructured (1.6.2) into
a shared key list plus flat value arrays, cutting the shipped bundle by ~27%. A
value identical to English (roughly half of them, mostly untranslated technical
terms) is stored as the sentinel 0 instead of the string again.
- Lookup goes through
HassProviderSingleton.localize('editor.field.unit')β a dot-path resolver over the active language's reconstructed nested tree (buildTranslationTree(), rebuilt once per language load/change, never per lookup β the resolver itself never changed). Missing keys return the key itself (neverundefined), and editor option maps fall back to the default language (CARD.config.language = 'en').
Important
The TRANSLATION_KEYS/TRANSLATIONS_FLAT block in the JS is generated β
never edit it by hand. The source of truth is the per-language JSON files in
translations/ (same card/editor tree, one file per
language code, still fully nested β only the generated JS shape changed). Any
language change β new key, fixed wording, new language β goes through those
JSON files first, then the block is rebuilt into src/utils/translations.js:
# everything goes through the unified toolchain:
node scripts/translations.js add-key editor.field.foo --values foo.json
node scripts/translations.js synchronize --to-js # regenerate the JS block
node scripts/translations.js validate # JSON β JS β template
A hand edit of the JS block would be silently overwritten by the next
regeneration β if it happened anyway, synchronize --to-json backports it
into the JSON files.
The toolchain (node scripts/translations.js, zero dependency) covers the whole
workflow β run it without argument for the full help:
| Command | Purpose |
|---|---|
validate |
Three-way drift report (JSON β JS β template.json), exit 1 on drift β CI-friendly. |
synchronize [--to-js\|--to-json] [--dry-run] |
Apply in either direction; --to-js is the nominal flow. |
orphans |
Heuristic: translated keys never referenced by the code, and localize() paths with no translation. Verify candidates manually (some keys are reached dynamically, e.g. toggle_${childKey}). |
stats |
Per-language coverage vs template.json. |
add-key / rename-key / remove-key |
Cross-language key surgery, order-preserving, template included. |
fill <lang> [--mark] |
Copy missing keys from another language (optionally [TODO]-marked). |
sort |
Normalize key order of every JSON to the template. |
new-lang <code> |
Bootstrap a new language file from en. |
- Every new key must exist at least in
en.json(the fallback), and ideally in every language file β the trees are strictly parallel. - Contributor-friendly rule: an imperfect machine translation beats a missing key β native speakers regularly submit fixes.
Cross-checking wording against Home Assistant's own translations¶
For any string whose concept already exists natively in HA (interaction labels like "Hold behavior", generic action/entity terminology, β¦), HA's own translation is a better reference than translating from scratch β it's what users already see everywhere else in their dashboard, in every supported language, done by HA's own translator community.
home-assistant/frontend's repo only commits src/translations/en.json
directly β the other 60+ languages are managed in Lokalise and never land in
git. But the deployed frontend (e.g. the public demo at
demo.home-assistant.io, no auth needed) serves every language's fully compiled
translations as plain static JSON, fetchable directly:
- Fetch the site's main JS entry chunk (its hashed filename is in the page's
own
<script src="../...">, e.g./frontend_latest/main.<hash>.js). - Search it for the per-language hash table: a JSON-ish literal shaped like
"fr":{"nativeName":"FranΓ§ais","hash":"<32 hex chars>"}β one entry per supported language code. - Build the URL:
https://demo.home-assistant.io/static/translations/<fragment/>/<lang>-<hash>.json.- Omit
<fragment>/for the "core" bundle (most common UI strings). - Use
lovelace/for anything under a Lovelace card/editor (confirmed working:ui.panel.lovelace.editor.card.generic.*,...card.tile.*, and generally anything underui.panel.lovelace.*) β other panels (config/,history/, β¦) likely follow the same pattern, not yet verified.
- Omit
- The result is a flat object β
"ui.panel.lovelace.editor.card.tile.icon_hold_action"as one literal key, not a nested tree. Look the key up directly (find it first in the fetcheden.json/enfragment by searching for the English string you already know).
Warning
Not every language has every string translated in HA itself. When a
language's value is byte-identical to the English one, that's HA's own
untranslated fallback, not a real translation β fetch the en fragment the
same way and diff against it before trusting a value. Copying an English
fallback into our own <lang>.json would silently reintroduce the exact
"shows English in a non-English language" bug this project has repeatedly had
to hunt down.
This only helps for strings that overlap HA's own vocabulary β most of this
project's option-specific wording (bar_effect, watermark, β¦) has no HA
equivalent to check against, so still needs translating from scratch.
Borrowing a label from Home Assistant¶
A key whose concept HA already names stores a pointer rather than a copy, at its
own place in translations/*.json:
"add_entity": "@ui.panel.lovelace.editor.entities.add|Add entity"
The same marker goes in every language file β it is not a translation, so it
folds to the 0 sentinel everywhere but English and costs nothing per language.
HassProviderSingleton's resolveLabel expands it when the translation tree is
built, never at read time: every reader β localize, localizeGroup,
EditorBase#labelFor β receives a finished string, and no call site can reach a
label without the resolution. That property is the point; resolving at each read
is how four label sites once quietly shipped English.
Timing is what makes ui.panel.lovelace.editor.* keys work at all: they live in
HA's lovelace translation fragment, which is absent on a plain dashboard. The
editor half of the tree is only ever built from ensureEditorTranslations(),
called from getConfigElement β with an editor opening, so with the fragment
loaded.
When HA doesn't know a key β an older version, a fragment that never loads β its
localize() returns '' and the English text after the | is used, for that
key alone. See the section above for how to find a key and check it is really
translated in the language you expect.
The translation table is cut in two¶
Roughly 89% of the translated text is editor-only β measured on
translations/*.json, editor.* weighs 114 KB across the 39 languages against
16 KB for card.*. A dashboard that is merely displayed never reads a single
one of those keys, so they do not ship inside the bundle.
The cut is positional. TRANSLATION_KEYS lists every key once;
EDITOR_KEY_START is the index of the first editor.* one, and
scripts/translations.js's editorStartOf refuses to generate anything if a
card.* key ever lands after it β the whole scheme is one slice() on both
sides, so the two groups have to stay contiguous.
What the generated src/utils/translations.js exports, and who reads it:
| binding | ships in the bundle | read by |
|---|---|---|
TRANSLATION_KEYS |
yes | hass-provider.ts |
EDITOR_KEY_START |
yes | hass-provider.ts |
TRANSLATIONS_CARD |
yes, 41 languages | hass-provider.ts |
TRANSLATIONS_EDITOR_EN |
yes, English only | hass-provider.ts |
TRANSLATIONS_EDITOR |
no | scripts/build.js |
Nothing under src/ imports TRANSLATIONS_EDITOR, so esbuild drops it.
scripts/build.js writes it out instead as one file per language,
dist/entity-progress-card-<lang>.json, a positional array carrying the same
0 sentinels as the bundled half β 1 to 2 KB gzipped each. English has no file:
it stays in the bundle as the fallback dictionary every other language resolves
its sentinels against, which is also what a failed fetch falls back to.
knip.json excludes the generated file from lint:unused for that same reason:
TRANSLATIONS_EDITOR is an unused export on purpose, and knip has no way to
know it.
That "nothing imports it" is an assumption no type checker can hold, and
breaking it silently adds ~110 KB to every install, so
scripts/check-i18n-split.js asserts it against the built bundle β the shipped
file must not contain a non-English editor label, and every language's file must
sit beside it with the expected length. check:github runs it after
build:prod, check:push again after the dev build.
The editor file¶
The editors ship beside the bundle, in <stem>-editor.js, and load the first
time one opens β the way Home Assistant loads its own cards' editors. A
dashboard never downloads, parses or compiles them.
What both files need exists once, in the bundle. scripts/build.js runs three
passes:
- Find the seam: build
src/index.tsandsrc/editor/entry.tsfor their metafiles only. Every card module an editor-only module imports is shared. Nothing lists them by hand. - The bundle:
src/index.ts, then a table holding those modules (import * as), frozen underglobalThis[Symbol.for('epb-host:<stem>:<VERSION>')]. The key carries the file and the version: a dev and a prod bundle loaded side by side never read each other's table, and an editor file left over from another version finds none. The first copy wins and the slot is locked (non-writable, non-configurable): a second load of the same version β HACS plus a manual resource β keeps the table of the bundle whose cards actually registered, and no later script can swap it. - The editor file:
src/editor/entry.ts, with a plugin that turns every import of a shared module into a read of that table. A table that is missing throws while the file evaluates.
The build then fails if any module was bundled into both files: a second
HassProviderSingleton, a second schema, a second set of shared stylesheets
would all look fine until they drifted. Neither file has an import or export
statement left, so both still load as a classic script (#108).
src/ knows none of this: src/editor/ imports ../card/schema.js like any
other module, and the tests bundle it that way β a DOM test that mounts an
editor imports src/editor/entry.js itself. test/bundle-suite.ts is the one
that loads the real pair from dist/, the editor file after the bundle.
Loading the editor¶
HACore.getConfigElement is async: it imports the editor file, unless its
elements are already defined, and awaits
HassProviderSingleton.ensureEditorTranslations() alongside. One import serves
the page; a failed one is retried at the next opening. A failure, or a file that
defined nothing, answers null, and Home Assistant offers its own YAML editor
instead. Home Assistant awaits getConfigElement() on all three element
families β see hui-card-element-editor.ts and its badge/feature twins in
home-assistant/frontend β so the editor element is only created once the
dictionary is in. Nothing is ever rendered in English and swapped afterwards.
Both files are fetched from the directory the bundle itself was served from
(sidecarUrl()): CARD_CONTEXT.moduleUrl (document.currentScript?.src, or
the Resource Timing entry matching CARD_CONTEXT.bundleStem for a module load β
never import.meta, see issue #108), falling back to
/hacsfiles/lovelace-entity-progress-card/. Its query string is the bundle's
own - HACS's hacstag, a dev's ?v= - plus version=<VERSION>: whatever makes
the browser fetch a new bundle makes it fetch new sibling files too, and a
manual install without a query still changes URL with each version.
Failure is not an error state. A 404, a timeout (4 s), a payload of the wrong length β any of these resolve the promise with the editor in English rather than blocking it. The promise itself is the lock, cached per language, so seven element types opened in a row share one request.
Release-side, .github/workflows/release.yaml uploads
dist/entity-progress-card[.-]* as a glob β the pattern deliberately excludes
the _dev build. HACS downloads every asset attached to the release, which is
what puts the editor file and the JSON files next to the bundle in the install
directory.
Adding a new option¶
Naming rules¶
Two naming layers coexist by design, not by accident: these rules govern every
new option, while the existing YAML surface is constrained by backward
compatibility with dashboards already written against it β renaming or reshaping
a shipped key is a breaking change (rule 6 below), so pre-rule options are kept
as-is rather than retrofitted. color vs bar_color and disable_unit vs
frameless predate these rules and stay exactly as shipped;
watermark.disable_low/disable_high (a negative boolean, rule 2) is the same
case but has since been reshaped into low/high: false - the old form still
works as a migrated alias. Every new option must follow these rules, so the
gap between "what's possible now" and "what's actually out there" stops growing:
- Family prefix: options belonging to a visual family share its prefix β
bar_*,icon_*,badge_*. A bare name (color) is ambiguous forever. - No negative booleans:
show_x: false, neverdisable_x/hide_x. - Nested object as soon as an option has β₯ 2 sub-settings
(
alert_when: {above, color}), never sibling flat keys (alert_above+alert_color). - Booleans are nouns or adjectives (
text_shadow,frameless), never imperative verbs (force_*). - Values in the entity's native unit by default (like
watermark.low); percent-based needs an explicit*_as: percentcompanion. - Renaming an existing option is a breaking change β add an alias in the negotiation instead, and document the new name as canonical.
Checklist¶
Checklist for a new YAML option, in the order that avoids back-tracking:
- Default β add it to the stub/default config object if it has one
(
CARD.configarea) and decide its default semantics (absent = default; never write the default value into the user's YAML). - Validation β add the property to the relevant schema(s) in
YamlSchemaFactoryusing thetypescombinators (optionalString(),enumsWithDefault(β¦),fallbackTo(β¦, SKIP_PROPERTY), β¦). Remember the negotiation philosophy: invalid input degrades with an editor message, it does not break the card. Card and template schemas are separate β update both if the option applies to both families. - Consumption β read it from the negotiated config
(
this._configHelper.config.<option>) in the view; expose a getter on the view if the element needs it. If the option changes the DOM structure, it must flow through_structureOptionsso theObjStructuretemplate cache keys on it. - Rendering β apply it via
DOMHelper(class toggle, CSS custom property,setText/setHTML). Never touch the DOM directly. If a CSS custom property is only set conditionally, pairsetStylewithremoveStylefor the case where the condition stops holding βsetStylenever unsets a value on its own, so a stale one would otherwise survive into a render where it no longer applies. - Editor β add the field to the relevant
static _fieldsmaps (EditorFactory), withshowIffor conditional visibility andonChange/onClearif the YAML shape differs from the UI shape. A new select type needs an entry inSELECT_TYPES(editor/elements/base.ts) and an option map in the translations. Never restate the allowed values there: point the entry at the schema withfrom(variant, field)β dot paths work (from('card', 'watermark.type')) β so the dropdown lists exactly what that variant validates, in the enum's own order. Only a genuine editor-side restriction (offering less than the schema accepts, likebar_position_density_compact) is written out by hand. - Translations β
editor.field.<name>label (+editor.option.<name>map for selects/chips) vianode scripts/translations.js add-key β¦, thensynchronize --to-js(see Internationalization β never edit the generated JS block directly). - Jinja support (optional) β if the option accepts templates: declare it in
validJinjaFields/_getJinjaHandlers, normalize the pushed result (native types!), and route any HTML rendering throughsetHTML. - Documentation β a section in
docs/configuration.md(badges, type, example, back-to-top link) and a line in the release notes. Thennpm run docs:optionsregenerates the option map: where each option is accepted, edited, documented, shown and tested. - Watched entities β if the option can reference another entity, add it to
_registerWatchedEntitiesso state changes trigger a refresh. - Value-shape/mark reuse β if the option is a value/entity/jinja triad
(like
min_value) or a "mark" (a per-item override falling back to a shared default, likewatermark.low/peak_marker.min), read and write it exclusively through schema.ts's own exported helpers (entityOf/attributeOf/jinjaOffor the triad;markValue/markAs/markType/markOpacity/markColor/isMarkOverridefor marks). Never re-derive the discriminator ('entity' in xvs.'value' in x) ad hoc in a new spot β this exact drift produced the same bug independently in 5+ places in one session before being consolidated onto these helpers. - Legacy migration reach β a migration added to
_migrateLegacyOptionsonly runs for the config helpers whose_customizeConfigactually calls it. Check whether it belongs onBaseConfigHelper(every variant) or is safelyCardConfigHelper-only (Card/Badge/Feature) because the option doesn't exist on Template/Badge Template's schema β getting this wrong silently drops the legacy value instead of migrating it (#140).
Code quality & tooling¶
- Linting (
eslint.config.mjs, flat config):js.configs.recommendedpluseslint-plugin-compat(browser support matrix β see Browser compatibility matrix),eslint-plugin-sonarjs(cognitive-complexitycapped at 15, duplicate-string/collapsible-if/ identical-functions checks), andeslint-plugin-import-x(import-x/ no-cycleβsrc/has real cross-file imports now that the module split exists; nothing currently prevents a future circular import from creeping in except this rule). Notable custom rules:eqeqeq: 'smart'(bans==/!=except thex == nullnull-or-undefined idiom, used once incommon-checks.ts),no-console(onlydebug/info/warn/error/groupCollapsed/groupEndallowed βconsole.logis banned everywhere except one inline-disabled call in the startup banner), andlines-between-class-members: 'always'(no exception for short members β every class member gets a blank line before it).npm run lint/make lint. - Nearly all TypeScript (
tsconfig.json:allowJs,checkJs: falseproject-wide,strict: true):src/is virtually 100%.tsβ the one remaining.jsfile,translations.js, is generated and never hand-edited (see Internationalization)..tsfiles are type-checked bynpm run type-check(tsc, wired intocheck:code).allowJs/checkJs: falsestay in place for the day a.jsfile is added: it can opt into the same checking without converting, via a// @ts-checkpragma plus JSDoc type annotations.eslint.config.mjshas a matching**/*.tsblock (@typescript-eslint/parser+ plugin) alongside the JS one, sharing the same rule set except identifier-resolution rules (no-undef/no-unused-vars), which TS itself already covers more reliably for.tsfiles. esbuild bundles the mixed.ts/.jstree natively β no separate compile step, imports keep the.jsextension even when the real file is.ts(standard TS/esbuild resolution convention). - Formatting:
.prettierrcapplies tosrc/**/*.{js,ts}too (not just markdown) βnpm run format:js/format:js:check/format(JS + MD).embeddedLanguageFormatting: "off"is deliberate: Prettier recognizes thecssidentity tag insrc/utils/styles/css-tag.ts(seescripts/build.js's CSS resolve/minify pass) as CSS-in-JS and would otherwise reformat the CSS text itself inside every tagged template literal, producing a massive diff for a purely cosmetic change.src/utils/translations.jsis excluded via.prettierignore(its own generator serializes it, not Prettier β formatting it here would just drift back out of sync on the nexti18n:sync). - Generated docs:
docs/option-map.mdis written bynpm run docs:options(scripts/option-map.js, which renderstest/docs/option-map.ts). Never edit it by hand:option-map.testfails when it differs from what the generator renders, so a change that moves an option's coverage needs a regeneration. It is in.prettierignore: a reformatted table would never match again. - Pre-commit hooks (
husky+lint-staged,.lintstagedrc.json): stagedsrc/**/*.{js,ts}files getprettier --writetheneslint --fix; staged*.mdfiles getprettier --writethenmarkdownlint-cli2 --fix. Installed automatically via thepreparescript onnpm ci/npm install. - DeepSource also runs as a CI status check (third-party static analysis, separate from ESLint) β treat its findings the same as an ESLint error: fix the root cause, don't suppress unless the finding is a false positive.
make helplists every available target (build, lint, type-check, format, i18n, release-dry-run...) with a one-line description.- Identifier naming (a followed convention, not lint-enforced): classes
PascalCase, functions/methods/variables camelCase, private fields
#camelCase, module-level constant objects (CARD,HA_CONTEXT,SEV, β¦) UPPER_SNAKE_CASE, filenames kebab-case. Distinct from the YAML option surface (snake_case, see Naming rules) β negotiated/ derived config keys deliberately switch to camelCase to mark "computed, not raw YAML":config.resolvedUnit/resolvedDecimal,center_zero's derived{ enabled, zeroValue, growthPercent }shape (config-helpers.ts).
Considered and deferred¶
Ideas that came up, were scoped seriously, and were set aside on purpose β recorded so nobody re-proposes or re-investigates them from zero, and so the reasoning survives a maintainer handoff instead of living only in chat history.
- Incremental editor preview (instead of full reset+render on every
keystroke). Today
HACore.setConfigdoes a fullreset()(shadowRoot.innerHTML = '') +render()on every single editor edit, which is the dominant cost of typing in the visual editor (well past the field-walk itself, already optimized β see Editor architecture). The lever: only reset+render when the DOM structure actually changed; a same-structure value edit (a color, a threshold, a label) could instead go through an incremental update path.ObjStructure.clone's own structure-signature (the same options βbarType/barPosition/layout/bar_size/orientation/center_zero/segments/β¦ β that already decides the<template>cache key, see Rendering & performance) is the natural "did structure change" check to reuse rather than re-derive. Risk: any structural option missing from that reused signature leaves a stale DOM; the incremental path would still need to re-process Jinja and re-register watched entities on every edit, just skip the teardown. Real correction surface, not started. - The progress bar as a standalone "dumb" web component
(
<entity- progress-bar>receiving pre-computed%/color/segments as props, with the calculation engine βHACore/ViewCore/ProgressMathβ living entirely outside it). Verdict: cosmetic for the current architecture, not worth it on its own β the Tile Feature (entity-progress-feature) already plays the role of a reusable bar-only building block for anything that needs one, so a formal smart/dumb split would mostly duplicate that without a concrete consumer needing it. Only worth reconsidering inside a genuine ground-up rendering rewrite, not as a standalone refactor.
Release process¶
- Versioning:
const VERSION = 'x.y.z[-dev]'insrc/utils/parameters.tsis the single source of truth displayed in the console banner; keep it in sync with the git tag.-devmarks unreleased builds.package.json's own"version": "1.0.0"is a deliberately frozen stub β this package is never published to npm (private: true), so it has no consumer; don't bump it,VERSIONabove is the only one that matters. - CI (
.github/workflows/), path-scoped where relevant so a PR only triggers the checks that matter for what it touches:validate-hacs.yamlβ not path-scoped, runs on every push/PR: HACS validation (hacs/action, categoryplugin). Deliberately unscoped β it checkshacs.json/README compliance too, not justsrc/, so a path filter would risk missing a manifest/README-only regression.validate-js.yamlβ onsrc/**/test/**/scripts/**/.github/workflows/**/translations/**/eslint.config.mjs/package.json/package-lock.jsonchanges:npm run check:github, the same gaterelease.yamlruns β whatever would block a release blocks the push that feeds it.validate-i18n.yamlβ ontranslations/**changes:npm run i18n:validate:structure(well-formed JSON + template structure only β no JS sync required, so a translation-only PR isn't blocked on something a contributor can't fix themselves; see Internationalization).validate-md.yamlβ on**/*.mdchanges:npm run lint:md.release.yamlβ on a published GitHub release:node scripts/check-release-tag.jsfirst (the three things a push cannot check, because no tag exists yet: the tag equalsVERSIONinmeta.ts,CHANGELOG.mdhas that version's section, and the tagged commit is reachable frommainβ hence thefetch-depth: 0checkout), thennpm run check:github, then uploads the artifact to the release assets. That single gate opens oncheck:release-flags(safety net β fails if the committedDEBUG_DEFAULTSbaseline has any flag lefttrue;devis URL-derived so it isn't checked here, see Logging & debugging) and ends onbuild:prod(esbuild,--target=es2021, pinned as a devDependency β re-forcesDEBUG_DEFAULTSall-falsein the built output regardless of the source state, seescripts/lib/release-flags.js), anode --checksanity pass on the minified output andnpm run check:es-target(es-check es2022plus the static-block check, catches syntax newer than the language floor thatnode --checkalone can't - Node's own parser is newer than the target, see issue #128). The upload glob,dist/entity-progress-card[.-]*, takes the bundle, its editor file and its language files, never the_devbuild. HACS serves those assets.
- Two build modes (
scripts/build.js, esbuild):build:testβentity-progress-card_dev.js(debug baseline left as committed) andbuild:prod(--prod) βentity-progress-card.js(minified,DEBUG_DEFAULTSre-forced all-false, seescripts/lib/release-flags.js), each with its-editor.jsand-<lang>.jsonfiles beside it (see The editor file).devmode isn't baked into either β it follows the served filename/URL at runtime (see Logging & debugging). Onlybuild:prodis minified and safe to ship. - Language floor: the esbuild target is
es2021, with class features declared native (NATIVE_CLASS_FEATURES) β private fields,??=and optional chaining are fine. esbuild lowers any other newer syntax, classstatic {}blocks included; a build config that stops doing so failsnpm run check:es-targetin the release build, even though its output runs in dev (modern browser) and passesnode --check(Node's parser is newer than the target). Test a release build locally withnpm run build:prod && npm run check:es-targetwhen in doubt. - HACS:
hacs.jsondeclares only thefilename(nocontent_in_rootβ nothing is served from the repo root). HACS installs from the release assetrelease.yamluploads; there is no in-repo fallback file, matching how other HACS plugins (e.g. Mushroom) ship a puresrc/+ release setup. - Release notes are drafted in
CHANGELOG.mdduring the RC cycle, then promoted to the GitHub release body. docs/images/is content-addressed and append-only. README.md is the only doc HACS renders in its own in-app viewer, and that viewer needs absoluteraw.githubusercontent.com/.../main/...URLs to resolve at all β every other doc (cookbook/theme/troubleshooting/...) is only ever viewed on GitHub directly, where a relative path (images/x.png) resolves against the ref actually being browsed, tag included - so those use relative paths instead. Absolute URLs resolve againstmainat view time, not at the tag's commit β a tagged release's README text is frozen, but its image URLs keep followingmainforever, so renaming or replacing a file under its existing name silently breaks every past release's README (issue found post-1.6.1:RVB.png,stack.png, and others were renamed/replaced in place). The fix, applied uniformly across every doc (not just README) so nothing needs re-thinking the day an image moves between docs: every file actually referenced anywhere is named<name>-<sha256:6>.<ext>(computed once withsha256sum file | cut -c1-6, no script) β same content always yields the same hash, so a real content change always produces a new filename instead of overwriting one an old release still points to. Never delete or overwrite a file already referenced anywhere; add a new hashed file and repoint current docs to it instead. Optimize losslessly before hashing (optipng -o7for PNG; verified pixel-identical output, including its palette/grayscale color-type conversions) -gifsicle -O3merges duplicate GIF frames instead, changing frame count/timing rather than pixels, so it's excluded until that's verified too.
Logging & debugging¶
dev/suffix/debug/noRegistration live in CARD_CONTEXT
(src/utils/parameters.ts).
- dev (
-devsuffix on every registered element name, so a dev build coexists with the shipped one) is baked in per build (__EPB_DEV_BUILD__, injected byscripts/build.jsβtrueinentity-progress-card_dev.js,falsein the shipped file), not URL-derived. This is also whydocs/demo-dashboard-dev.yamlexists as its own file rather than a URL flag ondemo-dashboard.yaml: every card type in it carries the same-devsuffix, so it only renders against the dev build, side by side with a production install. The-devfile is a superset: every showroom view exists in both, card for card,-devsuffixes as the only difference β and the two views nobody but a developer opens (the regression bench, one card per closed bug, and the deprecated-options bench) live in the-devfile alone. A bug is confirmed fixed against a dev build, never against the shipped one, so its card has no reason to reach a user's dashboard. A dev build can't be shipped by accident, and HACS's own?hacstag=β¦doesn't trigger it.?dev=trueis an optional runtime override on the prod file on top of that baked value, for testing dev behavior against the exact shipped bundle. - suffix (
?suffix=rc) renames and nothing else: every element, editor and card-picker entry of that copy gets-rc/(rc), and its diagnostic becomesEPB_RCβ a test copy of the shipped file beside a HACS install, no dev build needed (docs/rc-testing.md, Advanced). Lowercase letters and digits, 16 at most, or it is ignored; a dev build defaults todev(suffixOf). Every tag goes throughsuffixedName(). One limit: two copies of the same version share one host table (its key is fixed at build time), so the second one's editors never register. - debug (
?debug=area1,area2, or?debug=all) turns on per-area console logging at runtime, no rebuild, and works against the shipped file too.EPB.debug('a,b')saves areas inlocalStorage(one key per suffix), merged with?debug=at load; flags are read once, so a change waits for a reload. The committed baseline isDEBUG_DEFAULTS(all-false) β both only ever turn flags on.check-release-flags.jsverifiesDEBUG_DEFAULTSis all-false andbuild:prodre-forces it, so verbose logging can't ship. ?noRegistrationloads the whole module (banner,EPB, everything) but defines zero custom elements and pushes nothing tocustomCards/Badges/Featuresβ a diagnostic knob for telling apart "the bundle loading at all" from "the bundle registering itself" when chasing a freeze/clash (issue #108's own troubleshooting flow). URL-derived only, off unless asked.- Why
?dev/?debug/?noRegistrationreaddocument.currentScript.src, neverimport.meta.url: a bareimport.metais a parse-timeSyntaxErrorwhen the bundle is loaded as a classic<script>(a resource typedjsinstead ofmodulein HA, orbrowser_modre-loading it inside a popup) β it kills the whole module before anytry/catchcan even run, which is exactly what issue #108 turned out to be: a silent freeze with no console error, because the failure happens before the module's own error handling exists. Never reintroduceimport.metaanywhere insrc/.document.currentScript.srcis populated for a classic-script load andnullfor an ES-module load (import(), the real HACS/"JavaScript Module" path) β in the latter caseMODULE_URLreads the bundle's own URL off the stack of anErrorcreated while it loads (scriptUrlFromStack): a frame names the exact file it runs from, query string included, in Chrome, Firefox and Safari. Two copies with one file name β a stable and a?suffix=test one β each find their own. The Resource Timing API is the last resort (performance.getEntriesByType('resource')), matching the first script entry whose path ends with this exact build's own filename (entity-progress-card(_dev)?.js,isBundleEntry). Script only, and the end of the path, not anywhere in the URL: the editor file is imported from beside that URL, so an image or a fetch carrying the same name must never get to pick where executable code comes from. Still anchored to the resource's own URL either way, never the dashboard page's URL.CARD_CONTEXT.classicScript(document.currentScript !== null) is a separate signal, used to show a one-time console nudge toward switching the resource to "JavaScript Module" β the classic type still loads fine now, but stays deprecated by HA. - The editor file reads none of this itself.
CARD_CONTEXTlives inparameters.ts, one of the modules it reads off the bundle's host table: the same object, so?debug=,?dev=true,?suffix=and?noRegistrationset on the resource reach the editors too, and their suffixed tags always match the cards'. The file itself loads under the resource's own query string plusversion=<VERSION>, for the cache only - nothing reads it. - A console warning is printed after the load banner whenever dev or any debug area is active (listing the active areas), so a non-shipped configuration never runs silently. Normal prod loads stay quiet.
Debug areas (each traces via a Logger that wraps the class's
_loggedMethods β π / β
/ β with timing β or logs directly):
| Area | Wired in | Traces |
|---|---|---|
card |
HACore/HABase (core/) |
lifecycle (connect / disconnect / adopted / setConfig / refresh / render) |
editor |
EditorBase (editor/elements/base.ts) |
setConfig in, config-changed out |
interactionHandler |
ActionHelper (dom-helpers.ts) |
tap / hold / double-tap action resolution |
ressourceManager |
ResourceManager/DOMHelper |
timers / listeners / subscriptions |
hass |
HassProviderSingleton |
first hass (HA version, language, connection), language change |
registration |
RegistrationHelper (register.ts) |
every define (ok/skipped) + customCards push, with timing |
instances |
value-helper + view class constructors | per-class instantiation counter (traceInstance, leak probe) |
interference |
HACore MutationObserver on the host |
external mutations of our own host element (card-mod &c) |
To add a debug area: add it to DEBUG_DEFAULTS and the CARD_CONTEXT.debug
object (parameters.ts), the CLEAN_DEBUG_DEFAULTS_BODY literal
(scripts/lib/release-flags.js), then consume CARD_CONTEXT.debug.<area> where
you need it (via initLogger/traceInstance, or a module-level
Logger.create).
Other aids:
- The console banner printed at load confirms which version is actually running
(cache issues are the #1 support topic).
window.EPBis the console helper:EPB.version,EPB.help(), andEPB.doctor.dump(), an anonymized environment/registration report -EPB_DEVin a dev build,EPB_RCunder?suffix=rc, so copies loaded side by side each keep their own. Published once and locked (diagnostic.ts);EPB_DIAG, its 1.6.2 name, stays as an alias that points to it. The dump'seditorline says where the editor file is loaded from and whether it loaded (loadEditor,hass-provider.ts). With no card of ours on screen yet, it reads hass off Home Assistant's root element (currentHass), and so doesEPB.doctor.audit(), which lists every card, on every dashboard, with deprecated options or options without effect (card-audit.ts).EPB.doctor.cards()and.inspect(n | $0)(card/diagnostics/doctor.ts) walk every shadow root for cards of ours, a Multi's rows included;inspectclimbs from any element inside a card to it, and reportsViewBase.drawnFrom- the value and range the bar is drawn from..jinja()lists a card's Jinja fields with HA's last answer (JinjaSubscriptions.diagnose),.history()the samples of its trend and peak trackers.dump()is async: it adds a SHA-256 of both files, fetched again. - The editor's bug icon copies an issue report (
issueReportFor, doctor.ts):environmentReport()(whatdump()prints, without the digests: Safari refuses a clipboard write after an await), then the YAML Home Assistant holds, written bycard/diagnostics/yaml-writer.tswithnotesByPathcomments and a# drawn from:line read off the dialog's preview (drawnOfPreview). Multi rows don't offer it.EPB.doctor.copy(n | $0)builds the same report from the console, hence the writer in the bundle. - Logger and
?debug=instancesnames are passed explicitly (initLogger,traceInstance), never read fromconstructor.name: the prod build minifies class names. An element passes itslocalName(the tag), a helper a literal;?debug=instancescounts per root class. window.customCardscan be inspected to verify registration.- In DevTools, a card's shadow root should contain no
<style>element on modern browsers (adopted stylesheet) β seeing one means the fallback path was taken.