curo1305andClaude Sonnet 4.6
475e519158
Archive v0.2 (UI Overhaul and Optimization) to milestones/: - milestones/v0.2-ROADMAP.md — full phase archive (Phases 8–11, 33 plans) - milestones/v0.2-REQUIREMENTS.md — all 40 requirements marked complete - milestones/v0.2-MILESTONE-AUDIT.md — audit artifact (passed, 40/40) - MILESTONES.md — new living milestone index - RETROSPECTIVE.md — new living retrospective with v0.2 section - PROJECT.md — full evolution review: v0.2 requirements moved to Validated, 5 new Key Decisions added - STATE.md — updated to milestone-complete status - ROADMAP.md — v0.2 phases collapsed into <details> with progress table updated Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
155 lines
8.6 KiB
Markdown
155 lines
8.6 KiB
Markdown
# Milestone v0.2: UI Overhaul and Optimization
|
||
|
||
**Status:** ✅ SHIPPED 2026-06-17
|
||
**Phases:** 8–11
|
||
**Total Plans:** 33
|
||
|
||
## Overview
|
||
|
||
v0.2 transformed DocuVault from a feature-complete but rough alpha into a polished, production-quality web application. The milestone covered four areas: codebase quality (decomposing monolith routers, eliminating duplication, purging dead code), admin panel rearchitecture (standalone route subtree with deep-linkable views), UX & interaction (empty states, skeletons, keyboard shortcuts, OS drag-drop, toast notifications), and visual design with responsive layout (mobile sidebar, consistent spacing, form styling, bundle optimization).
|
||
|
||
## Phases
|
||
|
||
### Phase 8: Stack Upgrade & Backend Decomposition
|
||
|
||
**Goal**: The dependency stack is current, all three backend router monoliths are split into focused sub-packages with zero URL or behavior changes, and the frontend API client is decomposed into domain modules behind a re-export barrel — the entire change is invisible to consumers and tests.
|
||
**Depends on**: Phase 7.4 (last v0.1 phase)
|
||
**Requirements**: PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08
|
||
**Plans**: 8 plans (3 waves)
|
||
|
||
**Wave 0** — Foundation (parallel)
|
||
- [x] 08-01-PLAN.md — CR-01/02/03 test stubs (3 xfail stubs in test_auth.py) + Wave 0 scaffolds for regression detection
|
||
- [x] 08-02-PLAN.md — `api/schemas.py` creation + `CloudConnectionOut` migration from admin.py (MUST precede admin split)
|
||
|
||
**Wave 1** — Phase 7.1 completion (frontend only)
|
||
- [x] 08-03-PLAN.md — `useToastStore` stub + CR test promotion + SettingsAccountTab.vue + TotpEnrollment.vue inline toast replacement
|
||
|
||
**Wave 2** — Backend decomposition + frontend (parallel)
|
||
- [x] 08-04-PLAN.md — Split `api/admin.py` → `api/admin/` package (CODE-01)
|
||
- [x] 08-05-PLAN.md — Split `api/documents.py` → `api/documents/` package (CODE-02)
|
||
- [x] 08-06-PLAN.md — Split `api/auth.py` → `api/auth/` package (CODE-03)
|
||
- [x] 08-07-PLAN.md — Frontend `client.js` decomposition: utils.js + 7 domain modules + barrel rewrite (CODE-04)
|
||
- [x] 08-08-PLAN.md — PERF-01 dependency bump + tailwind/vite config wiring + requirements.txt exact pinning
|
||
|
||
**Completed:** 2026-06-12
|
||
|
||
---
|
||
|
||
### Phase 9: Admin Panel Rearchitecture
|
||
|
||
**Goal**: The admin interface is a standalone route subtree (`/admin/*`) with its own layout component and sidebar; each admin section is deep-linkable and browser-back-button works; the `requiresAdmin` navigation guard correctly protects all child routes; and the Tailwind safelist is configured so dynamic color classes render correctly in production builds.
|
||
**Depends on**: Phase 8
|
||
**Requirements**: ADMIN-08, ADMIN-09, ADMIN-10, ADMIN-11, ADMIN-12, CODE-06, CODE-09
|
||
**Plans**: 5 plans (4 waves)
|
||
|
||
**Wave 1** — Foundation (parallel)
|
||
- [x] 09-01-PLAN.md — Backend overview.py endpoint + 8 ADMIN-11 tests
|
||
- [x] 09-02-PLAN.md — Frontend AdminLayout + AdminSidebar + AdminOverviewView + getAdminOverview API client
|
||
|
||
**Wave 2**
|
||
- [x] 09-03-PLAN.md — Extract 4 admin tab components to standalone views
|
||
|
||
**Wave 3**
|
||
- [x] 09-04-PLAN.md — Router rearchitecture (nested /admin + to.matched.some guard) + Tailwind safelist + delete AdminView.vue
|
||
|
||
**Wave 4**
|
||
- [x] 09-05-PLAN.md — CODE-09 comment purge + human checkpoint UAT
|
||
|
||
**Completed:** 2026-06-13
|
||
|
||
---
|
||
|
||
### Phase 10: UX & Interaction
|
||
|
||
**Goal**: The application communicates state clearly at every moment — empty contexts have purposeful empty states, loading transitions show structured skeletons, power users can operate keyboard-first, files can be dragged from the OS directly onto the browser, and every action produces an immediate toast confirmation.
|
||
**Depends on**: Phase 9
|
||
**Requirements**: UX-01 through UX-14, CODE-05
|
||
**Plans**: 13 plans (6 waves)
|
||
|
||
**Wave 0** — Foundation components + xfail test stubs (parallel)
|
||
- [x] 10-01-PLAN.md — AppIcon.vue + tests (CODE-05 foundation)
|
||
- [x] 10-02-PLAN.md — EmptyState.vue + tests (UX-01 foundation)
|
||
- [x] 10-03-PLAN.md — BreadcrumbBar.vue + tests (UX-12 foundation)
|
||
- [x] 10-04-PLAN.md — Toast store + ToastContainer.vue + App.vue mount + tests (UX-10 foundation)
|
||
- [x] 10-05-PLAN.md — Wave 0 xfail test stubs for UX-02..09, UX-11, UX-13, UX-14
|
||
|
||
**Wave 1** — Wire EmptyState, skeletons, BreadcrumbBar (parallel)
|
||
- [x] 10-06-PLAN.md — StorageBrowser + FileManagerView + CloudFolderView wiring
|
||
- [x] 10-07-PLAN.md — AppSidebar wiring (skeleton, EmptyState, UX-14 removal)
|
||
- [x] 10-08-PLAN.md — Admin views + Settings + SharedView + CloudStorageView
|
||
|
||
**Wave 2** — Keyboard shortcuts
|
||
- [x] 10-09-PLAN.md — Global keydown in App.vue + ref chain through FileManagerView/StorageBrowser
|
||
|
||
**Wave 3** — OS drag overlay
|
||
- [x] 10-10-PLAN.md — OsDragOverlay.vue + App.vue mount + FileManagerView.handleOsDrop
|
||
|
||
**Wave 4** — Drag-to-move + dropdown clipping fixes
|
||
- [x] 10-11-PLAN.md — Click-after-drag guard + Teleport-based folder picker + FolderRow three-dot menu
|
||
|
||
**Wave 5** — SVG centralization
|
||
- [x] 10-12-PLAN.md — Replace all inline `<svg>` blocks with `<AppIcon name="..." />`
|
||
|
||
**UAT Gap Closure**
|
||
- [x] 10-13-PLAN.md — 6 UAT gaps closed: sidebar shimmer, search-at-root, admin sidebar isolation, keyboard dispatch fix, Escape modifier, OS drop capture phase
|
||
|
||
**Completed:** 2026-06-16
|
||
|
||
---
|
||
|
||
### Phase 11: Visual Design, Responsive Layout & Cleanup
|
||
|
||
**Goal**: Every component uses the Tailwind spacing scale and typography system consistently, form elements have cross-browser baseline styling, interactive elements have consistent hover/focus states, the layout adapts cleanly to mobile viewports with a hamburger-toggled sidebar drawer, dead code is deleted, and bundle size is measured before and after.
|
||
**Depends on**: Phase 10
|
||
**Requirements**: VISUAL-01 through VISUAL-04, RESP-01 through RESP-05, CODE-07, PERF-02, PERF-03
|
||
**Plans**: 7 plans (5 waves + 1 UAT gap closure)
|
||
|
||
- [x] 11-01-PLAN.md — Bundle baseline + Vite analyzer wiring + lazy-load admin routes (PERF-02, PERF-03)
|
||
- [x] 11-02-PLAN.md — Tailwind forms plugin + form element baseline styling (VISUAL-02)
|
||
- [x] 11-03-PLAN.md — Responsive shells and storage rows (RESP-01, RESP-02)
|
||
- [x] 11-04-PLAN.md — Mobile-safe modals and form baseline verification (RESP-04, RESP-05)
|
||
- [x] 11-05-PLAN.md — Visual consistency pass — typography, focus-visible, hover/active states (VISUAL-01, VISUAL-03, VISUAL-04, RESP-03)
|
||
- [x] 11-06-PLAN.md — Dead-code sweep + bundle final measurement (CODE-07, PERF-02 post-opt)
|
||
- [x] 11-07-PLAN.md — Mobile storage toolbar compact icon controls (RESP-02, RESP-03 gap closure)
|
||
|
||
**Completed:** 2026-06-17
|
||
|
||
---
|
||
|
||
## Milestone Summary
|
||
|
||
**Key Decisions:**
|
||
|
||
- Options API preserved in v0.2 refactor — Composition API migration is scope-creep for a UX milestone
|
||
- Admin panel as standalone route subtree — AdminView.vue as tabs-on-user-layout is architecturally wrong
|
||
- `client.js` barrel re-export pattern — zero consumer churn; all 35+ import sites stay unchanged
|
||
- Sub-routers carry NO prefix — parent `include_router` propagates prefix; sub-router with prefix causes double-segment URLs
|
||
- FastAPI 0.128+ empty-path restriction — `@router.get("")` on sub-router with empty include prefix raises FastAPIError
|
||
- `to.matched.some()` for requiresAdmin guard — Vue Router 4 does not inherit meta to children; direct `to.meta` check is a security regression
|
||
- Vite 6→8 upgrade — resolved moderate CVEs (CVE-2026-39363/39364); npm audit clean
|
||
- AdminLayout as route component, not App.vue branch — router resolves AdminLayout as /admin component; its router-view renders children
|
||
- Tailwind safelist with regex patterns — dynamic color classes (sky=OneDrive, amber=admin audit badges) are tree-shaken without safelist
|
||
|
||
**Issues Resolved:**
|
||
|
||
- Admin panel auth guard was checking `to.meta.requiresAdmin` directly (Vue Router 4 doesn't inherit meta to children) — fixed to `to.matched.some()`
|
||
- Three-dot dropdown menus clipped by scroll containers — fixed with Teleport + getBoundingClientRect positioning
|
||
- Admin views loaded synchronously — all lazy-loaded, reducing initial bundle by 81 kB (−30.6%)
|
||
- Inline SVG duplicated path data in 66 instances — centralized in AppIcon.vue
|
||
- Mobile toolbar overflow below 550px — compact icon controls added in 11-07
|
||
|
||
**Issues Deferred:**
|
||
|
||
- Virtual scrolling — quota cap (100 MB/user) limits lists to hundreds of items; v-for sufficient
|
||
- Dark mode — coherent color token system must exist first
|
||
- Folder reordering by drag — requires persistent `position` column in DB
|
||
- Composition API migration — separate milestone
|
||
|
||
**Technical Debt Incurred:**
|
||
|
||
- Options API retained throughout — intentional deferral; next milestone may begin Composition API migration
|
||
|
||
---
|
||
|
||
*For current project status, see .planning/ROADMAP.md*
|