Skip to content

Commit d2af59c

Browse files
segunadebayosegunadebayo
committed
docs: update
1 parent 125a002 commit d2af59c

File tree

6 files changed

+247
-181
lines changed

6 files changed

+247
-181
lines changed

‎.claude/docs/architecture.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Code Organization & Architecture
2+
3+
## Workspace Structure
4+
5+
This is a monorepo using pnpm workspaces:
6+
7+
```
8+
packages/
9+
├── machines/ # State machines for components (accordion, dialog, etc.)
10+
├── frameworks/ # Framework adapters (react, vue, solid, svelte, preact)
11+
├── utilities/ # Shared utilities (dom-query, popper, focus-trap, etc.)
12+
├── core/ # Core machine functionality
13+
├── anatomy/ # Component anatomy definitions
14+
├── anatomy-icons/ # Icon components for anatomy
15+
├── store/ # State management utilities
16+
├── types/ # Shared TypeScript types
17+
└── docs/ # Documentation generation
18+
```
19+
20+
## Machine Structure
21+
22+
Each machine package follows this structure:
23+
24+
```
25+
packages/machines/{component}/
26+
├── src/
27+
│ ├── {component}.machine.ts # State machine definition
28+
│ ├── {component}.connect.ts # Framework connection API
29+
│ ├── {component}.types.ts # TypeScript types
30+
│ ├── {component}.anatomy.ts # Component anatomy
31+
│ ├── {component}.dom.ts # DOM utilities
32+
│ └── index.ts # Main exports
33+
├── package.json
34+
├── README.md
35+
└── tsconfig.json
36+
```
37+
38+
## Framework Adapters
39+
40+
Each framework adapter provides:
41+
42+
- Machine consumption utilities
43+
- Props normalization
44+
- Framework-specific optimizations
45+
- TypeScript integration
46+
47+
## Utility Packages
48+
49+
Utilities are organized by functionality:
50+
51+
- `dom-query`: DOM manipulation and querying
52+
- `popper`: Positioning and floating elements
53+
- `focus-trap`: Focus management
54+
- `interact-outside`: Click outside detection
55+
- `dismissable`: Dismissal patterns

‎.claude/docs/commands.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Key Commands & Workflows
2+
3+
## Building
4+
5+
```bash
6+
pnpm build # Build all packages
7+
pnpm packages -- build # Build specific packages
8+
pnpm clean-pkgs # Clean all package builds
9+
```
10+
11+
## Development Servers
12+
13+
```bash
14+
pnpm start-react # Next.js example (React)
15+
pnpm start-vue # Nuxt.js example (Vue)
16+
pnpm start-solid # Solid.js example
17+
pnpm start-svelte # Svelte example
18+
pnpm start-website # Documentation website
19+
```
20+
21+
## Testing
22+
23+
```bash
24+
pnpm test # Run all tests
25+
pnpm test-js # Run JavaScript tests (utilities, core)
26+
pnpm test-react # Run React-specific tests
27+
pnpm test-vue # Run Vue-specific tests
28+
pnpm test-solid # Run Solid-specific tests
29+
pnpm test-svelte # Run Svelte-specific tests
30+
```
31+
32+
## E2E Testing
33+
34+
```bash
35+
pnpm e2e-react # E2E tests for React
36+
pnpm e2e-vue # E2E tests for Vue
37+
pnpm e2e-solid # E2E tests for Solid
38+
pnpm pw-report # View Playwright test reports
39+
```
40+
41+
## Code Quality
42+
43+
```bash
44+
pnpm lint # Lint all packages
45+
pnpm prettier # Check formatting
46+
pnpm prettier-fix # Fix formatting
47+
pnpm typecheck # TypeScript type checking
48+
```
49+
50+
## Code Generation
51+
52+
```bash
53+
pnpm generate-machine # Generate new component machine
54+
pnpm generate-util # Generate new utility package
55+
pnpm sync-pkgs # Sync package dependencies
56+
```
57+
58+
## Creating Changesets
59+
60+
```bash
61+
npx changeset # Interactive changeset creation (may not work in all terminals)
62+
# Or create manually in .changeset/descriptive-name.md with format:
63+
# ---
64+
# "@zag-js/package-name": patch|minor|major
65+
# ---
66+
# User-facing description of changes
67+
```

