webmanager-mvp/project_docs/SEARCH_V1_DESIGN.md

Search v1

1. Doel

Search voegt nu waarde toe omdat de app inmiddels bruikbaar is als dual-pane file manager, maar nog volledig afhankelijk is van handmatige navigatie. Bij grotere directory trees kost dat te veel stappen.

Search moet passen binnen de bestaande dual-pane workflow:

• zoeken gebeurt vanuit het actieve paneel
• resultaten helpen navigatie versnellen
• de browse-workspace blijft het primaire werkvlak
• search is ondersteunend, geen nieuw hoofdscherm

2. Scope

Search v1 ondersteunt:

• zoeken op bestandsnaam
• zoeken op mapnaam
• case-insensitive substring matching

Search v1 ondersteunt niet:

• full-text content search
• indexer of achtergrondindexering
• regex
• geavanceerde querytaal
• saved searches
• fuzzy ranking

Aanbevolen zoekmodel voor v1:

• eenvoudige naamzoeking met substring match
• optioneel later uit te breiden naar glob of prefix filters, maar niet in deze slice

3. Zoekbereik

Mogelijke richtingen:

• zoeken vanaf current path
• zoeken vanaf de root van het actieve paneel

Aanbeveling voor v1:

• standaard zoeken vanaf current path van het actieve paneel

Reden:

• laag regressierisico
• voorspelbaar voor de gebruiker
• technisch goedkoper
• minder kans op trage scans van volledige opslagvolumes
• sluit goed aan op de huidige paneel-context

Gedrag:

• activePane bepaalt de zoekcontext
• de query zoekt recursief onder currentPath van dat paneel
• resultaten horen dus altijd bij de context van het actieve paneel op het moment van starten

Later uitbreidbaar:

• een simpele scope-toggle Current folder tree versus Current root

4. UI-richting

Aanbevolen v1-richting:

• aparte compacte search-modal
• geen verstoring van de dual-pane layout

Startmechanisme:

• alleen keyboard shortcut
• geen zichtbare knop in topbar
• geen zichtbare knop in functiebalk

Aanbevolen shortcut voor v1:

• Mac: Cmd+Shift+F
• Windows/Linux: Ctrl+Shift+F

Reden:

• sluit goed aan op bestaande zoekverwachtingen
• vermijdt extra visuele drukte in de UI
• vermijdt conflict met bestaande F1-F8 functiebalklogica

Modal-inhoud:

• titel Search
• actieve paneelcontext tonen
• zoekveld
• korte contextregel: Searching under: <current path>
• resultatenlijst onder het invoerveld

Gedrag bij resultaatklik:

• klik op resultaat opent de parentlocatie in het actieve paneel
• en selecteert het gevonden item

Voor directories:

• resultaatklik navigeert naar die directory in het actieve paneel

Voor files:

• resultaatklik navigeert naar de parent directory in het actieve paneel
• en selecteert de file

Dit sluit aan op de bestaande browse- en selectieflow zonder extra viewer/open-semantiek.

5. Resultaatsemantiek

Minimale velden per resultaat:

• name
• path
• type (file of directory)
• parent_path
• root of equivalent contextveld

Weergave in v1:

• primaire regel: naam
• secundaire regel: parent path of volledig path
• compacte type-indicatie (file / dir)

Aanbevolen presentatie:

• naam prominent
• parent path als muted secundaire regel
• type als kleine badge of label

6. Backend-impact

Aanbevolen endpoint:

• GET /api/search?path=...&query=...

Waarom een nieuw endpoint nodig is:

• browse-endpoint is contractueel directory listing
• search vereist recursieve traversal en resultaatlimieten
• aparte fout- en limietsemantiek is logisch

Securitymodel:

• path moet via bestaande path_guard
• zoekroot moet binnen whitelist vallen
• traversal en invalid root alias blijven via bestaande validatie lopen
• geen vrije scan buiten geconfigureerde roots

Implementatierichting:

• backend scant recursief vanaf gevalideerde startdirectory
• vergelijkt naam case-insensitive met query
• retourneert gemaximeerde lijst van matches

7. Performance en risico

Grootste risico:

• diepe directory trees op grote volumes

Aanbevolen v1-beheersing:

• result limit, bijvoorbeeld 100
• optionele harde scan limit op aantal bezochte entries
• geen parallelle scanner
• geen indexer

Aanbevolen gedrag bij limiet:

• response bevat truncated: true/false
• als limiet bereikt is, toon alleen eerste resultaten

Timeouts:

• geen aparte timeoutsemantiek nodig in eerste slice als result-limiet en current-path scope klein blijven

8. Regressierisico

Belangrijkste risico’s:

• browse-flow mag niet veranderen
• selectieflow mag niet onverwacht resetten buiten het actieve paneel
• keyboardflow mag niet botsen met bestaande shortcuts
• modal focus moet bestaande paneelnavigatie blokkeren zolang search open is

Beperkende keuzes die risico laag houden:

• aparte modal
• zoeken alleen op naam
• starten vanuit actief paneel
• resultaten openen in bestaand paneelgedrag

9. Teststrategie

Backend golden tests:

• lege resultaatlijst
• simpele file match
• simpele directory match
• search onder current path
• traversal geblokkeerd
• path not found
• invalid root alias
• result limit / truncated gedrag

UI smoke/regressietests:

• search-modal container aanwezig
• zoekveld aanwezig
• resultaatlijst container aanwezig
• keyboard wiring voor Cmd/Ctrl+Shift+F

Handmatige validatie:

• zoeken vanuit links paneel raakt alleen linkse context
• zoeken vanuit rechts paneel raakt alleen rechtse context
• resultaatklik navigeert correct
• resultaatklik op directory opent directory
• resultaatklik op file opent parent + selecteert file
• Escape sluit modal

10. Aanbeveling

Aanbevolen v1-richting met laag regressierisico:

• nieuw backend-endpoint GET /api/search
• recursieve naamzoeking
• scope = currentPath van actief paneel
• case-insensitive substring match
• harde result limit, bijvoorbeeld 100
• aparte compacte search-modal
• resultaatklik hergebruikt bestaande paneelnavigatie en selectie

Niet aanbevelen voor v1:

• root-brede zoeking als default
• content search
• indexer
• regex
• aparte zoekpagina

Dit levert een bruikbare eerste search op zonder de huidige dual-pane file manager semantiek te verstoren.