Randify.pro/.sisyphus/notepads/dm-dashboard-redesign/learnings.md

DM Dashboard Redesign — Work Notes

Theme Tokens (Target)

• Primary: #534AB7
• Secondary: #c8a84b
• Background base: #16120e
• Surface: #1e1912
• Card: #221e18
• Green (crit): #6ab04c
• Red (fail): #e06060
• Accent hover: #6b5fc7
• Gold hover: #d4b76a

Current State (2026-05-15)

• dm-theme.css: 11 properties, orange theme
• DmHeader: simple header with quill icon
• DmButton: 3 variants (primary/secondary/ghost)
• DmCard: padding variants, shadow
• DmInput: label + input with focus ring
• dm-translations.ts: 14 strings only
• Playwright: installed (@playwright/test v1.60.0), script is test:ui

Decisions

• Keep CSS property names, only change values
• Russian-only, no EN translations needed
• Preserve all sessionStorage/localStorage keys

Learnings (2026-05-15)

• DmTabs.astro created: pill-style tab navigation with 4 tabs (Кубики, Инициатива, Справочник, Заметки)
• Uses CSS custom properties exclusively (no hardcoded colors)
• Server-side renders initial aria-selected based on Astro.url.hash
• Client script enhances with: click → pushState hash, dm-tab-change custom event, keyboard nav (ArrowLeft/Right, Home, End), localStorage persistence (dm-last-tab)
• Uses <a href="#tab"> for graceful degradation (JS prevents default)
• Touch-friendly sizing: min-h-[44px] min-w-[80px]
• Build passes cleanly
• DmSidebar.astro created: desktop-only sidebar navigation component with user info placeholder, tools section, reference section, and campaigns placeholder
• Sidebar uses emoji icons for tools, gold dot for reference items
• All translations validated against dm-translations.ts keys
• No mobile visibility toggle needed — DmLayout handles hidden lg:block for sidebar column
• Component takes optional user prop with name and avatar fields

InitiativeTracker Redesign (2026-05-15)

• Wrapped form, list, and empty state in DmCard for consistent card styling
• Changed sessionStorage key from it-combatants to dm-initiative per spec
• Added inline HP editing: click HP span → input, blur/Enter to save, Escape to cancel
• Added aria-live="polite" announcer for turn change announcements
• Used dmTranslations (T) for all static template strings; hardcoded Russian in client script
• Active row: bg-[var(--accent)]/10 + purple dot + "Ход" pill badge
• Initiative score rendered in text-[var(--gold)] for emphasis
• Delete button: plain <button> with ghost-like styling and ✕ SVG (DmButton doesn't forward aria-label)
• Build passes cleanly

Open5eReference Redesign (2026-05-15)

What changed

• Tabs redesigned from pill buttons to gold-underline style (border-b-2 border-[var(--gold)])
• Search input wrapped with magnifying-glass SVG icon (absolute positioned, pointer-events-none)
• Filter select styled to match DmInput focus ring (gold instead of accent)
• Results layout changed from vertical list to responsive grid (grid-cols-1 sm:grid-cols-2)
• Result cards use DmCard-like classes (bg-[var(--bg-card)], border-[var(--border-gold-strong)], shadow) with hover lift (hover:-translate-y-0.5)
• Card titles switched to text-[var(--gold)] with group-hover:text-[var(--gold-hover)]
• Loading skeletons added: 4 shimmer placeholders in Astro template, toggled via o5-skeletons container
• Custom @keyframes shimmer + .o5-shimmer class for gold-tinted skeleton animation
• Empty state enhanced with search icon (SVG) and two-line message
• Error state now includes retry button (DmButton secondary variant) wired to manager.search()
• Detail modal card gets border-2 border-[var(--accent)] for purple-tinted border

Preservation

• All Open5e API calls untouched (Open5eUIManager imported from @/lib/client/open5e-ui)
• Debounce already implemented in manager (setQueryDebounced uses setTimeout 300ms); component continues calling it
• Pagination, modal ESC/overlay-click close, ARIA attributes all preserved
• All event listeners and state management logic kept verbatim

Verification

• Build passes cleanly (npm run build completes with no errors)

InitiativeTracker E2E Tests (2026-05-15)

What was done

• Created tests/dm/initiative.spec.ts with 5 test cases covering:
  • Adding a combatant with auto-roll
  • Sorting by initiative descending (deterministic via manual initiative input)
  • Next turn cycling active combatant
  • Deleting a combatant
  • Mobile viewport rendering
• Added data-testid attributes to InitiativeTracker.astro for all test selectors
• Added dataTestid prop forwarding to DmInput.astro and DmButton.astro
• Added active class to active combatant row in client script for .active selector

Bug found and fixed

• DmButton.astro did NOT forward the id prop. InitiativeTracker's client script relies on document.getElementById('it-add-btn'), it-roll-btn, it-next-btn, it-clear-btn. Because id was swallowed by DmButton, all button event listeners were null and the tracker was completely non-functional.
• Fix: added id?: string to DmButton Props and forwarded id={id} to both <a> and <button> rendered elements.

Test determinism

• The "sort by initiative descending" test in the spec used auto-roll for both combatants, making it non-deterministic (could flake). Fixed by filling the manual initiative input with deterministic values (25 and 10) before adding each combatant.
• Similarly, "next turn" and "delete" tests now use deterministic initiative values to avoid any RNG-related flakiness.

Verification

• npm run build passes cleanly
• npx playwright test tests/dm/initiative.spec.ts passes all 10 tests (5 tests × 2 projects: chromium + mobile-chromium)

Verification (T18)

• Build passes cleanly (npm run build exit 0).
• Tests pass: 148/148 Vitest, 6/6 Playwright data-migration.
• npx tsc --noEmit --project tsconfig.json produces no errors (clean).
• Data migration findings:
  • Dice history: INCOMPATIBLE — old result field (no total/rolls) causes renderHistory to throw.
  • Initiative: PARTIAL — old data renders but delete is broken due to missing id.
  • Notes: FULLY COMPATIBLE — plain string loads correctly.

Playwright E2E Testing (2026-05-15)

Discoveries

• DmLayout renders slot name="context" twice (mobile in <main> + desktop in <aside>), causing duplicate component instances in DOM.
• Astro deduplicates <script> tags per page, so component scripts run once even when component appears twice. This breaks document.getElementById-based scripts.
• Fix: refactor scripts to use querySelectorAll within [data-testid] containers and initialize each instance independently.
• Playwright :visible pseudo-class is essential for selecting the correct instance when DOM has duplicates.
• new URL("/path", "https://api.example.com/v2") drops the /v2 base path because leading / replaces entire path. Must use relative paths or trailing slash on base.
• Open5e API challenge_rating_decimal field does not exist in v2; returned type is an object {name, key}, not a string.

Test Implementation

• Created tests/dm/reference.spec.ts covering tab switching, search filtering, detail modal, mobile viewport.
• Created tests/dm/notes.spec.ts covering textarea typing, auto-save indicator, clear button, character counter, mobile viewport.
• Added data-testid attributes to Open5eReference.astro, NotesPanel.astro, and DmCard.astro.
• Fixed src/lib/open5e/client.ts API URL construction bug (missing /v2 due to leading slash in endpoint paths).