Hamdast1/QUICK_REFERENCE.md

# Quick Reference - SubmitChallengePage Refactoring

## 🎯 At a Glance

| Item | Value |
|------|-------|
| **Main File** | `/src/app/components/SubmitChallengePage.tsx` |
| **Config File** | `/src/config/topicConfig.ts` |
| **Forms Directory** | `/src/app/components/submit-forms/` |
| **Shared Components** | `/src/app/components/submit-forms/shared/` |

---

## 📁 New Files Created

```
✅ /src/app/components/submit-forms/ImageForm.tsx
✅ /src/app/components/submit-forms/ImageVideoForm.tsx
✅ /src/app/components/submit-forms/shared/MediaUploadBox.tsx
✅ /src/app/components/submit-forms/shared/TeammatesSection.tsx
✅ /src/app/components/submit-forms/shared/FormInput.tsx
✅ /REFACTORING.md
✅ /REFACTORING_SUMMARY.md
✅ /MIGRATION_GUIDE.md
✅ /ARCHITECTURE_DIAGRAM.md
```

---

## ⚡ Quick Actions

### Add New Topic (Image Only)
```typescript
// In topicConfig.ts
"10": {
  id: "10",
  title: "New Topic",
  mediaType: "image",
  requiresTeammates: false,
  formComponent: ImageForm,
  // ... rest
}
```

### Add New Topic (Image + Video)
```typescript
"10": {
  mediaType: "both",
  requiresTeammates: true,
  formComponent: ImageVideoForm,
}
```

### Create Custom Form
```typescript
// 1. Create file
export function MyForm({ topicId, topicTitle, onSubmit }: SubmitFormProps) {
  return <div>Your UI</div>;
}

// 2. Import in config
import { MyForm } from "../app/components/submit-forms/MyForm";

// 3. Use in config
"10": {
  formComponent: MyForm,
}
```

---

## 🔧 Component Props

### SubmitFormProps
```typescript
interface SubmitFormProps {
  topicId: string;
  topicTitle: string;
  onSubmit: (data: any) => void;
}
```

### MediaUploadBox
```typescript
<MediaUploadBox
  type="image" | "video"
  uploadedFile={string | null}
  onUpload={(e) => void}
  onRemove={() => void}
  fileName?: string
  label?: string
  required?: boolean
/>
```

### TeammatesSection
```typescript
<TeammatesSection
  teammates={string[]}
  onAdd={() => void}
  onRemove={(index: number) => void}
  onChange={(index: number, value: string) => void}
/>
```

### FormInput
```typescript
<FormInput
  label={string}
  value={string}
  onChange={(value: string) => void}
  placeholder={string}
  multiline?: boolean
  rows?: number
/>
```

---

## 🎨 Styling Constants

```typescript
const inputStyle = {
  background: "linear-gradient(135deg, rgba(50, 107, 118, 0.6) 0%, rgba(32, 76, 106, 0.6) 100%)",
  border: "1.5px solid rgba(138, 206, 224, 0.3)",
  boxShadow: "0 4px 12px rgba(0, 0, 0, 0.2)",
};
```

---

## 📊 Topic Config Fields

```typescript
{
  id: string,                           // "1", "2", etc.
  title: string,                        // "تخته سیاه"
  description: string,                  // Short description
  accentColor: string,                  // "#8ACEE0"
  backgroundColor: string,              // "#0a1f2e"
  mediaType: "image" | "video" | "both",// NEW!
  requiresTeammates: boolean,           // NEW!
  formComponent: ComponentType,         // NEW!
  challenges: TopicChallenge[],
  chatbotIntro: string
}
```

---

## 🚀 Common Tasks

### Show/Hide Teammates
```typescript
// In config
requiresTeammates: true  // Shows section
requiresTeammates: false // Hides section
```

### Change Media Type
```typescript
// In config
mediaType: "image"  // ImageForm recommended
mediaType: "video"  // Create VideoForm
mediaType: "both"   // ImageVideoForm
```

### Custom Validation
```typescript
// In form component
const handleSubmit = () => {
  if (!title.trim()) {
    alert("عنوان الزامی است");
    return;
  }
  onSubmit(data);
};
```

