Archive scoped-beer-override and sync its specs
Applies the change's delta specs to the main specs and files the change under openspec/changes/archive/2026-09-16-scoped-beer-override. keg-auto-detection gains the scoped-override and override-visibility requirements, and its detection precedence is rewritten so no config value can precede detection except by matching the reported product ID. card-config drops the beer_name override requirement in favour of the beer_overrides map, and records beer_name alongside beer_entity as an ignored legacy key. Also corrects three stale beer_name references in beer-catalog and beer-label. The proposal's capability list missed those two specs; the substance of their requirements is unchanged, only the key name they name, so this is a naming correction rather than a requirement change. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -28,11 +28,11 @@ The card SHALL include static logo images for beers in the built-in catalog.
|
||||
- **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.
|
||||
The card SHALL support user-defined beer entries that extend or override the built-in catalog, reachable through a `beer_overrides` entry.
|
||||
|
||||
#### 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** those beers SHALL be resolvable by a `beer_overrides` entry 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
|
||||
|
||||
@@ -31,7 +31,7 @@ The card SHALL display the current beer temperature prominently in the left zone
|
||||
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
|
||||
- **WHEN** a beer has been determined by detection or by a `beer_overrides` entry
|
||||
- **THEN** the card SHALL display that beer's full name as text in the label zone
|
||||
|
||||
#### Scenario: Detected by product ID
|
||||
|
||||
@@ -50,14 +50,20 @@ The card SHALL validate its configuration and display clear errors for invalid c
|
||||
- **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)
|
||||
#### 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 an explicit override signals the user's intent
|
||||
- **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`, which is no longer supported
|
||||
- **THEN** the card SHALL ignore it without throwing
|
||||
- **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.
|
||||
@@ -69,9 +75,10 @@ The card SHALL provide a graphical configuration editor as the primary means of
|
||||
|
||||
#### 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** 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
|
||||
@@ -79,15 +86,15 @@ The card SHALL provide a graphical configuration editor as the primary means of
|
||||
- **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.
|
||||
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 override
|
||||
- **WHEN** `beer_name` matches the `name` of a `custom_beers` entry
|
||||
#### 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
|
||||
|
||||
### Requirement: YAML remains valid for power users
|
||||
@@ -98,20 +105,32 @@ While not required, the YAML config SHALL remain a valid and complete representa
|
||||
- **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.
|
||||
### 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: Override absent
|
||||
- **WHEN** the card config has no `beer_name`
|
||||
#### 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_name`, so newly created cards start with detection only
|
||||
- **THEN** `getStubConfig()` SHALL NOT populate `beer_overrides`, 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: 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: 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
|
||||
#### 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
|
||||
|
||||
|
||||
@@ -25,13 +25,18 @@ The card SHALL apply a single, defined precedence order when determining which b
|
||||
|
||||
#### 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** 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: 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
|
||||
#### 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
|
||||
|
||||
### 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.
|
||||
@@ -91,3 +96,47 @@ The card SHALL continue attempting entity resolution until the expected sensors
|
||||
- **THEN** the card SHALL resolve entities afresh for the newly configured device
|
||||
- **THEN** the card SHALL NOT display values read from the previous device
|
||||
|
||||
### 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user