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