mirror of
https://github.com/stablyai/orca.git
synced 2026-09-22 16:02:32 +00:00
144 lines
8.9 KiB
Markdown
144 lines
8.9 KiB
Markdown
# Design: Searchable Repository Selection in New Worktree Dialog
|
|
|
|
## 1. Problem Statement
|
|
|
|
GitHub issue [#379](https://github.com/stablyai/orca/issues/379): when creating a new worktree, the user must manually scroll a plain `Select` dropdown to pick the target repository. This does not scale once Orca manages many repositories.
|
|
|
|
The current Radix `Select` in `AddWorktreeDialog` has two product problems:
|
|
|
|
- It forces serial scanning instead of direct search.
|
|
- It makes the most important first step in the worktree-creation flow slower than every subsequent step.
|
|
|
|
The issue has no explicit acceptance criteria, so implementation requirements are inferred from the existing UX:
|
|
|
|
- Users must be able to search for a repository by name while creating a worktree.
|
|
- Existing auto-preselection behavior (preselectedRepoId, activeWorktreeRepoId, activeRepoId fallback chain) must keep working.
|
|
- Keyboard and mouse selection must both work.
|
|
- The change must not break the rest of the create-worktree flow: setup lookup, issue-command lookup, validation, and Enter-to-create behavior.
|
|
|
|
## 2. Approach
|
|
|
|
Replace the repository `Select` with a searchable combobox built from Orca's existing `Command` primitive (cmdk-based) and a new shared `Popover` primitive (Radix-based).
|
|
|
|
Rationale:
|
|
|
|
- A combobox is the standard pattern for "pick one item from a potentially long list, with search."
|
|
- Orca already ships `cmdk`-based command surfaces and Radix primitives, so this fits the existing stack without introducing new dependencies.
|
|
- Keeping the search scoped to the repo field preserves the current worktree-creation layout instead of turning the entire dialog into a command palette.
|
|
- Search logic lives in a pure helper (`searchRepos`) so matching rules are explicit and regression-testable outside React.
|
|
|
|
### Matching and ranking
|
|
|
|
- Search is case-insensitive substring matching.
|
|
- Primary target is `repo.displayName` (what issue #379 is specifically about). Secondary target is `repo.path` for disambiguating repos with similar display names.
|
|
- Ranking uses position-based scoring: matches earlier in the string rank higher. Display-name matches always outrank path-only matches (path scores are offset by 1000). Ties preserve original list order.
|
|
- Empty query returns the full eligible repo list in its original order.
|
|
|
|
## 3. Implementation Plan
|
|
|
|
### `src/renderer/src/components/ui/popover.tsx`
|
|
|
|
New shared Popover wrapper around Radix `Popover`. Follows the same styling conventions as existing `dialog.tsx`, `select.tsx`, and `dropdown-menu.tsx`. Generic and reusable — not inlined inside the worktree dialog.
|
|
|
|
### `src/renderer/src/lib/repo-search.ts`
|
|
|
|
New pure helper (`searchRepos`) that filters and ranks eligible repositories by a query string. Normalizes trimming and lowercasing in one place. Scoring logic:
|
|
|
|
- Display-name hit: score = index of substring match within `displayName`.
|
|
- Path-only hit: score = 1000 + index of substring match within `path`.
|
|
- No hit: excluded from results.
|
|
- Stable sort by `(score, originalIndex)` so equivalent matches preserve list order.
|
|
|
|
### `src/renderer/src/lib/repo-search.test.ts`
|
|
|
|
Unit tests covering:
|
|
|
|
- Empty query returns all repos in original order.
|
|
- Display-name matching is case-insensitive.
|
|
- Path fallback works when the display name does not match.
|
|
- Display-name matches rank ahead of path-only matches.
|
|
|
|
### `src/renderer/src/components/repo/RepoCombobox.tsx`
|
|
|
|
New reusable combobox component. Props: `repos`, `value`, `onValueChange`, optional `placeholder`.
|
|
|
|
Key design decisions:
|
|
|
|
- **External filtering**: `Command` is rendered with `shouldFilter={false}` because filtering is handled by `searchRepos`, not by cmdk's built-in filter. This keeps ranking rules in the pure helper where they are testable.
|
|
- **Trigger and content markup**: Both the trigger `Button` and `PopoverContent` carry `data-repo-combobox-root="true"` so the parent dialog's keydown handler can detect events originating inside the combobox surface (see Section 5).
|
|
- **Selected repo display**: The trigger renders the selected repo using the existing `RepoDotLabel` component, consistent with how repos appear elsewhere in Orca.
|
|
- **Result items**: Each item shows `RepoDotLabel` for the display name plus the full `repo.path` as secondary text, so repos with similar names are visually distinguishable.
|
|
- **Popover width**: `PopoverContent` uses `w-[var(--radix-popover-trigger-width)]` to match the trigger width for visual alignment.
|
|
- **Focus management**: `CommandInput` has `autoFocus` so the search input receives focus immediately when the popover opens.
|
|
- **Query reset on close**: `handleOpenChange` clears the query when the popover closes so stale filter text from a previous interaction does not hide repos on the next open.
|
|
- **Empty state**: `CommandEmpty` shows an explicit message when no repo matches.
|
|
|
|
### `src/renderer/src/components/sidebar/AddWorktreeDialog.tsx`
|
|
|
|
Changes to the existing dialog:
|
|
|
|
- Replace the `Select` repository control with `RepoCombobox`.
|
|
- All existing repo-selection state and side effects are preserved unchanged: `repoId`, `handleRepoChange`, auto-preselection on open, hook lookup, and issue-command lookup.
|
|
- Update the dialog-level `handleKeyDown` to suppress Enter when the event target lives inside a `[data-repo-combobox-root="true"]` element (see Section 5).
|
|
|
|
## 4. Edge Cases
|
|
|
|
| Scenario | Handling |
|
|
|---|---|
|
|
| No eligible git repos | Existing guard closes the dialog; the combobox is never rendered in a broken state. |
|
|
| Only one eligible repo | The combobox still renders normally. Search is trivial, but the UI stays consistent. |
|
|
| Multiple repos share a similar display name | Search also matches `repo.path`, and each item shows the full path as secondary text for disambiguation. |
|
|
| User opens combobox, types a query, closes, reopens | Query resets on close so the next open starts from the full list. |
|
|
| Enter pressed while focus is inside the repo search input | The dialog-level create shortcut is suppressed for events originating inside the combobox (see Section 5). |
|
|
| Preselected repo is not the first repo in the list | Auto-preselection logic is unchanged; the selected value is still controlled by `repoId` state. |
|
|
| Repo list changes while the dialog is open | The combobox renders from the live `eligibleRepos` array and updates reactively. If the selected repo disappears, existing dialog validation prevents create without a valid `selectedRepo`. |
|
|
|
|
## 5. Regressions and Mitigations
|
|
|
|
### Enter inside repo search creates a worktree
|
|
|
|
This is the most important correctness constraint. Without mitigation, typing a search query and pressing Enter to select a repo would bubble up to the dialog's keydown handler and trigger worktree creation.
|
|
|
|
Mitigation: `data-repo-combobox-root="true"` is placed on both the combobox trigger button and the popover content. The dialog's `handleKeyDown` checks `e.target.closest('[data-repo-combobox-root="true"]')` and returns early when it finds a match. This covers Enter events from:
|
|
|
|
- The `CommandInput` search field (inside the popover content).
|
|
- The trigger button itself when the popover is closed (Enter should open the popover, not submit the form).
|
|
|
|
An inline comment in `handleKeyDown` documents why this guard exists.
|
|
|
|
### Stale search query hides repos on reopen
|
|
|
|
Mitigation: `RepoCombobox.handleOpenChange` resets the query to `''` whenever the popover closes. An inline comment documents the timing interaction with the dialog's own delayed field reset.
|
|
|
|
### Repo preselection breaks
|
|
|
|
Mitigation: `repoId` remains the single source of truth for the selected repository. Only the presentation control was swapped; the state management and auto-selection logic in `AddWorktreeDialog` are untouched.
|
|
|
|
### Users cannot distinguish similarly named repos
|
|
|
|
Mitigation: Each combobox item shows both the `RepoDotLabel` display name and the full `repo.path` as secondary text.
|
|
|
|
### Matching behavior drifts over time
|
|
|
|
Mitigation: Search rules live in the pure `searchRepos` helper with dedicated unit tests, not inlined in JSX.
|
|
|
|
## 6. Test Plan
|
|
|
|
### Unit tests (`repo-search.test.ts`)
|
|
|
|
- Empty query returns all repos in original order.
|
|
- Display-name matching is case-insensitive.
|
|
- Path fallback works when the display name does not match.
|
|
- Display-name matches rank ahead of path-only matches.
|
|
|
|
### Manual verification
|
|
|
|
- Open the New Worktree dialog with multiple repos.
|
|
- Confirm the repo field opens a searchable combobox instead of a plain dropdown.
|
|
- Type part of a repo name and verify the list filters immediately.
|
|
- Press Enter to select a filtered repo and verify the dialog does not submit.
|
|
- Create a worktree after selecting a repo through search and verify the existing create flow still works end-to-end (setup, issue command, metadata).
|
|
- Reopen the dialog and verify the previous search text is cleared.
|
|
- Verify the preselected repo still appears when opening from flows that pass `preselectedRepoId`.
|
|
- Verify keyboard navigation (arrow keys, Enter to select, Escape to close popover) works within the combobox.
|