openstack-uicore-foundation 5.0.17-beta.3 → 5.0.17

package/.claude/rules/openstack-uicore-foundation-components.md

@@ -0,0 +1,62 @@
+# Component Patterns
+
+## Upload Components (3 generations)
+
+| Version | Location | Rendering | Use Case |
+|---------|----------|-----------|----------|
+| V1 | `inputs/upload-input/` | Legacy, basic file list | Simple single-file uploads |
+| V2 | `inputs/upload-input-v2/` | Custom React UI | Multi-file with progress |
+| V3 | `inputs/upload-input-v3/` | MUI-based UI | Chunked uploads, async processing |
+
+**All versions wrap `inputs/dropzone/index.js`** (DropzoneJS class) or `dropzone-v3.js` (DropzoneV3 wrapper). The underlying Dropzone library is `dropzone@5.7.2`.
+
+### Chunked Upload Architecture
+
+- `DropzoneJS` manages a chunk queue with `maxConcurrentChunks` (default: 6)
+- `setupChunkThrottle()` wraps Dropzone's `_uploadData` to enforce concurrency
+- Progress tracking uses `_completedBytes` floor to prevent oscillation during parallel chunk uploads
+- `options.uploadprogress` override in `getDjsConfig()` centralizes progress correction (guards against `NaN` bytesSent from queued chunks)
+- HTTP 202 responses trigger async polling via `_asyncProcessing` flag
+
+### Upload Gotchas
+
+- **Progress oscillation:** Dropzone creates chunk entries with `progress:0` and `bytesSent:undefined` upfront. Raw progress average across chunks causes backsliding — always apply `_completedBytes` floor.
+- **Cancel cleanup:** `xhr.abort()` fires `onabort`, not `onload`/`onerror`. Cancelled files must be filtered from `chunkQueue` and `chunksInFlight` decremented in `removedfile` handler.
+- **NaN guard:** `Math.max(bytesSent || 0, ...)` — bytesSent can be `undefined` for queued chunks.
+
+## MUI Components
+
+- Located in `src/components/mui/`
+- Follow pattern: component in `index.js`, styles in `.module.less` or `.module.scss`
+- Formik integration components in `mui/formik-inputs/` — prefix `mui-formik-*`
+- All MUI components use MUI v6 APIs
+
+## Redux Pattern
+
+```javascript
+// Action creator factory
+export const createAction = type => payload => ({ type, payload });
+
+// Async thunk pattern
+export const myAction = (params) => async (dispatch, getState) => {
+    dispatch(startLoading());
+    return getRequest(
+        createAction(REQUEST_TYPE),
+        createAction(RECEIVE_TYPE),
+        buildAPIBaseUrl('/api/v1/endpoint'),
+        authErrorHandler
+    )(params)(dispatch, getState);
+};
+```
+
+- Actions: constants + thunks in same file
+- Reducers: switch/case on action types
+- State shape: `loggedUserState` for auth, domain-specific reducers in consumers
+
+## Testing Conventions
+
+- Test files: `__tests__/` directories adjacent to components
+- Framework: Jest + @testing-library/react
+- Mock pattern: `jest.mock('module')` at top of file
+- Component tests render with `@testing-library/react`, assert on DOM
+- Dropzone tests mock the Dropzone constructor to capture options and simulate events

package/.claude/rules/openstack-uicore-foundation-project.md

