openstack-uicore-foundation/docs/plans/clickup-barrel-mui-dragalong.md

ui reactjs components for openstack marketing site

GOAL

Current state: The components barrel (src/components/index.js) exports UploadInputV3 (which imports @mui/material and @mui/icons-material) uncommented, along with 70 additional Mui* components. Any consumer importing from openstack-uicore-foundation/lib/components (the barrel) is forced to resolve @mui/material, @mui/icons-material, @mui/x-date-pickers, spark-md5, dropzone and react-dropzone as installed peerDependencies, even if it uses no MUI component at all. This broke track-chairs build when bumping from 4.2.24 to 4.2.34 (UploadInputV3 was added in 4.2.25), and the same pattern is present on main (v5.x), made worse because the barrel now has 70 uncommented Mui exports (0 in the version right before 4.2.25).

Target state: Consumers that don't use MUI (like track-chairs) can update the library without being forced to install the full MUI + spark-md5 + dropzone stack, following the convention already documented in this repo (No barrel imports from lib/) and the pattern already applied to TextEditorV3, CompanyInputV2, MuiStripePayment, etc. (commented out of the barrel but with a standalone webpack entry).

TASKS

- Audit which of summit-admin's 584 library imports use the barrel (openstack-uicore-foundation/lib/components) vs individual paths, and confirm the 13 barrel imports found don't depend on UploadInputV3/Mui* staying exposed there (summit-admin already uses MUI anyway, low risk for that consumer)
- Comment out the UploadInputV3 export from src/components/index.js, following the exact same pattern already used for TextEditorV3 (move it under the "// these include 3rd party deps" block); keep its standalone webpack entry (webpack.common.js) untouched so direct imports keep working
- Fix the 2 summit-admin files that import UploadInputV3 from the barrel before/alongside the release: src/components/upload-dialog/index.js line 26, and src/pages/companies/components/company-dialog.js line 36 (used at lines 481 and 502) — switch both to import from openstack-uicore-foundation/lib/components/inputs/upload-input-v3 directly
- Update .claude/rules/openstack-uicore-foundation-project.md and the README if the recommended import convention changes
- Communicate the correct import path to consumers (track-chairs, summit-admin, etc.) to avoid the MUI/spark-md5/dropzone drag-along

ACCEPTANCE CRITERIA

- A consumer that only imports non-MUI components from openstack-uicore-foundation/lib/components/(individual path) can run yarn install and build without having @mui/material, @mui/icons-material, @mui/x-date-pickers, spark-md5, dropzone or react-dropzone installed
- The library's webpack build still generates individual entries for each component, including upload-input-v3, without breaking consumers that import it directly (summit-admin)
- The import convention is documented consistently across README, CLAUDE.md and the actual code
- No regression in existing tests (jest) or in the library build (yarn build)

DEVELOPMENT NOTES

Key files:
src/components/index.js, the main barrel, contains the 70 uncommented Mui* exports and the UploadInputV3 export on line 8
webpack.common.js, multi-entry build, check the upload-input-v3 and editor-input-v3 entries as reference for the pattern already in use
src/utils/crypto.js, imports spark-md5 unconditionally, used by dropzone/index.js and by security/methods.js via getSHA256/getRandomBytes even though methods.js never calls getMD5
package.json, @mui/material, @mui/icons-material, @mui/x-date-pickers, spark-md5, dropzone and react-dropzone are in peerDependencies, not dependencies, consistent with the project's peer deps model

Gotchas:
spark-md5 is not new to UploadInputV3, it was added in v4.2.17 (commit f4474fa) via dropzone/index.js for V1/V2. The real regression in 4.2.25 was that UploadInputV3 was the first component to actually reference @mui/material from the barrel (previously declared as a peer dep but not imported by anything reachable from there) and to add @mui/icons-material as a new peer dep
On v5.x main the barrel already has 70 uncommented Mui* exports vs 0 before 4.2.25 (all pre-existing, out of scope here), so commenting out UploadInputV3 removes the spark-md5/icons-material-specific drag-along this ticket targets, but a fully MUI-free consumer importing anything else from the barrel still needs MUI because of those 70 exports — tracked separately if it becomes a problem
summit-admin (5.0.40) already uses MUI extensively, out of 584 imports of the library only 13 use the full barrel (includes UploadInputV3 and MuiFormikUpload), the rest already follow the documented individual-path convention
track-chairs is the consumer that broke on the 4.2.34 bump, its code was not reviewed in this session, the information about its import pattern comes from the user's initial report

Risks:
Risk: removing UploadInputV3 from the barrel is a breaking change for any consumer relying on that barrel import. Confirmed concretely: summit-admin imports UploadInputV3 from the barrel in src/components/upload-dialog/index.js (line 26) and src/pages/companies/components/company-dialog.js (line 36, used at lines 481 and 502) — both break the moment this ships
Mitigation: keep the standalone webpack entry, which already exists, and document the alternative import path before removing it from the barrel, communicating the change in release notes. Land the summit-admin import fix in the same window as the openstack-uicore-foundation release (or before it, since importing from the individual path already works today on 5.0.40) to avoid a broken window

Out of scope:
track-chairs code is not investigated in this session, it is outside this repo
The MUI v9 migration (branch feature/5.x-react-17-x-upgrade, tag v6.0.0-beta.1) is not addressed, it is a separate effort
This session did not modify code, investigation only