openstack-uicore-foundation 5.0.14 → 5.0.15-beta.2

package/docs/plans/2026-04-23-uploadv3-duplicate-file-max-reached.md

@@ -0,0 +1,109 @@
+# UploadInputV3 Duplicate File / Max Files Reached After Upload Fix Plan
+
+Created: 2026-04-23
+Author: smarcet@gmail.com
+Status: VERIFIED
+Approved: Yes
+Iterations: 0
+Worktree: No
+Type: Bugfix
+
+## Summary
+
+**Symptom:** After uploading a file via UploadInputV3, the component shows "Maximum number of files has been reached" error and displays the file twice — once with the original filename (`image.png`) and once with the server-renamed/hashed filename (`image_e2eed7fb3bc6bd1b16f77beb0f375b82.png`).
+**Trigger:** Upload a single file when `maxFiles=1`. The server renames the file (adds hash). The component fails to clean up the transitional `uploadingFiles` entry because the renamed filename doesn't match.
+**Root Cause:** `src/components/inputs/upload-input-v3/index.js:164` — The `useEffect` cleanup compares `v.filename === f.name` to match completed `uploadingFiles` entries against `value` entries. When the server renames the file, this comparison fails, the stale completed entry persists, and the file appears twice.
+
+**Secondary issue:** `src/components/inputs/dropzone/index.js:156` — Missing `return` after `done('Max files reached.')` causes `done()` to be called a second time (without error), potentially accepting files that should be rejected.
+
+## Investigation
+
+- **V3-specific bug.** V2 does not maintain `uploadingFiles` state — it relies on Dropzone's built-in preview and only renders from the `value` prop. V3 introduced `uploadingFiles` state for custom progress UI, with a `useEffect` that cleans up completed entries when `value` updates. This cleanup fails on server-renamed files.
+- **Flow:** `handleAddedFile` → `handleFileCompleted` (marks `complete:true` with original name) → parent updates `value` (with server-renamed filename) → `useEffect` compares `v.filename === f.name` → mismatch → stale entry persists.
+- **The `accept` callback** at `dropzone/index.js:155-159` has a missing `return` after rejecting with `done('Max files reached.')`, causing a fallthrough to `done()`.
+
+## Behavior Contract
+
+**Given:** UploadInputV3 with `maxFiles=1`, a file is uploaded and the server renames it (response contains a different filename than the original)
+**When:** The parent updates the `value` prop with the server-returned file entry (containing the renamed filename)
+**Currently (bug):** The completed `uploadingFiles` entry (with original name) persists because `v.filename !== f.name`, causing the file to appear twice — once from `uploadingFiles` and once from `value`
+**Expected (fix):** When `value` updates with new entries, all completed `uploadingFiles` entries are removed regardless of filename, since `value` is the source of truth for uploaded files. The file appears exactly once (from `value`).
+**Anti-regression:** Files still uploading (not yet complete) must NOT be removed from `uploadingFiles` when `value` changes. Error file display, progress tracking, and file deletion functionality must remain intact.
+
+## Fix Approach
+
+**Chosen:** Remove all completed entries on value change
+**Why:** The `value` prop is the authoritative source of truth for uploaded files. Once it changes to include new entries, any completed `uploadingFiles` entries are transitional and redundant — they exist only to bridge the visual gap between upload completion and parent state update. Removing all completed entries when `value` has entries is simple, handles server renames, and is semantically correct.
+**Alternatives considered:**
+- *Track server name through upload flow* — precise but complex; requires heuristic matching in `wrappedOnUploadComplete` to find which `uploadingFiles` entry corresponds to the response. Fragile for concurrent uploads.
+- *Fuzzy filename matching* — check if value entry's filename contains the base name; fragile, depends on server naming convention.
+
+**Files:**
+- `src/components/inputs/upload-input-v3/index.js` (primary fix — useEffect cleanup)
+- `src/components/inputs/dropzone/index.js` (secondary fix — missing return)
+- `src/components/inputs/upload-input-v3/__tests__/upload-input-v3.test.js` (reproducing test)
+
+**Strategy:** Change the `useEffect` at line 160-166 to remove all completed entries from `uploadingFiles` when `value` has entries, instead of matching by exact filename. Add missing `return` after `done('Max files reached.')` in the `accept` callback.
+
+**Tests:** Add test to `upload-input-v3.test.js` that simulates: file added → file completed → value updated with different filename → verify only one file entry visible (from value, not from uploadingFiles).
+
+## Verification Scenario
+
+### TS-001: Server-Renamed File Upload
+**Preconditions:** UploadInputV3 with maxFiles=1, server configured to rename uploaded files
+
+| Step | Action | Expected Result (after fix) |
+|------|--------|-----------------------------|
+| 1 | Upload a single file via UploadInputV3 | File appears as "Loading" then "Complete" |
+| 2 | Parent updates value with server-renamed file | File appears exactly once (from value), no duplicate entry, no "max files" error |
+
+## Progress
+
+- [x] Task 1: Write Reproducing Test (RED)
+- [x] Task 2: Implement Fix at Root Cause
+- [x] Task 3: Quality Gate
+      **Tasks:** 3 | **Done:** 3
+
+## Tasks
+
+### Task 1: Write Reproducing Test (RED)
+
+**Objective:** Encode the Behavior Contract as a failing test BEFORE writing any fix code.
+**Files:** `src/components/inputs/upload-input-v3/__tests__/upload-input-v3.test.js`
+**Entry point:** `UploadInputV3` component (rendered with mock DropzoneV3)
+**Test scenario:**
+1. Render UploadInputV3 with `maxFiles=1` and `value=[]`
+2. Simulate `onAddedFile({ name: 'image.png', size: 75000 })`
+3. Simulate `onFileCompleted({ name: 'image.png', size: 75000 })`
+4. Re-render with `value=[{ filename: 'image_abc123.png', size: 75000 }]` (server-renamed)
+5. Assert: only ONE file entry with text `image_abc123.png` is visible; original `image.png` is NOT visible
+**DoD:** Test exists, named `test('cleans up completed uploading file when value updates with server-renamed filename')`, runs, fails because the stale `image.png` entry persists alongside `image_abc123.png`.
+**Verify:** `npx jest src/components/inputs/upload-input-v3/__tests__/upload-input-v3.test.js --verbose`
+
+### Task 2: Implement Fix at Root Cause
+
+**Objective:** Minimal change to fix the useEffect cleanup and the missing return.
+**Files:**
+- `src/components/inputs/upload-input-v3/index.js` — change useEffect at line 160-166 to remove all completed entries when value has entries
+- `src/components/inputs/dropzone/index.js` — add `return` after `done('Max files reached.')` at line 156
+**Strategy:**
+1. In `upload-input-v3/index.js`, change the useEffect cleanup from:
+   ```javascript
+   setUploadingFiles(prev => prev.filter(f => {
+     if (!f.complete) return true;
+     return !value.some(v => v.filename === f.name);
+   }));
+   ```
+   To:
+   ```javascript
+   setUploadingFiles(prev => prev.filter(f => !f.complete));
+   ```
+2. In `dropzone/index.js`, add `return;` after `done('Max files reached.');` at line 156.
+**DoD:** Reproducing test PASSES. Full test suite PASSES. Diff touches root-cause files.
+**Verify:** `npx jest --verbose`
+
+### Task 3: Quality Gate
+
+**Objective:** Lint + build clean, full suite re-run.
+**DoD:** Full suite green, no lint errors, build succeeds.
+**Verify:** `npx jest --verbose && npm run build-dev`

