Add page for compare file filtering

Author: peterguy

docs/code-search/compare-file-filtering.mdx

@@ -0,0 +1,116 @@
+# File Filtering in the Repository Comparison Page
+
+The repository comparison page provides powerful file filtering capabilities that allow you to focus on specific files in a comparison. The system supports multiple ways to specify which files you want to view when comparing branches, tags, or commits.
+
+## Query Parameter-Based File Filtering
+
+The comparison page supports three different query parameters to specify which files to include in the comparison:
+
+### 1. Individual File Paths
+
+You can specify individual files using either of these parameters:
+
+- `filePath=path/to/file.js` - Primary parameter for specifying files
+- `f=path/to/file.js` - Shorthand alternative
+
+Multiple files can be included by repeating the parameter:
+
+```
+?filePath=src/index.ts&filePath=src/components/Button.tsx
+```
+
+### 2. Compressed File Lists
+
+For comparisons with a large number of files, the system supports compressed file lists (newline-separated):
+
+- `compressedFileList=base64EncodedCompressedData` - Efficiently packs many file paths
+
+This parameter uses base64-encoded, gzip-compressed data to efficiently transmit large sets of file paths. The compression makes it possible to include hundreds or thousands of files in a URL without exceeding length limits. The length limits vary depending on the browser, HTTP server, and other services involved like Cloudflare.
+
+```typescript
+// Behind the scenes, the code decompresses file lists using:
+const decodedData = atoburl(compressedFileList)
+const compressedData = Uint8Array.from([...decodedData].map(char => char.charCodeAt(0)))
+const decompressedData = pako.inflate(compressedData, { to: 'string' })
+```
+
+One way to create a list of files for the `compressedFileList` parameter is to use Python's built-in libraries to compress and encode using url-safe base64 encoding (which is smaller than base64-encoding, then url-encoding). 
+```shell
+python3 -c "import sys, zlib, base64; sys.stdout.write(base64.urlsafe_b64encode(zlib.compress(sys.stdin.buffer.read())).decode().rstrip('='))" < list.of.files > list.of.files.deflated.b64url
+```
+
+### 3. Special Focus Mode
+
+You can focus on a single file using:
+
+- `focus=true&filePath=path/to/specific/file.js` - Show only this file in detail view
+
+## File Filtering UI Components
+
+The comparison view provides several UI components to help you filter and navigate files:
+
+### FileDiffPicker
+
+The FileDiffPicker component allows you to:
+
+- Search for files by name or path
+- Filter files by type/extension
+- Toggle between showing all files or only modified files
+- Sort files by different criteria (path, size of change, etc.)
+
+This component uses a dedicated file metadata query optimized for quick filtering, with results displayed instantly as you type. The component can efficiently handle repositories with thousands of files through client-side filtering.
+
+### File Navigation
+
+When viewing diffs, you can:
+
+- Click on any file in the sidebar to switch to that file
+- Use keyboard shortcuts to navigate between files
+- Toggle between expanded and collapsed views of files
+- Show or hide certain types of changes (additions, deletions, etc.)
+
+### URL-Based Filtering
+
+Any filters you apply through the UI will update the URL with the appropriate query parameters. This means you can:
+
+1. Share specific filtered views with others
+2. Bookmark comparisons with specific file filters
+3. Navigate back and forth between different filter states using browser history
+
+## Implementation Details
+
+The system makes strategic performance trade-offs to provide a smooth user experience:
+
+```typescript
+/*
+ * For customers with extremely large PRs with thousands of files,
+ * we fetch all file paths in a single API call to enable client-side filtering.
+ *
+ * This eliminates numerous smaller API calls for server-side filtering
+ * when users search in the FileDiffPicker. While requiring one large
+ * initial API call, it significantly improves subsequent search performance.
+ */
+```
+
+The file filtering system uses a specialized file metadata query that is faster and more lightweight than the comprehensive file diffs query used for displaying actual code changes.
+
+## Usage Examples
+
+1. View only JavaScript files:
+
+   ```
+   ?filePath=src/utils.js&filePath=src/components/App.js
+   ```
+
+2. Focus on a single file:
+
+   ```
+   ?focus=true&filePath=src/components/Button.tsx
+   ```
+
+3. Use compressed file list for many files:
+   ```
+   ?compressedFileList=H4sIAAAAAAAAA2NgYGBg...
+   ```
+
+This flexible filtering system allows you to create customized views of repository comparisons, making it easier to review changes in large projects.