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:
|
Before Width: | Height: | Size: 145 KiB After Width: | Height: | Size: 145 KiB |
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user