webmanager-mvp/project_docs/UI_VIEW_V1_DESIGN.md

UI_VIEW_V1_DESIGN.md

1. Scope

View v1 is een eenvoudige read-only file viewer in de webui, gekoppeld aan de functiebalkactie View.

In scope:

• alleen read-only weergave
• alleen files, geen directories
• openen vanuit de bestaande UI
• eenvoudige modalweergave

Out of scope:

• geen editfunctionaliteit
• geen save
• geen inline rename
• geen compare
• geen syntax-aware editor

Backendwijzigingen:

• een nieuw read-only file-read endpoint is waarschijnlijk nodig
• alleen als veilig en strikt binnen het bestaande whitelist/path_guard model

---

2. Ondersteunde bestandstypen in v1

Voorstel v1:

• txt: ja
• log: ja
• md: ja
• yml / yaml: ja
• json: ja
• js: ja
• css: ja
• html: ja
• Dockerfile: ja
• Containerfile: ja

PDF

Voorstel: niet in v1

Motivatie:

• PDF-preview vraagt om aparte rendering of browser-embedgedrag
• dat vergroot complexiteit, testoppervlak en afhankelijkheid van browserverschillen
• View v1 blijft daardoor gefocust op tekstbestanden

Gevolg:

• PDF en andere niet-ondersteunde typen geven een duidelijke unsupported preview melding in de modal

---

3. UI/UX

Openen

• View wordt gestart via de functiebalk
• werkt alleen op het actieve paneel
• alleen geldig bij exact 1 geselecteerd item
• alleen geldig als dat item een file is

Presentatie

• openen in een modal boven de bestaande dual-pane UI
• modal bevat:
  • titel/header
  • bestandsnaam
  • volledig pad
  • read-only contentgebied
  • rechtsboven een X

Sluiten

• klik op X sluit modal
• Escape sluit modal
• klik buiten modal mag optioneel sluiten, maar hoeft niet verplicht in v1

Inhoud

• contentgebied is verticaal scrollbaar
• tekst blijft selecteerbaar en kopieerbaar
• monospace weergave voor tekstinhoud
• geen bewerkcontrols

---

4. Technische aanpak

Frontend

Voorstel:

• toevoegen van een viewer-modal in index.html
• View knop wordt enabled bij precies 1 geselecteerde file
• app.js opent modal en haalt previewdata op via nieuw backend-endpoint

Backend

Waarschijnlijk nieuw endpoint nodig:

• GET /api/files/view?path=...

Voorstel response shape:

• path
• name
• content_type
• encoding
• truncated
• size
• content

Voorbeeldgedrag:

• tekstbestand: inhoud als UTF-8 string terug
• unsupported type: nette 409/400-achtige applicatiefout of expliciete supported=false response

Preview-keuze / typebepaling

Voorstel v1:

• eerst extensie- en bestandsnaamgebaseerde allowlist
• speciale namen:
  • Dockerfile
  • Containerfile
• optioneel secundair op mime gokken, maar niet leidend maken

Grote bestanden

Voorstel:

• harde limiet op previewgrootte, bijvoorbeeld 256 KB of 512 KB
• backend leest maximaal tot die limiet
• response bevat truncated = true als bestand groter is

Dit voorkomt:

• grote memory responses
• trage modal-openingen
• onnodige load voor logbestanden

Unsupported bestandstypen

Voorstel:

• backend of frontend classificeert bestand als niet-previewbaar
• modal toont compacte melding:
  • bestandstype niet ondersteund in View v1

Geen fallback naar download of externe viewer in v1.

---

5. Security en scopebeperking

• alle padvalidatie via bestaand path_guard
• alleen paden binnen whitelist
• geen directoryweergave via viewer
• geen write/save-endpoint
• geen downloadmanager
• geen externe viewer libraries in v1

Voor tekstpreview:

• inhoud alleen server-side lezen via gecontroleerde backendroute
• geen directe file-URL of browser file access

---

6. Impactanalyse

Waarschijnlijk te wijzigen frontendbestanden:

• webui/html/index.html
• webui/html/app.js
• webui/html/style.css
• webui/backend/tests/golden/test_ui_smoke_golden.py

Waarschijnlijk te wijzigen backendbestanden:

• webui/backend/app/api/routes_files.py of aparte view-route
• webui/backend/app/api/schemas.py
• webui/backend/app/services/file_ops_service.py of aparte view service
• webui/backend/app/fs/filesystem_adapter.py
• eventueel nieuwe golden tests voor view-endpoint

Regressierisico

• functiebalk enabled/disabled logica kan fout lopen bij View
• modal-keyboardinteractie kan bestaande keyboard shortcuts blokkeren of lekken
• grote bestanden of binair ogende inhoud kunnen previewflow verstoren
• pad/securityvalidatie moet identiek streng blijven als bij browse/file ops

Mitigatie:

• View alleen bij exact 1 fileselectie
• modal-open toestand blokkeert gewone navigatieshortcuts
• size limit en type allowlist in backend

---

7. Teststrategie

Golden tests

Voor backend indien endpoint wordt toegevoegd:

• view success voor ondersteund tekstbestand
• unsupported type
• directory geselecteerd -> type conflict
• path not found
• traversal attempt
• invalid root alias
• truncated response voor groot bestand

UI smoke tests

Aan te passen:

• modalcontainer aanwezig in HTML
• View knop aanwezig in functiebalk

Niet nodig in smoke:

• volledige interactieflow headless afdwingen, tenzij de huidige stack dat eenvoudig ondersteunt

Handmatige validatie

• View enabled bij exact 1 geselecteerde file
• View disabled bij:
  • geen selectie
  • meerdere selectie
  • directoryselectie
• modal opent correct
• pad en bestandsnaam zichtbaar
• tekstinhoud scrollbaar
• selectie/kopiëren van tekst werkt
• Escape en X sluiten modal
• unsupported type geeft nette melding
• groot bestand wordt veilig afgekapt