# Monorepo Structure

This document covers the top-level monorepo layout and the workspace/package map. For the core `handsontable/src/` tree, plugin inventory, and core file layout, see `handsontable/.ai/STRUCTURE.md`.

## Directory Layout

```
handsontable/
├── handsontable/               # Core data grid package (TypeScript)
│   ├── src/                    # Source code (.ts files, including the Walkontable subdirectory)
│   ├── test/                   # Test infrastructure only (helpers, bootstrap, runners, types). Tests themselves live co-located with the modules they cover, in `__tests__/` directories under `src/`.
│   ├── dist/                   # UMD/minified build output
│   ├── tmp/                    # Auto-generated .d.ts + ES/CJS module build output (used by wrappers)
│   ├── styles/                 # Compiled CSS output
│   ├── languages/              # Compiled language files
│   ├── .config/                # Rspack configs (the `.config/` name predates the Webpack→Rspack switch)
│   ├── scripts/                # Build scripts
│   ├── dev.html                # Dev playground (gitignored; manual scratch page)
│   ├── dev-pr.html             # Generated by the `handsontable-demo-page` skill (gitignored; PR repro page using the local build)
│   ├── dev-latest.html         # Generated by the `handsontable-demo-page` skill (gitignored; same scenario against the published release for A/B comparison)
├── wrappers/
│   ├── react-wrapper/          # @handsontable/react-wrapper
│   ├── angular-wrapper/        # @handsontable/angular-wrapper
│   └── vue3/                   # @handsontable/vue3
├── docs/                       # Astro Starlight documentation site (Node 22)
│   └── angular-type-check/     # Internal Angular type-check workspace (docs-angular-type-check)
├── examples/                   # Code examples
├── visual-tests/               # Playwright visual regression tests
├── .changelogs/                # Changelog entry mechanism
├── bin/                        # CLI tools (changelog)
├── scripts/                    # Monorepo-level scripts
├── resources/                  # Shared resources
├── .github/                    # GitHub workflows and CI
├── hot.config.js               # Build environment variables
├── pnpm-workspace.yaml         # pnpm workspace definition
├── package.json                # Root package.json (pnpm 10.30.2)
├── babel.config.js             # Root Babel config
├── .eslintrc.js                # Root ESLint config
├── .eslintignore               # ESLint ignore patterns
├── browser-targets.js          # Supported browser targets
├── .nvmrc                      # Node.js version (22)
└── CHANGELOG.md                # Release changelog
```

## Workspace / package map

The repository is a **pnpm-based monorepo** (root package `handsontable-root`, pnpm 10.30.2). Workspaces are declared in `pnpm-workspace.yaml`:

```
packages:
  - handsontable
  - wrappers/*
  - visual-tests
  - examples
  - docs
  - docs/angular-type-check
```

| Workspace directory | npm name | Purpose |
|---|---|---|
| `handsontable/` | `handsontable` | Core JavaScript/TypeScript data grid library |
| `wrappers/react-wrapper/` | `@handsontable/react-wrapper` | React component wrapper |
| `wrappers/angular-wrapper/` | `@handsontable/angular-wrapper` | Angular component wrapper |
| `wrappers/vue3/` | `@handsontable/vue3` | Vue 3 component wrapper |
| `visual-tests/` | `handsontable-visual-tests` | Playwright/Argos visual regression suite |
| `examples/` | `handsontable-examples-internal` | Code examples for documentation |
| `docs/` | `handsontable-documentation` | Astro/Starlight documentation site (Node 20) |
| `docs/angular-type-check/` | `docs-angular-type-check` | Internal Angular type-check workspace for the docs site |

Note: `scripts/` and `performance-tests/` are directories in the repo but are **not** registered pnpm workspaces (they are not listed in `pnpm-workspace.yaml`).

**Version coordination:** All packages share a common version scheme managed through `hot.config.js`, which defines `HOT_VERSION` as the canonical version number. This ensures coordinated releases across the monorepo.

## Framework wrapper comparison

All framework wrappers follow a **peer dependency pattern**, requiring `handsontable` to be installed alongside the wrapper (currently `handsontable@^17.0.0` across all three). Each wrapper bridges the framework lifecycle to the Handsontable instance lifecycle.

| Package | Framework peer dependency | Main components |
|---|---|---|
| `@handsontable/react-wrapper` | `handsontable@^17.0.0` (React 18+) | `HotTable`, `HotColumn` |
| `@handsontable/angular-wrapper` | `@angular/core >=16.0.0 <22.0.0`, `rxjs@^7.0.0`, `handsontable@^17.0.0` | `HotTableComponent` (`hot-table`) |
| `@handsontable/vue3` | `vue@^3.2.22`, `handsontable@^17.0.0` | `HotTable`, `HotColumn` |

**Bridge points** (shared across wrappers):
- Framework component mount → `new Handsontable(element, options)` (or `hot.init()`).
- Framework state updates → `hot.updateSettings()` or `hot.setDataAtCell()`.
- Framework cleanup (unmount) → `hot.destroy()`.

**Framework-specific notes:**
- **React**: functional components; `ComponentEditor` support.
- **Vue 3**: Composition API support; reactive props binding.
- **Angular**: component wrapper built on Angular lifecycle hooks; Angular 16+ compatibility.
