webmanager-mvp/project_docs/UI_ACTION_SHORTCUTS_V1_DESIGN.md

# UI_ACTION_SHORTCUTS_V1_DESIGN.md

## 1. Doel en scope

Action shortcuts v1 maken de bestaande functiebalk sneller bruikbaar zonder de UI-semantiek te veranderen. Het doel is niet om nieuwe acties te ontwerpen, maar om de bestaande acties via toetsen te starten op exact dezelfde manier als via de functiebalk.

Doel:
- de huidige functiebalkacties sneller bereikbaar maken
- de dual-pane workflow dichter bij een Midnight Commander-achtige bediening brengen
- een bruikbare eerste set bieden die ook op Mac praktisch inzetbaar blijft

In scope:
- keyboard-start van bestaande functiebalkacties
- centrale shortcut-dispatch op basis van `activePane` en huidige selectie
- veilige focusguards zodat invoervelden en modals niet worden verstoord
- voorbereiding op latere visuele hints in de functiebalk

Out of scope:
- geen backendwijzigingen
- geen nieuwe acties buiten de bestaande functiebalk
- geen globale override van agressieve browser- of OS-shortcuts
- geen nieuwe dependencies
- geen extra keyboardnavigatie buiten action-triggering

---

## 2. Acties in scope

Deze ontwerpstap werkt uit voor:

- `View`
- `Edit`
- `Copy`
- `Move`
- `Rename`
- `MKdir`
- `Delete`

Semantisch uitgangspunt:
- elke shortcut triggert exact dezelfde action-handler als de corresponderende knop in de functiebalk
- enabled/disabled logica blijft centraal en wordt niet dubbel geïmplementeerd in aparte keyboardlogica
- als een knop in de huidige context disabled zou zijn, doet de shortcut geen destructieve fallback en start geen alternatieve flow

---

## 3. Toetsmapping

### Primaire mapping: F3 t/m F8

Voorgestelde primaire mapping:

- `F3` = `View`
- `F4` = `Edit`
- `F5` = `Copy`
- `F6` = `Move`
- `F7` = `MKdir`
- `F8` = `Delete`

Aanvullend:
- `Rename` krijgt in v1 geen vaste F-toets, omdat de klassieke mapping al dicht bezet is en `Rename` functioneel dichter bij contextactie dan bij de vaste MC-kern ligt
- `Rename` krijgt daarom een aparte, browser-veilige alternatieve shortcut

### Mac-vriendelijke alternatieven

F-toetsen zijn op Mac-toetsenborden vaak verborgen achter systeemfuncties of alleen bruikbaar met extra modifiers. Daarom krijgt v1 ook expliciete alternatieven.

Voorstel:
- `Alt+3` = `View`
- `Alt+4` = `Edit`
- `Alt+5` = `Copy`
- `Alt+6` = `Move`
- `Alt+7` = `MKdir`
- `Alt+8` = `Delete`
- `Alt+R` = `Rename`

Motivatie:
- numerieke mapping blijft mentaal gekoppeld aan `F3`-`F8`
- `Alt+R` is kort, semantisch duidelijk en minder conflictgevoelig dan veel andere browsercombinaties
- deze combinaties zijn compacter en realistischer op Mac dan het afdwingen van functietoetsgebruik

### Veiligheid in browsercontext

V1 kiest bewust geen mappings die sterk botsen met standaard browsergedrag, zoals:
- `Cmd+L`
- `Cmd+R`
- `Cmd+W`
- `Cmd+F`
- `Cmd+S`
- `Cmd+P`
- `Cmd+Backspace`

Ook geen pure lettershortcuts zonder modifier, omdat die te snel botsen met focus, tekstinvoer en toekomstige editorinteractie.

Belangrijk:
- `F3`-`F8` worden alleen gebruikt als extra shortcutlaag waar de browser/het OS dit toelaat
- de `Alt+...` varianten vormen de praktische browservriendelijke fallback

---

## 4. Focusregels

Shortcuts zijn alleen actief als de UI in browse-/paneelmodus zit en focus niet in een interactieve control staat.

### Shortcuts actief wanneer
- focus op `body`, paneelcontainer of bestandslijst staat
- geen modal met eigen invoer open is
- geen wildcard-popup open is
- geen editor-textarea focus heeft
- geen inputcontrol focus heeft

### Shortcuts niet actief wanneer focus in
- `input`
- `textarea`
- `select`
- `button`
- checkbox
- elk element met `contenteditable`

### Extra modalregels
- als `View` modal open is: geen action shortcuts voor onderliggende paneelacties
- als `Edit` modal open is: geen action shortcuts voor onderliggende paneelacties
- als wildcard popup open is: action shortcuts uitgeschakeld behalve popup-eigen `Enter`/`Escape`

### Browser/OS-collision mitigatie
- alleen exact ondersteunde combinaties afvangen
- geen brede `preventDefault()` voor andere toetsen
- bij twijfel niet afvangen; browser/OS behoudt dan prioriteit

---

## 5. Relatie met functiebalk en selectie

Kernregel:
- keyboard shortcuts gebruiken exact dezelfde centrale action-functies als de functiebalkknoppen

Dat betekent:
- `View` shortcut roept dezelfde open-viewer flow aan als de `View` knop
- `Edit` shortcut roept dezelfde open-editor flow aan als de `Edit` knop
- `Copy`/`Move` shortcut gebruiken dezelfde batch-startlogica als de bestaande knoppen
- `Rename`, `MKdir`, `Delete` shortcut gebruiken dezelfde validatie- en UI-flow als de bestaande knoppen

