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