RHL-043 docs(search): document recent search history behavior

Docs/frontend-api-usage.md

@@ -9,6 +9,7 @@ Scope:
 - Practical examples for building the UI.
 - PDF streaming/opening behavior in the Explorer and in Search.
 - Search **date filters** (`from` / `to`) and **shareable URL sync** (RHL-025).
+- Search **recent history** behavior (frontend-only storage policy, RHL-042).
 - Password change for authenticated users (RHL-009).
 - Must-change-password enforcement flow (RHL-044).
 - Admin user management API usage (RHL-012).
@@ -28,6 +29,7 @@ Notes:
 - The backend provides a binary PDF stream/download endpoint (RHL-015). The Explorer integrates it for “Open PDF” (RHL-023).
 - The Search UI integrates the same “Open PDF” pattern (RHL-024).
 - The Search UI supports **optional date filters** (`from` / `to`) with a date range picker and presets (RHL-025).
+- The Search recent-history dropdown is frontend-only (`localStorage`) and does not require backend changes (RHL-042).
 - The protected UI enforces `mustChangePassword` via centralized auth gating (RHL-044).
 - User management endpoints are implemented under `/api/admin/users` and are guarded by the user-management capability (RHL-041 + RHL-012).
 
@@ -613,7 +615,33 @@ For Search v1, the first-page identity is URL-driven (shareable).
 - `q`, `scope`, `branches`, `limit`, `from`, `to` are part of the shareable state.
 - `cursor` is intentionally **not** part of the shareable URL and stays in client state.
 