@@ -0,0 +1,64 @@
+# Project: openstack-uicore-foundation
+
+**Last Updated:** 2026-04-23
+
+## Overview
+
+Shared React component library for OpenStack marketing sites and summit management apps. Published as an npm package — consumers import from `lib/`.
+
+## Technology Stack
+
+- **Language:** JavaScript (ES6+, Babel-transpiled)
+- **UI:** React 17, MUI 6, Formik, React-Redux 5, Redux 3
+- **HTTP:** superagent
+- **Auth:** OAuth2 PKCE + OIDC (idtoken-verifier, browser-tabs-lock)
+- **Build:** Webpack 5, Babel 7 (babel.config.json)
+- **Test:** Jest 28, @testing-library/react 12, jsdom
+- **Styles:** LESS, SCSS, CSS Modules
+- **Node:** 18.15.0 (.nvmrc)
+- **Indentation:** 4 spaces (all file types — .editorconfig)
+
+## Directory Structure
+
+```
+src/
+├── components/
+│   ├── inputs/          # Form inputs (dropzone, upload V1/V2/V3, text, dropdown, etc.)
+│   ├── mui/             # MUI-based components (formik-inputs/, tables, dialogs, etc.)
+│   ├── security/        # OAuth/PKCE auth, session management, reducers
+│   ├── forms/           # SimpleForm, RsvpForm
+│   ├── sections/        # Panel
+│   ├── index.js         # Barrel re-exports for all components
+│   └── ...              # Individual components (clock, video-stream, etc.)
+├── models/              # Data models (summit-event)
+├── utils/               # Actions, reducers, methods, constants, crypto, money
+└── i18n/                # en.json, es.json, zh.json
+lib/                     # Built output (gitignored, npm-published)
+```
+
+## Key Files
+
+- **Entry/Exports:** `src/components/index.js` — barrel file with all public exports
+- **Webpack entries:** `webpack.common.js` — individual entry points per component (no single bundle)
+- **Auth core:** `src/components/security/methods.js` — OAuth PKCE, token refresh, session management
+- **API utils:** `src/utils/actions.js` — HTTP request helpers, error handlers, Redux action creators
+- **Constants:** `src/utils/constants.js` — shared numeric/string constants
+
+## Development Commands
+
+| Task | Command |
+|------|---------|
+| Install | `yarn install` |
+| Build (dev) | `yarn build-dev` |
+| Build (prod) | `yarn build` |
+| Test | `jest` (or `npx jest`) |
+| Clean rebuild | `yarn clean` |
+
+## Architecture Notes
+
+- **Multi-entry Webpack build:** Each component is a separate webpack entry point — consumers can import individual components without pulling the full bundle.
+- **Peer dependencies model:** React, MUI, Redux, and most libs are peer deps — consumers provide them.
+- **Redux pattern:** `createAction(TYPE)` factory → thunk actions → `getRequest`/`putRequest`/`postRequest`/`deleteRequest` helpers in `utils/actions.js`. Error handling via `authErrorHandler` with auto-redirect on 401.
+- **i18n:** `i18n-react` with JSON locale files. Language detected from browser, fallback to English.
+- **No barrel imports from `lib/`:** Components are imported directly from their paths (e.g., `openstack-uicore-foundation/lib/components/inputs/upload-input-v3`).
+- **Commented-out exports** in `src/components/index.js` are components with heavy 3rd-party deps (Stripe, react-beautiful-dnd) — imported separately by consumers.

package/.claude/rules/openstack-uicore-foundation-security.md

@@ -0,0 +1,39 @@
+# Security & Auth Conventions
+
+## OAuth2 PKCE Flow
+
+Auth lives in `src/components/security/`. The library implements OAuth2 Authorization Code + PKCE against an OpenStack IDP.
+
+### Key Modules
+
+| File | Purpose |
+|------|---------|
+| `methods.js` | Core auth: `doLogin`, `initLogOut`, `getAccessToken`, `storeAuthInfo`, token refresh with mutex (SuperTokensLock) |
+| `actions.js` | Redux actions: `onUserAuth`, `getUserInfo`, `doLogout` |
+| `reducers.js` | Auth state: `loggedUserState` with `member`, `sessionState` |
+| `constants.js` | Error code constants (`AUTH_ERROR_*`) |
+| `abstract-auth-callback-route.js` | Route component for OAuth callback handling (v1) |
+| `abstract-auth-callback-route-v2.js` | OAuth callback with PKCE verifier exchange (v2) |
+| `session-checker/op-session-checker.js` | Session iframe checker for silent re-auth |
+
+### Token Management
+
+- Access tokens stored via `storeAuthInfo()` in localStorage
+- Refresh uses `SuperTokensLock` (browser-tabs-lock) for cross-tab mutex
+- ID token validated with `idtoken-verifier`
+- PKCE: SHA256 code challenge via `src/utils/crypto.js` (`getSHA256`, `getRandomBytes`)
+
+### Auth Error Handling
+
+`authErrorHandler` in `utils/actions.js` handles HTTP errors:
+- **401:** Triggers `initLogin()` → redirects to IDP (with session-clearing guard to prevent loops)
+- **403:** Shows "not authorized" message
+- **412:** Shows server-provided validation errors
+- **Other:** Generic error with optional `res.body.message`
+
+### Conventions
+
+- Auth methods imported from `security/methods` — never call IDP directly
+- Access token passed as query param `access_token` (not Bearer header) in `getRequest`/`putRequest` helpers
+- `getAllowedUserGroups()` reads from env/config to restrict access by group membership
+- Consumer apps must provide `loggedUserState` in their Redux store