‎.claude/docs/common-tasks.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Common Tasks
2+
3+
## Adding a New Component
4+
5+
1. Use `pnpm generate-machine` to scaffold the package structure
6+
2. Implement the state machine in `{component}.machine.ts`
7+
3. Add framework connections in `{component}.connect.ts`
8+
4. Create E2E tests in `e2e/{component}.e2e.ts`
9+
5. Update documentation and examples
10+
6. Run `pnpm sync-pkgs` to update dependencies
11+
12+
## Modifying Existing Components
13+
14+
1. Update the state machine definition
15+
2. Test across all frameworks
16+
3. Update E2E tests if behavior changes
17+
4. Ensure accessibility compliance
18+
5. Update TypeScript types
19+
20+
## Framework-Specific Changes
21+
22+
1. Modify the framework adapter in `packages/frameworks/{framework}/`
23+
2. Test the specific framework thoroughly
24+
3. Ensure no breaking changes to the API
25+
4. Update framework-specific examples
26+
27+
## Adding Utilities
28+
29+
1. Use `pnpm generate-util` for scaffolding
30+
2. Place in appropriate category under `packages/utilities/`
31+
3. Ensure TypeScript types are exported
32+
4. Add unit tests
33+
5. Update documentation

‎.claude/docs/guidelines.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Development Guidelines
2+
3+
## State Machine Patterns
4+
5+
1. **Simple Machines**: Avoid complex nested states, spawn, etc.
6+
2. **Accessibility First**: All machines follow WAI-ARIA practices
7+
3. **Framework Agnostic**: Core logic never depends on framework specifics
8+
4. **Event-Driven**: Use events for state transitions, not direct mutations
9+
10+
## Code Style
11+
12+
1. **TypeScript First**: Everything is typed
13+
2. **Functional Programming**: Prefer pure functions and immutability
14+
3. **Consistent Naming**: Use camelCase for properties, PascalCase for types
15+
4. **Small Functions**: Break down complex logic into smaller, testable functions
16+
17+
## Testing Strategy
18+
19+
1. **E2E First**: All components have Playwright E2E tests
20+
2. **Framework Coverage**: Test same behavior across all supported frameworks
21+
3. **Accessibility Testing**: Verify ARIA attributes and keyboard interactions
22+
4. **Cross-Browser**: Ensure consistent behavior across browsers
23+
24+
## Quality Assurance
25+
26+
### Pre-Commit Hooks
27+
28+
- ESLint for code quality
29+
- Prettier for formatting
30+
- TypeScript type checking
31+
- Commit message linting (conventional commits)
32+
33+
### CI/CD Pipeline
34+
35+
- Build verification across all packages
36+
- Test execution (unit + E2E)
37+
- Type checking
38+
- Linting and formatting
39+
- Package publishing automation

‎.claude/docs/troubleshooting.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Troubleshooting
2+
3+
## Common Issues
4+
5+
1. **Build Failures**: Check TypeScript errors and missing dependencies
6+
2. **Test Failures**: Verify E2E test setup and browser compatibility
7+
- E2E tests run against built code - changes need to be built first
8+
- Use `pnpm pw-test {component}.e2e.ts` to run specific E2E tests
9+
- Add `.only` to test declarations for focused testing
10+
3. **Framework Issues**: Check framework adapter implementation
11+
4. **Type Errors**: Ensure proper type exports and imports
12+
13+
## Debugging Tips
14+
15+
1. Use framework examples for testing changes
16+
2. Check E2E test results for cross-framework issues
17+
3. Verify accessibility with screen readers and keyboard navigation
18+
4. Test in multiple browsers
19+
5. For keyboard/input issues, check both the machine logic and the connect file event handlers

0 commit comments

Comments
 (0)