---
phase: 13-add-remaining-rclone-remotes
plan: "03"
subsystem: ui
tags: [react, tailwind, search, categories, icons, wizard]

# Dependency graph
requires:
  - phase: 13-add-remaining-rclone-remotes/13-01
    provides: BACKEND_REGISTRY with category field on all 18 backends, BackendCategory type
  - phase: 13-add-remaining-rclone-remotes/13-02
    provides: BACKEND_ICONS map keyed by BackendType with inline SVG components

provides:
  - Category-grouped BackendSelectionStep with Cloud Object Storage / Cloud Drives / Protocol-based sections
  - Instant search bar filtering across displayName, description, category label, and field labels
  - BackendCard with optional icon prop (flex row with 24x24 icon + name)
  - 6 new test cases for search filtering and category collapse behavior

affects:
  - Any future plans modifying BackendSelectionStep or BackendCard
  - Phase 14+ if additional backends are added to the registry

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "type=search input to avoid role=textbox conflict with remote name TextFieldMD3"
    - "CATEGORY_ORDER constant drives render order; empty categories return null (conditional, not CSS)"
    - "matchesSearch checks 4 fields: displayName, description, category label, field labels"

key-files:
  created: []
  modified:
    - src/components/ui/BackendCard.tsx
    - src/components/wizard/BackendSelectionStep.tsx
    - src/components/wizard/BackendSelectionStep.test.tsx

key-decisions:
  - "Search input uses type=search (role=searchbox) not type=text — prevents getByRole('textbox') ambiguity with remote name field in existing tests"
  - "matchesSearch checks 4 fields for cross-field discovery (e.g. Cloudflare finds S3-Compatible via description)"
  - "Empty categories hidden via conditional null return, not CSS display:none — test-assertable absence"

patterns-established:
  - "Pattern: Use type=search for search inputs in forms that also have text inputs to avoid ARIA role collision"

requirements-completed: [REMOTE-03]

# Metrics
duration: 15min
completed: 2026-04-01
---

# Phase 13 Plan 03: BackendSelectionStep Category Grouping and Search Summary

**BackendSelectionStep refactored to show 18 backends in 3 category sections with instant search and inline SVG icons**

## Performance

- **Duration:** ~15 min
- **Started:** 2026-04-01T16:48:00Z
- **Completed:** 2026-04-01T16:53:00Z
- **Tasks:** 2
- **Files modified:** 3

## Accomplishments
- BackendCard updated to accept optional `icon` prop rendered in a flex row with the backend name
- BackendSelectionStep refactored from a flat grid to three category sections: Cloud Object Storage, Cloud Drives, Protocol-based
- Search bar added filtering across displayName, description, category label, and field labels with no debounce needed for 18 items
- Empty categories conditionally removed from DOM (not hidden with CSS)
- BACKEND_ICONS connected to BackendCard icon prop via React.createElement
- 6 new tests covering all REMOTE-03 acceptance criteria; all 276 project tests pass

## Task Commits

1. **Task 1: Add icon prop to BackendCard and build category/search into BackendSelectionStep** - `0a70620` (feat)
2. **Task 2: Add search filter and category collapse tests** - `aeb1528` (test)

## Files Created/Modified
- `src/components/ui/BackendCard.tsx` - Added optional `icon?: ReactNode` prop, renders flex row with icon+name when icon provided
- `src/components/wizard/BackendSelectionStep.tsx` - Added CATEGORY_ORDER, CATEGORY_LABELS, matchesSearch, searchQuery state, category sections, search input
- `src/components/wizard/BackendSelectionStep.test.tsx` - Added 6 new test cases under REMOTE-03 describe block

## Decisions Made
- **type=search for search input:** The remote name field has role=textbox. Adding a second type=text input would cause `getByRole('textbox')` to throw "multiple elements found" in all existing tests. Using `type=search` gives the input role=searchbox, avoiding the collision. This matches the semantic meaning (it is a search input) and required no test changes.
- **matchesSearch 4-field check:** Checking description enables cross-field discovery (e.g. typing "Cloudflare" finds S3-Compatible whose description mentions Cloudflare R2). Field labels allow users to search by credential type (e.g. "SAS URL" finds Azure Blob Storage).
- **Conditional null return for empty categories:** Categories with no matching backends return null from the map, removing them from the DOM entirely. This makes test assertions (`queryByText(...) toBeNull()`) reliable without needing CSS inspection.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Changed search input from type=text to type=search**
- **Found during:** Task 1 (BackendSelectionStep implementation)
- **Issue:** type=text gives role=textbox; existing tests use `getByRole('textbox')` to find the remote name input — adding a second textbox caused 6 tests to fail with "multiple elements found"
- **Fix:** Changed `type="text"` to `type="search"` on the search input (role becomes searchbox, not textbox)
- **Files modified:** src/components/wizard/BackendSelectionStep.tsx
- **Verification:** All 13 existing tests pass after change; 6 new tests also pass
- **Committed in:** 0a70620 (Task 1 commit)

---

**Total deviations:** 1 auto-fixed (Rule 1 - bug causing test failures)
**Impact on plan:** Minimal — single attribute change, semantically correct. No scope creep.

## Issues Encountered
None beyond the type=text conflict described above.

## User Setup Required
None - no external service configuration required.

## Next Phase Readiness
- BackendSelectionStep handles 18 backends with categories and search — ready for any v1.3 release
- Phase 13 all 3 plans complete: registry refactor (13-01), icons+OAuth UI (13-02), categorized selection (13-03)
- No blockers for phase completion

---
*Phase: 13-add-remaining-rclone-remotes*
*Completed: 2026-04-01*