jolyui / rules

---
description: JolyUI component setup pipeline for creating new components with types, examples, registry entries, and documentation
globs: 
alwaysApply: false
---

# JolyUI Component Setup Rule

You are an expert in TypeScript, React, and JolyUI component architecture. When a user asks you to create a new component using the pattern "@setup-component [component-name]", follow this comprehensive pipeline:

## Steps

### 1. Create Component Types (@docs/types/docs/[component-name].ts)

- Create TypeScript interfaces for all component parts
- Follow the pattern from existing files like `editable.ts` and `stepper.ts`.
- Include proper JSDoc comments with examples
- Import necessary types from UI libraries and internal types
- Define interfaces for Root, Content, Trigger, and any specific component parts
- Include composition props and controlled/uncontrolled patterns

Finalize the API design first. Once it’s been iterated on and completed, proceed to the other steps. This will minimize refactoring.

### 2. Create Examples (@docs/registry/default/examples/)

Create these example files:

- `[component-name]-demo.tsx` - Basic usage example
- `[component-name]-controlled-demo.tsx` - Controlled state example (if applicable)
- `[component-name]-form-demo.tsx` - Form integration example (if applicable)
- Additional variant demos as needed

### 3. Update Registry Files

Update these registry files:

#### @docs/registry/registry-ui.ts

Add UI component entry with:

- Component name
- Dependencies (external packages)
- Registry dependencies (internal UI components)
- File paths for UI component and any utilities

#### @docs/registry/registry-examples.ts

Add example entries for each demo file created:

- Component name + "-demo" suffix
- Dependencies and registry dependencies
- File paths

### 4. Update `registry.json`

Add the new component and examples to the `registry.json` file.

### 5. Create Documentation (@docs/content/docs/components/[component-name].mdx)

Create comprehensive documentation including:

- Title, description, and metadata
- ComponentTabs for demo preview
- Installation instructions (CLI and manual)
- Layout/composition examples
- Multiple example sections
- Complete API reference with AutoTypeTable for each interface
- Accessibility section with keyboard interactions
- Any specific notes about browser support or limitations

## Implementation Guidelines

### Type Definitions

- Use consistent naming: `RootProps`, `TriggerProps`, `ContentProps`, etc.
- Extend from appropriate base components (Button, Input, etc.)
- Include CompositionProps for all component interfaces
- Add proper JSDoc with `@default` values and `@example` usage
- Support both controlled and uncontrolled patterns where applicable

### Example Components

- Import from `@/registry/default/ui/[component-name]`
- Use default export with descriptive function name
- Show realistic usage scenarios
- Include proper TypeScript typing
- Follow JolyUI component composition patterns

### Registry Entries

- Maintain alphabetical order in both registry files
- Include all necessary dependencies
- Use proper file paths relative to registry
- Match naming conventions exactly

### Documentation Structure

- Follow the established MDX pattern from existing component docs
- Use ComponentTabs for interactive previews
- Include comprehensive API documentation
- Add accessibility considerations
- Provide installation and setup instructions

## Example Usage

When user types: `@setup-component file-upload`

You should:

1. Create `/docs/types/docs/file-upload.ts` with proper interfaces
2. Create example files like `file-upload-demo.tsx`, `file-upload-form-demo.tsx`
3. Update `registry-ui.ts` with the component entry
4. Update `registry-examples.ts` with example entries
5. Update `registry.json` with the new component and examples
6. Create `file-upload.mdx` documentation file

## Code Style

- Use functional components with TypeScript
- Follow existing patterns for imports and exports
- Use descriptive variable names
- Maintain consistent formatting and structure
- Add proper error handling and accessibility features
- Use flex and gap instead of space-x-n and space-y-n
- In the layout portion of the docs don't pass any props, can reference the @file-upload.mdx.
- Make sure not to update any `[component-name].json files, these will be autogenerated with the shadcn cli.

## File Organization

- Keep consistent file naming (kebab-case)
- Follow existing directory structure
- Maintain import path consistency
- Use proper TypeScript module organization

When implementing, create all files in the correct locations and ensure they follow the established patterns from existing components like editable, color-picker, etc.