# UI_KEYBOARD_V1_DESIGN.md

## 1) Doel

Keyboard navigation v1 maakt de huidige dual-pane UI efficiënter voor snelle bestandsnavigatie en selectie, in lijn met een Midnight Commander-achtige workflow: minder muisgebruik, voorspelbare focus, snelle pane-switching.

### In scope (v1)
- `Tab` wisselt actief paneel.
- `ArrowUp` / `ArrowDown` verplaatst `current row` in actief paneel.
- `Enter` opent de map van de `current row` als die row een directory is.
- `Space` togglet selectie van `current row`.
- `Escape` wist selectie in actief paneel.

### Out of scope (v1)
- Geen `F3/F4` viewer/editor.
- Geen `F5/F6/F7/F8` keyboard-acties.
- Geen shift/ctrl/insert multi-selectgedrag.
- Geen globale override van onbetrouwbare browser-shortcuts.

---

## 2) Scope Keyboard v1 (klein en veilig)

### Shortcutset
- `Tab`:
  - als focus niet in een input/control zit: wissel `activePane` (`left` <-> `right`).
  - default browser tab-navigatie blokkeren in dit geval.
- `ArrowUp` / `ArrowDown`:
  - beweeg `currentRowIndex` binnen zichtbare lijst van actief paneel.
  - clamp tussen `0` en `items.length - 1`.
  - geen wrap-around in v1.
- `Enter`:
  - als `current row` directory is: navigeer naar die directory.
  - als `current row` file is: geen open; behoud selectiegedrag (geen viewer).
- `Space`:
  - toggle selectie op `current row` item.
- `Escape`:
  - clear alle geselecteerde items in actief paneel.

---

## 3) State model

Per paneel (`left`/`right`) expliciet onderscheid:
- `currentPath`: huidige padcontext.
- `entries`: gecombineerde zichtbare lijst (dirs/files) in rendervolgorde.
- `currentRowIndex`: keyboard-cursorpositie binnen `entries`.
- `selectedItems`: geselecteerde items (set/list op pad).

Globaal:
- `activePane`: `left` of `right`.

### Semantiek
- `current row` is focus/cursor voor keyboardnavigatie.
- `selected items` is actiedoel (rename/delete/copy/move-regels blijven gelden).
- `active pane` bepaalt waar keyboardinput op werkt.

### Bij navigatie
- `ArrowUp/Down` verandert alleen `currentRowIndex` in actief paneel.
- Geen wijziging in ander paneel.

### Bij directory openen (`Enter` op directory)
- Navigeer in actief paneel naar directory.
- Wis selectie in actief paneel.
- Reset `currentRowIndex` naar eerste item (of `null` bij lege lijst).
- Inactief paneel blijft ongewijzigd.

### Bij leeg paneel
- `currentRowIndex = null`.
- `ArrowUp/Down/Enter/Space` doen niets.
- `Escape` blijft selectie-clear uitvoeren (idempotent).

---

## 4) UX-regels

### Focusveiligheid
Shortcuts zijn alleen actief als event target **geen** interactieve invoercontrol is:
- `input`, `textarea`, `select`, `button`, checkbox, of `contenteditable`.

### Wanneer shortcuts actief zijn
- Alleen op documentniveau handler als focus op lijst/paneelcontainer of body staat.
- Als gebruiker expliciet in form/control werkt, geen keyboard-capturing.

### Visualisatie
- `current row` krijgt aparte, subtiele cursorstijl (`is-current-row`).
- `selected rows` behouden bestaande selectiehighlight (`is-selected`).
- Row kan beide states tegelijk hebben: current + selected.
- `activePane` blijft via border/focusrand zichtbaar; geen sterke achtergrondwissel.

---

## 5) Impactanalyse

Waarschijnlijk te wijzigen:
- `webui/html/app.js`
  - keyboard event handling
  - state uitbreiding met `currentRowIndex`
  - paneelgerichte row-navigation helpers
- `webui/html/style.css`
  - styling voor `is-current-row` + gecombineerde state met `is-selected`
- `webui/html/index.html`
  - alleen kleine aanpassingen indien nodig (bv. paneelcontainer attributes)
- `webui/backend/tests/golden/test_ui_smoke_golden.py`
  - alleen bij structurele id/class wijzigingen

### Regressierisico
- Bestaande klik/selectieflow kan botsen met nieuwe current-row state.
- Event bubbling kan dubbele selectie-updates geven.
- Tab-handling kan browser-focusflow verstoren als te agressief.

Mitigatie:
- Centrale `shouldHandleShortcut(event)` guard.
- Centrale helpers voor `setCurrentRow`, `toggleSelectionForCurrentRow`, `openCurrentRowDirectory`.
- Geen backendaanpassingen.

---

## 6) Teststrategie

### Geautomatiseerd (klein)
- Bestaande UI smoke tests behouden (`/ui`, panelen, assets).
- Optioneel kleine regressietest op aanwezigheid van paneelcontainers en lijststructuur; geen zware browser-E2E in v1.

### Handmatige validatie (primair voor v1)
- `Tab` wisselt actief paneel betrouwbaar.
- `ArrowUp/Down` beweegt current row alleen in actief paneel.
- `Enter` opent alleen directory op current row.
- `Space` togglet selectie op current row.
- `Escape` wist selectie in actief paneel.
- Shortcuts doen niets tijdens focus in input/checkbox/button.
- Leeg paneel geeft geen errors bij keyboardinput.

### Regressiechecks
- Bestaand klikgedrag blijft intact:
  - checkbox toggle
  - rij-click selectie
  - directory-naam opent directory
- Onderbalkacties blijven werken op `selectedItems` van actief paneel.