package/docs/plans/2026-04-23-uploadv3-premature-complete-on-202.md

@@ -0,0 +1,99 @@
+# UploadInputV3 Premature Completion on HTTP 202 Fix Plan
+
+Created: 2026-04-23
+Author: smarcet@gmail.com
+Status: VERIFIED
+Approved: Yes
+Iterations: 0
+Worktree: No
+Type: Bugfix
+
+## Summary
+
+**Symptom:** After uploading a file via UploadInputV3 that triggers HTTP 202 (async server processing), the file immediately shows as "Complete" instead of waiting for polling to confirm the server has finished processing.
+**Trigger:** Upload a file via UploadInputV3. Server returns HTTP 202 with `file_id`. Dropzone's `success` event fires immediately (before polling starts or completes), and V3's `handleFileCompleted` marks the file as `complete: true`.
+**Root Cause:** `src/components/inputs/upload-input-v3/index.js:153` — `handleFileCompleted()` unconditionally marks the file as `complete: true` when Dropzone's `success` event fires, without checking `file._asyncProcessing`. For non-chunked 202 uploads, `_finished()` is called directly by Dropzone (`dropzone.js:2707`), bypassing the `chunksUploaded` override that defers completion for chunked uploads.
+
+**Secondary issue:** `wrappedOnUploadComplete` at line 190 is a passthrough — it doesn't mark uploading files as complete. When polling finishes, `onUploadComplete` fires but the `uploadingFiles` entry isn't cleaned up because `complete` was never set (if the guard blocks `handleFileCompleted`).
+
+## Investigation
+
+- **V3-specific bug.** V2 has zero handling for `success`/`onFileCompleted`/`complete` — it renders only from the `value` prop, which is updated after `onUploadComplete` (correctly waits for polling in the 202 case).
+- **Flow for non-chunked 202:** `xhr.onload` → `file._asyncProcessing = true` → `dropzoneOnLoad(e)` → `_finishedUploading` → `!chunked` → `_finished(files, response, e)` → emits `success` → DropzoneV3 `success` handler → `onFileCompleted` → `handleFileCompleted` marks `complete: true` → file shows "Complete" immediately. Polling starts AFTER `dropzoneOnLoad` returns, but the file already appears done.
+- **Chunking decision:** `file.upload.chunked = options.chunking && (options.forceChunking || file.size > options.chunkSize)`. Config sets `chunking: true` but not `forceChunking` (default `false`), and `chunkSize` defaults to 2MB. Files ≤ 2MB are uploaded as non-chunked, bypassing the `chunksUploaded` override entirely.
+- **`chunksUploaded` override** at `dropzone/index.js:164` correctly defers `done()` for chunked 202 uploads, but is never called for non-chunked uploads.
+- **`wrappedOnUploadComplete`** at `upload-input-v3/index.js:190` just passes through to the parent — it doesn't update `uploadingFiles` state at all.
+
+## Behavior Contract
+
+**Given:** UploadInputV3 with a file upload that returns HTTP 202 (async processing), where `file._asyncProcessing` is set to `true` on the Dropzone file object
+**When:** Dropzone's `success` event fires (immediately after `_finishedUploading` calls `_finished` for non-chunked uploads, or via `chunksUploaded` for chunked uploads)
+**Currently (bug):** `handleFileCompleted` marks the file as `complete: true` immediately, showing "Complete" in the UI before polling confirms server processing is done
+**Expected (fix):** When `file._asyncProcessing` is true, `handleFileCompleted` does NOT mark the file as complete. The file stays in "Loading" state. When polling finishes and `onUploadComplete` fires (via `wrappedOnUploadComplete`), uploading files are marked complete, enabling the existing useEffect cleanup to remove them when `value` updates.
+**Anti-regression:** Synchronous uploads (HTTP 200) must still mark files as "Complete" immediately via `handleFileCompleted`. File deletion, error display, progress tracking, and the existing server-renamed-filename cleanup must remain intact.
+
+## Fix Approach
+
+**Chosen:** Guard in V3 handlers
+**Why:** The `_asyncProcessing` flag is already set on the Dropzone file object before `success` fires. V3 just needs to check it in `handleFileCompleted` and mark files complete in `wrappedOnUploadComplete`. No changes to DropzoneJS or DropzoneV3 — purely V3 state management.
+**Alternatives considered:**
+- *Guard in DropzoneV3 success handler* — would work but touches the shared wrapper file used by all upload versions, increasing regression surface.
+- *Override _finishedUploading in DropzoneJS* — fixes at the Dropzone level but patches library internals, fragile across Dropzone upgrades.
+
+**Files:**
+- `src/components/inputs/upload-input-v3/index.js` (primary fix — handleFileCompleted guard + wrappedOnUploadComplete)
+- `src/components/inputs/upload-input-v3/__tests__/upload-input-v3.test.js` (reproducing test)
+
+**Strategy:**
+1. In `handleFileCompleted`: check `file._asyncProcessing` — if true, return early (don't mark complete)
+2. In `wrappedOnUploadComplete`: before calling the parent callback, mark all uploading files as `complete: true` via `setUploadingFiles`. This ensures cleanup works for both sync (where `handleFileCompleted` already set it) and async (where it was skipped).
+
+**Tests:** Add test to `upload-input-v3.test.js` that simulates: file added → file completed with `_asyncProcessing: true` → verify file still shows "Loading" (not "Complete").
+
+## Verification Scenario
+
+### TS-001: Async Upload Processing State
+**Preconditions:** UploadInputV3 with `maxFiles=1`, server configured to return HTTP 202 for uploads
+
+| Step | Action | Expected Result (after fix) |
+|------|--------|-----------------------------|
+| 1 | Upload a file that triggers HTTP 202 async processing | File shows "Loading" with progress bar, NOT "Complete" |
+| 2 | Wait for polling to return `status: 'complete'` and parent to update value | File transitions to "Complete" (from value section), no duplicate entries |
+
+## Progress
+
+- [x] Task 1: Write Reproducing Test (RED)
+- [x] Task 2: Implement Fix at Root Cause
+- [x] Task 3: Quality Gate
+      **Tasks:** 3 | **Done:** 3
+
+## Tasks
+
+### Task 1: Write Reproducing Test (RED)
+
+**Objective:** Encode the Behavior Contract as a failing test BEFORE writing any fix code.
+**Files:** `src/components/inputs/upload-input-v3/__tests__/upload-input-v3.test.js`
+**Entry point:** `UploadInputV3` component (rendered with mock DropzoneV3)
+**Test scenario:**
+1. Render UploadInputV3 with `maxFiles=1` and `value=[]`
+2. Simulate `onAddedFile({ name: 'video.mp4', size: 5000000 })`
+3. Simulate `onFileCompleted({ name: 'video.mp4', size: 5000000, _asyncProcessing: true })`
+4. Assert: file still shows "Loading" (not "Complete") — the `_asyncProcessing` flag should prevent marking as complete
+**DoD:** Test exists, named `test('does not mark file as complete when _asyncProcessing is true')`, runs, fails because `handleFileCompleted` currently ignores `_asyncProcessing` and marks complete unconditionally.
+**Verify:** `npx jest src/components/inputs/upload-input-v3/__tests__/upload-input-v3.test.js --verbose`
+
+### Task 2: Implement Fix at Root Cause
+
+**Objective:** Minimal change to `handleFileCompleted` and `wrappedOnUploadComplete` to prevent premature completion on HTTP 202.
+**Files:** `src/components/inputs/upload-input-v3/index.js`
+**Strategy:**
+1. In `handleFileCompleted` (line 153): add early return when `file._asyncProcessing` is true
+2. In `wrappedOnUploadComplete` (line 190): add `setUploadingFiles(prev => prev.map(f => ({ ...f, complete: true })))` before calling the parent callback, so all uploading files are marked complete when the server confirms processing is done
+**DoD:** Reproducing test PASSES. Full test suite PASSES. Diff touches root-cause file only.
+**Verify:** `npx jest --verbose`
+
+### Task 3: Quality Gate
+
+**Objective:** Full suite re-run, build clean.
+**DoD:** Full suite green, build succeeds, no performance regressions.
+**Verify:** `npx jest --verbose && npm run build-dev`