# volto-eea-design-system — Agent Notes

## Project Type

- **Volto add-on**, not a standalone app. Entrypoint is `src/index.js`.
- Provides a **Semantic UI theme** (`theme/`) and ~49 React UI components (`src/ui/`).
- Published as `@eeacms/volto-eea-design-system`.
- Depends on `@eeacms/volto-corsproxy`.

## Development Environment

- **Everything runs in Docker.** Do not run `yarn start` or `yarn test` directly on the host.
- Default stack: Plone backend (`eeacms/plone-backend`) + Volto frontend (builder image).
- **Setup:**
  ```bash
  make        # builds images (clean + install)
  make start  # docker compose up; wait for "Volto started at 0.0.0.0:3000"
  ```
- **Volto version override:**
  ```bash
  VOLTO_VERSION=17 make        # for legacy Volto 17
  VOLTO_VERSION=17 make start
  ```
  Default is `18-yarn`.
- **Shell inside frontend container:** `make shell`
- The repo root is volume-mounted into the container at `/app/src/addons/volto-eea-design-system`.

## Testing

- **Unit tests (Jest):** run inside Docker only.
  ```bash
  make test        # run tests
  make test-update # update snapshots (-u)
  ```
  Under the hood: `docker compose run --no-deps -e CI=1 frontend test`.
  - The project uses a custom `jest-addon.config.js` that resolves Volto and EEA addon aliases. Coverage thresholds are intentionally low (5%).
- **E2E tests (Cypress):** require the full Docker stack running on ports 3000 and 8080.
  ```bash
  make          # build
  make start    # start backend + frontend in background or separate terminal
  make cypress-open   # interactive
  make cypress-run    # headless (uses Chromium)
  ```
  - Retries: 2 in run mode, 0 in open mode.
  - Base URL: `http://localhost:3000`.
- **Do not run `yarn test` directly** — it will fail because it expects the Volto monorepo context inside the container.

## Linting & Formatting

Three separate linters; all wrapped in `make`:

```bash
make lint           # ESLint src/**/*.{js,jsx}
make lint-fix       # ESLint --fix
make prettier       # Prettier --check
make prettier-fix   # Prettier --write
make stylelint      # Stylelint src/**/*.{css,less}
make stylelint-overrides  # Stylelint theme/**/*.overrides
make stylelint-fix  # Fixes both src and theme styles
make i18n           # Extract i18n strings (deletes build/messages first)
```

- **Pre-commit hook** (Husky + lint-staged):
  - Staged `src/**/*.{js,jsx,ts,tsx,json}` → `make lint-fix && make prettier-fix`
  - Staged `src/**/*.jsx` → `make i18n`
  - Staged `theme/**/*.{css,less}` / `src/**/*.{css,less}` / `**/*.overrides` → `make stylelint-fix`
- **One-shot fix-all:** `make ci-fix` runs lint-fix, prettier-fix, and stylelint-fix.

## Release Workflow

- **Production releases:** fully automated via Jenkins.
  - Trigger: merge a PR from `develop` → `master`.
  - Jenkins runs tests on both Volto 18-yarn and Volto 17, then releases using the `eeacms/gitflow` image with `release-it`.
  - `master` is protected; direct commits are blocked.
- **Beta releases:** manual from `develop` branch only.
  ```bash
  yarn release-beta        # prepatch / preminor / premajor beta
  yarn release-major-beta  # premajor beta pre-selected
  yarn release             # generic (avoid on master)
  ```
  - Requires `GITHUB_TOKEN` and optionally `.npmrc` with auth token.
  - **Do not keep a `develop` → `master` PR open while doing beta releases.** The auto-release bot will overwrite `CHANGELOG.md` and `package.json` on every commit.
- **Changelog:** auto-generated by `auto-changelog`. Commits containing `[JENKINS]` or `[YARN]` are excluded.

## Architecture Notes

- **Theme system:**
  - `theme/theme.config` maps every Semantic UI component to the `eea` theme.
  - `theme/themes/eea/` contains the actual Less overrides and assets.
  - `theme/theme.less` is the entrypoint for custom EEA variables and utilities.
- **Webpack aliases** (`razzle.extend.js`):
  - `../../theme.config$` → `./theme/theme.config`
  - `eea-volto-themes` → `./theme/themes`
  - `ui-theme` / `ui-assets` → `./theme/themes/eea/...`
- **Add-on wiring:** `src/index.js` exports an `applyConfig` function that mutates the Volto config object (e.g., sets `navDepth: 3`).
- **i18n:** Translations live in `locales/`. Run `make i18n` after adding new translatable strings.
- **Storybook:** Not built from this repo. The `.storybook/` folder only has a `manager.js`. Storybook deployments are handled by the `eea-storybook` repo (triggered via GitHub Actions on pushes to `develop`).
- **Documentation site:** Docusaurus in `website/`; deployed by GitHub Actions on pushes to `develop`.

## CI / Jenkins Quirks

- Jenkins tests run in Docker containers and execute `make` targets inside them.
- On non-master/non-develop branches, Jenkins may skip tests if `eeacms/gitflow /check_if_testing_needed.sh` returns 0.
- Automated code fixes: Jenkins runs `make ci-fix` on feature branches and pushes the result back to the branch if changes are found.
- Coverage reports are published as HTML; unit test results are JUnit XML.
