|
1 | | -# AGENTS.md |
2 | | - |
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | | - |
5 | | -## Project Overview |
6 | | - |
7 | | -Dockview is a zero-dependency layout manager supporting tabs, groups, grids and splitviews. It provides framework support for React, Vue, Angular, and vanilla TypeScript. The project is organized as an NX monorepo (package-based approach) with Yarn v1 workspaces. |
8 | | - |
9 | | -See per-package `AGENTS.md` files under `packages/` for package-specific guidance. |
10 | | - |
11 | | -## Development Commands |
12 | | - |
13 | | -### Build |
14 | | - |
15 | | -- `yarn build` - Build all publishable packages via NX (dockview-core, dockview, dockview-vue, dockview-react, dockview-angular) |
16 | | -- `yarn clean` - Clean all packages |
17 | | -- `npx nx run <package>:<script>` - Run a specific script for a single package (e.g. `npx nx run dockview-core:build`) |
18 | | - |
19 | | -### Build Order |
20 | | - |
21 | | -NX handles build ordering automatically via `dependsOn: ["^build"]`. The dependency chain is: |
22 | | - |
23 | | - dockview-core → dockview → dockview-react |
24 | | - dockview-core → dockview-vue |
25 | | - dockview-core → dockview-angular |
26 | | - |
27 | | -### CSS Flow |
28 | | - |
29 | | -- `dockview-core` compiles SCSS to CSS via Gulp (`gulp sass`) |
30 | | -- All other packages copy CSS from `dockview-core` using `scripts/copy-css.js` |
31 | | - |
32 | | -### Testing |
33 | | - |
34 | | -- `yarn test` - Run Jest tests across all packages via NX |
35 | | -- `yarn test:cov` - Run tests with coverage (root-level Jest invocation for SonarCloud unified coverage) |
36 | | - |
37 | | -### Linting & Formatting |
38 | | - |
39 | | -- `yarn lint` - Run ESLint across all packages via NX |
40 | | -- `yarn lint:fix` - Run ESLint with automatic fixing |
41 | | -- `yarn format` - Run Prettier across all packages |
42 | | -- `yarn format:check` - Check Prettier formatting |
43 | | - |
44 | | -### Documentation |
45 | | - |
46 | | -- `yarn docs` - Generate TypeDoc documentation |
47 | | - |
48 | | -### Release |
49 | | - |
50 | | -- `yarn release` - NX release (fixed versioning, all packages share same version) |
51 | | -- `yarn release:version` - Bump version |
52 | | -- `yarn release:publish` - Publish to npm |
53 | | - |
54 | | -## Architecture |
55 | | - |
56 | | -### Monorepo Structure |
57 | | - |
58 | | -- **packages/dockview-core** - Core layout engine (TypeScript, framework-agnostic, zero dependencies) |
59 | | -- **packages/dockview** - React bindings and components |
60 | | -- **packages/dockview-vue** - Vue 3 bindings and components |
61 | | -- **packages/dockview-angular** - Angular bindings and components |
62 | | -- **packages/dockview-react** - Re-export wrapper (`export * from 'dockview'`) |
63 | | -- **packages/docs** - Documentation website (Docusaurus v3) |
64 | | - |
65 | | -### Key Components |
66 | | - |
67 | | -#### Core Architecture (dockview-core) |
68 | | - |
69 | | -- **DockviewComponent** - Main container managing panels and groups |
70 | | -- **DockviewGroupPanel** - Container for related panels with tabs |
71 | | -- **DockviewPanel** - Individual content panels |
72 | | -- **Gridview/Splitview/Paneview** - Different layout strategies |
73 | | -- **API Layer** - Programmatic interfaces for each component type |
74 | | - |
75 | | -#### Framework Integration |
76 | | - |
77 | | -- Framework-specific packages provide thin wrappers around core components |
78 | | -- React package uses HOCs and hooks for component lifecycle management |
79 | | -- Vue package provides Vue 3 composition API integration |
80 | | -- All frameworks share the same core serialization/deserialization logic |
81 | | - |
82 | | -#### Key Features |
83 | | - |
84 | | -- Drag and drop with customizable drop zones |
85 | | -- Floating groups and popout windows |
86 | | -- Serialization/deserialization for state persistence |
87 | | -- Theming system with CSS custom properties |
88 | | -- Comprehensive API for programmatic control |
89 | | - |
90 | | -### Build System |
91 | | - |
92 | | -- **NX** for monorepo orchestration (package-based, `useInferencePlugins: false`) |
93 | | -- **Yarn v1** for package management and workspaces |
94 | | -- **TypeScript** (`tsc`) for CJS + ESM compilation |
95 | | -- **Gulp** for SCSS processing (dockview-core only) |
96 | | -- **Rollup** for UMD bundles (dockview-core, dockview, dockview-react) |
97 | | -- **Vite** for Vue package builds |
98 | | -- **ng-packagr** for Angular Package Format builds |
99 | | - |
100 | | -### Testing Strategy |
101 | | - |
102 | | -- Jest with ts-jest preset for TypeScript support |
103 | | -- Testing Library for React component testing |
104 | | -- Coverage reporting with SonarCloud integration |
105 | | -- Each package has its own jest.config.ts extending root configuration |
106 | | - |
107 | | -### Code Quality |
108 | | - |
109 | | -- ESLint configuration extends recommended TypeScript rules |
110 | | -- Prettier for code formatting |
111 | | -- Linting targets source files in packages/\*/src/\*\* (excludes tests, docs, node_modules) |
112 | | -- Current rules focus on TypeScript best practices while allowing some flexibility |
113 | | - |
114 | | -## Development Notes |
115 | | - |
116 | | -### Working with Packages |
117 | | - |
118 | | -- Use NX commands for cross-package operations (`npx nx run-many -t <target>`) |
119 | | -- Each package can be built independently via `npx nx run <package>:build` |
120 | | -- Core package must be built before framework packages (NX handles this automatically) |
121 | | - |
122 | | -### Adding New Features |
123 | | - |
124 | | -- Start with core package implementation |
125 | | -- Add corresponding API methods in api/ directory |
126 | | -- Create framework-specific wrappers as needed |
127 | | -- Update TypeDoc documentation |
128 | | -- Add tests in \_\_tests\_\_ directories |
129 | | -- Run `yarn lint` to check code quality before committing |
130 | | - |
131 | | -### State Management |
132 | | - |
133 | | -- Components use internal state with event-driven updates |
134 | | -- Serialization provides snapshot-based state persistence |
135 | | -- APIs provide reactive interfaces with event subscriptions |
136 | | - |
137 | | -## Release Management |
138 | | - |
139 | | -### Creating Release Notes |
140 | | - |
141 | | -Release notes are stored in `packages/docs/blog/` with the naming format `YYYY-MM-DD-dockview-X.Y.Z.md`. |
142 | | - |
143 | | -To create release notes for a new version: |
144 | | - |
145 | | -1. Check git commits since the last release: `git log --oneline --since="YYYY-MM-DD"` |
146 | | -2. Create a new markdown file following the established format: |
147 | | - - Front matter with slug, title, and tags |
148 | | - - Sections for Features, Miscs, and Breaking changes |
149 | | - - Reference GitHub PR numbers for significant changes |
150 | | - - Focus on user-facing changes, bug fixes, and new features |
151 | | - |
152 | | -Example format: |
153 | | -```markdown |
154 | | ---- |
155 | | -slug: dockview-X.Y.Z-release |
156 | | -title: Dockview X.Y.Z |
157 | | -tags: [release] |
158 | | ---- |
159 | | - |
160 | | -# Release Notes |
161 | | - |
162 | | -Please reference docs @ [dockview.dev](https://dockview.dev). |
163 | | - |
164 | | -## Features |
165 | | -- Feature description [#PR](link) |
166 | | - |
167 | | -## Miscs |
168 | | -- Bug: Fix description [#PR](link) |
169 | | -- Chore: Maintenance description [#PR](link) |
170 | | - |
171 | | -## Breaking changes |
172 | | -``` |
173 | | - |
174 | | -## Active Technologies |
175 | | -- TypeScript 5.x (strict mode) + None (dockview-core is zero-dependency; framework wrappers are thin layers) (001-tab-drag-animation) |
176 | | -- N/A (purely visual feature, no state persistence changes) (001-tab-drag-animation) |
177 | | - |
178 | | -## Recent Changes |
179 | | -- 001-tab-drag-animation: Added TypeScript 5.x (strict mode) + None (dockview-core is zero-dependency; framework wrappers are thin layers) |
| 1 | +AGENTS.md |
0 commit comments