# Contributing to AeThex Studio

Thank you for your interest in contributing to AeThex Studio! We welcome contributions from the community.

## Getting Started

1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
   ```bash
   git clone https://github.com/YOUR_USERNAME/aethex-studio.git
   cd aethex-studio
   ```
3. **Install dependencies**:
   ```bash
   npm install
   ```
4. **Create a branch** for your feature:
   ```bash
   git checkout -b feature/my-amazing-feature
   ```

## Development Workflow

### Running the Development Server

```bash
npm run dev
```

Visit `http://localhost:3000` to see your changes in real-time.

### Code Style

- We use **TypeScript** for type safety
- Follow existing code patterns and conventions
- Use **ESLint** to check your code:
  ```bash
  npm run lint
  ```

### Testing

Before submitting a PR, ensure all tests pass:

```bash
# Run all tests
npm test

# Run tests in watch mode during development
npm run test:watch

# Check test coverage
npm run test:coverage
```

#### Writing Tests

- Place tests in `src/components/__tests__/` or `src/hooks/__tests__/`
- Use descriptive test names
- Test both success and error cases
- Example:
  ```typescript
  describe('MyComponent', () => {
    it('should render correctly', () => {
      // Your test here
    });

    it('should handle errors gracefully', () => {
      // Your test here
    });
  });
  ```

## Types of Contributions

### 🐛 Bug Fixes

1. Check if the bug is already reported in [Issues](https://github.com/AeThex-LABS/aethex-studio/issues)
2. If not, create a new issue with:
   - Clear description
   - Steps to reproduce
   - Expected vs actual behavior
   - Screenshots (if applicable)
3. Create a fix and submit a PR

### ✨ New Features

1. **Discuss first** - Open an issue to discuss the feature before implementing
2. Wait for approval from maintainers
3. Implement the feature
4. Add tests
5. Update documentation
6. Submit a PR

### 📝 Documentation

- Fix typos
- Improve clarity
- Add examples
- Update outdated information

### 🎨 UI/UX Improvements

- Follow the existing design system
- Ensure responsive design (mobile + desktop)
- Test accessibility
- Add screenshots to PR

## Pull Request Process

### Before Submitting

- [ ] Code builds without errors (`npm run build`)
- [ ] All tests pass (`npm test`)
- [ ] Linting passes (`npm run lint`)
- [ ] Code is well-commented
- [ ] Documentation is updated
- [ ] Commit messages are clear and descriptive

### Commit Messages

Use clear, descriptive commit messages:

```bash
# Good
git commit -m "Add drag-and-drop support for file tree"
git commit -m "Fix search highlighting bug in SearchPanel"

# Bad
git commit -m "Update stuff"
git commit -m "Fix bug"
```

### Submitting

1. Push your branch to your fork
2. Open a PR against the `main` branch
3. Fill out the PR template
4. Wait for review

### PR Template

```markdown
## Description
Brief description of what this PR does

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Testing
Describe how you tested this change

## Screenshots (if applicable)
Add screenshots here

## Checklist
- [ ] Tests pass
- [ ] Linting passes
- [ ] Documentation updated
- [ ] Responsive on mobile
```

## Code Organization

### File Structure

```
src/
├── components/          # React components
│   ├── ui/             # Reusable UI components
│   ├── __tests__/      # Component tests
│   └── ComponentName.tsx
├── hooks/              # Custom React hooks
│   ├── __tests__/      # Hook tests
│   └── use-hook-name.ts
├── lib/                # Utilities and helpers
│   └── helpers.ts
└── App.tsx             # Main application
```

### Naming Conventions

- **Components**: PascalCase (`FileTree.tsx`, `AIChat.tsx`)
- **Hooks**: camelCase with `use` prefix (`use-theme.ts`, `use-keyboard-shortcuts.ts`)
- **Utilities**: camelCase (`helpers.ts`, `validators.ts`)
- **Tests**: Match component name with `.test.tsx` or `.test.ts`

## Adding New Features

### Adding a New Template

1. Edit `src/lib/templates.ts`
2. Add your template to the `templates` array:
   ```typescript
   {
     id: 'your-template-id',
     name: 'Template Name',
     description: 'Brief description',
     category: 'beginner' | 'gameplay' | 'ui' | 'tools' | 'advanced',
     code: `-- Your Lua code here`,
   }
   ```

### Adding a New Component

1. Create the component file in `src/components/`
2. Write the component with TypeScript types
3. Add tests in `src/components/__tests__/`
4. Export from the component file
5. Import and use in `App.tsx` or parent component

### Adding a Keyboard Shortcut

1. Edit `src/App.tsx`
2. Add to the `useKeyboardShortcuts` array:
   ```typescript
   {
     key: 'x',
     meta: true,
     ctrl: true,
     handler: () => {
       // Your action here
     },
     description: 'Description of shortcut',
   }
   ```
3. Update README.md keyboard shortcuts table

### Adding a New CLI Command

The interactive terminal supports custom CLI commands for Roblox development.

1. Edit `src/lib/cli-commands.ts`
2. Add your command to the `commands` object:
   ```typescript
   mycommand: {
     name: 'mycommand',
     description: 'Description of what it does',
     usage: 'mycommand [args]',
     aliases: ['mc', 'mycmd'], // Optional
     execute: async (args, context) => {
       // Access current code, files, etc. from context
       // context.currentCode
       // context.currentFile
       // context.files
       // context.setCode()
       // context.addLog()

       // Perform your command logic

       return {
         success: true,
         output: 'Command output',
         type: 'info', // or 'log', 'warn', 'error'
       };
     },
   }
   ```

#### Available Context:
- `context.currentCode` - Current editor code
- `context.currentFile` - Active file name
- `context.files` - File tree array
- `context.setCode(code)` - Update editor code
- `context.addLog(message, type)` - Add terminal log

#### Command Features:
- Command aliases for shortcuts
- Argument parsing (args array)
- Context-aware execution
- Error handling with toast notifications
- Special `__CLEAR__` output to clear terminal

## Performance Guidelines

- Use React.lazy() for code splitting
- Memoize expensive computations with useMemo()
- Use useCallback() for function props
- Optimize re-renders with React.memo()
- Lazy load images and heavy components

## Accessibility Guidelines

- Add proper ARIA labels
- Ensure keyboard navigation works
- Test with screen readers
- Maintain good color contrast
- Add focus indicators

## Questions?

- Open an issue for questions
- Join our community discussions
- Check existing issues and PRs

## Code of Conduct

- Be respectful and inclusive
- Welcome newcomers
- Give constructive feedback
- Focus on the code, not the person

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to AeThex Studio! 🎉