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

ui reactjs components for openstack marketing site

# Project: openstack-uicore-foundation

**Last Updated:** 2026-07-30

## 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 7, Redux 3
- **HTTP:** superagent
- **Auth:** OAuth2 PKCE + OIDC (idtoken-verifier, browser-tabs-lock)
- **Build:** Webpack 5, Babel 7 (babel.config.json)
- **Test:** Jest 29, @testing-library/react 12, jsdom
- **Styles:** LESS, SCSS (dart-sass), CSS Modules
- **Node:** 22.22.1 (.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` |

## Versioning

- **`package.json` `version` on feature/PR branches is expected to differ from (including be lower than) `main`.** Branches carry their own independent beta pre-release sequence (e.g. `5.0.37-beta.2`) during development; it is reconciled/bumped to a real release version at merge/publish time, not before.
- **⛔ Do NOT flag "branch version < main version" as a regression or blocking finding in code review** (`/review-pr`, `/review-pr-deep`, `/code-review`, etc.) — this is a known false positive for this repo, confirmed by @smarcet (2026-07-06, reiterated 2026-07-08).

## 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.