### Geen selectie
- `View`: geen actie
- `Edit`: geen actie
- `Copy`: geen actie
- `Move`: geen actie
- `Rename`: geen actie
- `MKdir`: wel toegestaan, op actief paneel
- `Delete`: geen actie

### Exact 1 selectie
- `View`: alleen voor ondersteunde file
- `Edit`: alleen voor ondersteunde tekstfile
- `Copy`: alleen als selectie backend-geldig is
- `Move`: alleen als selectie backend-geldig is
- `Rename`: toegestaan
- `MKdir`: toegestaan
- `Delete`: toegestaan

### Meerdere selecties
- `View`: niet toegestaan
- `Edit`: niet toegestaan
- `Copy`: toegestaan als alle geselecteerde items voldoen aan huidige backend-scope
- `Move`: toegestaan als alle geselecteerde items voldoen aan huidige backend-scope
- `Rename`: niet toegestaan
- `MKdir`: toegestaan
- `Delete`: toegestaan

### Directory/file-selectie
- zolang backend `copy/move` file-only is:
  - selectie die directories bevat blokkeert `Copy`
  - selectie die directories bevat blokkeert `Move`
- `View` en `Edit` blokkeren directories
- `Delete` volgt bestaande backendregels
- `Rename` volgt bestaande single-selection regel

### Disabled gedrag bij toetsgebruik
- geen verborgen fallback
- geen half-uitgevoerde actie
- optioneel compacte feedback via bestaande statusregel, maar v1 mag ook stil no-op blijven als dit consistenter is met huidige knopdisabled-semantiek

Voorkeur v1:
- als actie disabled is, shortcut doet niets en toont hooguit compacte statusfeedback als dat al in bestaande UI-patterns past

---

## 6. UX-regels

### Visuele hints in de functiebalk

Voorstel v1:
- subtiele shortcut-hints per knop toelaten, maar klein houden
- voorbeeld later mogelijk:
  - `F3 View`
  - `F4 Edit`
  - `F5 Copy`
- Mac-alternatieven hoeven niet permanent zichtbaar in de hoofdbalk om ruis te vermijden

Voor deze ontwerpstap geldt:
- de functiebalk moet voorbereid zijn op zulke hints
- de daadwerkelijke implementatie kan starten zonder direct alle hints zichtbaar te maken

### Niet-beschikbare acties
- als actie disabled is in de huidige context, mag de shortcut die actie niet forceren
- gedrag moet gelijk zijn aan klikken op een disabled knop: er gebeurt functioneel niets

### Unsupported acties
- `View` of `Edit` op niet-ondersteunde filetypes:
  - shortcut opent geen alternatieve flow
  - zelfde fout- of disabled-behandeling als via knop
- `Copy`/`Move` op directoryselectie terwijl backend dit niet ondersteunt:
  - zelfde blokkade als via knop

### Consistentie-eis
- shortcuts zijn geen tweede API-laag
- de functiebalk blijft leidend; keyboard is alleen een alternatieve triggerroute

---

## 7. Impactanalyse

Waarschijnlijk te wijzigen frontendbestanden:
- `webui/html/app.js`
- `webui/html/index.html`
- `webui/html/style.css`
- `webui/backend/tests/golden/test_ui_smoke_golden.py`

### Verwachte code-impact

`app.js`:
- uitbreiding van centrale keyboard dispatcher
- mappingtabel voor action shortcuts
- centrale guards voor modal/input/focusstatus
- hergebruik van bestaande action handlers, niet dupliceren

`index.html`:
- mogelijk kleine markup-aanpassingen om shortcutlabels in functiebalk te kunnen tonen
- geen structurele layoutwijziging nodig

`style.css`:
- eventueel compacte styling voor functietoetsbadges of hints
- geen redesign nodig

### Regressierisico

Belangrijkste risico's:
- conflicten met bestaande keyboard navigation (`Tab`, `Arrow`, `Space`, `Escape`)
- shortcuts vuren terwijl input of modal focus heeft
- dubbele actie-aanroep als keyboard en knoplogica niet centraal gedeeld worden
- browser/OS-shortcuts per platform gedragen zich anders

Mitigatie:
- centrale `shouldHandleActionShortcut(event)` guard
- bestaande knophandlers of action-functions als single source of truth
- alleen exacte combinaties afvangen
- platform-onafhankelijke fallbacklogica beperkt en expliciet houden

---

## 8. Teststrategie

### Smoke/regressietests

Geautomatiseerd uit te breiden waar passend:
- UI smoke test blijft controleren dat functiebalk aanwezig is
- optioneel extra check dat knoplabels of data-attributes voor actions stabiel aanwezig zijn
- geen zware browser-E2E vereist voor deze stap

### Handmatige validatie

Essentieel bij implementatie:
- `F3`-`F8` triggeren de juiste acties waar ondersteund
- `Alt+3`-`Alt+8` werken als Mac-vriendelijke fallback
- `Alt+R` triggert `Rename`
- shortcuts werken alleen op actief paneel
- shortcuts respecteren disabled toestand bij:
  - geen selectie
  - meerdere selecties
  - directoryselectie
  - unsupported filetypes
- editor modal, viewer modal en wildcard popup blokkeren onderliggende action shortcuts correct
- bestaande keyboard navigation blijft intact

### Regressiechecks
- klikgedrag in de bestandslijst blijft intact
- current-row navigatie blijft intact
- wildcard popup shortcuts blijven werken
- functiebalkknoppen en keyboardtrigger geven identiek resultaat