feat: file viewer added

project_docs/UI_VIEW_V1_DESIGN.md

@@ -0,0 +1,223 @@
+# 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