From 01b4247cf34669c72eff925ea980442d8ce2ee2f Mon Sep 17 00:00:00 2001 From: Rick Falkvinge Date: Wed, 9 Sep 2026 19:01:35 +0200 Subject: [PATCH] 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 --- .../.openspec.yaml | 0 .../design.md | 0 .../keg-id-mapping.md | 0 .../proposal.md | 0 .../specs/beer-catalog/spec.md | 0 .../specs/beer-label/spec.md | 0 .../specs/card-config/spec.md | 0 .../specs/keg-auto-detection/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../assets/cropped-viewport.png | Bin .../design.md | 0 .../proposal.md | 0 .../specs/beer-imagery/spec.md | 0 .../specs/card-layouts/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../2026-09-09-perfectdraft-card}/design.md | 0 .../2026-09-09-perfectdraft-card}/proposal.md | 0 .../specs/beer-catalog/spec.md | 0 .../specs/beer-label/spec.md | 0 .../specs/card-config/spec.md | 0 .../specs/card-core/spec.md | 0 .../specs/freshness-warning/spec.md | 0 .../specs/hacs-packaging/spec.md | 0 .../specs/keg-display/spec.md | 0 .../2026-09-09-perfectdraft-card}/tasks.md | 0 openspec/specs/beer-catalog/spec.md | 73 ++++++++ openspec/specs/beer-imagery/spec.md | 81 +++++++++ openspec/specs/beer-label/spec.md | 64 +++++++ openspec/specs/card-config/spec.md | 117 +++++++++++++ openspec/specs/card-core/spec.md | 66 ++++++++ openspec/specs/card-layouts/spec.md | 159 ++++++++++++++++++ openspec/specs/freshness-warning/spec.md | 50 ++++++ openspec/specs/hacs-packaging/spec.md | 59 +++++++ openspec/specs/keg-auto-detection/spec.md | 93 ++++++++++ openspec/specs/keg-display/spec.md | 69 ++++++++ 37 files changed, 831 insertions(+) rename openspec/changes/{auto-detect-gap-closure => archive/2026-09-09-auto-detect-gap-closure}/.openspec.yaml (100%) rename openspec/changes/{auto-detect-gap-closure => archive/2026-09-09-auto-detect-gap-closure}/design.md (100%) rename openspec/changes/{auto-detect-gap-closure => archive/2026-09-09-auto-detect-gap-closure}/keg-id-mapping.md (100%) rename openspec/changes/{auto-detect-gap-closure => archive/2026-09-09-auto-detect-gap-closure}/proposal.md (100%) rename openspec/changes/{auto-detect-gap-closure => archive/2026-09-09-auto-detect-gap-closure}/specs/beer-catalog/spec.md (100%) rename openspec/changes/{auto-detect-gap-closure => archive/2026-09-09-auto-detect-gap-closure}/specs/beer-label/spec.md (100%) rename openspec/changes/{auto-detect-gap-closure => archive/2026-09-09-auto-detect-gap-closure}/specs/card-config/spec.md (100%) rename openspec/changes/{auto-detect-gap-closure => archive/2026-09-09-auto-detect-gap-closure}/specs/keg-auto-detection/spec.md (100%) rename openspec/changes/{auto-detect-gap-closure => archive/2026-09-09-auto-detect-gap-closure}/tasks.md (100%) rename openspec/changes/{card-layouts-and-imagery => archive/2026-09-09-card-layouts-and-imagery}/.openspec.yaml (100%) rename openspec/changes/{card-layouts-and-imagery => archive/2026-09-09-card-layouts-and-imagery}/assets/cropped-viewport.png (100%) rename openspec/changes/{card-layouts-and-imagery => archive/2026-09-09-card-layouts-and-imagery}/design.md (100%) rename openspec/changes/{card-layouts-and-imagery => archive/2026-09-09-card-layouts-and-imagery}/proposal.md (100%) rename openspec/changes/{card-layouts-and-imagery => archive/2026-09-09-card-layouts-and-imagery}/specs/beer-imagery/spec.md (100%) rename openspec/changes/{card-layouts-and-imagery => archive/2026-09-09-card-layouts-and-imagery}/specs/card-layouts/spec.md (100%) rename openspec/changes/{card-layouts-and-imagery => archive/2026-09-09-card-layouts-and-imagery}/tasks.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/.openspec.yaml (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/design.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/proposal.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/specs/beer-catalog/spec.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/specs/beer-label/spec.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/specs/card-config/spec.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/specs/card-core/spec.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/specs/freshness-warning/spec.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/specs/hacs-packaging/spec.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/specs/keg-display/spec.md (100%) rename openspec/changes/{perfectdraft-card => archive/2026-09-09-perfectdraft-card}/tasks.md (100%) create mode 100644 openspec/specs/beer-catalog/spec.md create mode 100644 openspec/specs/beer-imagery/spec.md create mode 100644 openspec/specs/beer-label/spec.md create mode 100644 openspec/specs/card-config/spec.md create mode 100644 openspec/specs/card-core/spec.md create mode 100644 openspec/specs/card-layouts/spec.md create mode 100644 openspec/specs/freshness-warning/spec.md create mode 100644 openspec/specs/hacs-packaging/spec.md create mode 100644 openspec/specs/keg-auto-detection/spec.md create mode 100644 openspec/specs/keg-display/spec.md diff --git a/openspec/changes/auto-detect-gap-closure/.openspec.yaml b/openspec/changes/archive/2026-09-09-auto-detect-gap-closure/.openspec.yaml similarity index 100% rename from openspec/changes/auto-detect-gap-closure/.openspec.yaml rename to openspec/changes/archive/2026-09-09-auto-detect-gap-closure/.openspec.yaml diff --git a/openspec/changes/auto-detect-gap-closure/design.md b/openspec/changes/archive/2026-09-09-auto-detect-gap-closure/design.md similarity index 100% rename from openspec/changes/auto-detect-gap-closure/design.md rename to openspec/changes/archive/2026-09-09-auto-detect-gap-closure/design.md diff --git a/openspec/changes/auto-detect-gap-closure/keg-id-mapping.md b/openspec/changes/archive/2026-09-09-auto-detect-gap-closure/keg-id-mapping.md similarity index 100% rename from openspec/changes/auto-detect-gap-closure/keg-id-mapping.md rename to openspec/changes/archive/2026-09-09-auto-detect-gap-closure/keg-id-mapping.md diff --git a/openspec/changes/auto-detect-gap-closure/proposal.md b/openspec/changes/archive/2026-09-09-auto-detect-gap-closure/proposal.md similarity index 100% rename from openspec/changes/auto-detect-gap-closure/proposal.md rename to openspec/changes/archive/2026-09-09-auto-detect-gap-closure/proposal.md diff --git a/openspec/changes/auto-detect-gap-closure/specs/beer-catalog/spec.md b/openspec/changes/archive/2026-09-09-auto-detect-gap-closure/specs/beer-catalog/spec.md similarity index 100% rename from openspec/changes/auto-detect-gap-closure/specs/beer-catalog/spec.md rename to openspec/changes/archive/2026-09-09-auto-detect-gap-closure/specs/beer-catalog/spec.md diff --git a/openspec/changes/auto-detect-gap-closure/specs/beer-label/spec.md b/openspec/changes/archive/2026-09-09-auto-detect-gap-closure/specs/beer-label/spec.md similarity index 100% rename from openspec/changes/auto-detect-gap-closure/specs/beer-label/spec.md rename to openspec/changes/archive/2026-09-09-auto-detect-gap-closure/specs/beer-label/spec.md diff --git a/openspec/changes/auto-detect-gap-closure/specs/card-config/spec.md b/openspec/changes/archive/2026-09-09-auto-detect-gap-closure/specs/card-config/spec.md similarity index 100% rename from openspec/changes/auto-detect-gap-closure/specs/card-config/spec.md rename to openspec/changes/archive/2026-09-09-auto-detect-gap-closure/specs/card-config/spec.md diff --git a/openspec/changes/auto-detect-gap-closure/specs/keg-auto-detection/spec.md b/openspec/changes/archive/2026-09-09-auto-detect-gap-closure/specs/keg-auto-detection/spec.md similarity index 100% rename from openspec/changes/auto-detect-gap-closure/specs/keg-auto-detection/spec.md rename to openspec/changes/archive/2026-09-09-auto-detect-gap-closure/specs/keg-auto-detection/spec.md diff --git a/openspec/changes/auto-detect-gap-closure/tasks.md b/openspec/changes/archive/2026-09-09-auto-detect-gap-closure/tasks.md similarity index 100% rename from openspec/changes/auto-detect-gap-closure/tasks.md rename to openspec/changes/archive/2026-09-09-auto-detect-gap-closure/tasks.md diff --git a/openspec/changes/card-layouts-and-imagery/.openspec.yaml b/openspec/changes/archive/2026-09-09-card-layouts-and-imagery/.openspec.yaml similarity index 100% rename from openspec/changes/card-layouts-and-imagery/.openspec.yaml rename to openspec/changes/archive/2026-09-09-card-layouts-and-imagery/.openspec.yaml diff --git a/openspec/changes/card-layouts-and-imagery/assets/cropped-viewport.png b/openspec/changes/archive/2026-09-09-card-layouts-and-imagery/assets/cropped-viewport.png similarity index 100% rename from openspec/changes/card-layouts-and-imagery/assets/cropped-viewport.png rename to openspec/changes/archive/2026-09-09-card-layouts-and-imagery/assets/cropped-viewport.png diff --git a/openspec/changes/card-layouts-and-imagery/design.md b/openspec/changes/archive/2026-09-09-card-layouts-and-imagery/design.md similarity index 100% rename from openspec/changes/card-layouts-and-imagery/design.md rename to openspec/changes/archive/2026-09-09-card-layouts-and-imagery/design.md diff --git a/openspec/changes/card-layouts-and-imagery/proposal.md b/openspec/changes/archive/2026-09-09-card-layouts-and-imagery/proposal.md similarity index 100% rename from openspec/changes/card-layouts-and-imagery/proposal.md rename to openspec/changes/archive/2026-09-09-card-layouts-and-imagery/proposal.md diff --git a/openspec/changes/card-layouts-and-imagery/specs/beer-imagery/spec.md b/openspec/changes/archive/2026-09-09-card-layouts-and-imagery/specs/beer-imagery/spec.md similarity index 100% rename from openspec/changes/card-layouts-and-imagery/specs/beer-imagery/spec.md rename to openspec/changes/archive/2026-09-09-card-layouts-and-imagery/specs/beer-imagery/spec.md diff --git a/openspec/changes/card-layouts-and-imagery/specs/card-layouts/spec.md b/openspec/changes/archive/2026-09-09-card-layouts-and-imagery/specs/card-layouts/spec.md similarity index 100% rename from openspec/changes/card-layouts-and-imagery/specs/card-layouts/spec.md rename to openspec/changes/archive/2026-09-09-card-layouts-and-imagery/specs/card-layouts/spec.md diff --git a/openspec/changes/card-layouts-and-imagery/tasks.md b/openspec/changes/archive/2026-09-09-card-layouts-and-imagery/tasks.md similarity index 100% rename from openspec/changes/card-layouts-and-imagery/tasks.md rename to openspec/changes/archive/2026-09-09-card-layouts-and-imagery/tasks.md diff --git a/openspec/changes/perfectdraft-card/.openspec.yaml b/openspec/changes/archive/2026-09-09-perfectdraft-card/.openspec.yaml similarity index 100% rename from openspec/changes/perfectdraft-card/.openspec.yaml rename to openspec/changes/archive/2026-09-09-perfectdraft-card/.openspec.yaml diff --git a/openspec/changes/perfectdraft-card/design.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/design.md similarity index 100% rename from openspec/changes/perfectdraft-card/design.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/design.md diff --git a/openspec/changes/perfectdraft-card/proposal.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/proposal.md similarity index 100% rename from openspec/changes/perfectdraft-card/proposal.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/proposal.md diff --git a/openspec/changes/perfectdraft-card/specs/beer-catalog/spec.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/specs/beer-catalog/spec.md similarity index 100% rename from openspec/changes/perfectdraft-card/specs/beer-catalog/spec.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/specs/beer-catalog/spec.md diff --git a/openspec/changes/perfectdraft-card/specs/beer-label/spec.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/specs/beer-label/spec.md similarity index 100% rename from openspec/changes/perfectdraft-card/specs/beer-label/spec.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/specs/beer-label/spec.md diff --git a/openspec/changes/perfectdraft-card/specs/card-config/spec.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/specs/card-config/spec.md similarity index 100% rename from openspec/changes/perfectdraft-card/specs/card-config/spec.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/specs/card-config/spec.md diff --git a/openspec/changes/perfectdraft-card/specs/card-core/spec.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/specs/card-core/spec.md similarity index 100% rename from openspec/changes/perfectdraft-card/specs/card-core/spec.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/specs/card-core/spec.md diff --git a/openspec/changes/perfectdraft-card/specs/freshness-warning/spec.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/specs/freshness-warning/spec.md similarity index 100% rename from openspec/changes/perfectdraft-card/specs/freshness-warning/spec.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/specs/freshness-warning/spec.md diff --git a/openspec/changes/perfectdraft-card/specs/hacs-packaging/spec.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/specs/hacs-packaging/spec.md similarity index 100% rename from openspec/changes/perfectdraft-card/specs/hacs-packaging/spec.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/specs/hacs-packaging/spec.md diff --git a/openspec/changes/perfectdraft-card/specs/keg-display/spec.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/specs/keg-display/spec.md similarity index 100% rename from openspec/changes/perfectdraft-card/specs/keg-display/spec.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/specs/keg-display/spec.md diff --git a/openspec/changes/perfectdraft-card/tasks.md b/openspec/changes/archive/2026-09-09-perfectdraft-card/tasks.md similarity index 100% rename from openspec/changes/perfectdraft-card/tasks.md rename to openspec/changes/archive/2026-09-09-perfectdraft-card/tasks.md diff --git a/openspec/specs/beer-catalog/spec.md b/openspec/specs/beer-catalog/spec.md new file mode 100644 index 0000000..3781fb6 --- /dev/null +++ b/openspec/specs/beer-catalog/spec.md @@ -0,0 +1,73 @@ +# beer-catalog Specification + +## Purpose +TBD - created by archiving change perfectdraft-card. Update Purpose after archive. +## Requirements +### Requirement: Built-in PerfectDraft beer database +The card SHALL include a built-in catalog of PerfectDraft beers with metadata for display purposes. + +#### Scenario: Catalog data structure +- **WHEN** the card is loaded +- **THEN** each beer entry in the catalog SHALL contain: a unique slug (kebab-case), display name, brewery name, style, ABV (number), and a brand color palette (primary color, secondary color, text color) +- **THEN** each entry MAY additionally carry a `kegId` product ID, a keg image path, and a brewery logo reference + +#### Scenario: Catalog coverage +- **WHEN** the card is loaded +- **THEN** the catalog SHALL include an entry for every keg the paired integration can identify, and MAY include further entries for beers the integration does not list + +### Requirement: Beer logo images +The card SHALL include static logo images for beers in the built-in catalog. + +#### Scenario: Image availability +- **WHEN** a beer from the built-in catalog is selected +- **THEN** the card SHALL display the beer's logo image in the label zone +- **THEN** images SHALL be optimised static assets (PNG or WebP) bundled with the card + +#### Scenario: Image fallback +- **WHEN** a beer has no logo image available (custom beer or missing asset) +- **THEN** the card SHALL display the beer's brand color palette as the visual background instead of an image + +### Requirement: Custom beer entries via configuration +The card SHALL support user-defined beer entries that extend or override the built-in catalog, reachable through the `beer_name` override. + +#### Scenario: Custom beer defined in config +- **WHEN** the card config includes a `custom_beers` array with entries containing at minimum a `name` field +- **THEN** those beers SHALL be resolvable by the `beer_name` override alongside built-in entries +- **THEN** custom entries SHALL support optional fields: `color_primary`, `color_secondary`, `color_text`, `image_url`, `brewery`, `style`, `abv` + +#### Scenario: Custom beer overrides built-in +- **WHEN** a custom beer entry has the same slug as a built-in beer +- **THEN** the custom entry SHALL override the built-in entry's fields + +### Requirement: Product ID mapping to the integration catalog +Each catalog entry SHALL be able to carry the PerfectDraft product ID of its keg, so the card can join against the product ID reported by the integration. + +#### Scenario: Entry carries a product ID +- **WHEN** a catalog entry corresponds to a keg listed in the integration's `keg_catalog.json` +- **THEN** the entry SHALL carry a `kegId` field holding that product ID as a string + +#### Scenario: Full coverage of the integration catalog +- **WHEN** the card is loaded +- **THEN** every product ID present in the integration's bundled keg catalog SHALL be carried by exactly one card catalog entry +- **THEN** no `kegId` SHALL appear on more than one entry +- **THEN** no `kegId` SHALL reference a product ID absent from the integration catalog + +#### Scenario: Lookup by product ID +- **WHEN** the card looks up a beer by product ID +- **THEN** the lookup SHALL resolve without scanning the catalog linearly, using an index built once at module load alongside the existing slug and name indexes + +### Requirement: Catalog coverage is verifiable +The project SHALL provide a repeatable check that the card's product ID mapping agrees with the integration's keg catalog, so drift is detected rather than discovered by users. + +#### Scenario: Check detects a missing mapping +- **WHEN** the integration catalog contains a product ID that no card catalog entry carries +- **THEN** the check SHALL fail and SHALL name the unmapped product ID and its integration-reported name + +#### Scenario: Check detects a stale or duplicate mapping +- **WHEN** a card catalog entry carries a `kegId` that is absent from the integration catalog, or two entries carry the same `kegId` +- **THEN** the check SHALL fail and SHALL name the offending entries + +#### Scenario: Check is offline +- **WHEN** the check runs +- **THEN** it SHALL compare against a committed snapshot of the integration catalog and SHALL NOT require network access + diff --git a/openspec/specs/beer-imagery/spec.md b/openspec/specs/beer-imagery/spec.md new file mode 100644 index 0000000..471a06b --- /dev/null +++ b/openspec/specs/beer-imagery/spec.md @@ -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 + diff --git a/openspec/specs/beer-label/spec.md b/openspec/specs/beer-label/spec.md new file mode 100644 index 0000000..4783671 --- /dev/null +++ b/openspec/specs/beer-label/spec.md @@ -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 + diff --git a/openspec/specs/card-config/spec.md b/openspec/specs/card-config/spec.md new file mode 100644 index 0000000..1da0aec --- /dev/null +++ b/openspec/specs/card-config/spec.md @@ -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 + diff --git a/openspec/specs/card-core/spec.md b/openspec/specs/card-core/spec.md new file mode 100644 index 0000000..874e825 --- /dev/null +++ b/openspec/specs/card-core/spec.md @@ -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 + diff --git a/openspec/specs/card-layouts/spec.md b/openspec/specs/card-layouts/spec.md new file mode 100644 index 0000000..d099111 --- /dev/null +++ b/openspec/specs/card-layouts/spec.md @@ -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 + diff --git a/openspec/specs/freshness-warning/spec.md b/openspec/specs/freshness-warning/spec.md new file mode 100644 index 0000000..0a69d54 --- /dev/null +++ b/openspec/specs/freshness-warning/spec.md @@ -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) + diff --git a/openspec/specs/hacs-packaging/spec.md b/openspec/specs/hacs-packaging/spec.md new file mode 100644 index 0000000..070994d --- /dev/null +++ b/openspec/specs/hacs-packaging/spec.md @@ -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 + diff --git a/openspec/specs/keg-auto-detection/spec.md b/openspec/specs/keg-auto-detection/spec.md new file mode 100644 index 0000000..7785207 --- /dev/null +++ b/openspec/specs/keg-auto-detection/spec.md @@ -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 + diff --git a/openspec/specs/keg-display/spec.md b/openspec/specs/keg-display/spec.md new file mode 100644 index 0000000..69e5a19 --- /dev/null +++ b/openspec/specs/keg-display/spec.md @@ -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) +