vizro / vizro-dash-components

# CLAUDE.md for `vizro-dash-components` folder

Vizro Dash Components are used by the Vizro framework but can be used in a pure Dash app.

## Development

### Working Directory

**Important**: All Hatch commands must be run from the `vizro-dash-components/` directory.

### Prerequisites

- Node.js and npm (for building JS/CSS assets)
- Hatch (Python project manager)
- Run `npm install` once after cloning to install npm dependencies

### npm commands (no Python required)

- `npm run build:js` - Compile JS/CSS via webpack
- `npm run watch` - Watch mode for JS development (auto-rebuilds on file changes)
- `npm run fmt:js` - Auto-fix JS/TS formatting with Biome
- `npm run lint:js` - Lint JS/TS with Biome

### Hatch commands (require Python)

- `hatch run generate-components` - Full build: compile JS/CSS via webpack + generate Python component classes via `dash-generate-components`
- `hatch run lint` - Run all linters via pre-commit (includes Biome for JS/TS)
- `hatch run test` - Run integration tests (requires Chrome; uses `dash_duo` for browser-based testing)
- `hatch run example` - Run the multi-page example app on port 8050 (sidebar: **components** and **other** page groups)
- `hatch run changelog:add` - Create a changelog fragment (required for PRs)

**Source of truth**: Only edit TypeScript/JS files in `src/ts/`. Never directly edit auto-generated files in `vizro_dash_components/` — Python bindings (`*.py`) are regenerated by `dash-generate-components` and the JS bundle (`*.js`) is regenerated by webpack. After editing source files, run `hatch run generate-components` to regenerate.

### Project structure

- `src/ts/components/` - Dash component definitions (TypeScript/React). Each file here becomes a Python Dash component
- `src/ts/fragments/` - Internal React components used by the Dash components (not exported as Dash components)
- `src/ts/utils/` - Shared utilities (lazy loaders, helper functions)
- `vizro_dash_components/` - Auto-generated Python package (built artifacts, do not edit manually)
- `examples/app.py` - Multi-page Dash app entry point; navbar lists **components** then **other** pages (run with `hatch run example`)
- `examples/pages/home.py` - Home page with links to other component pages
- `examples/pages/cascader.py` - Cascader component page
- `examples/pages/markdown.py` - Markdown component page
- `pyproject.toml` - Python package configuration (version sourced from `package.json` via `hatch-nodejs-version`)
- `package.json` - npm package configuration with build scripts (version must be semver-compatible, e.g. `0.1.0` or `0.1.0-dev0`)
- `hatch.toml` - Hatch environment and script configuration
- `webpack.config.js` - Webpack config with async chunk splitting for lazy-loaded modules (Markdown, MathJax)

### Writing Dash components

Each `.tsx` file in `src/ts/components/` becomes a Dash component. Key patterns:

- Extend `DashComponentProps` for the required `id` and `setProps` props
- Call `setProps({prop: newValue})` to trigger Dash callbacks
- JSDoc comments on the component and its props become Python docstrings
- `defaultProps` on the component set Python default values

## Testing with vizro-core

`vizro-core` depends on the `vizro-dash-components` package. To test local changes:

1. `vizro-dash-components/`: Build with `hatch run generate-components`
1. `vizro-core/`: Override the installed package with your local version: `hatch run examples:pip install -e ../vizro-dash-components`
1. `vizro-core/`: Add the component under test to `scratch_dev/app.py`
1. `vizro-core/`: Run the example with `hatch run example`

More agent context in mckinsey/vizro

10 other files this repository gives its agents.