Find/Replace dialog replacement

Open KeyWorksRW opened this issue 2 months ago • 0 comments

Description:

I had a hunch that all the training data AI has would include data would about complaints about missing features in standard OS Find/Replace dialogs. I also figured it would know about applications that created a replacement and what users liked/disliked about it. So, I asked AI to collate all the information and write a spec for what UI would need to contain to support what users have asked for. It didn't disappoint -- in fact I was a bit overwhelmed by just how much information it generated! 🫨 It certainly contains a lot of information to consider...

Find/Replace Dialog UI Specification

Overview

A unified, non-modal Find/Replace interface that combines the best practices from VS Code, Sublime Text, and other modern editors while addressing the most common user complaints and feature requests.

Core Architecture

Modal Behavior

The dialog should be non-modal (modeless), allowing users to switch between the search interface and the document being edited without closing it. This avoids the frustration of having to close and reopen the dialog repeatedly.

Unified Single Interface

Combine Find and Replace into a single interface rather than separate dialogs. Users should never need to switch between "Find mode" and "Replace mode." A simple toggle or toggle button reveals the Replace field when needed.

Default Persistence

Keep the dialog visible as a dockable panel or floating window that can:

Remain open while working on the document
Be hidden/shown with a keyboard shortcut (typically Ctrl+F for Find, Ctrl+H for Find/Replace)
Remember its state and size between sessions

Search Input Controls

Find What Field

Always visible and focused when opened
Text should be fully selected when the dialog first opens or when the dialog reopens, allowing immediate typing to replace the previous search term
Support for multi-line input: Users should be able to press Ctrl+Enter to add newlines within the search field for finding/replacing multi-line patterns
Search history: Provide a dropdown showing previous search terms, accessible via Up/Down arrow keys
Placeholder text: "Search..." or similar clear guidance

Visual Feedback

Real-time highlighting of all matches in the document as the user types
Match counter showing "X of Y matches" to indicate current position and total matches
Highlight the currently selected match distinctly from other matches
Wrap-around indicator when reaching the end and cycling back to the beginning

Advanced Search Options (Always Accessible)

Position these as toggleable icons or buttons immediately adjacent to the Find field:

Case Sensitivity

Toggle button for "Match Case" (Abc icon)
Should be explicitly togglable, not hidden in an options menu

Whole Word Matching

Toggle for "Whole Word" (ab| icon or similar)
Prevents partial matches within words

Regular Expression Support

Toggle for "Regular Expressions" (.* icon)
When enabled, the interface should support:
- Standard regex syntax (ECMAScript 5 or PCRE2)
- Backreferences for use in both find and replace patterns
- Lookahead and lookbehind (if using PCRE2)
- Clear documentation or help inline showing regex syntax
Should remain off by default (literal string search is the default)

Search Scope Options

Entire File/Document (default)
Selection Only: When text is selected, this option should be available and explicitly shown
Current Folder or Project-wide (for IDE/code editors)
File Type Filter (optional): Limit to specific file extensions when searching across files
Clear indicator of current scope

Search Direction

Forward (next occurrence after cursor)
Backward (previous occurrence before cursor)
Wrap Around: Toggle to continue from start/end when reaching the document boundary

Replace Controls

Replace Field

Revealed via:
- Clicking an expand arrow/toggle
- Pressing Ctrl+H (standard keyboard shortcut)
- Pressing Tab while focused on the Find field (optional convenience)
Text input for the replacement string
Support for format strings and capture group references (when regex is enabled)
- Use standard notation: $1, $2 for numbered groups or $&variable for named groups
- Support for text transformations like \L$1 (lowercase), \U$1 (uppercase), \l$1 (lowercase first), \u$1 (uppercase first)

Replacement Preview

Show a diff-style preview of what the replacement will do
Display proposed changes before executing them
Allow users to hover over match instances to see the preview inline in the document

Case Preservation Mode

Preserve Case toggle that intelligently preserves the original casing of matches
When enabled:
- camelCase → adapts replacement to camelCase
- PascalCase → adapts to PascalCase
- UPPERCASE → adapts to UPPERCASE
- lowercase → adapts to lowercase
Extremely useful for refactoring variable and class names

Action Buttons

Essential Buttons

Positioned clearly below or to the right of input fields, clearly labeled:

Find Next or Find Previous: Navigate to next/previous match (keyboard: Enter for next, Shift+Enter for previous, or F3/Shift+F3)
Replace: Replace the current match only
Replace All: Replace all matches in the current scope
Replace Next and Find: Replace current match and advance to next (Ctrl+Shift+1 in some editors)

Behavior Safeguards

Require confirmation for Replace All when:
- There are more than a threshold number of matches (e.g., > 10)
- The search spans multiple files
- Display count of matches that will be changed
Undo awareness: Make Replace All operations undoable as a single action

Optional Advanced Actions

Skip Current Match: Move to next without replacing (keyboard shortcut or button)
Select All Matches: Highlight all occurrences for multi-cursor editing
Select Next Match (incremental selection for multi-caret editing)

Keyboard Shortcuts

Standard Shortcuts (Non-Negotiable)

