music_library/backlog/completed/ml-176.2 - Presto-add-splash-screen-search-views-and-on-screen-keyboard.md

id, title, status, assignee, created_date, updated_date, labels, milestone, dependencies, references, modified_files, parent_task_id, priority, ordinal

id	title	status	assignee	created_date	updated_date	labels	milestone	dependencies	references	modified_files	parent_task_id	priority	ordinal
ML-176.2	Presto: add splash screen, search views, and on-screen keyboard	Done		2026-05-10 13:35	2026-05-11 06:47	presto	m-0	ML-176.1	presto/AGENTS.md presto/README.md doc-17 - Implementation-Plan-ML-176.2-—-Presto-splash-screen-search-views-and-on-screen-keyboard	presto/records_on_the_day.py	ML-176	medium	2000

Description

Refactor presto/records_on_the_day.py into a unified app with a splash screen, search capability, and the existing calendar. All work is in the single MicroPython file.

New states

• STATE_HOME (new, default on boot/wake)
• STATE_SEARCH_INPUT (new — search box + on-screen keyboard)
• STATE_SEARCH_RESULTS (new — results list, reuses day-view rendering)
• STATE_MONTH / STATE_DAY / STATE_RECORD (existing, unchanged logic)

Splash screen (STATE_HOME)

• Two large touch targets: "Search Collection" and "Today's Records"
• "Today's Records" → transitions to existing STATE_MONTH / today's records flow
• "Search Collection" → transitions to STATE_SEARCH_INPUT
• On boot and display wake: always show STATE_HOME

On-screen keyboard (part of STATE_SEARCH_INPUT)

• 3-row QWERTY layout: qwertyuiop / asdfghjkl / zxcvbnm
• Bottom row: [123 toggle] [space] [⌫ backspace] [OK]
• Numbers keyboard: 1234567890 / symbols row / [ABC toggle] [space] [⌫] [OK]
• Space and ⌫ are shared between both layouts
• Lowercase only, no shift/caps
• OK button disabled (dimmed) when query is empty
• Each key is a rounded rectangle, touch-mapped to append/delete chars
• Visual feedback on key press (brief highlight)
• Query buffer displayed in a text field area above the keyboard, max ~50 chars

Search triggering

• User types query, presses OK
• OK calls fetch_search_results(query) → API
• Transitions to STATE_SEARCH_RESULTS

Search results (STATE_SEARCH_RESULTS)

• Reuses existing _draw_record_list(), scroll, and row rendering from day view
• Header shows "Search: " with Back button
• Back returns to STATE_SEARCH_INPUT (preserving query so user can refine)
• Tapping a record → STATE_RECORD (detail view, unchanged)
• Back from detail → returns to search results
• Empty results: "No records found" full-screen message
• Error: "Could not reach server" with retry-on-tap (same as day view)
• 20 results per page, no infinite scroll

API client

• New fetch_search_results(query) function
• Calls GET /api/v1/collection?q=<url-encoded-query>&limit=20
• Parses {total, records, ...} response
• Returns (records_list, error_flag) tuple (same shape as fetch_records)

Navigation state

• Track previous state to know where "Back" in detail view should go
• Detail Back → search results when entered from search
• Detail Back → day view when entered from day
• Month view and search views both have "Back to Home"

Constraints

• Must reuse existing record row rendering (_draw_record_row), detail view (draw_record_detail), thumbnail fetching, WiFi, NTP, display sleep logic
• Scroll performance rules from AGENTS.md still apply
• Memory: no large buffers, keep GC pressure low

Acceptance Criteria

• #1 On boot, splash screen shows with 'Search Collection' and 'Today's Records' buttons
• #2 Tapping 'Today's Records' opens the existing month calendar (unchanged behavior)
• #3 Tapping 'Search Collection' opens search input view with on-screen QWERTY keyboard
• #4 Keyboard: tapping letter keys builds query string shown in input field
• #5 Keyboard: backspace removes last character
• #6 Keyboard: 123/ABC toggle switches between QWERTY and numbers keyboard layouts
• #7 Keyboard: OK button is visually disabled (dimmed) when query is empty
• #8 Keyboard: OK button triggers API search when query is non-empty
• #9 Search results display using same record row layout as day view (cover, title, artist, format, year)
• #10 Search results: Back button returns to search input view with query preserved
• #11 Search results: tapping a record opens detail view
• #12 Detail view Back returns to search results when entered from search
• #13 Detail view Back returns to day view when entered from day
• #14 Empty results show 'No records found' full-screen message
• #15 API error shows 'Could not reach server' with retry-on-tap
• #16 Display sleep/wake always returns to splash screen
• #17 Scroll in search results works identically to day view scroll
• #18 Keyboard renders correctly at 720×720: all keys visible and tappable
• #19 Back-to-Home navigation available from month view and search views

Implementation Notes

Implementation complete (~617 new lines, 2450 total)

State constants + globals

• Renumbered STATE_MONTH=0, STATE_DAY=1, STATE_RECORD=2. Added STATE_HOME=3, STATE_SEARCH_INPUT=4, STATE_SEARCH_RESULTS=5. Removed STATE_STARTUP.
• New globals: search_query, search_results, search_results_error, search_scroll_offset, _search_content_height, keyboard_mode, previous_state.

Splash screen (STATE_HOME)

• draw_home_screen() with "Search Collection" and "Today's Records" buttons. Tapping "Today's Records" → month view with today highlighted. Tapping "Search Collection" → search input.

On-screen keyboard (STATE_SEARCH_INPUT)

• QWERTY layout (3 rows) + numbers/symbols. Bottom row: [123/ABC] [Space] [Backspace] [OK]. OK dimmed when query empty. _keyboard_hit_test() maps touch to action. handle_search_input_touch() dispatches all actions. Visual feedback via _flash_key().

Search results (STATE_SEARCH_RESULTS)

• Reuses _draw_record_row(). Own scroll state (search_scroll_offset, _search_content_height). Header: "Search: " with truncation. Empty: "No records found". Error: "Could not reach server" with retry-on-tap.

API client

• fetch_search_results(query) → GET /api/v1/collection?q=<encoded>&limit=20. Returns (records_list, error_flag).

Generic display pipeline

• prepare_records_for_display(recs=None) and preload_record_thumbnails(recs=None) accept optional list. Height cache tracked per source.

Navigation tracking

• previous_state tracks detail origin (STATE_DAY / STATE_SEARCH_RESULTS). Back → correct origin. draw_record_detail() reads from search_results or records.

Back-to-Home

• Month header gains "H" Home button. wake_display() always sets state = STATE_HOME. Search input header Back → Home.

Boot flow

• Starts at draw_home_screen(), no auto-fetch. User taps a button.

Main loop

• New dispatches for STATE_HOME, STATE_SEARCH_INPUT, STATE_SEARCH_RESULTS (drag scroll mirrors day view).

Touch helpers

• touch_to_record_index() accepts optional recs and offset params.

Verification

• Syntax check passes (python3 py_compile). No STATE_STARTUP references remain.