Rebuild the dashboard around drink-window filters

[GuvHas]

The page was a sortable table with a search box. On a phone, with 151 bottles, that is a very long scroll and no way to ask the only question worth asking: what can I drink tonight? The integration has counted ready_to_drink and past_drink_window since 0.0.18, but the dashboard had no way to act on either.

431 tests (72 added), ruff clean, mypy clean, and checked by hand in Chromium.

One correction to the brief

The filter chips were not "missing or not rendering" — they had never existed. git log on cellar.html shows a search box and a table from the first commit. That is worth being exact about, because "restore" and "build" are different jobs: there was no regression to find, so this is new work and it needed new tests rather than a fix to old ones.

UX critique, and what I did about it

Problem	What was wrong	Change
No way to narrow by intent	The only question a cellar app answers is "what's drinkable", and the table could not express it	Four chips with live counts: All wines, Ready to drink, Past window, Needs aging
Controls scroll away	Search sat at the top of a 151-row page; by row 20 it is gone	Search, chips and sort in a sticky header
Two numbers instead of a state	FROM 2027 TO 2032 makes the reader do the arithmetic against the current year, per row	A bar showing where this year sits in the window, plus a pill saying what to do
Colour was the only signal	Red/green alone fails for the ~8% of men with colour-vision deficiency, and in bright sun on a phone	Colour and a text label, always both
Tap targets too small	12px table cells; nothing was tappable except the wine link	48px minimum on everything interactive, matching Home Assistant's own rows
Columns hidden on mobile	Loc and Bin had .hide-mobile, so the phone — the device you hold at the rack — was the one that could not see the bin	Bin and location on the summary line; barcode one tap away
Search was nearly useless	One substring test over name+location+bin. Vintage was not searchable at all, and "bindi 2023" matched nothing	Five fields, every token must match
Nothing to act on	The row was inert apart from an external link	Drawer with Copy bin and Open in CellarTracker

Typography and density. Wine names are the scanning target, so they get the weight; everything else steps down to 13px secondary. Prices and years use tabular-nums so columns of digits line up. On desktop the card collapses to one dense line — name, meta, window, price — because a mouse and 1000px want more rows per screen, not bigger ones.

The change that is behavioural, not cosmetic

The last year of a drinking window now reads "Drink this year" instead of red. The page had painted it red since the beginning, which reads as expired; the coordinator has always counted it as ready. They disagreed, and the repo knew — test_drink_window.py documents it as "one deliberate divergence".

They agree now, and test_dashboard_agrees_with_sensors.py keeps them agreeing: it runs the Python coordinator and the page's JavaScript over the same awkward cellar (inverted windows, single bounds, blanks, both boundary years) and compares the counts. A chip contradicting the sensor card beside it is the integration contradicting itself, and the user has no way to tell which number is wrong.

Phase 1 — tests first

File	Covers
tests/dashboard_js.py	Harness: runs the page's real script under node with a fake DOM
tests/test_dashboard_filters.py	53 specs — window states, progress, search, chips, sorting
tests/test_dashboard_agrees_with_sensors.py	5 — the cross-check above
tests/test_dashboard_render.py	13 — cards, pills, bar widths, drawer, state across refresh

All red before the rewrite. Edge cases the brief asked for are covered explicitly: missing bounds, blank strings, null, "N/A", negative years, inverted windows, a single-year window (which would otherwise divide by zero), rows missing the sort key, and ties.

No Jest or Vitest. The page has no build step, deliberately — it is served straight out of the integration directory into the Companion app. Adding npm to a HACS integration repo would cost more than it returns, and the repo already had a working pattern: extract the <script>, run it under node. I extended that. The page's decision logic is plain top-level functions with no DOM access, which is what makes them callable directly; a comment in cellar.html says so, since it is a testability constraint rather than an accident.

Phase 2 — implementation

Vanilla JS, one file, no dependencies, one request. textContent throughout — no innerHTML touches server data. One DocumentFragment per render, so a 1,000-bottle cellar reflows once.

The page grows 16 KB → 31 KB (~7 KB gzipped). Worth stating plainly; it is still negligible beside the inventory payload, and still one request.

Barcode joins COMPACT_FIELDS. A field the page searches but the API never sends is dead code that tests can still satisfy, so test_every_field_the_page_searches_is_actually_served now reads SEARCH_FIELDS out of the page and checks it against the projection.

Two things I did not build, and why

Notes in the drawer. The brief asked for them. They are free-form prose, potentially long, and PR #18 deliberately kept tasting and cellar notes out of diagnostics for exactly that reason. Shipping every note to every dashboard load is a payload and privacy decision that deserves its own PR; the drawer links to CellarTracker, where the notes live.

"Highlight in Rack" / ESPHome LED. The plumbing is easy — the page already holds a session that can POST /api/services/.... What is missing is which service: nothing in the integration knows the entity, and inventing one produces a button that fails. Doing this properly means an options-flow field naming the service, then a button rendered only when it is set. Happy to do that as a follow-up; it is a config-surface change, not a dashboard change. Copy bin ships now because it needs no configuration.

Interactive verification

The automated tests use a fake DOM, which proves structure and text but not layout. I checked layout in Chromium:

git checkout feature/interactive-dashboard-ux
python -m pytest -q            # 431 passed
ruff check .                   # clean (0.15.8, as CI pins)

To drive it yourself against a synthetic 151-bottle cellar, serve cellar.html from any static server alongside stub JSON at /api/cellartracker/inventory and /api/cellartracker/settings, then open it at 412px wide. Or install the branch in Home Assistant and open /cellartracker/cellar.html.

What I confirmed by hand, at 412px and 1000px, in both colour schemes:

• chip counts 151 / 76 / 15 / 45, and each chip renders exactly that many rows
• chip + search compose — "chianti 2023" inside All wines gives 15
• the drawer opens with location, bin, barcode, window and both actions
• sort by value descending puts the Penfolds Grange on top
• empty search shows "No wines match this filter." rather than a blank page
• no console errors

That pass is also what caught the desktop grid placing the wine name in the middle of the row with a hole beside it — the tests were green while it was broken, because a fake DOM has no layout.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01LLPEGFSy3fLEuXNUPAPWR4

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a9ee95d967

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".