Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
e8977143c5 | ||
|
|
30138df1a5 | ||
|
|
16ea0267d7 | ||
|
|
4a879e84bd | ||
|
|
01b4247cf3 |
@@ -38,6 +38,14 @@ Designed and optimised for the Sonoff NSPanel Pro 120 in landscape mode, but wor
|
||||
3. Go to **Settings → Dashboards → Resources** and add `/local/perfectdraft-card/perfectdraft-card.js` as a JavaScript Module
|
||||
4. Refresh your browser
|
||||
|
||||
### Confirming which version is running
|
||||
|
||||
Browsers cache dashboard resources aggressively, so after an update it is worth
|
||||
checking which bundle actually loaded. The card logs a `PERFECTDRAFT-CARD
|
||||
v<version>` banner to the browser console on load. If that version is not the one
|
||||
you installed, hard-reload the page (Ctrl/Cmd + Shift + R) — the card behaviour
|
||||
you are seeing is the old bundle's, not the new one's.
|
||||
|
||||
## Configuration
|
||||
|
||||
**No YAML editing required.** Add the card through the HA dashboard UI:
|
||||
@@ -53,10 +61,26 @@ The card identifies the tapped beer from the integration's keg sensors, matching
|
||||
on the keg's product ID first and its reported name second. When no keg is
|
||||
tapped, the card says so rather than showing a beer.
|
||||
|
||||
If your keg is not recognised, or is shown as the wrong beer, set **Beer
|
||||
override** in the card editor (or `beer_name` in YAML). That wins over detection.
|
||||
Reports of unrecognised kegs are welcome as issues — the fix is usually a
|
||||
one-line catalog addition.
|
||||
If your keg is not recognised, or is shown as the wrong beer, use **Correct the
|
||||
beer for the keg in the machine** in the card editor. The correction is saved
|
||||
against that keg's product ID (`beer_overrides` in YAML), so it applies while
|
||||
that keg is tapped and stops applying when you swap kegs — a correction can
|
||||
never outlive the keg it was for. The card marks any beer it is showing because
|
||||
of a correction, so an override is never mistaken for a detection result.
|
||||
|
||||
Reports of unrecognised or mis-detected kegs are welcome as issues — the fix is
|
||||
usually a one-line catalog addition, which is better for everyone than a local
|
||||
correction.
|
||||
|
||||
#### Upgrading from 0.3.x or earlier
|
||||
|
||||
`beer_name` is no longer supported and is ignored when present. Versions before
|
||||
0.3.0 required it — the editor always wrote it and new cards were seeded with
|
||||
it — and 0.3.1 then treated those leftover values as permanent overrides, which
|
||||
made cards show a beer that was no longer in the machine. Ignoring the key
|
||||
returns those cards to auto-detection. No automatic migration is possible,
|
||||
because the old value records no product ID; re-apply the correction from the
|
||||
editor if you still need it.
|
||||
|
||||
### YAML reference (for power users)
|
||||
|
||||
@@ -65,9 +89,10 @@ type: custom:perfectdraft-card
|
||||
device_id: "perfectdraft_pro"
|
||||
glass_size: 330
|
||||
layout: landscape # landscape | portrait | compact | hero | vessel
|
||||
# beer_name: "Leffe Blonde" # override auto-detection; normally leave unset
|
||||
# matrix_columns: auto # "auto" or a fixed number of emoji columns
|
||||
# max_matrix_width: "480px" # cap + centre the emoji grid on wide cards
|
||||
# beer_overrides: # corrections keyed by keg product ID; normally unset
|
||||
# "1095": "Leffe Ruby" # applies only while that keg is tapped
|
||||
# custom_beers:
|
||||
# - name: "My Homebrew IPA"
|
||||
# brewery: "Home"
|
||||
|
||||
Vendored
+153
-49
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 145 KiB After Width: | Height: | Size: 145 KiB |
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-16
|
||||
@@ -0,0 +1,105 @@
|
||||
## Context
|
||||
|
||||
0.3.1 resolves the displayed beer through four rungs: the `beer_name` config override, a catalogue entry matched on the `keg_product_id` sensor, a beer resolved from the `keg_name` sensor, then the no-keg state. Rung 1 is unconditional and permanent, and that is the defect. The override records "the beer currently in my machine is detected wrongly" but stores it as a global config value with no link to that keg, so it keeps asserting itself after the keg is gone.
|
||||
|
||||
Two populations hit this. Cards configured before 0.3.0 all carry a `beer_name`, because the ≤0.2.0 editor's "Default Beer" select had no auto option and `getStubConfig` seeded `beer_name: "Stella Artois"`. 0.3.0 deleted the key and ignored it; 0.3.1 revived the same key with inverted semantics, reactivating those dormant values as detection overrides. The second population is anyone who sets an override correctly today — their card goes wrong at the next keg change.
|
||||
|
||||
The binding constraint on any fix: a Lovelace card cannot rewrite its own config. `config-changed` is only honoured while the editor dialog is open, so the card cannot expire or clean up a stale override even when it can prove one is stale. Staleness has to be structurally impossible, or visible enough that the user clears it.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- A stale override becomes inert without anyone editing config.
|
||||
- Auto-detection is what an upgraded card does, regardless of what earlier versions wrote into its YAML.
|
||||
- The escape hatch survives: a keg the catalogue maps to the wrong beer, or does not know at all, can still be corrected without hand-editing YAML.
|
||||
- The card never silently displays a beer that contradicts what the machine reports.
|
||||
- The 0.3.1 no-keg honesty property is preserved: no configured value can make the card name a beer that is not in the machine.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Correcting the catalogue itself. A mis-mapped product ID should still be reported upstream and fixed in `beer-catalog.ts`; the override is a local stopgap, not a substitute.
|
||||
- Any change to the integration. Its sensors and `keg_catalog.json` remain a fixed upstream contract.
|
||||
- Reinstating the in-card beer picker dialog. Corrections belong in the config editor, as decided in the previous change.
|
||||
- Migrating legacy `beer_name` values to the new key. See decision 2.
|
||||
- Per-keg glass size, freshness or layout scoping. Only beer identity is keg-scoped.
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. The override is keyed by product ID
|
||||
|
||||
`beer_overrides` is a map from the product ID string the integration reports to a beer name resolved through the existing `resolveBeer` path (catalogue name, slug, or `custom_beers` entry):
|
||||
|
||||
```yaml
|
||||
beer_overrides:
|
||||
"1095": "Leffe Ruby"
|
||||
```
|
||||
|
||||
An entry applies only while `keg_product_id` reports that ID. Swap the keg and the key stops matching, so the correction expires on its own with no writes — which is what makes it viable under the can't-persist constraint. A stale entry costs nothing but a line of YAML, and it becomes useful again if that keg is ever tapped a second time.
|
||||
|
||||
The previous change considered and rejected this shape as "a new config surface for a rare case, and it cannot help when the ID is unresolved." The first half is now outweighed: the global key's unbounded lifetime is a correctness bug, not a convenience question. The second half was too quick — an ID that the *catalogue* does not recognise is still a perfectly good map key, and that is precisely the common case for a new beer. The genuine gap is narrower: a machine whose `keg_product_id` is missing or unavailable cannot be corrected this way. Rung 3 (the reported name) already covers that case, and the no-keg state covers the rest.
|
||||
|
||||
Rejected alternatives:
|
||||
|
||||
- **Keep the global key, gate it with a `config_version` stamp.** Distinguishes legacy values from deliberate ones, which solves the migration but not the recurrence: a deliberate override still goes stale at the next keg change. It also adds a config field whose only purpose is to compensate for a key having had two meanings.
|
||||
- **Rename the global key** (e.g. `beer_override`). Same objection — it fixes the name collision and nothing about lifetime.
|
||||
- **Demote `beer_name` to a fallback that applies only when nothing is detected.** Cheap, and stale values become harmless. Rejected because it discards the escape hatch entirely — a keg detected as the wrong beer cannot be corrected at all — and it regresses the no-keg state back to naming a beer that is not in the machine.
|
||||
|
||||
### 2. Legacy `beer_name` is ignored, not migrated
|
||||
|
||||
Reading the old value into the new map is impossible to do correctly: `beer_name` carries no record of which keg it was for, so there is no ID to key it under. Guessing the currently reported ID would silently manufacture an override the user never asked for, which is the present bug wearing a new key name.
|
||||
|
||||
So `beer_name` joins `beer_entity` as a key the card ignores without throwing. There is a precedent for exactly this in `card-config`: `beer_entity` was removed in the same commit that removed `beer_name`, and it got the ignore treatment while `beer_name` was resurrected instead. This restores the symmetry.
|
||||
|
||||
The cost falls on anyone who set an override deliberately during 0.3.1's lifetime: their card reverts to auto-detection. That is a short window, the reverted behaviour is correct for most of them (the catalogue now covers all 114 upstream IDs), and re-applying the correction is one editor action. A README upgrade note covers it.
|
||||
|
||||
### 3. An override that contradicts detection is shown, not hidden
|
||||
|
||||
When an override is active, the card SHALL indicate it, and the indication SHALL carry the name detection resolved so the two are comparable. This is what turns a future stale override from an unexplainable wrong card into something a user can diagnose without reading YAML.
|
||||
|
||||
Keep it small: a compact marker adjacent to the beer name, not a dialog. The marker appears whenever an override is applied — including when it agrees with detection, since an agreeing override is still a value the user should know is there. Rejected alternative: show the marker only on disagreement. Slightly quieter, but it hides the override in exactly the case where it is redundant and should be deleted.
|
||||
|
||||
The existing `freshness-indicator` element is the styling precedent for a compact status pill on the card.
|
||||
|
||||
### 4. Overrides do not apply in the no-keg state
|
||||
|
||||
With no keg reported there is no product ID, so no map entry can match and the card falls through to "no keg detected". This is a property of decision 1 rather than a rule to implement, and it is worth stating as a requirement so a future refactor cannot quietly reintroduce a configured value that names an absent beer.
|
||||
|
||||
### 5. Overrides live in config, not `localStorage`
|
||||
|
||||
Glass size is stored per-browser in `localStorage` because it is a personal preference. A keg correction is a fact about the machine and the catalogue, so it belongs in config: shared across every browser and dashboard, visible in YAML, reviewable, and portable. Storing it per-browser would make two people looking at the same dashboard see different beers.
|
||||
|
||||
### 6. The editor writes the override from the live product ID
|
||||
|
||||
`_discoverDevices` already builds a `translation_key → entityId` map per device, so `entities.get("keg_product_id")` gives the editor the sensor directly and `hass.states[...]` gives the live value. The 120-entry dropdown is replaced by an action scoped to what is currently tapped — "this keg is detected wrongly" — plus a beer selector, writing a single `beer_overrides` entry keyed by that ID.
|
||||
|
||||
The editor also lists existing entries with the beer each names and a remove control, which is how a stale entry from a previous keg becomes visible and clearable. When no product ID is currently reported, the action is disabled with a short explanation rather than hidden, so the feature is discoverable before it is needed.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **A machine that reports no usable `keg_product_id` cannot be corrected.** → Rung 3 already renders the integration-reported name, and the honest no-keg state covers the rest. Accepted as a documented limitation rather than adding a second, name-keyed override surface for a case that may not exist in practice.
|
||||
|
||||
- **`beer_overrides` is a nested map, which is harder to hand-write than a flat string and easy to get wrong** (unquoted numeric keys, wrong ID). → The editor is the supported path and writes the ID itself. An entry whose key never matches is inert, so the failure mode of a typo is "override does nothing", not a wrong beer.
|
||||
|
||||
- **Users who set `beer_name` deliberately in 0.3.1 lose their setting on upgrade.** → Ignored rather than erroring, called out in the README upgrade note, and re-applied with one editor action. Weighed against leaving every pre-0.3.0 card silently misidentifying its keg.
|
||||
|
||||
- **Stale entries accumulate in config over time.** → They are inert and small. The editor's list makes them visible, and the alternative — the card pruning them — is precluded by the can't-persist constraint.
|
||||
|
||||
- **The override marker adds visual noise to a card whose layouts are already dense**, particularly `compact`. → It is a small pill following the `freshness-indicator` precedent, and it only renders when an override is actually applied, which is rare by design.
|
||||
|
||||
- **The keg-scoped editor action reads live sensor state, coupling the editor to entity resolution that currently lives in the card.** → The editor already resolves the same entities by `translation_key` for device discovery; this reads one more key from a map it has already built. If that duplication grows, extracting a shared resolver is a separate refactor.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Types and detection: add `beer_overrides`, remove `beer_name`, ignore it when present, and rewrite the precedence in `_updateDetectedBeer`. At this point every existing card reverts to auto-detection — the behaviour fix lands here on its own.
|
||||
2. The override marker in the label and the layouts that show beer identity.
|
||||
3. The editor: keg-scoped correction action plus the existing-overrides list, replacing the dropdown.
|
||||
4. Spec deltas, README (`beer_overrides`, ignored `beer_name`, upgrade note), version bump to 0.4.0 and rebuilt bundle.
|
||||
|
||||
Rollback is a bundle revert. Since step 1 only ignores a key, a card configured under 0.4.0 stays loadable on 0.3.1 — `beer_overrides` is unknown there and ignored, and the card falls back to detection, which is the same behaviour minus the correction.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- ~~Exact wording and placement of the override marker per layout, especially `compact` and `vessel`, where horizontal space is tight.~~ Resolved in implementation: `landscape` and `portrait` carry the pill in the label zone, `hero` in the scrim, `vessel` under the count. `compact` has no room for a pill, so it prefixes the name with a `⚙` glyph carrying the same explanation in its tooltip. The pill is `inline-block` with a `currentColor` border so it shrink-wraps and reads against both the dark card and the light end of the label palettes.
|
||||
- Whether the editor's beer selector for a correction should offer the full catalogue or bias toward the detected beer's brewery, which is where sibling mis-mappings cluster.
|
||||
- Whether a mis-mapping corrected locally should prompt the user to report it upstream, given the fix belongs in the catalogue rather than in every affected user's config.
|
||||
@@ -0,0 +1,35 @@
|
||||
## Why
|
||||
|
||||
The `beer_name` override reinstated in 0.3.1 has no connection to the keg it corrects, so it outlives that keg and silently misidentifies every later one. This is not hypothetical: a user upgrading from 0.2.0 reported the card showing "Leffe Blonde" while the machine's `keg_name` sensor read "Leffe Ruby". The cause was a dormant `beer_name: Leffe Blonde` in their card YAML, written by the ≤0.2.0 editor — whose "Default Beer" select had no auto option and always wrote the key, with `getStubConfig` seeding `beer_name: "Stella Artois"` on card creation. Every card configured before 0.3.0 therefore carries a value that 0.3.1 promoted into a permanent, invisible detection override.
|
||||
|
||||
Dropping the legacy value alone would not fix this. A global override is stale by construction: a user who legitimately sets one today to correct a mis-detected keg gets a wrong card the moment they swap kegs, with nothing on screen explaining why. The card cannot self-heal, because `config-changed` is only honoured while the editor dialog is open — a card cannot rewrite its own Lovelace config. Staleness must therefore be made structurally impossible rather than cleaned up after the fact.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Scope the manual override to the product ID it corrects, via a new `beer_overrides` map keyed by product ID (e.g. `{ "1095": "Leffe Ruby" }`). An override applies only while the machine reports that ID, so swapping kegs makes it inert with no writes required.
|
||||
- **BREAKING (repair)** — `beer_name` is removed as a config key and ignored when present, joining `beer_entity` in the ignored-keys list. Auto-detection becomes the default for every existing card, which is the behaviour users upgrading from ≤0.2.0 expect.
|
||||
- Surface disagreement instead of resolving it silently: when an active override names a different beer than detection resolved, the card SHALL indicate that an override is in effect.
|
||||
- An override SHALL NOT apply in the no-keg state. With no keg reported there is no ID to match, so the honest "no keg detected" state introduced in 0.3.1 is preserved rather than being papered over by a stale name.
|
||||
- Replace the editor's 120-entry "Beer override" dropdown with an action scoped to the currently detected keg — "this keg is detected wrongly" — which captures the reported product ID and writes the map entry. Unrecognised IDs are still valid keys, so this covers kegs the catalogue does not know.
|
||||
- `custom_beers` stays reachable, now as an override target resolved through the same name/slug/custom path.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
None. This change modifies the requirements of existing capabilities.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `keg-auto-detection`: Detection precedence changes. The unconditional `beer_name` override at rung 1 is replaced by a product-ID-scoped override that applies only when the reported ID matches an entry in `beer_overrides`. The "Override wins over successful detection" scenario is restated in scoped terms, override behaviour in the no-keg state is specified, and a requirement is added to surface an override that contradicts detection.
|
||||
- `card-config`: `beer_name` moves from a supported key to an ignored legacy key. `beer_overrides` is added as a product-ID-keyed map. The unknown-override-name scenario is restated against the new key, `custom_beers` is redocumented as an override target, and the editor's beer field is respecified as a keg-scoped correction action.
|
||||
|
||||
## Impact
|
||||
|
||||
- `src/types.ts` — remove `beer_name`, add `beer_overrides?: Record<string, string>`.
|
||||
- `src/perfectdraft-card.ts` — `_updateDetectedBeer` precedence, override-conflict state for the label, no-keg interaction.
|
||||
- `src/editor.ts` — replace the beer dropdown with the keg-scoped correction action; needs the live product-ID state, which the editor does not read today.
|
||||
- `src/beer-catalog.ts` — no change expected; `resolveBeer` already handles name, slug and custom entries.
|
||||
- `README.md` — document `beer_overrides`, state that `beer_name` is ignored, and add an upgrade note for users coming from ≤0.2.0 whose cards carry the key.
|
||||
- `package.json` / `dist/perfectdraft-card.js` — minor version bump to 0.4.0 (config-breaking) and rebuilt bundle. The bundle's console banner is the only way a user can confirm which build is running, and 0.3.0 shipped without a bump, so the bump is load-bearing for supportability.
|
||||
- No integration dependency change: still PerfectDraft integration 0.4.0+ for the keg sensors.
|
||||
@@ -0,0 +1,98 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Keg-scoped beer overrides configuration
|
||||
The card SHALL accept an optional `beer_overrides` config map, keyed by the product ID the integration reports, so a correction is bound to the keg it corrects.
|
||||
|
||||
#### Scenario: Map shape
|
||||
- **WHEN** a `beer_overrides` value is provided in config
|
||||
- **THEN** each key SHALL be the product ID string as reported by the `keg_product_id` sensor
|
||||
- **THEN** each value SHALL be a beer name resolvable against the catalog, a catalog slug, or the `name` of a `custom_beers` entry
|
||||
|
||||
#### Scenario: Overrides absent
|
||||
- **WHEN** the card config has no `beer_overrides`
|
||||
- **THEN** the card SHALL rely entirely on auto-detection
|
||||
- **THEN** `getStubConfig()` SHALL NOT populate `beer_overrides`, so newly created cards start with detection only
|
||||
|
||||
#### Scenario: Entry recorded against the currently tapped keg
|
||||
- **WHEN** the user corrects the detected beer from the visual editor
|
||||
- **THEN** the editor SHALL write a single `beer_overrides` entry keyed by the product ID currently reported for the configured device
|
||||
- **THEN** the editor SHALL NOT write an entry that is not keyed by a reported product ID
|
||||
|
||||
#### Scenario: No product ID currently reported
|
||||
- **WHEN** the visual editor is displayed AND the configured device reports no usable `keg_product_id` state
|
||||
- **THEN** the correction control SHALL be shown in a disabled state with an explanation that a keg must be detected first
|
||||
- **THEN** the editor SHALL NOT be prevented from displaying or removing existing entries
|
||||
|
||||
#### Scenario: Existing entries are reviewable and removable
|
||||
- **WHEN** the visual editor is displayed AND `beer_overrides` contains entries
|
||||
- **THEN** the editor SHALL list each entry with the product ID and the beer it names
|
||||
- **THEN** the editor SHALL provide a control to remove an individual entry
|
||||
- **THEN** removing the last entry SHALL remove `beer_overrides` from the config
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Configuration validation
|
||||
The card SHALL validate its configuration and display clear errors for invalid config.
|
||||
|
||||
#### Scenario: Missing device configuration
|
||||
- **WHEN** the card config has no `device_id`
|
||||
- **THEN** the card SHALL throw an error during `setConfig()` that triggers HA's built-in error card display
|
||||
- **THEN** the error message SHALL instruct the user to configure the card via the visual editor
|
||||
|
||||
#### Scenario: Invalid glass_size value
|
||||
- **WHEN** the card config specifies a `glass_size` that is not one of the supported values (250, 330, 500, 568, 473)
|
||||
- **THEN** the card SHALL fall back to the default of 330 mL
|
||||
|
||||
#### Scenario: Unknown beer name in an override entry
|
||||
- **WHEN** a `beer_overrides` entry whose key matches the reported product ID names a beer that matches nothing in the catalog (built-in or custom)
|
||||
- **THEN** the card SHALL treat it as a custom beer with that name and use a generic color palette
|
||||
- **THEN** the card SHALL NOT fall back to auto-detection, since a matching override signals the user's intent
|
||||
|
||||
#### Scenario: Override entry with a malformed key
|
||||
- **WHEN** a `beer_overrides` key does not correspond to any product ID the machine reports
|
||||
- **THEN** the card SHALL ignore that entry without throwing
|
||||
- **THEN** the card SHALL resolve the beer by detection
|
||||
|
||||
#### Scenario: Removed configuration keys ignored
|
||||
- **WHEN** the card config contains `beer_entity` or `beer_name`, neither of which is supported
|
||||
- **THEN** the card SHALL ignore them without throwing
|
||||
- **THEN** the card SHALL resolve the beer by detection as though the key were absent
|
||||
|
||||
### Requirement: Visual card editor
|
||||
The card SHALL provide a graphical configuration editor as the primary means of configuration.
|
||||
|
||||
#### Scenario: Editor registration
|
||||
- **WHEN** `getConfigElement()` is called on the card class
|
||||
- **THEN** it SHALL return a custom element that renders a configuration form
|
||||
- **THEN** `getStubConfig()` SHALL return a minimal valid configuration for new card creation (auto-selecting the sole device if only one exists)
|
||||
|
||||
#### Scenario: Editor fields
|
||||
- **WHEN** the visual editor is displayed
|
||||
- **THEN** it SHALL provide: a device picker (dropdown of discovered PerfectDraft devices), glass size (dropdown of five options), layout selection, and a correction control scoped to the currently detected keg
|
||||
- **THEN** all fields SHALL be UI controls — no freeform text input for entity IDs or product IDs
|
||||
- **THEN** the editor SHALL NOT present beer selection as a required or default setting
|
||||
- **THEN** the editor SHALL NOT offer a beer setting that applies regardless of which keg is tapped
|
||||
|
||||
#### Scenario: Editor fires config-changed events
|
||||
- **WHEN** the user changes any editor field
|
||||
- **THEN** the editor SHALL fire a `config-changed` custom event with the updated config
|
||||
- **THEN** the card preview SHALL update to reflect the change
|
||||
|
||||
### Requirement: Custom beers configuration
|
||||
The card SHALL support extending the beer catalog via the `custom_beers` config array, reachable through a `beer_overrides` entry.
|
||||
|
||||
#### Scenario: Custom beer entry structure
|
||||
- **WHEN** a `custom_beers` array entry is provided in config
|
||||
- **THEN** it SHALL require at minimum a `name` field (string)
|
||||
- **THEN** it SHALL accept optional fields: `color_primary` (CSS color), `color_secondary` (CSS color), `color_text` (CSS color), `image_url` (URL string), `brewery` (string), `style` (string), `abv` (number)
|
||||
|
||||
#### Scenario: Custom beer selected by a matching override
|
||||
- **WHEN** a `beer_overrides` entry matching the reported product ID names the same string as the `name` of a `custom_beers` entry
|
||||
- **THEN** the card SHALL display that custom beer using its configured colors and image
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Optional manual beer override
|
||||
**Reason**: `beer_name` applied unconditionally and permanently, with no link to the keg it corrected, so it misidentified every subsequent keg. Every card configured before 0.3.0 carries the key, because the editor of that era always wrote it and `getStubConfig()` seeded it, and 0.3.1 promoted those dormant values into silent detection overrides.
|
||||
|
||||
**Migration**: `beer_name` is ignored when present; no automatic migration is possible because the value records no product ID and guessing one would manufacture an override the user never set. Cards revert to auto-detection, which for most is the correct result now that the catalog covers all upstream product IDs. To re-apply a correction, use the keg-scoped correction control in the editor while that keg is tapped, which records it under `beer_overrides`.
|
||||
@@ -0,0 +1,65 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Manual override scoped to the reported keg
|
||||
A manual override SHALL apply only while the machine reports the product ID that override was recorded against, so that a correction cannot outlive the keg it corrects.
|
||||
|
||||
#### Scenario: Override applies to the keg it was recorded for
|
||||
- **WHEN** `beer_overrides` contains an entry whose key equals the state of the `keg_product_id` sensor
|
||||
- **THEN** the card SHALL display the beer resolved from that entry's value, resolved by catalog name, slug, or matching `custom_beers` entry
|
||||
- **THEN** the card SHALL use that beer for the name, brand colors, style, ABV, and artwork
|
||||
|
||||
#### Scenario: Override does not apply to a different keg
|
||||
- **WHEN** `beer_overrides` contains entries AND none of their keys equals the reported `keg_product_id` state
|
||||
- **THEN** the card SHALL ignore every entry and resolve the beer by detection
|
||||
- **THEN** the card SHALL NOT display any beer named by a non-matching entry
|
||||
|
||||
#### Scenario: Override for an unrecognised product ID
|
||||
- **WHEN** the reported `keg_product_id` matches no catalog entry's `kegId` AND `beer_overrides` contains an entry for that ID
|
||||
- **THEN** the card SHALL display the beer named by that entry
|
||||
- **THEN** the card SHALL NOT fall back to the integration-reported keg name
|
||||
|
||||
#### Scenario: No override applies when no keg is reported
|
||||
- **WHEN** the `keg_product_id` sensor reports no usable state AND `beer_overrides` contains entries
|
||||
- **THEN** the card SHALL enter the no-keg-detected state
|
||||
- **THEN** the card SHALL NOT display any beer named by `beer_overrides`
|
||||
|
||||
#### Scenario: Override entry naming an unknown beer
|
||||
- **WHEN** a matching `beer_overrides` entry names a beer present in neither the catalog nor `custom_beers`
|
||||
- **THEN** the card SHALL display that name against the generic color palette
|
||||
- **THEN** the card SHALL NOT fall back to detection, since a matching override signals the user's intent for this keg
|
||||
|
||||
### Requirement: Active override is visible
|
||||
When the card displays a beer because of an override rather than detection, it SHALL make that visible, so a user can tell an override from a detection result without reading config.
|
||||
|
||||
#### Scenario: Override applied
|
||||
- **WHEN** the card displays a beer resolved from a matching `beer_overrides` entry
|
||||
- **THEN** the card SHALL render an indication that an override is in effect
|
||||
|
||||
#### Scenario: Override contradicts detection
|
||||
- **WHEN** an override is applied AND detection would have resolved a different beer for the same keg
|
||||
- **THEN** the indication SHALL identify the beer that detection resolved
|
||||
- **THEN** the card SHALL NOT silently present the override as a detection result
|
||||
|
||||
#### Scenario: No override applied
|
||||
- **WHEN** the card displays a beer resolved by detection with no matching override
|
||||
- **THEN** the card SHALL NOT render an override indication
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Detection precedence
|
||||
The card SHALL apply a single, defined precedence order when determining which beer to display.
|
||||
|
||||
#### Scenario: Precedence order
|
||||
- **WHEN** the card determines the beer to display
|
||||
- **THEN** it SHALL apply the first applicable source in this order: (1) a `beer_overrides` entry whose key matches the reported product ID, (2) a catalog entry matched by reported product ID, (3) a beer resolved from the reported keg name, (4) the no-keg-detected state
|
||||
- **THEN** no later source SHALL override an earlier one
|
||||
|
||||
#### Scenario: Matching override wins over successful detection
|
||||
- **WHEN** a `beer_overrides` entry matches the reported product ID AND that same product ID also resolves to a different catalog entry
|
||||
- **THEN** the card SHALL display the beer named by the override entry
|
||||
- **THEN** the card SHALL indicate that an override is in effect rather than substituting silently
|
||||
|
||||
#### Scenario: No configured value can precede detection unconditionally
|
||||
- **WHEN** the card determines the beer to display
|
||||
- **THEN** no config value SHALL take precedence over detection except by matching the currently reported product ID
|
||||
- **THEN** a config value that names a beer without reference to a product ID SHALL NOT affect the displayed beer
|
||||
@@ -0,0 +1,43 @@
|
||||
## 1. Config surface and detection precedence
|
||||
|
||||
- [x] 1.1 In `src/types.ts`, remove `beer_name` from `PerfectDraftCardConfig` and add `beer_overrides?: Record<string, string>`
|
||||
- [x] 1.2 In `src/perfectdraft-card.ts`, rewrite the first rung of `_updateDetectedBeer` to look up `_config.beer_overrides` by the reported `keg_product_id` state instead of reading `_config.beer_name`
|
||||
- [x] 1.3 Resolve a matching override's value through the existing `resolveBeer(value, this._config.custom_beers)` path so catalog names, slugs and `custom_beers` entries all work
|
||||
- [x] 1.4 Confirm no override is consulted when the product ID state is absent, `unknown` or `unavailable`, so the no-keg state is unreachable from config
|
||||
- [x] 1.5 Track whether the displayed beer came from an override and what detection would have resolved, so the marker in group 2 has both names available
|
||||
- [x] 1.6 Verify `beer_name` and `beer_entity` in a config load without throwing and leave the card on detection
|
||||
|
||||
## 2. Override visibility on the card
|
||||
|
||||
- [x] 2.1 Add an override marker element and styles, following the `freshness-indicator` pill precedent
|
||||
- [x] 2.2 Include the detection-resolved name in the marker when it differs from the override
|
||||
- [x] 2.3 Render the marker in the layouts that show beer identity: `landscape`, `portrait`, `hero`, `vessel`
|
||||
- [x] 2.4 Decide and implement the `compact` layout treatment, where horizontal space is tight (open question in design.md)
|
||||
- [x] 2.5 Confirm the marker is absent whenever no override is applied
|
||||
|
||||
## 3. Editor
|
||||
|
||||
- [x] 3.1 Remove the `beer_name` dropdown and its `getAllBeers()` import if it becomes unused
|
||||
- [x] 3.2 Read the live `keg_product_id` state for the selected device from the `translation_key` map `_discoverDevices` already builds
|
||||
- [x] 3.3 Add the keg-scoped correction control: a beer selector that writes one `beer_overrides` entry keyed by the currently reported product ID
|
||||
- [x] 3.4 Disable the correction control with an explanation when no product ID is currently reported, without hiding it
|
||||
- [x] 3.5 List existing `beer_overrides` entries with product ID and beer name, each with a remove control
|
||||
- [x] 3.6 Remove the `beer_overrides` key entirely when its last entry is removed
|
||||
- [x] 3.7 Confirm each editor mutation fires `config-changed` and the preview updates
|
||||
|
||||
## 4. Documentation and release
|
||||
|
||||
- [x] 4.1 Document `beer_overrides` in `README.md`, replacing the `beer_name` override section, including the YAML example
|
||||
- [x] 4.2 Add an upgrade note stating that `beer_name` is ignored, why, and how to re-apply a correction
|
||||
- [x] 4.3 State in the README how to confirm which bundle version is running, since the console banner is the only signal
|
||||
- [x] 4.4 Bump `package.json`, `CARD_VERSION` and `EDITOR_VERSION` to 0.4.0 — all three, so the banner cannot disagree with the release again
|
||||
- [x] 4.5 Rebuild `dist/perfectdraft-card.js` with `npm run build`
|
||||
|
||||
## 5. Verification
|
||||
|
||||
- [x] 5.1 Run `npm run lint` and `npm run check:catalog` clean
|
||||
- [x] 5.2 Reproduce the original report: a config carrying `beer_name: "Leffe Blonde"` with a keg reporting product ID `1095` SHALL display Leffe Ruby
|
||||
- [x] 5.3 Verify the recurrence case: an override recorded for one product ID stops applying when the reported ID changes, with no config edit
|
||||
- [x] 5.4 Verify an override on a product ID absent from the catalog displays the named beer rather than the integration-reported name
|
||||
- [x] 5.5 Verify the no-keg state still renders "No keg detected" with `beer_overrides` populated
|
||||
- [x] 5.6 Verify a 0.4.0 config loads on the 0.3.1 bundle without throwing, per the rollback path in design.md
|
||||
@@ -0,0 +1,73 @@
|
||||
# beer-catalog Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change perfectdraft-card. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Built-in PerfectDraft beer database
|
||||
The card SHALL include a built-in catalog of PerfectDraft beers with metadata for display purposes.
|
||||
|
||||
#### Scenario: Catalog data structure
|
||||
- **WHEN** the card is loaded
|
||||
- **THEN** each beer entry in the catalog SHALL contain: a unique slug (kebab-case), display name, brewery name, style, ABV (number), and a brand color palette (primary color, secondary color, text color)
|
||||
- **THEN** each entry MAY additionally carry a `kegId` product ID, a keg image path, and a brewery logo reference
|
||||
|
||||
#### Scenario: Catalog coverage
|
||||
- **WHEN** the card is loaded
|
||||
- **THEN** the catalog SHALL include an entry for every keg the paired integration can identify, and MAY include further entries for beers the integration does not list
|
||||
|
||||
### Requirement: Beer logo images
|
||||
The card SHALL include static logo images for beers in the built-in catalog.
|
||||
|
||||
#### Scenario: Image availability
|
||||
- **WHEN** a beer from the built-in catalog is selected
|
||||
- **THEN** the card SHALL display the beer's logo image in the label zone
|
||||
- **THEN** images SHALL be optimised static assets (PNG or WebP) bundled with the card
|
||||
|
||||
#### Scenario: Image fallback
|
||||
- **WHEN** a beer has no logo image available (custom beer or missing asset)
|
||||
- **THEN** the card SHALL display the beer's brand color palette as the visual background instead of an image
|
||||
|
||||
### Requirement: Custom beer entries via configuration
|
||||
The card SHALL support user-defined beer entries that extend or override the built-in catalog, reachable through the `beer_name` override.
|
||||
|
||||
#### Scenario: Custom beer defined in config
|
||||
- **WHEN** the card config includes a `custom_beers` array with entries containing at minimum a `name` field
|
||||
- **THEN** those beers SHALL be resolvable by the `beer_name` override alongside built-in entries
|
||||
- **THEN** custom entries SHALL support optional fields: `color_primary`, `color_secondary`, `color_text`, `image_url`, `brewery`, `style`, `abv`
|
||||
|
||||
#### Scenario: Custom beer overrides built-in
|
||||
- **WHEN** a custom beer entry has the same slug as a built-in beer
|
||||
- **THEN** the custom entry SHALL override the built-in entry's fields
|
||||
|
||||
### Requirement: Product ID mapping to the integration catalog
|
||||
Each catalog entry SHALL be able to carry the PerfectDraft product ID of its keg, so the card can join against the product ID reported by the integration.
|
||||
|
||||
#### Scenario: Entry carries a product ID
|
||||
- **WHEN** a catalog entry corresponds to a keg listed in the integration's `keg_catalog.json`
|
||||
- **THEN** the entry SHALL carry a `kegId` field holding that product ID as a string
|
||||
|
||||
#### Scenario: Full coverage of the integration catalog
|
||||
- **WHEN** the card is loaded
|
||||
- **THEN** every product ID present in the integration's bundled keg catalog SHALL be carried by exactly one card catalog entry
|
||||
- **THEN** no `kegId` SHALL appear on more than one entry
|
||||
- **THEN** no `kegId` SHALL reference a product ID absent from the integration catalog
|
||||
|
||||
#### Scenario: Lookup by product ID
|
||||
- **WHEN** the card looks up a beer by product ID
|
||||
- **THEN** the lookup SHALL resolve without scanning the catalog linearly, using an index built once at module load alongside the existing slug and name indexes
|
||||
|
||||
### Requirement: Catalog coverage is verifiable
|
||||
The project SHALL provide a repeatable check that the card's product ID mapping agrees with the integration's keg catalog, so drift is detected rather than discovered by users.
|
||||
|
||||
#### Scenario: Check detects a missing mapping
|
||||
- **WHEN** the integration catalog contains a product ID that no card catalog entry carries
|
||||
- **THEN** the check SHALL fail and SHALL name the unmapped product ID and its integration-reported name
|
||||
|
||||
#### Scenario: Check detects a stale or duplicate mapping
|
||||
- **WHEN** a card catalog entry carries a `kegId` that is absent from the integration catalog, or two entries carry the same `kegId`
|
||||
- **THEN** the check SHALL fail and SHALL name the offending entries
|
||||
|
||||
#### Scenario: Check is offline
|
||||
- **WHEN** the check runs
|
||||
- **THEN** it SHALL compare against a committed snapshot of the integration catalog and SHALL NOT require network access
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
# beer-imagery Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change card-layouts-and-imagery. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Expanded keg image coverage
|
||||
The built-in catalog SHALL provide keg product images for the PerfectDraft beers currently sold across the regional storefronts, closing the gap left by beers that previously had no image.
|
||||
|
||||
#### Scenario: Previously-missing current beer gains an image
|
||||
- **WHEN** a currently-sold catalog beer that previously had no `imagePath` is displayed
|
||||
- **THEN** the card SHALL display its keg product image
|
||||
- **THEN** the image SHALL be a bundled static asset, not fetched at runtime
|
||||
|
||||
#### Scenario: Discontinued or unavailable beer
|
||||
- **WHEN** a catalog beer has no keg image because it is seasonal, discontinued, or otherwise unavailable from any storefront
|
||||
- **THEN** the card SHALL present it via the tiered visual fallback rather than a bare placeholder
|
||||
|
||||
### Requirement: Tiered visual fallback
|
||||
When a beer's keg photo is unavailable, the card SHALL resolve its visual through an ordered fallback chain so that no beer renders as a bare letter on a plain background.
|
||||
|
||||
#### Scenario: Keg photo available
|
||||
- **WHEN** a beer has a keg photo (`imagePath`, or a custom beer's `image_url`)
|
||||
- **THEN** the card SHALL display the keg photo
|
||||
|
||||
#### Scenario: Brewery logo fallback
|
||||
- **WHEN** a beer has no keg photo but its brewery has a bundled logo
|
||||
- **THEN** the card SHALL display the brewery logo
|
||||
|
||||
#### Scenario: Generated silhouette fallback
|
||||
- **WHEN** a beer has neither a keg photo nor a brewery logo
|
||||
- **THEN** the card SHALL display a generated keg/glass silhouette tinted from the beer's brand color palette
|
||||
|
||||
#### Scenario: Runtime image load failure
|
||||
- **WHEN** a resolved image asset fails to load in the browser
|
||||
- **THEN** the card SHALL degrade to the next tier in the chain rather than showing a broken image
|
||||
|
||||
### Requirement: Generated silhouette is asset-free and palette-tinted
|
||||
The generated fallback silhouette SHALL be rendered without any downloaded image asset and SHALL derive its appearance from data already present on the beer entry.
|
||||
|
||||
#### Scenario: Silhouette uses brand palette
|
||||
- **WHEN** the generated silhouette is shown
|
||||
- **THEN** its fill SHALL be derived from the beer's `colors` palette
|
||||
- **THEN** it SHALL remain legible across light and dark palettes via a contrasting outline or accent
|
||||
|
||||
#### Scenario: Silhouette scales with layout
|
||||
- **WHEN** the generated silhouette is shown in any layout
|
||||
- **THEN** it SHALL render crisply at that layout's size (including the large `hero` and `vessel` sizes) without pixelation
|
||||
|
||||
### Requirement: Brewery logo assets
|
||||
The card SHALL bundle brewery logo assets that can serve as the fallback visual for multiple beers from the same brewery.
|
||||
|
||||
#### Scenario: One logo covers multiple variants
|
||||
- **WHEN** several catalog beers share a brewery and lack individual keg photos
|
||||
- **THEN** a single bundled brewery logo SHALL be usable as the fallback visual for all of them
|
||||
|
||||
#### Scenario: Brewery logo resolution
|
||||
- **WHEN** a brewery logo is displayed
|
||||
- **THEN** it SHALL be loaded as a bundled static asset resolved against the card's install base URL, consistent with keg image resolution
|
||||
|
||||
### Requirement: Images sourced as bundled product references
|
||||
Keg and brewery images SHALL be sourced once from the products' own storefront/brand imagery and committed as bundled static assets; the card SHALL NOT fetch or scrape imagery at runtime.
|
||||
|
||||
#### Scenario: No runtime fetching
|
||||
- **WHEN** the card renders any beer visual
|
||||
- **THEN** it SHALL reference only bundled assets (or a user-provided `image_url`) and SHALL NOT perform network scraping of external storefronts
|
||||
|
||||
#### Scenario: Assets copied into the distribution
|
||||
- **WHEN** the card is built
|
||||
- **THEN** keg images and brewery logos SHALL be copied into `dist/` alongside the card JS so HACS and manual installs receive them
|
||||
|
||||
### Requirement: Optimized image encoding
|
||||
Bundled keg images SHALL be encoded to keep download weight reasonable while remaining sharp in the image-forward layouts.
|
||||
|
||||
#### Scenario: Optimized assets
|
||||
- **WHEN** keg images are bundled
|
||||
- **THEN** they SHALL be encoded in an efficient web format and capped at a dimension suitable for the largest layout, rather than shipped at full source resolution
|
||||
|
||||
#### Scenario: Sharp in hero and vessel layouts
|
||||
- **WHEN** a keg image is shown in the `hero` or `vessel` layout
|
||||
- **THEN** it SHALL render without visible pixelation at that size
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
# beer-label Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change perfectdraft-card. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Beer logo display
|
||||
The card SHALL display the selected beer's logo image in the upper portion of the left zone.
|
||||
|
||||
#### Scenario: Beer with logo image
|
||||
- **WHEN** the selected beer has a logo image available (built-in or custom via `image_url`)
|
||||
- **THEN** the card SHALL render the image in the label zone, sized to fit without distortion
|
||||
- **THEN** the image SHALL be loaded as a static asset (no lazy loading or progressive enhancement needed)
|
||||
|
||||
#### Scenario: Beer without logo image
|
||||
- **WHEN** the selected beer has no logo image (e.g., custom beer without `image_url`)
|
||||
- **THEN** the card SHALL display the beer name in large text against the beer's brand color palette background
|
||||
|
||||
### Requirement: Temperature display
|
||||
The card SHALL display the current beer temperature prominently in the left zone below the beer logo.
|
||||
|
||||
#### Scenario: Temperature available
|
||||
- **WHEN** the temperature sensor reports a numeric value
|
||||
- **THEN** the card SHALL display the temperature with a cold/frost icon (e.g., ❄) and the value followed by °C
|
||||
- **THEN** the temperature SHALL be displayed in a large, easily readable font size
|
||||
|
||||
#### Scenario: Temperature unavailable
|
||||
- **WHEN** the temperature sensor is unavailable or unknown
|
||||
- **THEN** the card SHALL display a placeholder (e.g., "-- °C") instead of the temperature value
|
||||
|
||||
### Requirement: Beer name display
|
||||
The card SHALL display the detected beer's name in the label zone below the temperature, using the card's own curated name where it has one.
|
||||
|
||||
#### Scenario: Beer detected
|
||||
- **WHEN** a beer has been determined by detection or by the `beer_name` override
|
||||
- **THEN** the card SHALL display that beer's full name as text in the label zone
|
||||
|
||||
#### Scenario: Detected by product ID
|
||||
- **WHEN** the beer was matched by product ID
|
||||
- **THEN** the displayed name SHALL be the card catalog entry's curated name, not the name reported by the integration
|
||||
|
||||
#### Scenario: No beer detected
|
||||
- **WHEN** no beer could be determined
|
||||
- **THEN** the label zone SHALL indicate that no keg is detected
|
||||
- **THEN** the label zone SHALL NOT display the name of any catalog beer
|
||||
|
||||
### Requirement: Label zone reflects detection state
|
||||
The label zone's styling SHALL follow the detection state so a user can tell a detected beer from an undetected one at a glance.
|
||||
|
||||
#### Scenario: Beer detected
|
||||
- **WHEN** a beer has been determined
|
||||
- **THEN** the label zone SHALL use that beer's brand color palette as its background gradient
|
||||
|
||||
#### Scenario: No beer detected
|
||||
- **WHEN** no beer could be determined
|
||||
- **THEN** the label zone SHALL use a neutral palette rather than any brand palette
|
||||
- **THEN** the card SHALL NOT render a keg photograph or brewery logo
|
||||
|
||||
### Requirement: Label zone is not a beer picker
|
||||
The label zone SHALL NOT act as a control for choosing a beer, since the beer is detected rather than chosen.
|
||||
|
||||
#### Scenario: Tapping the label zone
|
||||
- **WHEN** the user taps the label zone in any layout
|
||||
- **THEN** no beer selection dialog SHALL open
|
||||
|
||||
@@ -0,0 +1,117 @@
|
||||
# card-config Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change perfectdraft-card. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: UI-driven device selection
|
||||
The card SHALL identify its PerfectDraft device via a visual editor — no manual YAML editing SHALL be required to configure the card.
|
||||
|
||||
#### Scenario: Auto-discovery of PerfectDraft devices
|
||||
- **WHEN** the visual card editor is opened
|
||||
- **THEN** the editor SHALL scan `hass` state for entities belonging to the `perfectdraft` integration
|
||||
- **THEN** it SHALL group discovered entities by their HA device registry entry
|
||||
- **THEN** it SHALL present discovered PerfectDraft devices as selectable options
|
||||
|
||||
#### Scenario: Single device auto-selection
|
||||
- **WHEN** exactly one PerfectDraft device is discovered
|
||||
- **THEN** the editor SHALL auto-select that device
|
||||
- **THEN** the user SHALL see the device name displayed but not need to make a selection
|
||||
|
||||
#### Scenario: No devices found
|
||||
- **WHEN** no PerfectDraft devices are discovered in `hass`
|
||||
- **THEN** the editor SHALL display a clear message: the PerfectDraft integration must be installed and configured first
|
||||
|
||||
### Requirement: Device-based entity resolution
|
||||
The card SHALL derive its sensor entity IDs from the configured device, not from manually entered entity IDs or prefixes.
|
||||
|
||||
#### Scenario: Entity resolution at runtime
|
||||
- **WHEN** the card has a `device_id` in its config
|
||||
- **THEN** the card SHALL resolve the temperature, keg_remaining, keg_freshness, keg_product_id, and keg_name sensor entities associated with that device
|
||||
- **THEN** the card SHALL use those resolved entities for all display values
|
||||
|
||||
#### Scenario: Device removed or unavailable
|
||||
- **WHEN** the configured `device_id` no longer exists in HA or has no associated entities
|
||||
- **THEN** the card SHALL display an error indicating the device is not found
|
||||
- **THEN** the error SHALL suggest re-configuring the card via the editor
|
||||
|
||||
#### Scenario: Keg sensors missing from an otherwise valid device
|
||||
- **WHEN** the device resolves and other sensors are found, but the keg_product_id and keg_name sensors are absent
|
||||
- **THEN** the card SHALL indicate that the PerfectDraft integration needs updating rather than reporting a device error
|
||||
|
||||
### Requirement: Configuration validation
|
||||
The card SHALL validate its configuration and display clear errors for invalid config.
|
||||
|
||||
#### Scenario: Missing device configuration
|
||||
- **WHEN** the card config has no `device_id`
|
||||
- **THEN** the card SHALL throw an error during `setConfig()` that triggers HA's built-in error card display
|
||||
- **THEN** the error message SHALL instruct the user to configure the card via the visual editor
|
||||
|
||||
#### Scenario: Invalid glass_size value
|
||||
- **WHEN** the card config specifies a `glass_size` that is not one of the supported values (250, 330, 500, 568, 473)
|
||||
- **THEN** the card SHALL fall back to the default of 330 mL
|
||||
|
||||
#### Scenario: Unknown beer_name override
|
||||
- **WHEN** the card config specifies a `beer_name` that does not match any beer in the catalog (built-in or custom)
|
||||
- **THEN** the card SHALL treat it as a custom beer with that name and use a generic color palette
|
||||
- **THEN** the card SHALL NOT fall back to auto-detection, since an explicit override signals the user's intent
|
||||
|
||||
#### Scenario: Removed configuration keys ignored
|
||||
- **WHEN** the card config contains `beer_entity`, which is no longer supported
|
||||
- **THEN** the card SHALL ignore it without throwing
|
||||
|
||||
### Requirement: Visual card editor
|
||||
The card SHALL provide a graphical configuration editor as the primary means of configuration.
|
||||
|
||||
#### Scenario: Editor registration
|
||||
- **WHEN** `getConfigElement()` is called on the card class
|
||||
- **THEN** it SHALL return a custom element that renders a configuration form
|
||||
- **THEN** `getStubConfig()` SHALL return a minimal valid configuration for new card creation (auto-selecting the sole device if only one exists)
|
||||
|
||||
#### Scenario: Editor fields
|
||||
- **WHEN** the visual editor is displayed
|
||||
- **THEN** it SHALL provide: a device picker (dropdown of discovered PerfectDraft devices), glass size (dropdown of five options), layout selection, and an optional beer override
|
||||
- **THEN** all fields SHALL be UI controls — no freeform text input for entity IDs
|
||||
- **THEN** the editor SHALL NOT present beer selection as a required or default setting
|
||||
|
||||
#### Scenario: Editor fires config-changed events
|
||||
- **WHEN** the user changes any editor field
|
||||
- **THEN** the editor SHALL fire a `config-changed` custom event with the updated config
|
||||
- **THEN** the card preview SHALL update to reflect the change
|
||||
|
||||
### Requirement: Custom beers configuration
|
||||
The card SHALL support extending the beer catalog via the `custom_beers` config array, reachable through the `beer_name` override.
|
||||
|
||||
#### Scenario: Custom beer entry structure
|
||||
- **WHEN** a `custom_beers` array entry is provided in config
|
||||
- **THEN** it SHALL require at minimum a `name` field (string)
|
||||
- **THEN** it SHALL accept optional fields: `color_primary` (CSS color), `color_secondary` (CSS color), `color_text` (CSS color), `image_url` (URL string), `brewery` (string), `style` (string), `abv` (number)
|
||||
|
||||
#### Scenario: Custom beer selected by override
|
||||
- **WHEN** `beer_name` matches the `name` of a `custom_beers` entry
|
||||
- **THEN** the card SHALL display that custom beer using its configured colors and image
|
||||
|
||||
### Requirement: YAML remains valid for power users
|
||||
While not required, the YAML config SHALL remain a valid and complete representation so power users can edit it directly if they choose.
|
||||
|
||||
#### Scenario: YAML round-trip
|
||||
- **WHEN** a card is configured via the visual editor
|
||||
- **THEN** the resulting YAML SHALL contain all settings as readable key-value pairs
|
||||
- **THEN** editing that YAML directly and saving SHALL produce the same card behaviour as the editor
|
||||
|
||||
### Requirement: Optional manual beer override
|
||||
The card SHALL accept an optional `beer_name` config value that overrides auto-detection, so a user is never stuck with a wrong or unrecognised beer.
|
||||
|
||||
#### Scenario: Override absent
|
||||
- **WHEN** the card config has no `beer_name`
|
||||
- **THEN** the card SHALL rely entirely on auto-detection
|
||||
- **THEN** `getStubConfig()` SHALL NOT populate `beer_name`, so newly created cards start with detection only
|
||||
|
||||
#### Scenario: Override set
|
||||
- **WHEN** the card config sets `beer_name`
|
||||
- **THEN** the card SHALL display the beer resolved from that value regardless of what the keg sensors report
|
||||
|
||||
#### Scenario: Override presented as optional in the editor
|
||||
- **WHEN** the visual editor is displayed
|
||||
- **THEN** the beer override field SHALL be empty by default and SHALL be labelled as an override for when detection is wrong
|
||||
- **THEN** clearing the field SHALL remove `beer_name` from the config and return the card to detection
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# card-core Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change perfectdraft-card. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Card registration as custom element
|
||||
The card SHALL register itself as a custom HTML element named `perfectdraft-card` and appear in the HA card picker.
|
||||
|
||||
#### Scenario: Card loaded in Home Assistant
|
||||
- **WHEN** the card's JS file is loaded as a dashboard resource
|
||||
- **THEN** `customElements.get('perfectdraft-card')` SHALL return the card class
|
||||
- **THEN** `window.customCards` SHALL contain an entry with `type: "perfectdraft-card"`, `name: "PerfectDraft Card"`, and a description
|
||||
|
||||
#### Scenario: Card added to dashboard
|
||||
- **WHEN** a user adds `type: custom:perfectdraft-card` to a dashboard view
|
||||
- **THEN** the card SHALL render without errors given valid configuration
|
||||
|
||||
### Requirement: Entity state subscription
|
||||
The card SHALL subscribe to and reactively display state from the PerfectDraft integration's sensor entities.
|
||||
|
||||
#### Scenario: State updates from integration
|
||||
- **WHEN** the `hass` property is set by Home Assistant with updated entity states
|
||||
- **THEN** the card SHALL resolve the temperature, keg_remaining, and keg_freshness sensor entities for its configured device
|
||||
- **THEN** the card SHALL update its display to reflect the new values
|
||||
|
||||
#### Scenario: Entity unavailable
|
||||
- **WHEN** any resolved entity has state `unavailable` or `unknown`
|
||||
- **THEN** the card SHALL display a fallback indicator (e.g., `--`) for that value instead of crashing
|
||||
|
||||
#### Scenario: Device entity resolution failure
|
||||
- **WHEN** the configured device's sensor entities cannot be resolved from `hass`
|
||||
- **THEN** the card SHALL display an error message indicating the device or its entities are missing
|
||||
|
||||
### Requirement: Two-zone landscape layout
|
||||
The card SHALL render a two-column layout with the beer label zone on the left (~1/3 width) and the keg emoji zone on the right (~2/3 width).
|
||||
|
||||
#### Scenario: Card rendered on NSPanel Pro 120 landscape
|
||||
- **WHEN** the card renders in a viewport of 1334×750 or similar landscape dimensions
|
||||
- **THEN** the left zone SHALL occupy approximately one-third of the card width
|
||||
- **THEN** the right zone SHALL occupy approximately two-thirds of the card width
|
||||
- **THEN** both zones SHALL fill the full card height
|
||||
|
||||
#### Scenario: Card rendered on desktop browser
|
||||
- **WHEN** the card renders in a standard HA dashboard grid on a desktop viewport
|
||||
- **THEN** the two-zone layout SHALL scale proportionally to the card's allocated width
|
||||
- **THEN** content SHALL remain legible at typical card widths (400-800px)
|
||||
|
||||
### Requirement: Minimal JS execution footprint
|
||||
The card SHALL minimise JavaScript execution to perform well on the NSPanel Pro's limited hardware.
|
||||
|
||||
#### Scenario: State change handling
|
||||
- **WHEN** the `hass` property is updated
|
||||
- **THEN** the card SHALL only re-render DOM elements whose backing data has actually changed
|
||||
- **THEN** the card SHALL NOT trigger full component re-renders on every hass update
|
||||
|
||||
### Requirement: Card sizing for HA layout engines
|
||||
The card SHALL report its size to HA's layout engines for proper grid placement.
|
||||
|
||||
#### Scenario: Masonry view sizing
|
||||
- **WHEN** `getCardSize()` is called
|
||||
- **THEN** the card SHALL return a size value appropriate for a full-width, medium-height card
|
||||
|
||||
#### Scenario: Sections view grid options
|
||||
- **WHEN** `getGridOptions()` is called
|
||||
- **THEN** the card SHALL return grid options indicating it prefers full-width placement
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
# card-layouts Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change card-layouts-and-imagery. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Layout selection via configuration
|
||||
The card SHALL support a `layout` configuration option that selects one of five named layouts, defaulting to `landscape` when unset.
|
||||
|
||||
#### Scenario: Layout explicitly configured
|
||||
- **WHEN** the card config sets `layout` to one of `landscape`, `portrait`, `compact`, `hero`, or `vessel`
|
||||
- **THEN** the card SHALL render using that layout
|
||||
|
||||
#### Scenario: No layout configured
|
||||
- **WHEN** the card config has no `layout` value
|
||||
- **THEN** the card SHALL render using the `landscape` layout
|
||||
- **THEN** the rendered result SHALL be behaviorally identical to the card prior to this change
|
||||
|
||||
#### Scenario: Unrecognized layout value
|
||||
- **WHEN** the card config sets `layout` to a value that is not a known layout
|
||||
- **THEN** the card SHALL fall back to the `landscape` layout without throwing
|
||||
|
||||
#### Scenario: Layout selectable in the visual editor
|
||||
- **WHEN** the visual card editor is displayed
|
||||
- **THEN** it SHALL provide a Layout control listing the five layouts
|
||||
- **THEN** changing the control SHALL fire a `config-changed` event updating `layout`
|
||||
- **THEN** the card preview SHALL re-render in the chosen layout
|
||||
|
||||
### Requirement: Landscape layout
|
||||
The card SHALL provide a `landscape` layout that preserves the existing two-zone horizontal arrangement: beer label zone on the left (~1/3) and keg emoji zone on the right (~2/3).
|
||||
|
||||
#### Scenario: Landscape rendering
|
||||
- **WHEN** the active layout is `landscape`
|
||||
- **THEN** the label zone SHALL occupy approximately one-third of the card width on the left
|
||||
- **THEN** the keg emoji zone SHALL occupy approximately two-thirds on the right
|
||||
- **THEN** both zones SHALL fill the full card height
|
||||
|
||||
### Requirement: Portrait layout
|
||||
The card SHALL provide a `portrait` layout that stacks the beer label above the keg display for tall/narrow surfaces.
|
||||
|
||||
#### Scenario: Portrait rendering
|
||||
- **WHEN** the active layout is `portrait`
|
||||
- **THEN** the beer label (image/fallback, temperature, name) SHALL render in an upper band
|
||||
- **THEN** the keg emoji display SHALL render below it
|
||||
- **THEN** content SHALL remain legible at narrow widths typical of phones and portrait wall panels
|
||||
|
||||
### Requirement: Compact layout
|
||||
The card SHALL provide a `compact` layout that presents keg status in a single low-height row suitable for dashboards containing many cards.
|
||||
|
||||
#### Scenario: Compact rendering
|
||||
- **WHEN** the active layout is `compact`
|
||||
- **THEN** the card SHALL render a single horizontal row containing the beer visual, name, temperature, a horizontal fill bar sized to the keg-remaining percentage, and the count text
|
||||
- **THEN** the card SHALL NOT render the full multi-row emoji grid
|
||||
- **THEN** overflowing beer names SHALL be truncated rather than wrapping the row
|
||||
|
||||
### Requirement: Hero layout
|
||||
The card SHALL provide a `hero` layout that makes the beer visual the centerpiece with status overlaid.
|
||||
|
||||
#### Scenario: Hero rendering with image
|
||||
- **WHEN** the active layout is `hero` and the beer has a keg photo
|
||||
- **THEN** the photo SHALL be displayed as the dominant visual element
|
||||
- **THEN** the photo SHALL fill the card (cover), and temperature, beer name, and remaining count SHALL sit on a gradient scrim so they remain legible against the image
|
||||
|
||||
#### Scenario: Hero rendering without image
|
||||
- **WHEN** the active layout is `hero` and the beer has no keg photo
|
||||
- **THEN** the card SHALL display the resolved fallback visual (brewery logo or generated silhouette) as the centerpiece
|
||||
|
||||
### Requirement: Vessel layout
|
||||
The card SHALL provide a `vessel` layout that represents remaining keg volume as a single proportionally-filled beer glass instead of a grid of emoji.
|
||||
|
||||
#### Scenario: Vessel proportional fill
|
||||
- **WHEN** the active layout is `vessel` and `keg_remaining` reports a percentage > 0
|
||||
- **THEN** the card SHALL render one beer-glass vessel filled in proportion to the keg-remaining percentage
|
||||
- **THEN** the remaining glasses count and glass size SHALL be shown as text
|
||||
|
||||
#### Scenario: Vessel empty keg
|
||||
- **WHEN** the active layout is `vessel` and the keg is empty (0%)
|
||||
- **THEN** the vessel SHALL render visibly empty
|
||||
- **THEN** the card SHALL communicate the empty state consistently with other layouts
|
||||
|
||||
### Requirement: Consistent behavior across layouts
|
||||
All layouts SHALL share the same data, interactions, and warning behavior; only the visual arrangement differs.
|
||||
|
||||
#### Scenario: Interactions available in every layout
|
||||
- **WHEN** any layout is active
|
||||
- **THEN** the user SHALL be able to open the glass size selection dialog from the card
|
||||
- **THEN** selecting a glass size SHALL update the display and persist exactly as in the landscape layout
|
||||
|
||||
#### Scenario: Detected beer shown in every layout
|
||||
- **WHEN** any layout is active
|
||||
- **THEN** the beer SHALL be determined by the `keg-auto-detection` rules rather than by a per-layout control
|
||||
- **THEN** the no-keg-detected state SHALL be surfaced in every layout, not only in landscape
|
||||
|
||||
#### Scenario: Freshness warnings in every layout
|
||||
- **WHEN** the keg freshness tier is `warning` or worse
|
||||
- **THEN** the active layout SHALL surface the freshness indicator and the card-level freshness styling
|
||||
- **THEN** freshness animations SHALL remain CSS-driven with no added JavaScript animation loop
|
||||
|
||||
#### Scenario: Glasses calculation is layout-independent
|
||||
- **WHEN** the layout changes
|
||||
- **THEN** the remaining-glasses value SHALL be computed identically (`floor((keg_remaining% / 100 × 6000) / glass_size_mL)`) regardless of layout
|
||||
|
||||
### Requirement: Layout-aware card sizing
|
||||
The card SHALL report sizing to Home Assistant layout engines appropriate to the active layout.
|
||||
|
||||
#### Scenario: Sizing reflects layout
|
||||
- **WHEN** `getCardSize()` or `getGridOptions()` is called
|
||||
- **THEN** the returned values SHALL reflect the active layout (e.g., `compact` reports a short height; `hero` and `portrait` report taller placements; `landscape` reports its existing values)
|
||||
|
||||
### Requirement: Width-tolerant emoji matrix
|
||||
The emoji matrix SHALL shrink to fit the available card width without overflowing, and SHALL NOT impose a minimum width wider than its container.
|
||||
|
||||
#### Scenario: Narrow placement
|
||||
- **WHEN** the card is placed in a container narrower than its natural content width (e.g., a narrow dashboard column, or a phone in a multi-column view)
|
||||
- **THEN** the label and keg zones SHALL shrink to fit
|
||||
- **THEN** the emoji matrix SHALL remain fully visible without horizontal overflow or clipping
|
||||
|
||||
#### Scenario: Emoji size tracks the card, not the viewport
|
||||
- **WHEN** the card is narrow while the browser viewport is wide
|
||||
- **THEN** the emoji SHALL be sized relative to the card's own width
|
||||
- **THEN** the emoji SHALL become smaller as the card narrows rather than retaining a fixed viewport-derived size
|
||||
|
||||
#### Scenario: Placement floor allows narrow slots
|
||||
- **WHEN** Home Assistant queries the card's grid options for placement
|
||||
- **THEN** the card SHALL permit placement in a single grid column and SHALL NOT require a minimum of two columns
|
||||
|
||||
#### Scenario: Fixed slot shape preserved
|
||||
- **WHEN** the matrix shrinks to fit a narrow card
|
||||
- **THEN** the full-keg slot count and the greyed empty/ghost slots SHALL remain in their fixed grid positions (the grid shrinks to fit rather than changing its column count)
|
||||
|
||||
### Requirement: Emoji matrix display options
|
||||
The card SHALL provide optional configuration to control the emoji matrix's column count and maximum width, independent of the selected layout.
|
||||
|
||||
#### Scenario: Default column behavior
|
||||
- **WHEN** `matrix_columns` is unset or set to `auto`
|
||||
- **THEN** the card SHALL choose the column count automatically using its built-in heuristic
|
||||
- **THEN** the matrix SHALL remain width-tolerant
|
||||
|
||||
#### Scenario: Explicit column count
|
||||
- **WHEN** `matrix_columns` is set to a positive integer N
|
||||
- **THEN** the matrix SHALL render N columns, wrapping the full-keg slot count across as many rows as needed
|
||||
|
||||
#### Scenario: Maximum matrix width
|
||||
- **WHEN** `max_matrix_width` is set to a CSS length
|
||||
- **THEN** the matrix SHALL NOT exceed that width
|
||||
- **THEN** the matrix SHALL be centered within the keg zone
|
||||
|
||||
#### Scenario: No maximum width configured
|
||||
- **WHEN** `max_matrix_width` is unset
|
||||
- **THEN** the matrix SHALL fill the available zone width, subject to the width-tolerant behavior
|
||||
|
||||
#### Scenario: Invalid option values
|
||||
- **WHEN** `matrix_columns` or `max_matrix_width` has a malformed value
|
||||
- **THEN** the card SHALL ignore the malformed option and fall back to its default (auto columns / no maximum width) without throwing
|
||||
|
||||
#### Scenario: Matrix options in the editor
|
||||
- **WHEN** the visual card editor is displayed
|
||||
- **THEN** it SHALL provide controls for `matrix_columns` and `max_matrix_width`
|
||||
- **THEN** changing either control SHALL fire a `config-changed` event and update the card preview
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
# freshness-warning Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change perfectdraft-card. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Tiered freshness warning system
|
||||
The card SHALL display escalating visual warnings based on the keg freshness sensor value, using four severity tiers.
|
||||
|
||||
#### Scenario: Fresh keg (more than 14 days remaining)
|
||||
- **WHEN** the `keg_freshness` sensor reports a value greater than 14
|
||||
- **THEN** the card SHALL display no freshness warning indicators
|
||||
- **THEN** the card SHALL use its normal color scheme and no animation
|
||||
|
||||
#### Scenario: Warning tier (7-14 days remaining)
|
||||
- **WHEN** the `keg_freshness` sensor reports a value between 7 and 14 (inclusive)
|
||||
- **THEN** the card SHALL display a subtle amber-tinted border
|
||||
- **THEN** a freshness text indicator SHALL appear showing the days remaining (e.g., "⏳ 12d fresh")
|
||||
|
||||
#### Scenario: Urgent tier (3-6 days remaining)
|
||||
- **WHEN** the `keg_freshness` sensor reports a value between 3 and 6 (inclusive)
|
||||
- **THEN** the card SHALL display an orange pulsing border via CSS `@keyframes` animation
|
||||
- **THEN** a warning message SHALL appear (e.g., "⚠ 5 days left — drink up!")
|
||||
|
||||
#### Scenario: Critical tier (1-2 days remaining)
|
||||
- **WHEN** the `keg_freshness` sensor reports a value between 1 and 2 (inclusive)
|
||||
- **THEN** the card SHALL display an aggressive red pulsing border via CSS `@keyframes` animation
|
||||
- **THEN** an urgent message SHALL appear (e.g., "🚨 2 days left!")
|
||||
|
||||
#### Scenario: Expired (0 days remaining)
|
||||
- **WHEN** the `keg_freshness` sensor reports 0
|
||||
- **THEN** the card SHALL display a persistent red overlay or border (no pulsing — static danger state)
|
||||
- **THEN** an expired message SHALL appear (e.g., "Keg expired")
|
||||
|
||||
### Requirement: CSS-only animation implementation
|
||||
All freshness warning animations SHALL be implemented using CSS only, with no JavaScript animation loops.
|
||||
|
||||
#### Scenario: Animation technique
|
||||
- **WHEN** a freshness tier requires pulsing or fading animation
|
||||
- **THEN** the animation SHALL be implemented via CSS `@keyframes` and `animation` properties
|
||||
- **THEN** the card's JavaScript SHALL only set CSS custom properties or CSS classes based on the freshness value
|
||||
- **THEN** no `requestAnimationFrame`, `setInterval`, or `setTimeout` SHALL be used for animation
|
||||
|
||||
### Requirement: Freshness sensor unavailable handling
|
||||
The card SHALL handle the keg freshness sensor being unavailable gracefully.
|
||||
|
||||
#### Scenario: Freshness sensor unavailable
|
||||
- **WHEN** the `keg_freshness` sensor has state `unavailable` or `unknown`
|
||||
- **THEN** the card SHALL display no freshness warning indicators
|
||||
- **THEN** the card SHALL use its normal color scheme (same as >14 days)
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# hacs-packaging Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change perfectdraft-card. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: HACS plugin manifest
|
||||
The repository SHALL include a `hacs.json` manifest in the root that conforms to HACS plugin (Dashboard) requirements.
|
||||
|
||||
#### Scenario: hacs.json present and valid
|
||||
- **WHEN** HACS scans the repository
|
||||
- **THEN** a `hacs.json` file SHALL exist in the repository root
|
||||
- **THEN** it SHALL contain a `name` field with a human-readable display name (e.g., "PerfectDraft Card")
|
||||
- **THEN** it SHALL contain a `filename` field pointing to the built JS file name (e.g., `perfectdraft-card.js`)
|
||||
- **THEN** it SHALL set `content_in_root` to `false` (build output lives in `dist/`)
|
||||
|
||||
### Requirement: dist/ directory with built assets
|
||||
The repository SHALL contain a `dist/` directory with the built card JS file and any co-located static assets.
|
||||
|
||||
#### Scenario: JS file in dist/
|
||||
- **WHEN** HACS downloads the card
|
||||
- **THEN** `dist/` SHALL contain a `.js` file whose name matches the repository name (with or without the `lovelace-` prefix)
|
||||
- **THEN** the JS file SHALL be a self-contained ES module that registers the `perfectdraft-card` custom element
|
||||
|
||||
#### Scenario: Static assets in dist/
|
||||
- **WHEN** the card references static assets (beer logo images)
|
||||
- **THEN** those assets SHALL be co-located in `dist/` (e.g., `dist/assets/`) so HACS downloads them alongside the JS file
|
||||
|
||||
### Requirement: README with installation instructions
|
||||
The repository SHALL include a `README.md` in the root with complete installation and usage documentation.
|
||||
|
||||
#### Scenario: README contents
|
||||
- **WHEN** a user views the repository or the HACS listing
|
||||
- **THEN** the README SHALL include: a brief description of what the card does, a screenshot or visual preview, HACS installation steps (add custom repository, install, add resource), manual installation steps (copy to `www/`, add resource), minimal and full YAML configuration examples, a list of required sensor entities from the PerfectDraft integration, and a list of supported glass sizes
|
||||
|
||||
### Requirement: GitHub releases for versioning
|
||||
The repository SHALL use GitHub releases with semantic version tags for HACS version tracking.
|
||||
|
||||
#### Scenario: Tagged release
|
||||
- **WHEN** a new version of the card is published
|
||||
- **THEN** a GitHub release SHALL be created with a semantic version tag (e.g., `v0.1.0`)
|
||||
- **THEN** the release SHALL include the built `dist/` assets
|
||||
- **THEN** HACS SHALL be able to detect and offer the update to users
|
||||
|
||||
### Requirement: Repository metadata for HACS discoverability
|
||||
The repository SHALL include GitHub metadata to support HACS discovery and display.
|
||||
|
||||
#### Scenario: GitHub repository settings
|
||||
- **WHEN** the repository is added to HACS as a custom repository of type "Dashboard" (plugin)
|
||||
- **THEN** the repository SHALL have a description set on GitHub
|
||||
- **THEN** the repository SHALL have relevant GitHub topics (e.g., `home-assistant`, `hacs`, `lovelace`, `custom-card`, `perfectdraft`)
|
||||
|
||||
### Requirement: Resource registration for HA dashboard
|
||||
The built JS file SHALL be loadable as a dashboard resource in Home Assistant.
|
||||
|
||||
#### Scenario: Resource loaded
|
||||
- **WHEN** a user adds `/hacsfiles/perfectdraft-card/perfectdraft-card.js` (HACS path) or `/local/perfectdraft-card.js` (manual path) as a dashboard resource with type `module`
|
||||
- **THEN** the card SHALL register itself and be available for use in dashboard views
|
||||
- **THEN** the card SHALL appear in the HA card picker with its name and description
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# keg-auto-detection Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change auto-detect-gap-closure. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Tapped beer detected from integration sensors
|
||||
The card SHALL determine the tapped beer from the PerfectDraft integration's keg sensors without requiring the user to select it.
|
||||
|
||||
#### Scenario: Keg sensors resolved for the configured device
|
||||
- **WHEN** the card has a `device_id` and the device exposes sensors with translation keys `keg_product_id` and `keg_name`
|
||||
- **THEN** the card SHALL resolve both entity IDs and read their states on every `hass` update
|
||||
- **THEN** the card SHALL NOT require any beer-related configuration for detection to work
|
||||
|
||||
#### Scenario: Product ID matches a catalog entry
|
||||
- **WHEN** the `keg_product_id` sensor reports a state consisting only of digits that matches the `kegId` of a catalog entry
|
||||
- **THEN** the card SHALL use that catalog entry for the beer's name, brand colors, style, ABV, and keg artwork
|
||||
|
||||
#### Scenario: Product ID does not match but a name is reported
|
||||
- **WHEN** the `keg_product_id` state is absent, non-numeric, or matches no catalog entry, AND the `keg_name` sensor reports a state other than `unavailable` or `unknown`
|
||||
- **THEN** the card SHALL resolve the beer by that reported name against the catalog
|
||||
- **THEN** if the reported name matches no catalog entry, the card SHALL display that name against the generic color palette
|
||||
|
||||
### Requirement: Detection precedence
|
||||
The card SHALL apply a single, defined precedence order when determining which beer to display.
|
||||
|
||||
#### Scenario: Precedence order
|
||||
- **WHEN** the card determines the beer to display
|
||||
- **THEN** it SHALL apply the first applicable source in this order: (1) the `beer_name` config override, (2) a catalog entry matched by reported product ID, (3) a beer resolved from the reported keg name, (4) the no-keg-detected state
|
||||
- **THEN** no later source SHALL override an earlier one
|
||||
|
||||
#### Scenario: Override wins over successful detection
|
||||
- **WHEN** `beer_name` is set in config AND the product ID resolves to a different catalog entry
|
||||
- **THEN** the card SHALL display the beer named by `beer_name`
|
||||
- **THEN** the card SHALL NOT silently substitute the detected beer
|
||||
|
||||
### Requirement: Curated name preferred for the label
|
||||
When the card recognises the reported product ID, it SHALL use its own catalog name for display rather than the name reported by the integration.
|
||||
|
||||
#### Scenario: Product ID resolves and names differ
|
||||
- **WHEN** the product ID matches a catalog entry AND the `keg_name` sensor reports a different string for the same keg
|
||||
- **THEN** the card SHALL display the catalog entry's curated name
|
||||
- **THEN** the card SHALL NOT display the integration-reported name
|
||||
|
||||
#### Scenario: Product ID does not resolve
|
||||
- **WHEN** the product ID matches no catalog entry AND a usable `keg_name` state is reported
|
||||
- **THEN** the card SHALL display the integration-reported name, as it is the only name available
|
||||
|
||||
### Requirement: No-keg-detected state
|
||||
The card SHALL never display a specific beer that it has not detected, and SHALL make the absence of a detected beer visible.
|
||||
|
||||
#### Scenario: Sensors present but no keg reported
|
||||
- **WHEN** both keg sensors are resolved but neither yields a beer, for example because both report `unknown` or `unavailable`
|
||||
- **THEN** the card SHALL render a neutral palette with no keg photograph and no brewery logo
|
||||
- **THEN** the card SHALL display a label indicating that no keg is detected
|
||||
- **THEN** the card SHALL NOT display the name or branding of any catalog beer
|
||||
|
||||
#### Scenario: Detection never falls back to an arbitrary catalog entry
|
||||
- **WHEN** no beer can be determined from any source in the precedence order
|
||||
- **THEN** the card SHALL NOT select a beer by catalog position, insertion order, or any other arbitrary rule
|
||||
|
||||
#### Scenario: Other sensor values still shown
|
||||
- **WHEN** the card is in the no-keg-detected state AND the temperature or freshness sensors report usable values
|
||||
- **THEN** the card SHALL continue to display those values
|
||||
|
||||
### Requirement: Integration version guidance
|
||||
The card SHALL distinguish an out-of-date integration from an empty machine and guide the user accordingly.
|
||||
|
||||
#### Scenario: Device resolved but keg sensors absent
|
||||
- **WHEN** the configured device resolves and a temperature sensor is found, but no sensor with translation key `keg_product_id` or `keg_name` exists for that device
|
||||
- **THEN** the card SHALL display a message stating that the PerfectDraft integration must be updated to a version that provides the keg sensors
|
||||
- **THEN** that message SHALL be distinct from the no-keg-detected state
|
||||
|
||||
#### Scenario: Keg sensors present but idle
|
||||
- **WHEN** the keg sensors exist for the device but report no usable value
|
||||
- **THEN** the card SHALL show the no-keg-detected state and SHALL NOT suggest updating the integration
|
||||
|
||||
### Requirement: Entity resolution completes as entities appear
|
||||
The card SHALL continue attempting entity resolution until the expected sensors are found, so that sensors registered after the card first renders are still discovered.
|
||||
|
||||
#### Scenario: Keg sensors appear after initial resolution
|
||||
- **WHEN** the card has already resolved a temperature entity for its device AND the keg sensors are subsequently added to that device, for example because the user updated the integration
|
||||
- **THEN** the card SHALL resolve the keg entities on a following `hass` update without requiring a browser reload
|
||||
|
||||
#### Scenario: Resolution stops once complete
|
||||
- **WHEN** all expected sensor entities for the device have been resolved
|
||||
- **THEN** the card SHALL NOT repeat the registry scan on subsequent `hass` updates
|
||||
|
||||
#### Scenario: Configured device changes
|
||||
- **WHEN** the card's configured `device_id` changes, for example because the user picked a different device in the editor
|
||||
- **THEN** the card SHALL discard the previously resolved entity IDs and the previously detected beer
|
||||
- **THEN** the card SHALL resolve entities afresh for the newly configured device
|
||||
- **THEN** the card SHALL NOT display values read from the previous device
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# keg-display Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change perfectdraft-card. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Glasses-remaining emoji pictogram
|
||||
The card SHALL display the number of remaining glasses in the keg as a grid of 🍺 emoji characters in the right zone.
|
||||
|
||||
#### Scenario: Normal keg level
|
||||
- **WHEN** the `keg_remaining` sensor reports a percentage > 0
|
||||
- **THEN** the card SHALL calculate glasses remaining as `floor((keg_remaining% / 100 × 6.0L × 1000) / glass_size_mL)`
|
||||
- **THEN** the card SHALL render that many 🍺 emoji characters in a wrapping grid layout
|
||||
- **THEN** a text label SHALL display the count and glass size (e.g., "18 × 330 mL")
|
||||
|
||||
#### Scenario: Dynamic emoji sizing
|
||||
- **WHEN** the number of glasses to display changes
|
||||
- **THEN** the emoji font-size SHALL scale inversely with count — fewer glasses render larger, more glasses render smaller
|
||||
- **THEN** the maximum count (24 glasses at 250mL from a full keg) SHALL fit within the right zone without scrolling
|
||||
|
||||
#### Scenario: Full keg at each glass size
|
||||
- **WHEN** the keg is 100% full (6.0L)
|
||||
- **THEN** at 250 mL the card SHALL display 24 emoji
|
||||
- **THEN** at 330 mL the card SHALL display 18 emoji
|
||||
- **THEN** at 500 mL the card SHALL display 12 emoji
|
||||
- **THEN** at 568 mL (UK pint) the card SHALL display 10 emoji
|
||||
- **THEN** at 473 mL (US pint) the card SHALL display 12 emoji
|
||||
|
||||
### Requirement: Empty keg state
|
||||
The card SHALL display a distinct visual state when the keg is empty.
|
||||
|
||||
#### Scenario: Keg at zero
|
||||
- **WHEN** the `keg_remaining` sensor reports 0% (or the calculated glass count is 0)
|
||||
- **THEN** the emoji grid SHALL be replaced with an empty-keg disaster scene visual
|
||||
- **THEN** the disaster scene SHALL clearly communicate that the keg is empty
|
||||
|
||||
### Requirement: Glass size selection dialog
|
||||
The card SHALL provide a modal dialog for selecting the glass volume used in the pictogram calculation.
|
||||
|
||||
#### Scenario: Opening the dialog
|
||||
- **WHEN** the user taps anywhere in the keg emoji zone (right zone)
|
||||
- **THEN** a modal dialog SHALL appear overlaying the card
|
||||
- **THEN** the dialog SHALL list five glass size options: 250 mL, 330 mL, 500 mL, 568 mL (UK pint), 473 mL (US pint)
|
||||
- **THEN** the currently selected size SHALL be visually highlighted
|
||||
|
||||
#### Scenario: Selecting a glass size
|
||||
- **WHEN** the user taps a glass size option in the dialog
|
||||
- **THEN** the dialog SHALL close
|
||||
- **THEN** the emoji grid SHALL immediately recalculate and re-render with the new glass size
|
||||
- **THEN** the count label SHALL update to reflect the new size
|
||||
|
||||
#### Scenario: Dismissing without change
|
||||
- **WHEN** the user taps outside the dialog or taps a close/cancel control
|
||||
- **THEN** the dialog SHALL close without changing the glass size
|
||||
|
||||
### Requirement: Glass size persistence
|
||||
The selected glass size SHALL persist across page refreshes on the same device.
|
||||
|
||||
#### Scenario: Persisting selection
|
||||
- **WHEN** the user selects a glass size via the dialog
|
||||
- **THEN** the selection SHALL be saved to `localStorage` keyed by the card's primary entity ID
|
||||
|
||||
#### Scenario: Restoring selection
|
||||
- **WHEN** the card loads and a glass size exists in `localStorage` for this card
|
||||
- **THEN** the card SHALL use the persisted glass size instead of the config default
|
||||
|
||||
#### Scenario: No persisted selection
|
||||
- **WHEN** the card loads and no glass size exists in `localStorage` for this card
|
||||
- **THEN** the card SHALL use the `glass_size` value from the card config (defaulting to 330 mL if not specified)
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "perfectdraft-card",
|
||||
"version": "0.3.1",
|
||||
"version": "0.4.0",
|
||||
"description": "Custom Lovelace card for the PerfectDraft Pro Home Assistant integration",
|
||||
"main": "dist/perfectdraft-card.js",
|
||||
"type": "module",
|
||||
|
||||
+150
-30
@@ -1,11 +1,11 @@
|
||||
import { LitElement, html, css, type CSSResultGroup, type TemplateResult } from "lit";
|
||||
import { LitElement, html, css, nothing, type CSSResultGroup, type TemplateResult } from "lit";
|
||||
import { customElement, property, state } from "lit/decorators.js";
|
||||
|
||||
import type { PerfectDraftCardConfig } from "./types.js";
|
||||
import { GLASS_SIZES, DEFAULT_GLASS_SIZE, DOMAIN, LAYOUTS, DEFAULT_LAYOUT } from "./const.js";
|
||||
import { getAllBeers } from "./beer-catalog.js";
|
||||
import { getAllBeers, getBeerByKegId } from "./beer-catalog.js";
|
||||
|
||||
const EDITOR_VERSION = "0.3.1";
|
||||
const EDITOR_VERSION = "0.4.0";
|
||||
|
||||
interface DiscoveredDevice {
|
||||
deviceId: string;
|
||||
@@ -59,6 +59,26 @@ export class PerfectDraftCardEditor extends LitElement {
|
||||
}
|
||||
}
|
||||
|
||||
/** The product ID the configured device reports right now, if any. */
|
||||
private _currentProductId(): string | undefined {
|
||||
const device = this._devices.find((d) => d.deviceId === this._config?.device_id);
|
||||
const entityId = device?.entities.get("keg_product_id");
|
||||
if (!entityId) return undefined;
|
||||
const state = this.hass?.states[entityId]?.state;
|
||||
return state && state !== "unavailable" && state !== "unknown" ? state : undefined;
|
||||
}
|
||||
|
||||
/** Writes or clears one correction, keyed by the keg it corrects. */
|
||||
private _setOverride(productId: string, beerName: string): void {
|
||||
const next = { ...(this._config.beer_overrides ?? {}) };
|
||||
if (beerName) {
|
||||
next[productId] = beerName;
|
||||
} else {
|
||||
delete next[productId];
|
||||
}
|
||||
this._updateConfig("beer_overrides", Object.keys(next).length > 0 ? next : undefined);
|
||||
}
|
||||
|
||||
private _updateConfig(key: string, value: unknown): void {
|
||||
this._config = { ...this._config, [key]: value };
|
||||
const event = new CustomEvent("config-changed", {
|
||||
@@ -69,6 +89,87 @@ export class PerfectDraftCardEditor extends LitElement {
|
||||
this.dispatchEvent(event);
|
||||
}
|
||||
|
||||
/**
|
||||
* A correction is recorded against the product ID currently in the machine, so
|
||||
* it stops applying when that keg is swapped. Saved corrections are listed so
|
||||
* an entry left over from an earlier keg is visible and removable.
|
||||
*/
|
||||
private _renderOverrideSection(): TemplateResult {
|
||||
const productId = this._currentProductId();
|
||||
const active = productId ? (this._config.beer_overrides?.[productId] ?? "") : "";
|
||||
const detected = productId ? getBeerByKegId(productId) : undefined;
|
||||
const entries = Object.entries(this._config.beer_overrides ?? {});
|
||||
|
||||
return html`
|
||||
<div class="advanced-heading">Beer detection</div>
|
||||
|
||||
<div class="field">
|
||||
<label>Correct the beer for the keg in the machine</label>
|
||||
<select
|
||||
.value=${active}
|
||||
?disabled=${!productId}
|
||||
@change=${(e: Event) => {
|
||||
if (productId) this._setOverride(productId, (e.target as HTMLSelectElement).value);
|
||||
}}
|
||||
>
|
||||
<option value="" ?selected=${!active}>Use auto-detection</option>
|
||||
${getAllBeers().map(
|
||||
(b) => html`
|
||||
<option value=${b.name} ?selected=${active === b.name}>${b.name} (${b.brewery})</option>
|
||||
`,
|
||||
)}
|
||||
${(this._config.custom_beers ?? []).map(
|
||||
(cb) => html`<option value=${cb.name} ?selected=${active === cb.name}>${cb.name} (custom)</option>`,
|
||||
)}
|
||||
</select>
|
||||
<div class="hint">
|
||||
${productId
|
||||
? html`
|
||||
Applies only to the keg now in the machine — product ID ${productId}${detected
|
||||
? `, detected as ${detected.name}`
|
||||
: ", not in the catalog"}. Swap kegs and it stops applying.
|
||||
`
|
||||
: "No keg detected right now. A correction is saved against the keg it corrects, so tap a keg first."}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
${entries.length > 0
|
||||
? html`
|
||||
<div class="field">
|
||||
<label>Saved corrections</label>
|
||||
<div class="override-list">
|
||||
${entries.map(([id, name]) => {
|
||||
const catalog = getBeerByKegId(id);
|
||||
return html`
|
||||
<div class="override-row">
|
||||
<div class="override-text">
|
||||
<span class="override-beer">${name}</span>
|
||||
<span class="override-meta">
|
||||
ID ${id}${catalog ? ` · detected as ${catalog.name}` : ""}${id === productId
|
||||
? " · applying now"
|
||||
: ""}
|
||||
</span>
|
||||
</div>
|
||||
<button
|
||||
class="override-remove"
|
||||
title="Remove this correction"
|
||||
@click=${() => this._setOverride(id, "")}
|
||||
>
|
||||
✕
|
||||
</button>
|
||||
</div>
|
||||
`;
|
||||
})}
|
||||
</div>
|
||||
<div class="hint">
|
||||
Entries for kegs that are not in the machine have no effect. Remove them if you no longer want them.
|
||||
</div>
|
||||
</div>
|
||||
`
|
||||
: nothing}
|
||||
`;
|
||||
}
|
||||
|
||||
protected render(): TemplateResult {
|
||||
if (!this.hass) {
|
||||
return html`<div>Loading...</div>`;
|
||||
@@ -131,33 +232,7 @@ export class PerfectDraftCardEditor extends LitElement {
|
||||
</select>
|
||||
</div>
|
||||
|
||||
<div class="field">
|
||||
<label>Beer override</label>
|
||||
<select
|
||||
.value=${this._config.beer_name ?? ""}
|
||||
@change=${(e: Event) =>
|
||||
this._updateConfig("beer_name", (e.target as HTMLSelectElement).value || undefined)}
|
||||
>
|
||||
<option value="" ?selected=${!this._config.beer_name}>Auto-detect from the machine</option>
|
||||
${getAllBeers().map(
|
||||
(b) => html`
|
||||
<option value=${b.name} ?selected=${this._config.beer_name === b.name}>
|
||||
${b.name} (${b.brewery})
|
||||
</option>
|
||||
`,
|
||||
)}
|
||||
${(this._config.custom_beers ?? []).map(
|
||||
(cb) => html`
|
||||
<option value=${cb.name} ?selected=${this._config.beer_name === cb.name}>
|
||||
${cb.name} (custom)
|
||||
</option>
|
||||
`,
|
||||
)}
|
||||
</select>
|
||||
<div class="hint">
|
||||
Leave on auto-detect. Only set this if your keg is not recognised or is shown wrongly.
|
||||
</div>
|
||||
</div>
|
||||
${this._renderOverrideSection()}
|
||||
|
||||
<div class="advanced-heading">Emoji matrix (advanced)</div>
|
||||
|
||||
@@ -206,6 +281,51 @@ export class PerfectDraftCardEditor extends LitElement {
|
||||
margin-bottom: 4px;
|
||||
font-size: 0.9em;
|
||||
}
|
||||
.field select:disabled {
|
||||
opacity: 0.5;
|
||||
cursor: not-allowed;
|
||||
}
|
||||
.override-list {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 6px;
|
||||
}
|
||||
.override-row {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
padding: 8px 10px;
|
||||
border: 1px solid var(--divider-color, #333);
|
||||
border-radius: 4px;
|
||||
}
|
||||
.override-text {
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
}
|
||||
.override-beer {
|
||||
font-size: 0.95em;
|
||||
}
|
||||
.override-meta {
|
||||
font-size: 0.75em;
|
||||
opacity: 0.55;
|
||||
}
|
||||
.override-remove {
|
||||
flex: 0 0 auto;
|
||||
background: none;
|
||||
border: none;
|
||||
color: inherit;
|
||||
opacity: 0.6;
|
||||
font-size: 1em;
|
||||
cursor: pointer;
|
||||
padding: 4px 6px;
|
||||
border-radius: 4px;
|
||||
}
|
||||
.override-remove:hover {
|
||||
opacity: 1;
|
||||
background: rgba(255, 255, 255, 0.08);
|
||||
}
|
||||
.field select,
|
||||
.field input {
|
||||
width: 100%;
|
||||
|
||||
+84
-14
@@ -21,7 +21,7 @@ import {
|
||||
} from "./beer-catalog.js";
|
||||
import "./editor.js";
|
||||
|
||||
const CARD_VERSION = "0.3.1";
|
||||
const CARD_VERSION = "0.4.0";
|
||||
|
||||
const NO_KEG_LABEL = "No keg detected";
|
||||
|
||||
@@ -71,6 +71,8 @@ export class PerfectDraftCard extends LitElement {
|
||||
@state() private _maxMatrixWidth?: string;
|
||||
@state() private _showGlassDialog = false;
|
||||
@state() private _failedImages = new Set<string>();
|
||||
@state() private _overrideActive = false;
|
||||
@state() private _detectedName?: string;
|
||||
|
||||
private _entityIds: { temperature?: string; kegRemaining?: string; kegFreshness?: string; kegProduct?: string; kegName?: string } = {};
|
||||
private _entitiesResolved = false;
|
||||
@@ -89,6 +91,8 @@ export class PerfectDraftCard extends LitElement {
|
||||
this._entityIds = {};
|
||||
this._entitiesResolved = false;
|
||||
this._beer = undefined;
|
||||
this._overrideActive = false;
|
||||
this._detectedName = undefined;
|
||||
}
|
||||
|
||||
this._config = { ...config };
|
||||
@@ -214,37 +218,49 @@ export class PerfectDraftCard extends LitElement {
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolves the beer to display, in precedence order: the manual override, then
|
||||
* a catalog entry matched on the reported product ID, then the reported keg
|
||||
* name. Leaves `_beer` undefined when none of those yield anything, which is
|
||||
* what puts the card into its no-keg state.
|
||||
* Resolves the beer to display, in precedence order: an override recorded
|
||||
* against the reported product ID, then a catalog entry matched on that ID,
|
||||
* then the reported keg name. Leaves `_beer` undefined when none of those
|
||||
* yield anything, which is what puts the card into its no-keg state.
|
||||
*/
|
||||
private _updateDetectedBeer(): void {
|
||||
if (!this._config) return;
|
||||
|
||||
const override = this._config.beer_name?.trim();
|
||||
if (override) {
|
||||
this._assignBeer(resolveBeer(override, this._config.custom_beers));
|
||||
return;
|
||||
}
|
||||
|
||||
const idState = this._getState(this._entityIds.kegProduct);
|
||||
const productId =
|
||||
idState && idState !== "unavailable" && idState !== "unknown" ? idState : undefined;
|
||||
const nameState = this._getState(this._entityIds.kegName);
|
||||
const reportedName =
|
||||
nameState && nameState !== "unavailable" && nameState !== "unknown" ? nameState : undefined;
|
||||
|
||||
let detected: BeerEntry | undefined;
|
||||
if (idState && /^\d+$/.test(idState)) {
|
||||
if (productId && /^\d+$/.test(productId)) {
|
||||
// A recognised product ID keeps the curated catalog name. The integration's
|
||||
// catalog is a product listing, so its names carry pack sizes and
|
||||
// qualifiers we do not want on the label.
|
||||
detected = getBeerByKegId(idState);
|
||||
detected = getBeerByKegId(productId);
|
||||
}
|
||||
if (!detected && reportedName) {
|
||||
detected = resolveBeer(reportedName, this._config.custom_beers);
|
||||
}
|
||||
|
||||
// An override is bound to the keg it corrects, so it retires itself when the
|
||||
// keg changes. The card cannot clean up config — `config-changed` is only
|
||||
// honoured while the editor is open — so the binding has to come from the
|
||||
// lookup rather than from pruning stale entries. No product ID means no
|
||||
// possible match, which keeps the no-keg state unreachable from config.
|
||||
const override = productId ? this._config.beer_overrides?.[productId]?.trim() : undefined;
|
||||
if (override) {
|
||||
const corrected = resolveBeer(override, this._config.custom_beers);
|
||||
this._assignBeer(corrected);
|
||||
this._overrideActive = true;
|
||||
this._detectedName = detected && detected.name !== corrected.name ? detected.name : undefined;
|
||||
return;
|
||||
}
|
||||
|
||||
this._assignBeer(detected);
|
||||
this._overrideActive = false;
|
||||
this._detectedName = undefined;
|
||||
}
|
||||
|
||||
private _assignBeer(beer: BeerEntry | undefined): void {
|
||||
@@ -407,6 +423,7 @@ export class PerfectDraftCard extends LitElement {
|
||||
${this._beerDetected
|
||||
? html`<div class="beer-style" style="color: ${beer.colors.text}88;">${beer.brewery} · ${beer.abv}%</div>`
|
||||
: nothing}
|
||||
${this._renderOverrideMarker(beer.colors.text)}
|
||||
`;
|
||||
}
|
||||
|
||||
@@ -450,7 +467,7 @@ export class PerfectDraftCard extends LitElement {
|
||||
<div class="card-content layout-compact-content">
|
||||
<div class="compact-visual">${this._renderVisual(c.beer)}</div>
|
||||
<div class="compact-main">
|
||||
<div class="compact-name">${c.beer.name}</div>
|
||||
<div class="compact-name">${this._renderCompactOverrideGlyph()}${c.beer.name}</div>
|
||||
<div class="compact-bar">
|
||||
<div class="compact-bar-fill" style="width: ${pct}%; background: ${c.beer.colors.primary};"></div>
|
||||
</div>
|
||||
@@ -474,6 +491,7 @@ export class PerfectDraftCard extends LitElement {
|
||||
<span class="hero-temp">❄ ${this._tempText(c.temp)}</span>
|
||||
</div>
|
||||
<div class="hero-count">${this._countText(c.glassCount)}</div>
|
||||
${this._renderOverrideMarker()}
|
||||
</div>
|
||||
${this._renderFreshnessIndicator(c.freshDays, c.tier)}
|
||||
</div>
|
||||
@@ -490,6 +508,7 @@ export class PerfectDraftCard extends LitElement {
|
||||
</div>
|
||||
<div class="vessel-mid" @click=${this._openGlassDialog}>${this._renderGlassVessel(c.beer, pct)}</div>
|
||||
<div class="vessel-count" @click=${this._openGlassDialog}>${this._countText(c.glassCount)}</div>
|
||||
${this._renderOverrideMarker()}
|
||||
${this._renderFreshnessIndicator(c.freshDays, c.tier)}
|
||||
</div>
|
||||
`;
|
||||
@@ -528,6 +547,34 @@ export class PerfectDraftCard extends LitElement {
|
||||
`;
|
||||
}
|
||||
|
||||
private _overrideTitle(): string {
|
||||
const base = "This beer comes from a correction saved for this keg in the card config.";
|
||||
return this._detectedName ? `${base} The machine reports ${this._detectedName}.` : base;
|
||||
}
|
||||
|
||||
/**
|
||||
* Marks an applied correction, so an override is never mistaken for a
|
||||
* detection result. Shown even when it agrees with detection: an override
|
||||
* that agrees is redundant and worth seeing so it can be removed.
|
||||
*/
|
||||
private _renderOverrideMarker(color?: string): TemplateResult | typeof nothing {
|
||||
if (!this._overrideActive) return nothing;
|
||||
const text = this._detectedName
|
||||
? `⚙ Override · machine reports ${this._detectedName}`
|
||||
: "⚙ Override";
|
||||
return html`
|
||||
<div class="override-marker" style="${color ? `color: ${color};` : ""}" title="${this._overrideTitle()}">
|
||||
${text}
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
|
||||
/** Compact has no room for the pill, so the override becomes a glyph on the name. */
|
||||
private _renderCompactOverrideGlyph(): TemplateResult | typeof nothing {
|
||||
if (!this._overrideActive) return nothing;
|
||||
return html`<span class="compact-override" title="${this._overrideTitle()}">⚙</span>`;
|
||||
}
|
||||
|
||||
private _renderFreshnessIndicator(days: number | null, tier: FreshnessTier): TemplateResult {
|
||||
if (tier === "normal" || days === null) return html``;
|
||||
const messages: Record<string, string> = {
|
||||
@@ -914,6 +961,29 @@ export class PerfectDraftCard extends LitElement {
|
||||
margin-top: 4px;
|
||||
}
|
||||
|
||||
/* === OVERRIDE MARKER === */
|
||||
.override-marker {
|
||||
display: inline-block;
|
||||
margin-top: 8px;
|
||||
padding: 3px 10px;
|
||||
border-radius: 12px;
|
||||
font-size: 0.75em;
|
||||
font-weight: 500;
|
||||
text-align: center;
|
||||
/* Neutral grey plus a currentColor border, so the pill reads against
|
||||
both the dark card and the light end of the label palettes. */
|
||||
background: rgba(127, 127, 127, 0.18);
|
||||
border: 1px solid currentColor;
|
||||
opacity: 0.8;
|
||||
cursor: help;
|
||||
}
|
||||
.compact-override {
|
||||
margin-right: 5px;
|
||||
font-size: 0.85em;
|
||||
opacity: 0.65;
|
||||
cursor: help;
|
||||
}
|
||||
|
||||
/* === FRESHNESS INDICATOR === */
|
||||
.freshness-indicator {
|
||||
margin-top: 12px;
|
||||
|
||||
+5
-2
@@ -4,8 +4,11 @@ export interface PerfectDraftCardConfig {
|
||||
type?: string;
|
||||
device_id: string;
|
||||
glass_size?: number;
|
||||
/** Overrides auto-detection. Left unset, the tapped beer is read from the integration. */
|
||||
beer_name?: string;
|
||||
/**
|
||||
* Corrections keyed by the product ID the integration reports, so an entry
|
||||
* only applies while that keg is tapped and cannot outlive it.
|
||||
*/
|
||||
beer_overrides?: Record<string, string>;
|
||||
custom_beers?: CustomBeerEntry[];
|
||||
layout?: CardLayout;
|
||||
matrix_columns?: number | "auto";
|
||||
|
||||
Reference in New Issue
Block a user