### Custom Field
```typescript
// In form component
const [customField, setCustomField] = useState("");

<FormInput
  label="فیلد سفارشی"
  value={customField}
  onChange={setCustomField}
  placeholder="..."
/>
```

---

## 🐛 Common Issues

| Issue | Solution |
|-------|----------|
| Form not showing | Check import in topicConfig.ts |
| TypeScript error | Implement SubmitFormProps interface |
| Teammates always show | Set requiresTeammates: false |
| Wrong form renders | Check topicId mapping in config |
| Styles not applying | Check inputStyle is imported |

---

## 📋 Checklist for New Forms

- [ ] Component implements `SubmitFormProps`
- [ ] Uses shared components (MediaUploadBox, etc.)
- [ ] Follows RTL pattern (dir="rtl")
- [ ] Has submit button with validation
- [ ] Imports from correct paths
- [ ] Added to topicConfig.ts
- [ ] TypeScript compiles without errors
- [ ] Tested with real topicId

---

## 🔍 Testing URLs

```
/submit/1  → تخته سیاه (ImageForm)
/submit/2  → نیمکت (ImageVideoForm)
/submit/3  → دفترچه یادداشت (ImageForm)
/submit/4  → دیوار حیاط (ImageForm)
/submit/5  → آبخوری (ImageForm)
/submit/6  → زنگ ورزش (ImageForm)
/submit/7  → سه ماه تعطیلی (ImageForm)
/submit/8  → روزنامه دیواری (ImageForm)
/submit/9  → زنگ تفریح (ImageForm)
```

---

## 📚 Documentation Files

| File | Purpose |
|------|---------|
| `REFACTORING.md` | Detailed technical documentation |
| `REFACTORING_SUMMARY.md` | High-level overview |
| `MIGRATION_GUIDE.md` | Step-by-step migration instructions |
| `ARCHITECTURE_DIAGRAM.md` | Visual architecture diagrams |
| `QUICK_REFERENCE.md` | This file - quick lookup |

---

## 💡 Pro Tips

1. **Reuse shared components** - Don't create duplicate upload boxes
2. **Follow naming conventions** - `TopicNameForm.tsx` (PascalCase)
3. **Use config first** - Try existing forms before creating new
4. **Keep forms simple** - Move complex logic to separate hooks
5. **Test with Arabic** - Ensure RTL works correctly
6. **Check animations** - Use Motion for all interactions
7. **Type everything** - Avoid `any` types
8. **Document custom forms** - Add JSDoc comments

---

## 🎓 Key Principles

1. **Config-Driven** - Data drives UI, not code
2. **Single Responsibility** - One job per component
3. **DRY** - Don't Repeat Yourself
4. **Composition** - Build complex from simple
5. **Type Safety** - Full TypeScript coverage
6. **Testability** - Easy to unit test

---

## 📞 Quick Help

**Q: How do I add a new topic?**
A: Update topicConfig.ts, use existing form or create new

**Q: How do I customize a form?**
A: Edit the form component in `/submit-forms/`

**Q: How do I add a new field?**
A: Add state and FormInput in the form component

**Q: How do I change validation?**
A: Modify handleSubmit in the form component

**Q: Where are styles defined?**
A: In components using Tailwind + inline styles

---

## ⚡ Performance

- **Bundle size**: Same or smaller (tree-shaking)
- **Load time**: Faster (code-splitting)
- **Runtime**: Identical performance
- **Memory**: Slightly better (less duplication)

---

## ✅ Validation Examples

```typescript
// Required field
if (!title.trim()) {
  alert("عنوان الزامی است");
  return;
}

// Video cover required
if (mediaType === "video" && !videoCover) {
  // Button already disabled
  return;
}

// Min length
if (learnings.length < 10) {
  alert("توضیحات باید حداقل ۱۰ کاراکتر باشد");
  return;
}
```

---

## 🎯 Remember

✅ **DO:**
- Use existing components when possible
- Follow established patterns
- Update config for new topics
- Test with RTL
- Use TypeScript

❌ **DON'T:**
- Hardcode topicId checks
- Duplicate upload logic
- Mix layout with business logic
- Forget to import in config
- Use `any` types

---

**Keep this file handy for quick reference!** 📌