101 lines
4.4 KiB
Markdown
101 lines
4.4 KiB
Markdown
# pdftract-2wqir: Keyboard shortcuts verification
|
||
|
||
## Summary
|
||
|
||
Implemented comprehensive keyboard shortcuts in the inspector frontend for power user productivity.
|
||
|
||
## Changes made
|
||
|
||
### `crates/pdftract-cli/src/inspect/frontend/app.js`
|
||
|
||
1. **Extended `setupKeyboard()` function** (lines 443-467 → new):
|
||
- Added `ArrowUp`/`ArrowDown` handlers for scrolling within page
|
||
- Added `?` key handler to toggle help overlay
|
||
- Added `Escape` handler to close help overlay (priority over Escape in inputs)
|
||
- Improved input handling: Escape now blurs any input/textarea, clears search if in search input
|
||
|
||
2. **Added `prevPage()` and `nextPage()` wrapper functions** (after `navigatePage()`):
|
||
- Semantic wrappers for `navigatePage(-1)` and `navigatePage(1)`
|
||
- Matches naming convention suggested in task description
|
||
|
||
3. **Added `scrollPage(delta)` function**:
|
||
- Scrolls the canvas container by 100px per keypress
|
||
- Supports smooth scrolling within long pages
|
||
|
||
4. **Added `toggleHelp(show)` function**:
|
||
- Toggles help overlay visibility
|
||
- Focuses close button for accessibility when opening
|
||
- Hides overlay when `show` is false
|
||
|
||
5. **Added `setupHelp()` function**:
|
||
- Wires up the ? button click handler
|
||
- Wires up close button click handler
|
||
- Adds click-outside-to-close behavior
|
||
|
||
6. **Updated `init()` function**:
|
||
- Added call to `setupHelp()`
|
||
|
||
### `crates/pdftract-cli/src/inspect/frontend/index.html`
|
||
|
||
1. **Added "?" button** in toolbar:
|
||
- Placed between search input and layer toggles
|
||
- `aria-label="Show keyboard shortcuts"` and `title="Keyboard shortcuts (?)"`
|
||
- Class `btn-help` for circular styling
|
||
|
||
2. **Added help overlay** at end of body:
|
||
- Modal with semi-transparent backdrop
|
||
- Lists all keyboard shortcuts with semantic formatting
|
||
- Close button (×) in top-right corner
|
||
- Click-outside-to-close behavior
|
||
|
||
### `crates/pdftract-cli/src/inspect/frontend/style.css`
|
||
|
||
1. **Added `.btn-help` styles**:
|
||
- Circular button (32px × 32px)
|
||
- Centered "?" text, weight 600
|
||
|
||
2. **Added `.help-overlay` styles**:
|
||
- Fixed full-screen backdrop (rgba(0,0,0,0.5))
|
||
- Flex centering for content
|
||
- z-index 2000 (above all other UI)
|
||
|
||
3. **Added `.help-content` styles**:
|
||
- White rounded card (8px radius)
|
||
- Max-width 500px, responsive width
|
||
- Box shadow and max-height constraints
|
||
|
||
4. **Added `.help-shortcuts`, `.help-shortcut`, `.help-key`, `.help-desc` styles**:
|
||
- Tabular layout for key + description pairs
|
||
- Monospace font for keys
|
||
- Visual separator between navigation and layer keys
|
||
|
||
## Acceptance criteria verification
|
||
|
||
| Criteria | Status | Notes |
|
||
|----------|--------|-------|
|
||
| ArrowLeft on page 5 → goes to page 4 | **PASS** | `navigatePage(-1)` called via ArrowLeft handler |
|
||
| ArrowRight on last page → no-op | **PASS** | `if(newPage>=0&&newPage<totalPages)` check prevents out-of-bounds |
|
||
| / focuses search | **PASS** | Already implemented, confirmed working |
|
||
| 1-8 toggle overlays with visual feedback | **PASS** | `toggleLayer()` called; layer button `active` class toggles via `applyLayers()` |
|
||
| Esc blurs input + clears focus | **PASS** | `document.activeElement.blur()` on Escape; help overlay closes on Escape |
|
||
| ? shows help overlay | **PASS** | `toggleHelp()` shows overlay; lists all shortcuts |
|
||
|
||
## Retrospective
|
||
|
||
### What worked
|
||
- The existing `setupKeyboard()` function was well-structured and easy to extend
|
||
- Using `dataset.layers` for layer state management made toggleLayer() straightforward
|
||
- CSS-only layer visibility via `html[data-layers~="layerName"]` selector pattern is clean
|
||
|
||
### What didn't
|
||
- Initial `setupKeyboard()` check `if(e.target.tagName==='INPUT'&&e.target!==searchInput)return` was too broad—it prevented Escape from blurring non-search inputs. Fixed by restructuring to handle Escape separately before the early return.
|
||
|
||
### Surprise
|
||
- The code already had `setupKeyboard()` with most shortcuts implemented (arrows, /, 1-9, Escape). This task was primarily about:
|
||
1. Adding `?` for help
|
||
2. Adding `ArrowUp`/`ArrowDown` for scrolling
|
||
3. Improving Escape handling to close help overlay
|
||
|
||
### Reusable pattern
|
||
- Help overlay pattern: `toggleHelp(show)` with semantic boolean, click-outside-to-close via `e.target===overlay` check, and close button focus for accessibility
|
||
- Keyboard shortcut pattern: Check `e.target.tagName` for INPUT/TEXTAREA, special-case Escape for blur, use `e.preventDefault()` on navigation keys to suppress browser defaults
|