Ctrl+F (Cmd+F on Mac): Open Find, focus Find field
Ctrl+H (Cmd+H on Mac): Open Find/Replace, focus Replace field
Ctrl+Shift+F: Find in Files / Project-wide search
Ctrl+Shift+H: Replace in Files / Project-wide replace
Enter / Ctrl+G: Find Next
Shift+Enter / Ctrl+Shift+G: Find Previous
Ctrl+Shift+1: Replace and Find Next
Ctrl+Alt+Enter: Replace All
Escape: Close Find/Replace panel (but don't clear history)
Ctrl+Enter: Add newline in multi-line mode

Mnemonic Shortcuts (For Power Users)

Alt+A: Replace All (preserves TextMate/Eclipse muscle memory)
Alt+C: Toggle Case Sensitivity
Alt+W: Toggle Whole Word
Alt+R: Toggle Regular Expression mode
Alt+L: Toggle "In Selection" (VS Code's mechanism)

Navigation Within Results

F3: Next match
Shift+F3: Previous match
Ctrl+Up/Down: Navigate through history

Scope and Selection Management

Selection-Aware Behavior

If text is selected when Find/Replace opens:
- Automatically populate the Find field with the selected text (unless user has explicitly set a search term in history)
- Enable "In Selection" mode by default (but allow users to disable it)
Provide clear visual indication when searching is limited to a selection
Allow toggling between "entire document" and "selection only" without closing the dialog

Multi-File Search

For project-wide search, display results in a hierarchical list:
- File name (grouped)
- Line number and preview of the match
- Allow clicking to navigate to that match
- Preview changes before replacing across files

Smart Default Scope

Single file open → search current file
Multiple files open → option to search current file or all open files
Project open → option for current file, open files, or entire project

Display and UX Considerations

Dialog Positioning

Can be floated as a window or docked to a side/bottom panel
User can drag and resize freely
Should not obstruct too much of the document
If positioned at top of editor, should allow scrolling the document beneath it
When floating, should always be on top but allow the user to interact with the document

Resizable Input Fields

Users can expand the Find/Replace fields by dragging to accommodate longer search patterns
Multi-line input should expand to show all text (max reasonable height)

Text Field Focus Management

Focus should be predictable and consistent
Tab key should move between: Find field → Replace field (if visible) → Action buttons → Back to Find
Shift+Tab should reverse this order
Clicking anywhere in a text field should maintain proper cursor positioning

Consistency Cues

Clear labels for all controls
Icons should be universally recognizable (magnifying glass for Find, sliders for options, etc.)
Color coding for different matches:
- Current match: highlight (e.g., orange/gold)
- Other matches: subtle highlight (e.g., light gray or light blue)
- Match counter should update in real-time

Accessibility

All buttons should have keyboard shortcuts OR be accessible via Tab navigation
Sufficient color contrast for visibility
Screen reader friendly: proper ARIA labels for all controls
Do not rely on color alone to distinguish between states

Error Handling and Edge Cases

Invalid Regular Expression

Display an error message inline below the Find field
Suggest valid regex syntax
Prevent Replace All until regex is corrected

No Matches Found

Display "No matches" message clearly
Offer to extend search scope (e.g., "Search entire document?" when currently limited to selection)
Suggest case-insensitive search if case-sensitive search found nothing

Large File Handling

For very large files, show a progress indicator during search
Implement incremental search (search as user types rather than searching entire file each keystroke)
Lazy-load results for multi-file searches

Search Across Line Breaks

When replacing with line breaks, display \n as a visible representation
Warn user if Replace All would create many newlines in result

Undo/Redo

All replacements should be undoable
Replace All should create a single undo point
Show undo count or transaction ID if available

Optional Advanced Features

Find and Replace History

Maintain separate history for Find and Replace strings
Allow users to access and reuse previous searches
Optionally save frequently used search patterns

Search Presets

Allow users to save complex regex patterns with names
Useful for recurring search tasks
Accessible via a dropdown or sidebar

Column Selection

If the editor supports multi-caret editing, integrate it:
- "Select All Matches" populates multiple cursors
- User can then type replacement text that applies to all selected instances simultaneously

Context and Statistics

Show context lines around matches (e.g., one line before and after)
Display statistics: "5 replacements made, 0 errors" after Replace All
Show time taken for large searches

Language/Syntax Awareness

For code editors, optionally ignore results in comments or strings
Respect language-specific conventions (e.g., camelCase refactoring)

Macro Support

Allow recording Find/Replace operations as part of macros
Enable users to replay complex find/replace sequences

Validation Checklist

Does the interface satisfy these requirements?

[ ] Single unified Find/Replace interface (not separate dialogs)
[ ] Non-modal (allows interacting with document)
[ ] Real-time highlighting of matches
[ ] Match counter with position indicator
[ ] Case sensitivity toggle
[ ] Whole word toggle
[ ] Regular expression support
[ ] Search scope options (selection, file, project)
[ ] Replace field with capture group support
[ ] Intelligible visual distinction between current and other matches
[ ] Replace preview before Replace All
[ ] Case preservation mode
[ ] Standard keyboard shortcuts (Ctrl+F, Ctrl+H, Enter, Shift+Enter)
[ ] Mnemonic shortcuts for power users
[ ] Multi-line search support (Ctrl+Enter for newlines)
[ ] Search history navigation
[ ] Clear error messages for invalid regex
[ ] "No matches" handling
[ ] Undo support for replacements
[ ] "In Selection" mode that respects user selection
[ ] Intuitive dialog positioning and resizing
[ ] Accessible to keyboard-only users
[ ] Accessible to screen readers
[ ] Replace All confirmation for large numbers of matches

Summary of Most Requested Features (From User Feedback)

Unified dialog instead of separate Find and Replace windows
Persistent, non-modal access that doesn't hide the document
Real-time match highlighting and count
In-selection search that actually respects the selection
Keyboard-driven workflow with discoverable shortcuts
Case preservation during replacement
Regular expression support with clear syntax help
Multi-line search support
Confirmation dialogs for Replace All to prevent accidental bulk replacements
Consistent behavior across selections, single files, and multiple files

Nov 21 '25 20:11 KeyWorksRW