diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 347bb4cac..19a11af34 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,30 +1,83 @@ # Contributing to Object UI -Thank you for your interest in contributing to Object UI! This document provides guidelines and instructions for contributing. +Thank you for your interest in contributing to Object UI! This document provides guidelines and instructions for contributing to the project. + +## Table of Contents + +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Development Workflow](#development-workflow) +- [Architecture Overview](#architecture-overview) +- [Writing Tests](#writing-tests) +- [Code Style](#code-style) +- [Commit Guidelines](#commit-guidelines) +- [Pull Request Process](#pull-request-process) +- [Documentation](#documentation) +- [Adding Components](#adding-components) +- [Questions & Support](#questions--support) ## Getting Started -1. Fork the repository -2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/object-ui.git` -3. Install dependencies: `pnpm install` -4. Create a new branch: `git checkout -b feature/your-feature-name` +### Prerequisites + +- **Node.js** 18.0 or higher +- **pnpm** (recommended package manager) +- **Git** for version control +- Basic knowledge of React, TypeScript, and Tailwind CSS + +### Fork and Clone + +1. Fork the repository on GitHub +2. Clone your fork: + ```bash + git clone https://github.com/YOUR_USERNAME/objectui.git + cd objectui + ``` +3. Add upstream remote: + ```bash + git remote add upstream https://github.com/objectql/objectui.git + ``` + +## Development Setup + +### Install Dependencies + +```bash +# Install pnpm if you haven't +npm install -g pnpm + +# Install project dependencies +pnpm install +``` + +### Create a Branch + +```bash +# Sync with upstream +git fetch upstream +git checkout main +git merge upstream/main + +# Create a feature branch +git checkout -b feature/your-feature-name +``` ## Development Workflow -### Running Tests +### Running Development Servers ```bash -# Run all tests -pnpm test +# Run the playground (main development app) +pnpm playground -# Run tests in watch mode -pnpm test:watch +# Run the visual designer demo +pnpm designer -# Run tests with UI -pnpm test:ui +# Run the prototype example +pnpm prototype -# Generate coverage report -pnpm test:coverage +# Run documentation site +pnpm docs:dev ``` ### Building @@ -37,76 +90,356 @@ pnpm build cd packages/core && pnpm build ``` +### Testing + +```bash +# Run all tests +pnpm test + +# Run tests in watch mode +pnpm test:watch + +# Run tests with UI (interactive) +pnpm test:ui + +# Generate coverage report +pnpm test:coverage +``` + ### Linting ```bash # Lint all packages pnpm lint + +# Lint specific package +cd packages/react && pnpm lint +``` + +## Architecture Overview + +Object UI follows a modular monorepo architecture: + +``` +packages/ +├── types/ # TypeScript type definitions (Zero dependencies) +├── core/ # Core logic, validation, registry (Zero React) +├── react/ # React bindings and SchemaRenderer +├── components/ # UI components (Tailwind + Shadcn) +├── designer/ # Visual schema editor +├── plugin-charts/ # Chart components plugin +└── plugin-editor/ # Rich text editor plugin ``` +### Key Principles + +1. **Protocol Agnostic**: Core never depends on specific backends +2. **Tailwind Native**: All styling via Tailwind utility classes +3. **Type Safety**: Strict TypeScript everywhere +4. **Tree Shakable**: Modular imports, no monolithic bundles +5. **Zero React in Core**: Core package has no React dependencies + +See [Architecture Documentation](./docs/spec/architecture.md) for details. + ## Writing Tests -All tests should be placed in `__tests__` directories within the source code. We use **Vitest** and **React Testing Library**. +### Test Structure -Example test structure: +All tests should be placed in `__tests__` directories within the source code. We use **Vitest** and **React Testing Library**. ```typescript -import { describe, it, expect } from 'vitest'; -import { render, screen } from '@testing-library/react'; +import { describe, it, expect } from 'vitest' +import { render, screen } from '@testing-library/react' +import { MyComponent } from './MyComponent' -describe('ComponentName', () => { +describe('MyComponent', () => { it('should render correctly', () => { - render(); - expect(screen.getByText('Expected Text')).toBeInTheDocument(); - }); -}); + render() + expect(screen.getByText('Expected Text')).toBeInTheDocument() + }) + + it('should handle user interaction', async () => { + const { user } = render() + await user.click(screen.getByRole('button')) + expect(screen.getByText('Clicked')).toBeInTheDocument() + }) +}) +``` + +### Testing Best Practices + +- Write tests for all new features +- Test user interactions, not implementation details +- Use meaningful test descriptions +- Aim for 80%+ code coverage +- Test edge cases and error states + +## Code Style + +### TypeScript Guidelines + +```typescript +// ✅ Good: Explicit types, clear naming +interface UserData { + id: string + name: string + email: string +} + +function getUserById(id: string): UserData | null { + // implementation +} + +// ❌ Bad: Implicit any, unclear naming +function get(x) { + // implementation +} ``` +### React Component Guidelines + +```tsx +// ✅ Good: TypeScript, named exports, clear props +interface ButtonProps { + label: string + onClick: () => void + variant?: 'primary' | 'secondary' +} + +export function Button({ label, onClick, variant = 'primary' }: ButtonProps) { + return ( + + ) +} + +// ❌ Bad: No types, default export, inline styles +export default function Button(props) { + return +} +``` + +### Styling Guidelines + +- **Always use Tailwind**: Never use inline styles or CSS modules +- **Use `cn()` utility**: For conditional classes +- **Extract repeated classes**: Create reusable class combinations +- **Follow Shadcn patterns**: Match the style of existing components + +```tsx +// ✅ Good +
+ {children} +
+ +// ❌ Bad +
+ {children} +
+``` + +### General Guidelines + +- Use meaningful variable and function names +- Keep functions small and focused (< 50 lines) +- Add JSDoc comments for public APIs +- Avoid deep nesting (max 3 levels) +- Use early returns to reduce complexity + ## Commit Guidelines -We follow conventional commit messages: +We follow [Conventional Commits](https://www.conventionalcommits.org/): + +### Commit Types - `feat:` - New features - `fix:` - Bug fixes - `docs:` - Documentation changes - `test:` - Adding or updating tests -- `chore:` - Maintenance tasks -- `refactor:` - Code refactoring +- `chore:` - Maintenance tasks (deps, config) +- `refactor:` - Code refactoring (no behavior change) +- `perf:` - Performance improvements +- `style:` - Code style changes (formatting) + +### Examples + +```bash +feat: add date picker component +fix: resolve schema validation error +docs: update installation guide +test: add tests for SchemaRenderer +chore: update dependencies +refactor: simplify expression evaluator +``` + +### Commit Message Format + +``` +: + + -Example: `feat: add new button variant` +