package/.codegraph/config.json

@@ -0,0 +1,140 @@
+{
+  "version": 1,
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.jsx",
+    "**/*.py",
+    "**/*.go",
+    "**/*.rs",
+    "**/*.java",
+    "**/*.c",
+    "**/*.h",
+    "**/*.cpp",
+    "**/*.hpp",
+    "**/*.cc",
+    "**/*.cxx",
+    "**/*.cs",
+    "**/*.php",
+    "**/*.rb",
+    "**/*.swift",
+    "**/*.kt",
+    "**/*.kts",
+    "**/*.dart",
+    "**/*.svelte",
+    "**/*.liquid",
+    "**/*.pas",
+    "**/*.dpr",
+    "**/*.dpk",
+    "**/*.lpr",
+    "**/*.dfm",
+    "**/*.fmx"
+  ],
+  "exclude": [
+    "**/.git/**",
+    "**/node_modules/**",
+    "**/vendor/**",
+    "**/Pods/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/out/**",
+    "**/bin/**",
+    "**/obj/**",
+    "**/target/**",
+    "**/*.min.js",
+    "**/*.bundle.js",
+    "**/.next/**",
+    "**/.nuxt/**",
+    "**/.svelte-kit/**",
+    "**/.output/**",
+    "**/.turbo/**",
+    "**/.cache/**",
+    "**/.parcel-cache/**",
+    "**/.vite/**",
+    "**/.astro/**",
+    "**/.docusaurus/**",
+    "**/.gatsby/**",
+    "**/.webpack/**",
+    "**/.nx/**",
+    "**/.yarn/cache/**",
+    "**/.pnpm-store/**",
+    "**/storybook-static/**",
+    "**/.expo/**",
+    "**/web-build/**",
+    "**/ios/Pods/**",
+    "**/ios/build/**",
+    "**/android/build/**",
+    "**/android/.gradle/**",
+    "**/__pycache__/**",
+    "**/.venv/**",
+    "**/venv/**",
+    "**/site-packages/**",
+    "**/dist-packages/**",
+    "**/.pytest_cache/**",
+    "**/.mypy_cache/**",
+    "**/.ruff_cache/**",
+    "**/.tox/**",
+    "**/.nox/**",
+    "**/*.egg-info/**",
+    "**/.eggs/**",
+    "**/go/pkg/mod/**",
+    "**/target/debug/**",
+    "**/target/release/**",
+    "**/.gradle/**",
+    "**/.m2/**",
+    "**/generated-sources/**",
+    "**/.kotlin/**",
+    "**/.dart_tool/**",
+    "**/.vs/**",
+    "**/.nuget/**",
+    "**/artifacts/**",
+    "**/publish/**",
+    "**/cmake-build-*/**",
+    "**/CMakeFiles/**",
+    "**/bazel-*/**",
+    "**/vcpkg_installed/**",
+    "**/.conan/**",
+    "**/Debug/**",
+    "**/Release/**",
+    "**/x64/**",
+    "**/release/**",
+    "**/*.app/**",
+    "**/*.asar",
+    "**/DerivedData/**",
+    "**/.build/**",
+    "**/.swiftpm/**",
+    "**/xcuserdata/**",
+    "**/Carthage/Build/**",
+    "**/SourcePackages/**",
+    "**/__history/**",
+    "**/__recovery/**",
+    "**/*.dcu",
+    "**/.composer/**",
+    "**/storage/framework/**",
+    "**/bootstrap/cache/**",
+    "**/.bundle/**",
+    "**/tmp/cache/**",
+    "**/public/assets/**",
+    "**/public/packs/**",
+    "**/.yardoc/**",
+    "**/coverage/**",
+    "**/htmlcov/**",
+    "**/.nyc_output/**",
+    "**/test-results/**",
+    "**/.coverage/**",
+    "**/.idea/**",
+    "**/logs/**",
+    "**/tmp/**",
+    "**/temp/**",
+    "**/_build/**",
+    "**/docs/_build/**",
+    "**/site/**"
+  ],
+  "languages": [],
+  "frameworks": [],
+  "maxFileSize": 1048576,
+  "extractDocstrings": true,
+  "trackCallSites": true,
+  "enableEmbeddings": true
+}