-##### 4.4.3 Recommended usage (client-side)
+##### 4.4.3 Recent search history (frontend-only, RHL-042)
+
+The recent-search feature is intentionally frontend-only and stores compact first-page identities in browser `localStorage`.
+
+Storage policy:
+
+- Key format:
+  - `rhl.searchHistory.v1.<userId>`
+- Max entries:
+  - `10` (LRU; reusing a search moves it to the top)
+- Stored fields:
+  - `routeBranch`, `q`, `scope`, `branches`, `limit`, `from`, `to`, `createdAt`
+- Not stored:
+  - `cursor`
+
+Write trigger:
+
+- Persist only after a successful first-page search response.
+- Do not persist keystrokes or draft query changes.
+
+Restore rule:
+
+- Build an internal `/:branch/search` href from the stored entry.
+- Keep shareable first-page params only.
+- Never restore pagination cursor from history.
+
+##### 4.4.4 Recommended usage (client-side)
 
 ```js
 import { search, ApiClientError } from "@/lib/frontend/apiClient";

Docs/frontend-ui.md

@@ -1,4 +1,4 @@
-# Frontend UI: App Shell, Routing, Auth/RBAC, Explorer, Search, Date Range Filter, Navigation Polish, Profile Password Change, User Management, Role Refinement, Must-Change-Password Gate, and User Management UX Hardening (RHL-019 / RHL-020 / RHL-021 / RHL-022 / RHL-023 / RHL-024 / RHL-025 / RHL-037 / RHL-032 / RHL-009 / RHL-012 / RHL-041 / RHL-044 / RHL-043)
+# Frontend UI: App Shell, Routing, Auth/RBAC, Explorer, Search, Date Range Filter, Recent Search History, Navigation Polish, Profile Password Change, User Management, Role Refinement, Must-Change-Password Gate, and User Management UX Hardening (RHL-019 / RHL-020 / RHL-021 / RHL-022 / RHL-023 / RHL-024 / RHL-025 / RHL-037 / RHL-032 / RHL-009 / RHL-012 / RHL-041 / RHL-044 / RHL-042 / RHL-043)
 
 This document describes the **frontend routing scaffold**, the **application shell layout**, and the core UI modules for the RHL Lieferscheine app.
 
@@ -11,6 +11,7 @@ Timeline:
 - **RHL-023**: Explorer file action “Open PDF” using the binary PDF endpoint (opens in a new tab).
 - **RHL-024**: Search UI v1 (URL-driven `q`, scopes, cursor pagination, open PDF + jump to day).
 - **RHL-025**: Search date range filter (from/to) with a calendar popover, presets, local validation, and URL sync.
+- **RHL-042**: Search history dropdown (recent queries, per-user localStorage, LRU behavior, and first-page-only restore links).
 - **RHL-037**: Search scope UX improvements (TopNav deep-link branch switching + Single combobox + Multi selection UX + deterministic URL state).
 - **RHL-032**: Navigation UX polish (TopNav branding, theme toggle, user menu, tooltips, session indicator without content flicker, favicon, active states, and debounced loading UI).
 - **RHL-009**: Profile password change UI (Change Password form + toasts).
@@ -35,7 +36,7 @@ Timeline:
 
 ## 1. Scope
 
-### 1.1 Implemented (as of RHL-012 + RHL-041 + RHL-037 + RHL-025 + RHL-032 + RHL-009 + RHL-044 + RHL-043)
+### 1.1 Implemented (as of RHL-012 + RHL-041 + RHL-037 + RHL-025 + RHL-042 + RHL-032 + RHL-009 + RHL-044 + RHL-043)
 
 - **Public** `/login` route with a functional login form (shadcn/ui primitives).
 
@@ -160,6 +161,23 @@ Timeline:
   - The active filter is shown as a compact chip and can be cleared.
   - The filter is validated locally (fast feedback) and is also validated by the backend.
 
+- **Search history (recent queries, RHL-042)**
+  - A recent-search dropdown is available from the query box clock button.
+  - The clock trigger is icon-only, keyboard accessible, and has a tooltip.
+  - Entries are stored in browser `localStorage` per authenticated user:
+    - key: `rhl.searchHistory.v1.<userId>`
+    - max items: `10` (LRU: reused query moves to top)
+  - Stored entry fields:
+    - `routeBranch`, `q`, `scope`, `branches`, `limit`, `from`, `to`, `createdAt`
+    - `cursor` is intentionally never stored.
+  - Write trigger policy:
+    - entries are stored only when first-page search loading succeeds.
+  - Selection behavior:
+    - selecting a recent item navigates to a canonical first-page search URL
+      (including route branch switching when needed, e.g. `/NL32/search` -> `/NL17/search`).
+  - Clear behavior:
+    - users can clear all recent-search entries from the dropdown (`Verlauf löschen`).
+
 - **TopNav / navigation polish (RHL-032)**
   - Solid header (no blur/transparency) for crisp borders.
   - Branding logo (light + dark assets).
@@ -610,7 +628,7 @@ Implementation notes:
 
 ---
 
-## 9. Search UI (RHL-024 / RHL-037) + Date Range Filter (RHL-025)
+## 9. Search UI (RHL-024 / RHL-037) + Date Range Filter (RHL-025) + Recent Search History (RHL-042)
 
 ### 9.1 Route and state model
 
@@ -657,7 +675,39 @@ Shareable params (first page identity):
   - ISO date filter in `YYYY-MM-DD`
   - preserved in URLs and across branch switching
 
-### 9.2 Debounced loading UI (RHL-032)
+### 9.2 Recent search history (RHL-042)
+
+Search history is a frontend-only convenience feature built on top of the URL-driven first-page state model.
+
+Storage model:
+
+- Per-user browser key:
+  - `rhl.searchHistory.v1.<userId>`
+- Max entries:
+  - `10`
+- Deduplication:
+  - stable identity over `routeBranch`, `q`, `scope`, `branches`, `limit`, `from`, `to`
+  - reusing an existing search moves it to the top (LRU)
+
+Write trigger policy:
+
+- Entries are persisted only when the first-page request has succeeded.
+- Keystrokes/draft updates are never persisted.
+
+Restore behavior:
+
+- Restoring a recent item navigates to a canonical internal href under `/:branch/search`.
+- The route branch is restored from the stored entry (`routeBranch`) when needed.
+- The URL contains shareable first-page params only (`cursor` remains excluded).
+
+UI behavior:
+
+- Recent history is opened via the clock icon button in the query row.
+- The trigger has a tooltip (“Letzte Suchen anzeigen”).
+- The dropdown supports keyboard navigation (Command list).
+- A global clear action is available: “Verlauf löschen”.
+
+### 9.3 Debounced loading UI (RHL-032)
 
 Goal:
 
@@ -840,6 +890,11 @@ npm run build
 - Branch switching for admin-like users.
 - Explorer drill-down.
 - Search scopes (admin-like) + Search restrictions (branch).
+- Search history:
+  - execute several searches with different scopes/date filters/limits
+  - open recent-search dropdown via clock button
+  - restore recent entries across same and different branches
+  - clear history via `Verlauf löschen`
 - Open PDFs.
 - User management UI (superadmin/dev):
   - list/create/update/delete