Sync all changes to main specs and archive them

openspec/specs/ had been empty since the project started: all three changes
were left active and unsynced, so there was no consolidated statement of how
the card is meant to behave.

Synced in dependency order -- perfectdraft-card, then card-layouts-and-imagery,
then auto-detect-gap-closure -- so the MODIFIED and REMOVED operations in the
last one had the base requirements they refer to. Result is 10 capability
specs holding 57 requirements, all validating.

Fixed a contradiction the merge exposed: card-layouts still required a beer
selection dialog reachable from every layout, which auto-detect-gap-closure
had removed. Its interaction scenario now covers the glass dialog only, plus
a scenario tying beer display to the keg-auto-detection rules.

Note the archived tasks.md files retain their unchecked items -- the three
hardware verification tasks in auto-detect-gap-closure, and pre-existing
incomplete tasks in the two older changes.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-09-09 19:01:35 +02:00
co-authored by Cursor
parent 74b5e36ef1
commit 01b4247cf3
37 changed files with 831 additions and 0 deletions
+73
View File
@@ -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
+81
View File
@@ -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
+64
View File
@@ -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
+117
View File
@@ -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
+66
View File
@@ -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
+159
View File
@@ -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
+50
View File
@@ -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)
+59
View File
@@ -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
+93
View File
@@ -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
+69
View File
@@ -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)