feat(ui): add hotkey sort/filter search bar with settings-search extraction

[thewrz]

This was written agentically; verify its assertions and edit accordingly:

Why

Issue #199 asks for the hotkeys settings section to gain the same search/sort/filter affordances already available elsewhere in settings, so users with large hotkey lists can find and reorder entries quickly.

What

Adds a search bar, sort-menu overlay, and portal-status badge to the hotkeys settings section, backed by a new src/ui/settings/hotkeys.rs module and a FilterTarget-based routing refactor shared with the existing tile filtering. src/app/filtering/targets.rs was extracted to keep filtering.rs under the 400-line file budget.

Design decisions

Pre-spike decisions 1-12 all held (see spike learnings §6 positive confirmations: shared sort_menu_anchor, Hotkey-prefixed Message variants, owned HotkeyRow, FilterTarget-based routing as a pure refactor for tiles, ui/settings/hotkeys.rs extraction) — none reversed. Five additional corrections made on contact with real code, all narrow and mechanical, none changing the architecture:

1. Cross-module-tree visibility bridge added (new, not in pre-spike design at all): src/ui/settings/hotkeys.rs sits in a sibling module tree to crate::app, unlike src/app/header.rs which is a descendant and can read private fields directly. Fixed with two pub(crate) accessor methods (hotkey_filter_query(), hotkey_sort_state(), mirroring the existing search_query() pattern) plus one pub(crate) use hotkeys::HotkeyRow; re-export at the app module root. This is the single most consequential spike finding — a design gap, not an implementation bug — and is now folded into structs/interfaces/todos as first-class elements rather than an afterthought.

2. HotkeySortState visibility corrected from pub(super) to pub(crate) at its definition site. Rust's re-export rule only allows narrowing, never widening (E0365); pub(super) would make it unusable the moment any pub(crate) method (like hotkey_sort_state()) names it in a return-type position (private-interfaces violation). No corresponding re-export of the type itself was needed — it only flows through generic inference at the sort-chip call site, confirmed by spike, so no dead-code re-export was added.

