130 lines
5.2 KiB
Markdown
130 lines
5.2 KiB
Markdown
# APP-3830: Worktree Sidecar Selection Semantics
|
|
|
|
Linear: `APP-3830` (inferred from the branch name)
|
|
Related spec: `specs/moirahuang/APP-3743/PRODUCT.md`
|
|
|
|
## Summary
|
|
|
|
Polish the `New worktree config` sidecar so the repo that looks active is always the repo that executes. Mouse hover should take precedence over stale keyboard selection, repo clicks should consistently open a worktree, and keyboard confirmation from the search field should use the same visible selection model.
|
|
|
|
## Problem
|
|
|
|
The worktree sidecar currently mixes two concepts of "active repo":
|
|
|
|
- keyboard selection, which is initialized so the search field can drive arrow-key navigation
|
|
- hover state, which can move to a different repo row without updating the underlying actionable selection
|
|
|
|
This creates confusing behavior:
|
|
|
|
- two different repo rows can appear active at once
|
|
- clicking a hovered repo can no-op or execute from stale state
|
|
- `Enter` from the search field and mouse click do not reliably resolve the same repo
|
|
|
|
The sidecar is intended to be a fast path for worktree creation, so ambiguity in selection makes the feature feel flaky and untrustworthy.
|
|
|
|
## Goals
|
|
|
|
- The hovered repo row becomes the active selection as soon as the user moves the mouse over it.
|
|
- Mouse click and keyboard confirmation resolve the same repo the user sees as active.
|
|
- The search field remains keyboard-focused without becoming an actionable repo selection.
|
|
- `+ Add new repo` does not accidentally execute a previously selected repo.
|
|
- Closing behavior remains predictable: selecting a repo closes both the sidecar and the parent menu.
|
|
|
|
## Non-goals
|
|
|
|
- Redesigning the unified new-session menu layout.
|
|
- Changing how the default worktree tab config is authored or executed.
|
|
- Reworking all Warp menus to use a new selection model.
|
|
- Removing the search field or the pinned `+ Add new repo` footer.
|
|
|
|
## Figma / design references
|
|
|
|
Figma: none provided
|
|
|
|
## User experience
|
|
|
|
### Opening the sidecar
|
|
|
|
When the user opens the `New worktree config` sidecar:
|
|
|
|
- the search field is focused
|
|
- the first actionable repo row is selected if at least one repo is available
|
|
- if no repos are available, the search field and `+ Add new repo` footer still render and no repo row is selected
|
|
|
|
### Keyboard behavior
|
|
|
|
While the search field is focused:
|
|
|
|
- `Down` moves selection to the next actionable repo row
|
|
- `Up` moves selection to the previous actionable repo row
|
|
- `Enter` opens a worktree for the currently selected repo
|
|
- if no repo is selected but actionable repo rows exist, `Enter` first resolves the first actionable repo and opens it
|
|
- if no actionable repo rows exist, `Enter` does nothing
|
|
- `Escape` closes the sidecar and parent menu as it does today
|
|
|
|
### Hover precedence
|
|
|
|
If the user moves the mouse over a repo row:
|
|
|
|
- that hovered repo row becomes the active selection immediately
|
|
- any previously selected repo row stops being the effective active selection
|
|
- subsequent click or keyboard confirmation uses the hovered repo row unless the user changes selection again
|
|
|
|
Hover precedence only applies to actionable rows. Non-actionable rows such as the search row do not replace the current repo selection.
|
|
|
|
### Mouse click behavior
|
|
|
|
Clicking a repo row:
|
|
|
|
- opens a worktree for that repo using the default worktree tab config
|
|
- closes the sidecar
|
|
- closes the parent new-session menu
|
|
|
|
The clicked row should never no-op because of responder-chain routing or stale sidecar state.
|
|
|
|
### Search behavior
|
|
|
|
Typing in the search field filters repo rows live.
|
|
|
|
When filtering changes the available repo list:
|
|
|
|
- the filtered repo list updates immediately
|
|
- if actionable rows remain, the first actionable repo row becomes selected
|
|
- if no actionable rows remain, repo selection is cleared
|
|
|
|
### Add new repo footer
|
|
|
|
The pinned `+ Add new repo` footer remains visible while the repo list scrolls.
|
|
|
|
Clicking it:
|
|
|
|
- opens the folder picker
|
|
- does not open a worktree for any repo
|
|
- does not reuse stale repo selection as part of the click handling
|
|
|
|
## Success criteria
|
|
|
|
- At most one actionable repo row is treated as active at a time.
|
|
- Hovering a repo row updates the underlying actionable selection, not just the visual hover state.
|
|
- Clicking a repo row consistently opens a worktree for that repo.
|
|
- `Enter` from the search field opens the same repo the UI currently presents as active.
|
|
- The search field does not steal actionable selection when hovered.
|
|
- `+ Add new repo` opens the picker without also opening a repo.
|
|
- The sidecar closes cleanly after repo selection and leaves no stale selection state behind.
|
|
|
|
## Validation
|
|
|
|
- Unit-test hover precedence by starting with one selected repo, hovering a different repo row, and asserting the selected row changes to the hovered row.
|
|
- Unit-test the close-via-select path to verify sidecar repo selection executes from `Workspace`.
|
|
- Unit-test keyboard confirmation from the search editor to verify `Enter` opens the selected repo and closes the menu.
|
|
- Manual validation:
|
|
- open `New worktree config`
|
|
- move selection with arrow keys
|
|
- hover a different repo row and confirm the active row updates
|
|
- click the hovered repo and verify the correct worktree tab opens
|
|
- click `+ Add new repo` and verify only the picker opens
|
|
|
|
## Open questions
|
|
|
|
None currently.
|