diff --git a/.planning/phases/03-document-migration-multi-user-isolation/03-UI-SPEC.md b/.planning/phases/03-document-migration-multi-user-isolation/03-UI-SPEC.md new file mode 100644 index 0000000..66ca471 --- /dev/null +++ b/.planning/phases/03-document-migration-multi-user-isolation/03-UI-SPEC.md @@ -0,0 +1,350 @@ +--- +phase: 3 +slug: document-migration-multi-user-isolation +status: draft +shadcn_initialized: false +preset: none +created: 2026-05-23 +--- + +# Phase 3 — UI Design Contract + +> Visual and interaction contract for Phase 3: Document Migration & Multi-User Isolation. +> Generated by gsd-ui-researcher, verified by gsd-ui-checker. + +--- + +## Design System + +| Property | Value | +|----------|-------| +| Tool | none — raw Tailwind CSS v3 | +| Preset | not applicable | +| Component library | none | +| Icon library | Inline SVG heroicons (stroke, no fill) — matches existing AppSidebar, DropZone, and UploadProgress patterns | +| Font | System font stack (Tailwind default: ui-sans-serif, system-ui, sans-serif) | + +**Source:** Inherited from Phase 2 UI-SPEC (approved 2026-05-22). No design system changes in Phase 3. `tailwind.config.js` has empty `theme.extend` — no custom tokens. + +--- + +## Spacing Scale + +Identical to Phase 2 — inherited, not re-specified. + +| Token | Value | Usage | +|-------|-------|-------| +| xs | 4px | Icon-to-label gaps, badge padding, progress step gaps | +| sm | 8px | Compact inline spacing, quota bar label gap | +| md | 16px | Default field padding, card internal padding | +| lg | 24px | Section vertical gap | +| xl | 32px | Upload card top margin | +| 2xl | 48px | Page vertical centering padding | +| 3xl | 64px | Page-level clearance | + +Exceptions: +- Upload progress bar track height: 8px (`h-2`). Justification: 4px (xs) is too narrow to show color transitions clearly at small viewport widths; 8px is the established browser progress-bar idiom and remains within the scale. +- Quota bar track height: 8px (`h-2`). Same justification as upload progress bar. +- Quota bar touch/click area (sidebar widget, not interactive): no min-height required — display-only element. + +**Source:** Phase 2 UI-SPEC approved spacing scale. Phase 3 adds no new interactive controls that require new spacing exceptions. + +--- + +## Typography + +Identical to Phase 2 — inherited, not re-specified. + +| Role | Size | Weight | Line Height | Tailwind Class | +|------|------|--------|-------------|----------------| +| Body | 14px | 400 (regular) | 1.5 | `text-sm` | +| Label | 14px | 600 (semibold) | 1.4 | `text-sm font-semibold` | +| Heading | 20px | 600 (semibold) | 1.3 | `text-xl font-semibold` | +| Display | 24px | 600 (semibold) | 1.2 | `text-2xl font-semibold` | + +Font weight scale: exactly 2 weights — regular (400) and semibold (600). Do not introduce `font-medium` (500) or `font-bold` (700). Do not use `font-medium` that already appears in `.nav-link` scoped styles — that is a pre-existing pattern in AppSidebar and must not be propagated to new components. + +**New in Phase 3:** +- Quota bar label: `text-xs text-gray-500` (body at reduced size — acceptable exception for sidebar metadata density). +- Upload step label (beneath progress bar): `text-xs text-gray-400` — same pattern as existing `UploadProgress.vue` status lines. +- Error detail lines in quota rejection: `text-xs text-red-600` — matches Phase 2 inline field error style. + +**Source:** Phase 2 UI-SPEC. `UploadProgress.vue` uses `text-xs text-gray-400` for status lines — retained for consistency. + +--- + +## Color + +Identical to Phase 2 palette — no new colors introduced. Phase 3 adds two state-specific usages within the existing amber and red semantic tokens. + +| Role | Value | Tailwind Token | Usage | +|------|-------|----------------|-------| +| Dominant (60%) | #f9fafb | `bg-gray-50` | Page background | +| Secondary (30%) | #ffffff | `bg-white` | Cards, upload progress rows, sidebar | +| Accent (10%) | #4f46e5 | `indigo-600` / `indigo-700` | Primary CTA buttons only, active nav link text, brand logo text | +| Accent subtle | #eef2ff | `indigo-50` | Active nav link background; upload progress bar fill (in-progress step) | +| Destructive | #dc2626 | `red-600` | Quota bar at ≥ 95% fill; quota rejection error banner border/text | +| Warning | #d97706 | `amber-600` | Quota bar at ≥ 80% fill (below 95%); quota warning text | +| Success | #16a34a | `green-600` | Upload complete checkmark icon — existing UploadProgress pattern | +| Neutral border | #e5e7eb | `gray-200` | Card borders, progress row borders, quota bar track background | +| Muted text | #9ca3af | `gray-400` | Quota bar label secondary text, upload step sub-labels | + +**Source:** Phase 2 UI-SPEC. CONTEXT.md STORE-04 locks amber at 80%, red at 95%. CONTEXT.md D-07 specifies HTTP 413 response — maps to `red-600` error treatment. + +Accent reserved for: primary CTA buttons, active sidebar nav link text, DocuVault brand/logo text, in-progress upload step indicator fill (`indigo-50` track fill). +Accent is NOT used on: quota bar fills, error banners, or secondary link text. + +### Quota Bar Color Logic (State Machine) + +| Condition | Bar fill color | Label color | +|-----------|---------------|-------------| +| `usage < 80%` | `bg-indigo-500` | `text-gray-500` | +| `80% ≤ usage < 95%` | `bg-amber-500` | `text-amber-600` | +| `usage ≥ 95%` | `bg-red-500` | `text-red-600` | + +Bar track (background): `bg-gray-200` always. +Bar fill width: `style="width: {percent}%"` clamped to `max-w-full`. + +--- + +## Upload Flow — Interaction Contract + +### Overview + +The two-step presigned upload (CONTEXT.md D-05) is invisible to the user as a multi-step operation. The user sees a single continuous upload experience from file selection to completion. + +### Step Mapping to UI States + +| Internal Step | User-visible state | +|---------------|--------------------| +| Step 1: `POST /api/documents/upload-url` | "Preparing upload…" — spinner active, 0% progress | +| Step 2: `PUT {presigned_url}` (browser → MinIO) | "Uploading…" — progress bar advances 5% → 90% using XHR `progress` event | +| Step 3: `POST /api/documents/{id}/confirm` | "Processing…" — progress bar at 95%, spinner resumes | +| Celery enqueued (confirm returns 200) | "Done — classifying…" — progress bar completes to 100%, green checkmark | +| Error at any step | Error state (see Error States below) | + +### Progress Bar Visual Contract + +The progress bar is an addition to the existing `UploadProgress.vue` component row. + +Each upload row in `UploadProgress.vue` gains a progress bar between the filename and the status line: + +``` +[ filename.pdf (spinner/checkmark/error icon) ] +[ ████████████░░░░░░░░░░ 62% ] +[ Uploading… ] +``` + +Bar specifications: +- Track: `w-full h-2 bg-gray-100 rounded-full mt-1` +- Fill: `h-2 rounded-full transition-all duration-300` + color class from state +- In-progress fill color: `bg-indigo-500` +- Complete fill color: `bg-green-500` +- Error fill color: `bg-red-400` (stops at last % value, does not reset to 0) +- Percentage label: `text-xs text-gray-400 text-right mt-0.5` — shown during upload, hidden after completion + +### Upload Progress Values by Step + +| Step | Progress value | Visual | +|------|---------------|--------| +| Awaiting upload URL | 0% | Bar at 0, status "Preparing upload…" | +| Upload URL received | 5% | Bar jumps to 5% | +| XHR progress events | 5% → 90% (linear from XHR `loaded/total`) | Bar animates smoothly | +| Confirm call in flight | 92% | Bar at 92%, status "Processing…" | +| Confirm returned 200 | 100% | Bar fills green, status "Done — classifying…" | + +The 5%–90% range is reserved for the XHR PUT. The remaining 10% (90%–100%) covers confirm + classification enqueue. This prevents the bar appearing "stuck" at 100% waiting for the confirm call. + +### CORS and MinIO PUT + +The browser PUTs directly to MinIO over a presigned URL (cross-origin). This is transparent to the user. If the PUT fails due to a network error or CORS rejection, treat it as a generic upload error (see Error States). Do not surface "CORS" in any user-facing copy. + +--- + +## Quota Usage Bar — Sidebar Contract + +### Placement in AppSidebar.vue + +Insert the quota bar between the topics nav section (`.flex-1 nav`) and the bottom settings/admin/identity footer (`.px-3.py-4.border-t`). + +``` +[ Topics nav section ] +[ ────────────────────── ] ← existing border-t border-gray-100 +[ Quota bar widget ] ← NEW: Phase 3 +[ ────────────────────── ] ← existing border-t border-gray-100 +[ Admin / Settings / Footer ] +``` + +### Quota Bar Widget Structure + +```html +
+ +
+ Storage + X MB of Y MB +
+ +
+
+
+
+``` + +Label format: `"{used} MB of {limit} MB"` — values rounded to 1 decimal place (e.g., "12.3 MB of 100.0 MB"). Do not show bytes or KB — always MB with 1 decimal place. + +### Loading and Error States + +| State | Display | +|-------|---------| +| Loading (initial fetch) | Skeleton bar: `bg-gray-100 animate-pulse h-2 rounded-full w-full` — no label text | +| Fetch error | Hide widget entirely — fail silently (consistent with AdminQuotasTab pattern of filtering failed quota fetches silently) | +| `used_bytes = 0` | Show bar at 0% with label "0.0 MB of Y MB" — do not hide the widget | + +### Data Source + +Fetches from `GET /api/me/quota` on sidebar mount. Re-fetches after every successful document upload (confirm step returns 200) and after every document delete. No polling. + +Store: quota state lives in `useAuthStore` as `quota: { used_bytes, limit_bytes }` — updated by the documents store after upload/delete. Do not create a separate quota store. + +--- + +## Error States + +### Upload Error Types + +| HTTP status | Trigger | User-facing copy | +|------------|---------|-----------------| +| 401 | Access token expired mid-upload | Dismiss upload row, show session-expired toast (Phase 2 contract), redirect to `/login` | +| 413 | Quota exceeded at confirm step | Show quota rejection error block (see below) | +| Network error (XHR fail, CORS) | MinIO unreachable or CORS misconfiguration | "Upload failed. Please try again." — row error state | +| 500 | Server error on upload-url or confirm | "Something went wrong. Please try again." — row error state | +| Other 4xx | Unexpected API error | "Upload failed. Please try again." — row error state | + +### Quota Rejection Error Block (413) + +Displayed inline within the upload progress row, replacing the progress bar and status line. NOT a toast — inline only. + +``` +[ filename.pdf (error icon red) ] +[ ┌─────────────────────────────────────────────────────┐ ] +[ │ Not enough storage │ ] +[ │ This file (X MB) would exceed your quota. │ ] +[ │ You're using Y MB of Z MB. │ ] +[ │ Manage storage → │ ] +[ └─────────────────────────────────────────────────────┘ ] +``` + +Error block styles: +- Container: `mt-1 p-3 rounded-lg bg-red-50 border border-red-200` +- Heading: `text-sm font-semibold text-red-700` +- Body lines: `text-xs text-red-600 mt-0.5` +- Link: `text-xs text-red-600 underline hover:text-red-700 font-semibold` — navigates to `/settings` (the existing settings route; storage settings live there in Phase 3 since the dedicated storage page is Phase 4) + +Values populated from 413 response body: `{"detail": {"used_bytes": N, "limit_bytes": M, "rejected_bytes": K}}`. +- "This file (X MB)" — `rejected_bytes` converted to MB, 1 decimal place +- "You're using Y MB of Z MB" — `used_bytes` / `limit_bytes` converted to MB, 1 decimal place + +### 401 During Upload + +When a 401 occurs at any upload step: +1. Mark the upload row as failed with copy "Session expired. Signing you in again…" +2. Fire the session-expired toast (Phase 2 contract: `bg-gray-900 text-white text-sm px-4 py-3 rounded-lg shadow-lg`, 5s auto-dismiss) +3. Redirect to `/login` after 1.5s (gives user time to read the row message) +4. Do NOT retry the upload automatically — the user must sign in and re-upload + +--- + +## Loading States (Phase 3 Additions) + +Extends Phase 2 loading state contract. + +| Action | Loading indicator | Element state | +|--------|------------------|---------------| +| Upload step 1 (get URL) | Spinner in row icon slot, progress bar at 0% | Row status "Preparing upload…" | +| Upload step 2 (XHR PUT) | Progress bar advancing, spinner removed | Row status "Uploading…" | +| Upload step 3 (confirm) | Progress bar at 92%, spinner in row icon slot resumes | Row status "Processing…" | +| Quota bar initial load | Skeleton pulse bar | No label text | +| Quota refetch after upload | Silent — bar updates on next successful fetch; no spinner shown in sidebar | + +Spinner reuse: `AppSpinner.vue` from Phase 2 — `animate-spin rounded-full border-2 border-current border-t-transparent` inheriting color. + +--- + +## Copywriting Contract + +Phase 2 copy contract is fully inherited. Phase 3 additions only. + +| Element | Copy | +|---------|------| +| Upload step: preparing | "Preparing upload…" | +| Upload step: uploading | "Uploading…" | +| Upload step: processing | "Processing…" | +| Upload step: complete | "Done — classifying…" | +| Upload step: classified | "Done — classified as: {topics}" (matches existing UploadProgress pattern) | +| Upload step: no topics | "Done — no topics assigned" (matches existing UploadProgress pattern) | +| Upload generic error | "Upload failed. Please try again." | +| Upload 401 error | "Session expired. Signing you in again…" | +| Upload quota rejection heading | "Not enough storage" | +| Upload quota rejection body line 1 | "This file ({X} MB) would exceed your quota." | +| Upload quota rejection body line 2 | "You're using {Y} MB of {Z} MB." | +| Upload quota rejection link | "Manage storage →" | +| Quota bar label | "Storage" | +| Quota bar usage display | "{used} MB of {limit} MB" | +| Quota bar loading (aria) | `aria-label="Loading storage usage"` on skeleton element | +| Empty document list | Heading: "No documents yet" / Body: "Upload a file to get started." | +| Document list loading error | "Failed to load documents. Please refresh." | + +### Security Copy Rules (Inherited) + +- Never confirm or deny whether an email exists +- Generic error messages must not echo PII +- Quota messages display bytes only from the server-authoritative 413 response body — never from client-side file size alone + +--- + +## Component Inventory (New or Modified — Phase 3) + +| Component | Path | Change Type | Description | +|-----------|------|-------------|-------------| +| AppSidebar | `src/components/layout/AppSidebar.vue` | Modified | Add QuotaBar widget between topics nav and footer section | +| UploadProgress | `src/components/upload/UploadProgress.vue` | Modified | Add progress bar track + fill per row; add step status strings; add quota rejection error block | +| QuotaBar | `src/components/layout/QuotaBar.vue` | New | Standalone quota bar widget — extracted for testability; used inside AppSidebar | +| documents store | `src/stores/documents.js` | Modified | Replace single `upload()` with three-step flow (upload-url → PUT → confirm); add `uploadProgress` reactive map keyed by filename; dispatch quota refetch after upload/delete | + +No new views required. No new layouts required. All Phase 3 UI is additive to existing AppSidebar and UploadProgress components. + +--- + +## Registry Safety + +| Registry | Blocks Used | Safety Gate | +|----------|-------------|-------------| +| shadcn official | none | not applicable — shadcn not installed | +| third-party | none | not applicable | + +No third-party component registries. All components are handwritten Vue 3 SFC with raw Tailwind CSS. + +--- + +## Accessibility + +| Element | Requirement | +|---------|-------------| +| Quota bar | `role="progressbar"` on the fill `
`, `aria-valuenow="{percent}"`, `aria-valuemin="0"`, `aria-valuemax="100"`, `aria-label="Storage usage: {used} MB of {limit} MB"` | +| Upload progress bar | `role="progressbar"` on each row's fill `
`, `aria-valuenow="{percent}"`, `aria-valuemin="0"`, `aria-valuemax="100"`, `aria-label="Upload progress for {filename}"` | +| Quota rejection error | `role="alert"` on the error container so screen readers announce it immediately | +| Quota bar skeleton | `aria-label="Loading storage usage"` + `aria-busy="true"` | + +--- + +## Checker Sign-Off + +- [ ] Dimension 1 Copywriting: PASS +- [ ] Dimension 2 Visuals: PASS +- [ ] Dimension 3 Color: PASS +- [ ] Dimension 4 Typography: PASS +- [ ] Dimension 5 Spacing: PASS +- [ ] Dimension 6 Registry Safety: PASS + +**Approval:** pending