3. Per-row view function needs an explicit 'static output lifetime, not Rust's elided &HotkeyRow-borrowed lifetime — otherwise the returned Vec<Element> illegally borrows from the function-local Vec<HotkeyRow> that hotkey_rows() returns (E0515). Matches an established sibling pattern already in the same file (view_about_section(t) -> Element<'static, Message>), so this is a consistency fix, not a new idiom.

4. view_hotkeys_section needed one additional extraction (portal_status_badge()) beyond what the pre-spike design's todos flagged — it only called out handle_type_to_filter/handle_escape as complexity risks, but the inline search-bar + sort-chip + portal-badge + row-list body measured 62/50 lines. Same file-organization instinct as the design's other proactive extractions, just applied one level deeper.

5. src/app/filtering/targets.rs extraction is now unconditional, not the design's original "if needed" hedge. Spike measured filtering.rs at 431/400 lines with the full retargeting landed inline. Moving FilterTarget + active_filter_target() out is now todo item 8, always executed, using Rust's file+dir sibling-module form (filtering.rs declares mod targets; alongside filtering/targets.rs — no mod.rs needed).

All five corrections are visibility/lifetime/line-budget fixes fully compatible with the original architecture; no struct, Message variant, or module boundary was added, removed, or renamed as a result of the spike.

Testing

• cargo build --release passes
• cargo test (running in background at PR-creation time; verify CI is green)
• cargo clippy -- -D warnings (running in background at PR-creation time; verify CI is green)
• Manual verification in a live Wayland session

🤖 Co-authored by Claude Sonnet 5. Closes #199

Summary by CodeRabbit

• New Features

  • Added a searchable Shortcuts settings section with filtering by name, filename, and tag.
  • Added sorting for shortcut bindings by slot, name, length, tag, modified date, and added date.
  • Added persistent sort preferences and clear empty-state messages.
  • Added shortcut rows with helpful labels for missing sounds, deleted macros, and unassigned slots.

• Bug Fixes

  • Improved keyboard filtering so input and Escape actions affect only the active search field.
  • Improved sorting stability and maintained consistent slot ordering when values match.
  • Sort menus now close correctly when switching settings sections.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d6bab2fb-7060-4d1b-b715-d7a3647fd87b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds an independent filter and sort pipeline for Settings → Shortcuts, including target-aware keyboard routing, persisted sort preferences, shortcut-row resolution, dedicated search UI, and sort-menu overlay behavior.

Changes

Hotkeys filtering and sorting

Layer / File(s)	Summary
Target-aware filtering and Escape routing src/app/filtering.rs, src/app/filtering/targets.rs, src/app/filtering/tests.rs	Typing and Escape are routed between tiles and hotkeys according to the active UI target, with scoped query clearing and expanded filtering tests.
Hotkey rows and sorting model src/app/hotkeys.rs, src/app/hotkeys/rows.rs, src/app/hotkeys/tests.rs, src/app/slot_sort.rs, src/ui/list_controls/sort.rs	Bound shortcut triggers become searchable rows, including missing-content states, with configurable sorting and deterministic tie-breaking.
Application state and message wiring src/app/message.rs, src/app/mod.rs, src/app/settings.rs	Hotkey filter/sort state, messages, configuration loading, persistence, and settings-section menu dismissal are wired into the application.
Settings UI and overlay src/ui/search_bar.rs, src/ui/settings/*, src/app/hotkeys/view.rs, src/app/settings/gui_tests.rs	The Shortcuts section gains a dedicated search bar, sorted bindings list, status badge, and conditional sort-menu overlay.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant SettingsView
  participant HonkHonk
  participant HotkeyRows
  User->>SettingsView: type search or open sort menu
  SettingsView->>HonkHonk: HotkeySearchChanged or sort message
  HonkHonk->>HotkeyRows: build, filter, and sort rows
  HotkeyRows-->>SettingsView: rendered shortcut rows

Loading

Possibly related PRs

• wrzonance/HonkHonk#202: Extends the shared filter and staged Escape plumbing used by this target-aware routing.
• wrzonance/HonkHonk#211: Shares the generic sorting and tie-break behavior used by hotkey rows.
• wrzonance/HonkHonk#213: Provides the staged settings-search state consulted by hotkey filter routing.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately reflects the hotkey sort/filter UI work, though it mentions settings-search extraction as a secondary detail.
Linked Issues check	✅ Passed	The PR adds the shared search bar, SlotSortKey sort chip, shortcut filtering, persistence, and tests required by #199.
Out of Scope Changes check	✅ Passed	The changes stay focused on shortcut-list filtering/sorting and the supporting UI/state plumbing, with no clear unrelated additions.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch feat/issue-199

---

_{Comment @coderabbitai help to get the list of available commands.}

[thewrz]

This was written agentically; verify its assertions and edit accordingly:

Adversarial cross-review — Codex (gpt-5.6-sol, reasoning effort xhigh)

Ran as the final draft-phase gate against origin/main, after CI went green. Codex independently compiled the branch, ran the full test suite and cargo clippy --all-targets -- -D warnings, and reported 1 finding.

[P2] Type-to-filter never focused the Shortcuts search input — FIXED in 2c91b41

src/app/filtering.rs — the FilterTarget::Hotkeys branch of handle_type_to_filter seeded hotkey_filter but returned Task::none(), where the tiles branch returns a focus operation.

Confirmed valid against the code rather than taken on faith. FilterState's own activation contract is "An ignored printable keypress may focus and seed the filter input", and the Shortcuts branch only did the seeding half. The user-visible consequence: the list filtered as expected, but because the input was never focused, Backspace/Delete/arrow keys and selection edits kept targeting whichever widget held focus before typing began. Plain printable characters kept appending (they re-enter through type_to_filter_text), but is_control() filtering means Backspace never reaches the filter — so the query could be typed and not corrected.

Fix returns iced::widget::operation::focus(search_bar::hotkeys_input_id()), mirroring insert_tiles_filter_text. The input already carried that id, so no view change was needed.

Pinned by a regression test asserting both filter targets schedule a focus task (typed_filter_text_focuses_the_targeted_search_input). Written TDD-first: it failed on the hotkeys assertion while the tiles assertion passed, which reproduced the asymmetry precisely.

Verification

• cargo test — 745 unit tests + all integration suites pass
• cargo clippy --all-targets -- -D warnings — clean
• cargo fmt --check — clean

No other [P1]/[P2] findings. Also checked independently and found sound: the shared sort_menu_anchor is cleared on every view/section transition (show_settings, show_settings_section, ShowMain, ShowSlots), so no stale sort overlay can leak between the tiles and Shortcuts views; and slot_index + 1 cannot overflow, as slot_triggers is a fixed 20-element array.

🤖 Co-authored by Claude Opus 5.

[thewrz]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (4)

src/app/filtering/targets.rs (1)

54-88: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Test oracle mirrors the implementation.

expected_target is a verbatim copy of active_filter_target's match, so routing_is_total_and_mutually_exclusive_across_every_state can only fail if the two copies diverge — it can't catch a wrong rule. Consider an explicit expectation table (view_mode, section, searching) → target instead.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/app/filtering/targets.rs` around lines 54 - 88, Replace the
implementation-mirroring expected_target helper in
routing_is_total_and_mutually_exclusive_across_every_state with an explicit
expectation table mapping each (view_mode, section, searching) combination to
its intended FilterTarget or None. Assert active_filter_target(&app) against the
table-driven expected value, preserving coverage of every state without
duplicating active_filter_target’s match logic.

src/app/settings/gui_tests.rs (1)

50-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Document the whitespace-sensitive label convention. " Name" (two leading spaces) is what distinguishes an unselected sort-menu row from other "Name" text in the view; that's invisible to future readers and silently breaks if row formatting changes. Add a short comment, and a message on the bare assert at line 62.

♻️ Suggested tweak

+    // Sort-menu rows are prefixed with "✓ " when selected and "  " otherwise;
+    // the two-space prefix is what distinguishes a menu row from other labels.
     assert!(
         !harness.find("  Name"),
         "sort menu should be closed until the sort chip is clicked"
     );
@@
-    assert!(harness.find("  Name"));
+    assert!(
+        harness.find("  Name"),
+        "the open sort menu should list unselected keys such as Name"
+    );

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/app/settings/gui_tests.rs` around lines 50 - 62, Add a concise comment
near the whitespace-sensitive harness.find("  Name") assertion explaining that
the two leading spaces identify an unselected sort-menu row, and give the bare
assert!(harness.find("  Name")) a descriptive failure message. Keep the existing
selector and test behavior unchanged.

src/app/filtering/tests.rs (1)

149-167: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Assert the focus target, not just a non-empty task. units() > 0 only proves something was scheduled; it won’t fail if TypeToFilter("h") starts returning a different task instead of focus(search_bar::hotkeys_input_id()). A widget-level focus assertion would catch this regression more directly.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/app/filtering/tests.rs` around lines 149 - 167, Update the
typed_filter_text_focuses_the_targeted_search_input test to assert that
TypeToFilter("h") schedules focus on the correct search input, rather than only
checking that the returned task has nonzero units. Verify the main view targets
the tiles search input and the settings hotkeys view targets hotkeys_input_id(),
using the widget-level focus assertion mechanism.

src/ui/settings/hotkeys.rs (1)

190-200: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Remove the Iced view smoke test.

This directly tests Iced view composition; retain coverage at the hotkey app-state boundary instead.

As per coding guidelines, do not test Iced view rendering or third-party internals.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/ui/settings/hotkeys.rs` around lines 190 - 200, Remove the
view_hotkeys_section smoke test function
view_hotkeys_section_builds_for_the_default_state and its associated test-only
setup if no longer needed. Retain coverage through the hotkey app-state
boundary, including hotkey_rows(), without adding replacement tests for Iced
view rendering.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/app/hotkeys/view.rs`:
- Around line 20-24: Update change_settings_search to clear sort_menu_anchor
when a staged settings search begins, ensuring the Hotkeys sort overlay is
dismissed before search_results is shown. Preserve the existing search behavior
and use the existing sort_menu_anchor state.

In `@src/app/message.rs`:
- Around line 42-54: Update the MacroStepDecoded and Decoded message variants to
carry the audio module’s typed thiserror-based decode error instead of Result
payloads using String. Propagate that concrete error type through the audio/app
boundary and adjust affected handling paths to preserve the typed failures.

In `@src/ui/search_bar.rs`:
- Line 78: Update the doc comment above the hotkeys-section search builder to
describe it as type-to-filter activated, removing the inaccurate “click-only”
wording. Keep the existing description of the stable input stack and align the
wording with active_filter_target and handle_type_to_filter.

---

Nitpick comments:
In `@src/app/filtering/targets.rs`:
- Around line 54-88: Replace the implementation-mirroring expected_target helper
in routing_is_total_and_mutually_exclusive_across_every_state with an explicit
expectation table mapping each (view_mode, section, searching) combination to
its intended FilterTarget or None. Assert active_filter_target(&app) against the
table-driven expected value, preserving coverage of every state without
duplicating active_filter_target’s match logic.

In `@src/app/filtering/tests.rs`:
- Around line 149-167: Update the
typed_filter_text_focuses_the_targeted_search_input test to assert that
TypeToFilter("h") schedules focus on the correct search input, rather than only
checking that the returned task has nonzero units. Verify the main view targets
the tiles search input and the settings hotkeys view targets hotkeys_input_id(),
using the widget-level focus assertion mechanism.

In `@src/app/settings/gui_tests.rs`:
- Around line 50-62: Add a concise comment near the whitespace-sensitive
harness.find("  Name") assertion explaining that the two leading spaces identify
an unselected sort-menu row, and give the bare assert!(harness.find("  Name")) a
descriptive failure message. Keep the existing selector and test behavior
unchanged.

In `@src/ui/settings/hotkeys.rs`:
- Around line 190-200: Remove the view_hotkeys_section smoke test function
view_hotkeys_section_builds_for_the_default_state and its associated test-only
setup if no longer needed. Retain coverage through the hotkey app-state
boundary, including hotkey_rows(), without adding replacement tests for Iced
view rendering.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0b93010b-171f-4eeb-af2a-ab337e898ac6

📥 Commits

Reviewing files that changed from the base of the PR and between db77857 and 2c91b41.

📒 Files selected for processing (17)

• src/app/filtering.rs
• src/app/filtering/targets.rs
• src/app/filtering/tests.rs
• src/app/hotkeys.rs
• src/app/hotkeys/rows.rs
• src/app/hotkeys/tests.rs
• src/app/hotkeys/view.rs
• src/app/message.rs
• src/app/mod.rs
• src/app/settings.rs
• src/app/settings/gui_tests.rs
• src/app/slot_sort.rs
• src/ui/list_controls/sort.rs
• src/ui/search_bar.rs
• src/ui/settings/hotkeys.rs
• src/ui/settings/mod.rs
• src/ui/settings/other.rs