CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Start development server: bun dev (runs on port 8080)
Build library: bun build (builds library with vite.config.lib.ts)
Build site: bun build:site (builds demo site with vite.config.ts)
Run tests: bun run test:bun (runs unit tests with Bun, excluding E2E) or bun run test (runs Vitest)
Run E2E tests: bun pw (runs Playwright tests)
Run E2E tests (CI): bun pw:ci (runs with GitHub reporter for CI)
Open Playwright UI: bun pw:ui
Update Playwright snapshots: bun pw:update
Install Playwright browsers: bun pw:install
Run smoke tests: bun pw:smoke
Lint code: bun eslint (runs ESLint with auto-fix)
Format code: bun prettier (runs Prettier)
Generate ANTLR parser: bun antlr (generates JavaScript parser from grammar)

Project Architecture

ZenUML is a JavaScript-based diagramming library for creating sequence diagrams from text definitions. The project has two main parts:

1. DSL Parser (ANTLR-based)

Grammar files: src/g4/ contains ANTLR grammar definitions
Generated parser: src/generated-parser/ contains generated JavaScript parser
Parser enhancements: src/parser/ contains custom functionality layered on top of ANTLR

2. React-based Renderer

Core entry point: src/core.tsx - main library export and ZenUml class
Component structure: src/components/ - React components for rendering diagrams
Store management: src/store/Store.ts - Jotai-based state management
Positioning engine: src/positioning/ - algorithms for layout and positioning

Key Components Architecture

DiagramFrame: Main container component that orchestrates the entire diagram
SeqDiagram: Core sequence diagram renderer with layers:
- LifeLineLayer: Renders participants and their lifelines
- MessageLayer: Renders messages and interactions between participants
Statement components: Individual renderers for different UML elements (interactions, fragments, etc.)

Parser Architecture

The parser uses a two-stage approach:

ANTLR-generated parser: Converts text to parse tree
Custom parser layer: Transforms parse tree into structured data for rendering

Key parser modules:

Participants.ts: Manages participant detection and ordering
MessageContext.ts: Handles message parsing and context
FrameBuilder.ts: Builds the overall diagram structure
Fragment handling: Support for UML fragments (alt, opt, loop, par, etc.)

Build System

The project uses Vite with two configurations:

vite.config.ts: Development server and demo site build
vite.config.lib.ts: Library build (ESM and UMD outputs)

Output formats:

ESM: dist/zenuml.esm.mjs for modern bundlers
UMD: dist/zenuml.js for browser scripts

Testing Strategy

Unit tests: Vitest for parser and utility functions
Component tests: React Testing Library for component logic
E2E tests: Playwright for full integration testing with visual snapshots
Test files: Co-located with source files using .spec.ts extension

Key Dependencies

React 19: UI framework
ANTLR4: Parser generation
Jotai: State management
Tailwind CSS: Styling framework
html-to-image: PNG export functionality
Vite: Build tool and development server

Package Management

Uses Bun as the package manager and JavaScript runtime. Bun is a fast all-in-one JavaScript runtime that includes a package manager, test runner, and bundler.

Test Configuration

Unit tests with Bun: bun run test:bun - Runs unit tests in src/ and test/unit/ folders (excludes /tests E2E folder)
Vitest: bun run test - Uses Vitest for compatibility with existing test suite
E2E tests: bun pw - Runs Playwright tests in /tests folder
Tests use vi mocking utilities which are mapped to Jest-compatible APIs in test-setup.ts
Coverage is disabled by default due to resource issues; enable with bun test --coverage

Development Notes

The project builds both a library and a demo site
Parser generation requires Java and ANTLR4
E2E tests use visual snapshots for regression testing
The library is published as @zenuml/core to npm
GitHub Pages deployment is automated via GitHub Actions

4.4 KiB Raw Blame History