package/docs/plans/2026-04-09-showconfirmdialog-react16-compat.md

@@ -0,0 +1,83 @@
+# showConfirmDialog React 16 Compatibility Fix Plan
+
+Created: 2026-04-09
+Author: smarcet@gmail.com
+Status: VERIFIED
+Approved: Yes
+Iterations: 0
+Worktree: No
+Type: Bugfix
+
+## Summary
+
+**Symptom:** `showConfirmDialog` causes "Module not found: Error: Can't resolve 'react-dom/client'" build error on React 16 projects, despite a `/* webpackIgnore: true */` dynamic import guard.
+
+**Trigger:** Any consuming project on React 16 that bundles `openstack-uicore-foundation` hits the error during webpack build.
+
+**Root Cause:** `src/components/mui/showConfirmDialog.js:27` — The `import(/* webpackIgnore: true */ "react-dom/client")` compiles into the UMD output as a bare `import("react-dom/client")` (the magic comment is stripped during this library's build). When a consuming project's webpack processes the compiled bundle, it encounters the bare dynamic import, tries to resolve `react-dom/client`, and fails because React 16 has no such module path.
+
+## Investigation
+
+- **Evolution:** Original code (cd39cf3) used only `ReactDOM.render()`. PR #214 (094c6b9) added `require("react-dom/client")` in try/catch for React 18+ support — caused the same build error. Commit 6c95b33 replaced `require()` with `import(/* webpackIgnore: true */ ...)` — the magic comment works for THIS library's webpack but is stripped from the compiled UMD output.
+- **Confirmed in built output:** `lib/components/mui/show-confirm-dialog.js` contains literal `await import("react-dom/client")` with no webpack annotation — any consuming webpack resolves it at build time.
+- **Key insight:** The `webpackIgnore` comment is a build-time directive that only affects the webpack instance that processes the source file. It does not survive into the output and cannot protect consuming projects.
+- **Internal callers** (5 files: mui-table, mui-table-sortable, mui-table-editable, meta-field-values, additional-input-list) all use `showConfirmDialog` as a plain imperative function — `const isConfirmed = await showConfirmDialog({...})`.
+
+## Fix Approach
+
+**Chosen:** Bridge Pattern + Context Provider
+
+**Why:** Completely eliminates all references to `react-dom/client` from the source and compiled output. The dialog renders inside the existing React tree (managed by whatever React version the app uses), so no version-specific rendering API is needed. Preserves the imperative `showConfirmDialog()` API unchanged.
+
+**Alternatives considered:**
+- *Configuration injection* (`configureConfirmDialog({ createRoot })`) — simpler but less ergonomic; consumer must handle version detection and import themselves.
+- *Remove createRoot entirely* (pure `ReactDOM.render`) — works on 16/17/18 but breaks React 19 where `ReactDOM.render` was removed.
+
+**How it works:**
+1. A new `ConfirmDialogProvider` component manages dialog state (open/closed, options, resolve callback) and renders `ConfirmDialog` within the existing React tree.
+2. On mount, the provider registers a "bridge" callback in a module-level variable inside `showConfirmDialog.js`.
+3. When `showConfirmDialog()` is called, it delegates to the bridge if registered. If no provider is mounted, it falls back to `ReactDOM.render()` with a console warning (backward compat for React 16/17/18 consumers who haven't added the provider yet).
+4. Zero references to `react-dom/client` remain in the codebase.
+
+**Files:**
+- `src/components/mui/showConfirmDialog.js` — Add bridge registration, fallback logic
+- `src/components/mui/ConfirmDialogProvider.js` — NEW: Provider component
+- `src/components/index.js` — Export the new provider
+- `webpack.common.js` — Add entry point for the new provider
+
+**Tests:**
+- `src/components/mui/__tests__/show-confirm-dialog.test.js` — Update for bridge-based flow
+- `src/components/mui/__tests__/confirm-dialog-provider.test.js` — NEW: Provider tests
+
+**Defense-in-depth:** Not applicable — this is a build-time resolution error, not a data flow issue.
+
+## Progress
+
+- [x] Task 1: Implement bridge pattern + provider
+- [x] Task 2: Verify
+      **Tasks:** 2 | **Done:** 2
+
+## Tasks
+
+### Task 1: Implement bridge pattern + provider
+
+**Objective:** Replace the `react-dom/client` dynamic import with a bridge pattern. Create `ConfirmDialogProvider`, modify `showConfirmDialog` to use bridge with ReactDOM.render fallback, export the new provider.
+
+**Files:**
+- `src/components/mui/showConfirmDialog.js` — Remove `getCreateRoot()`, add bridge registration exports (`_registerBridge`, `_unregisterBridge`). When bridge is registered, delegate. When not, fall back to `ReactDOM.render()` with `console.warn` suggesting provider migration.
+- `src/components/mui/ConfirmDialogProvider.js` — NEW: Functional component using `useState` + `useEffect`. On mount, registers bridge via `_registerBridge`. Bridge callback sets dialog state and returns a Promise. Renders `<ConfirmDialog>` when dialog state is active. On unmount, calls `_unregisterBridge`.
+- `src/components/index.js` — Add export: `export { default as ConfirmDialogProvider } from './mui/ConfirmDialogProvider'`
+- `webpack.common.js` — Add entry: `'components/mui/confirm-dialog-provider': './src/components/mui/ConfirmDialogProvider.js'`
+
+**TDD:**
+1. Write regression test: import `showConfirmDialog` without mocking `react-dom/client` — verify no reference to `react-dom/client` exists in the module
+2. Write provider test: render `ConfirmDialogProvider`, call `showConfirmDialog`, verify dialog appears and resolves correctly
+3. Write fallback test: call `showConfirmDialog` without provider mounted — verify `ReactDOM.render` is called with console warning
+4. Verify all existing tests still pass (callers mock `showConfirmDialog` so they are unaffected)
+
+**Verify:** `npx jest --no-cache`
+
+### Task 2: Verify
+
+**Objective:** Full test suite passes, no regressions across all components that use `showConfirmDialog`.
+**Verify:** `npx jest --no-cache && grep -r "react-dom/client" src/ && echo "FAIL: react-dom/client still referenced" || echo "PASS: no react-dom/client references"`

package/docs/plans/2026-04-22-dropzone-pooling-ux.md

@@ -0,0 +1,129 @@
+# Dropzone Polling UX Fix Plan
+
+Created: 2026-04-22
+Author: smarcet@gmail.com
+Status: VERIFIED
+Approved: Yes
+Iterations: 2
+Worktree: No
+Type: Bugfix
+
+## Summary
+
+**Symptom:** After the last chunk is uploaded and the server returns HTTP 202 (async processing), both UploadInputV2 and UploadInputV3 immediately show the file as "Complete" / "success" — even though server-side processing hasn't finished and polling has just started.
+**Trigger:** Upload a file where the server returns HTTP 202 on the last chunk (async processing path). The file appears fully uploaded while `pollUploadStatus` is still polling in the background.
+**Root Cause:** `src/components/inputs/dropzone/index.js:313` — In the `sending` handler's custom `xhr.onload`, `dropzoneOnLoad(e)` is called unconditionally before checking the HTTP status code. For the 202 path, Dropzone.js processes the response through `_finishedUploading` → `finishedChunkUpload` → `chunksUploaded(file, done)` → `done()` → `_finished` → emits `success` event. This makes both V2 (Dropzone's default UI) and V3 (DropzoneV3 → UploadInputV3) mark the file as complete prematurely.
+
+## Investigation
+
+- Dropzone.js v5.7.2 has a `chunksUploaded(file, done)` option (line 563 in dist/dropzone.js). It's called when all chunks have been uploaded successfully. The default implementation calls `done()` immediately, which triggers `_finished` → `success` event.
+- The `success` event sets `file.status = Dropzone.SUCCESS` and updates the file preview in V2's default template. In V3, DropzoneV3 maps `success` → `onFileCompleted` → UploadInputV3 sets `{complete: true}` → shows "Complete" with green check.
+- The polling code (`pollUploadStatus`) was added in commit `6bad1f7` but didn't account for the fact that Dropzone.js fires `success` on any 2xx response for the final chunk.
+- The `sending` event fires for EVERY chunk. The `xhr.onload` override is per-chunk. For intermediate chunks (200 without `name` field), Dropzone tracks chunk completion. Only when the last chunk response arrives does `finishedChunkUpload` trigger `chunksUploaded`.
+
+## Behavior Contract
+
+**Given:** A file is being uploaded in chunks and the server returns HTTP 202 on the last chunk (indicating async server-side processing is needed)
+**When:** The last chunk's XHR response is received and processed
+**Currently (bug):** Dropzone.js immediately fires the `success` event, causing both V2 and V3 UIs to show the file as "Complete" / "success" while polling is still running
+**Expected (fix):** The `success` event should NOT fire until polling confirms server-side processing is complete (`data.status === 'complete'`). During the polling phase, the file should remain in its uploading/in-progress visual state.
+**Anti-regression:** HTTP 200 uploads (synchronous path where the response contains `name` field) must continue to fire `success` immediately as before. Component unmount cleanup must still clear polling intervals. Error handling during polling must still work.
+
+## Fix Approach
+
+**Chosen:** Defer `chunksUploaded` done callback for 202 responses
+**Why:** Uses Dropzone.js's public `chunksUploaded` option to control when `_finished` (and thus `success`) fires. Single-file change in `dropzone/index.js` that fixes the UX for both V2 and V3 consumers. No internal API hacking.
+
+**Alternatives considered:**
+- *Suppress success via internal `_callbacks` manipulation:* Would require accessing Dropzone's private `_callbacks` object — fragile and version-dependent. Rejected.
+- *Add "Processing" state to V3 with new callback:* Better UX (shows "Processing..." text with indeterminate progress) but requires changes across 3 files. Can be done as a follow-up enhancement.
+- *Skip `dropzoneOnLoad` for 202:* Would break Dropzone's internal state (chunk tracking, file counters, queue advancement). Rejected.
+
+**Files:** `src/components/inputs/dropzone/index.js`
+**Strategy:**
+1. In `getDjsConfig()`: Override `chunksUploaded` option with a conditional callback that checks `file._asyncProcessing`. If the flag is set, store the `done` callback on the file object instead of calling it — this prevents `_finished` and the `success` event.
+2. In `sending` handler's `xhr.onload`: Set `file._asyncProcessing = true` BEFORE calling `dropzoneOnLoad(e)` when `xhr.status == 202`. This ensures the `chunksUploaded` callback sees the flag.
+3. In `pollUploadStatus`: Accept the `file` parameter. When polling returns `status: 'complete'`, call the stored `done` callback (`file._chunksUploadedDone()`) to complete the Dropzone lifecycle — this fires `success`, updating both V2 and V3 UIs.
+
+**Tests:** `src/components/inputs/dropzone/__tests__/dropzone.test.js` (new file)
+
+## Verification Scenario
+
+### TS-001: File Upload with 202 Async Processing
+**Preconditions:** App is running, upload endpoint configured to return 202 for async processing
+
+| Step | Action | Expected Result (after fix) |
+|------|--------|-----------------------------|
+| 1 | Upload a file that triggers 202 response | File stays in uploading/progress state — NOT shown as "Complete" — while server processes |
+| 2 | Wait for polling to complete (server returns `status: 'complete'`) | File transitions to "Complete" / success state only now |
+| 3 | Upload a file that triggers 200 response (sync) | File immediately shows "Complete" / success (no regression) |
+
+## 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
+
+**Note:** Build fails with pre-existing PostCSS/SCSS error in schedule-print/styles.module.scss (unrelated to dropzone fix). All 97 tests pass.
+
+**Iteration 1 Fix:** Added polling guard (`file._pollingActive`) to prevent multiple intervals when server returns 202 for every chunk (not just the final one). Without this, each 202 chunk spawned a separate polling loop, causing request flood.
+
+**Iteration 2 Fix:** Fixed request flood (216 HTTP 200 requests for single file) and resource leak on upload cancellation:
+1. **Root cause**: `file._asyncProcessing = true` was being set for EVERY 202 response. Server behavior: intermediate chunks return HTTP 200, final chunk returns HTTP 202 with `file_id`. The original Iteration 1 code set the flag at line 340 (before the `else if(xhr?.status == 202)` check), causing the flag to be set even for 200 responses, which deferred `chunksUploaded` for all uploads.
+2. **Fix**: Move `file._asyncProcessing = true` inside the `else if(xhr?.status == 202)` branch AND guard it with `if (fileId)` check. Now the flag is only set when we receive the final 202 chunk with `file_id`.
+3. **XHR tracking**: Added `this.activeXHRs` Map to track all active XHR requests per file.
+4. **Cancellation support**: Cancel pending XHRs when file is removed or component unmounts, preventing resource waste.
+5. **Chunk throttling**: Added `maxConcurrentChunks` prop (default: 3) to DropzoneJS, V2, and V3. Wraps Dropzone's `_uploadData` with a concurrency-limited queue. When `parallelChunkUploads: true`, only N chunks upload concurrently instead of all at once. Queue drains as chunks complete via `onChunkComplete()` callback in xhr.onload/onerror.
+
+## Tasks
+
+### Task 1: Write Reproducing Test (RED)
+
+**Objective:** Encode the Behavior Contract as a failing test BEFORE writing any fix code. Create test file for DropzoneJS component.
+**Files:** `src/components/inputs/dropzone/__tests__/dropzone.test.js` (new)
+**Entry point:** `DropzoneJS` component — specifically the `chunksUploaded` behavior when HTTP 202 is returned on the last chunk.
+**Test cases:**
+1. `test_dropzone_202_response_should_not_fire_success_immediately` — Simulate a chunked upload where the last chunk returns 202. Verify that the Dropzone `success` event does NOT fire immediately (the `onFileCompleted` callback in the consumer should not be triggered).
+2. `test_dropzone_202_polling_complete_fires_success` — After 202 triggers polling and polling returns `status: 'complete'`, verify that the `success` event fires and `onUploadComplete` is called.
+3. `test_dropzone_200_response_fires_success_immediately` — (Anti-regression) Simulate a synchronous upload where the last chunk returns 200 with `name` field. Verify `success` fires immediately as before.
+**DoD:** Tests exist, run, and FAIL because the current code fires `success` immediately for 202.
+**Verify:** `npx jest src/components/inputs/dropzone/__tests__/dropzone.test.js`
+
+### Task 2: Implement Fix at Root Cause
+
+**Objective:** Minimal change in `dropzone/index.js` that defers the `success` event for 202 responses until polling confirms completion.
+**Files:** `src/components/inputs/dropzone/index.js`
+**Strategy:**
+1. In `getDjsConfig()`, after the `options.accept` assignment, add:
+   ```javascript
+   options.chunksUploaded = (file, done) => {
+       if (file._asyncProcessing) {
+           file._chunksUploadedDone = done;
+           return;
+       }
+       done();
+   };
+   ```
+2. In `setupEvents()` → `sending` handler → `xhr.onload`, add before `dropzoneOnLoad(e)`:
+   ```javascript
+   if (xhr?.status == 202) {
+       file._asyncProcessing = true;
+   }
+   ```
+3. In `pollUploadStatus`, add `file` parameter. When `data.status === 'complete'`:
+   ```javascript
+   if (file?._chunksUploadedDone) {
+       file._chunksUploadedDone();
+   }
+   this.onUploadComplete(data);
+   ```
+4. Update the 202 branch in `xhr.onload` to pass `file` to `pollUploadStatus`.
+**DoD:** Reproducing test PASSES. Full test suite PASSES. Diff touches only `src/components/inputs/dropzone/index.js`.
+**Verify:** `npx jest src/components/inputs/dropzone/__tests__/dropzone.test.js && npx jest`
+
+### Task 3: Quality Gate
+
+**Objective:** Lint + build clean, full suite re-run.
+**DoD:** Lint clean, build green, full suite green. No performance regressions (polling interval unchanged, no new allocations on hot paths).
+**Verify:** `npx jest && npm run build`

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`