` (show only on mobile)
**Color Palette**:
- Primary: `blue-500` (#2563eb)
- Success: `green-500`
- Danger: `red-500`
- Backgrounds: `gray-50`, `gray-100`
- Text: `gray-700`, `gray-900`
---
### Form Validation
**Pattern**: Client-side validation before API calls
```typescript
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault()
// Validation
if (!name.trim()) {
alert('Name is required')
return
}
if (quantity <= 0) {
alert('Quantity must be greater than 0')
return
}
// API call
const response = await fetch('/api/ingredients', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data)
})
if (response.ok) {
onSaved?.()
}
}
```
---
## Component Architecture
### Page Components (`/app/dashboard/*/page.tsx`)
**Responsibilities**:
1. Fetch data from API routes
2. Manage filter/pagination state
3. Orchestrate modals
4. Pass data to display components
**Structure**:
```typescript
'use client'
export default function IngredientsPage() {
// State
const [data, setData] = useState([])
const [filters, setFilters] = useState({})
const [modals, setModals] = useState({ add: false, view: false })
// Data fetching
useEffect(() => { /* fetch */ }, [filters])
// Render
return (
<>
)
}
```
---
### Modal Components
#### Add/Edit Modal Pattern
```typescript
export default function AddEntityModal({ open, onClose, onSaved, entityId }: ModalProps) {
const [formData, setFormData] = useState({ /* fields */ })
const isEditMode = !!entityId
useEffect(() => {
if (isEditMode && open) {
// Fetch existing data
fetch(`/api/entities/${entityId}`).then(/* populate form */)
} else {
// Reset form
setFormData({ /* defaults */ })
}
}, [entityId, open])
const handleSubmit = async () => {
const method = isEditMode ? 'PUT' : 'POST'
const url = isEditMode ? `/api/entities/${entityId}` : '/api/entities'
const response = await fetch(url, {
method,
body: JSON.stringify(formData)
})
if (response.ok) {
onSaved?.()
}
}
if (!open) return null
return (
)
}
```
---
#### View Modal Pattern
```typescript
export default function ViewEntityModal({ open, onClose, entityId }: ModalProps) {
const [entity, setEntity] = useState
(null)
useEffect(() => {
if (open && entityId) {
fetch(`/api/entities/${entityId}`)
.then(res => res.json())
.then(setEntity)
}
}, [open, entityId])
if (!open || !entity) return null
return (
{/* Read-only display */}
)
}
```
---
### Table/Display Components
**Props Pattern**:
```typescript
interface TableProps {
items: Item[]
onView: (id: string) => void
onEdit: (id: string) => void
onDelete: (id: string) => void
}
```
**Responsive Pattern**:
```tsx
{/* Desktop: Table */}
{/* Mobile: Cards */}
{items.map(item => (
{/* card content */}
))}
Total: €{totalPrice.toFixed(2)}
```
**Step 3**: Optional - Save to database
```typescript
const handleSubmit = async () => {
const data = {
quantity,
unitPrice,
vat,
totalPrice // Include computed value
}
await fetch('/api/ingredients', { method: 'POST', body: JSON.stringify(data) })
}
```
---
### 4. Adding Inline Creation to Dropdowns
**Pattern from `AddIngredientModal.tsx`**:
**Step 1**: Add state for inline form
```typescript
const [showInlineCategory, setShowInlineCategory] = useState(false)
const [newCategoryName, setNewCategoryName] = useState('')
```
**Step 2**: Conditional rendering
```tsx
{showInlineCategory ? (
setNewCategoryName(e.target.value)}
placeholder="New category name"
/>
) : (
<>
)}
```
**Step 3**: Handle creation
```typescript
const handleCreateCategory = async () => {
const response = await fetch('/api/categories', {
method: 'POST',
body: JSON.stringify({ name: newCategoryName })
})
const data = await response.json()
setCategories([...categories, { _id: data.insertedId, name: newCategoryName }])
setSelectedCategory(data.insertedId)
setShowInlineCategory(false)
}
```
---
### 5. Adding Search Functionality
**Step 1**: Add search state
```typescript
const [searchTerm, setSearchTerm] = useState('')
```
**Step 2**: Debounced API call
```typescript
useEffect(() => {
const timer = setTimeout(() => {
fetchData() // Includes searchTerm in API call
}, 300)
return () => clearTimeout(timer)
}, [searchTerm])
```
**Step 3**: API route with case-insensitive search
```typescript
const searchTerm = searchParams.get('search')
const query: any = {}
if (searchTerm) {
query.$or = [
{ name: { $regex: searchTerm, $options: 'i' } },
{ code: { $regex: searchTerm, $options: 'i' } }
]
}
const items = await db.collection('entities').find(query)
```
---
### 6. Adding Pagination
**Pattern** (already implemented in ingredients):
**State**:
```typescript
const [currentPage, setCurrentPage] = useState(1)
const [totalPages, setTotalPages] = useState(1)
const itemsPerPage = 10
```
**API call**:
```typescript
const params = new URLSearchParams({
page: currentPage.toString(),
limit: itemsPerPage.toString()
})
const response = await fetch(`/api/entities?${params}`)
const data = await response.json()
setTotalPages(Math.ceil(data.total / itemsPerPage))
```
**API route**:
```typescript
const page = parseInt(searchParams.get('page') || '1')
const limit = parseInt(searchParams.get('limit') || '10')
const items = await db.collection('entities')
.find(query)
.skip((page - 1) * limit)
.limit(limit)
.toArray()
const total = await db.collection('entities').countDocuments(query)
return NextResponse.json({ items, total })
```
**UI**:
```tsx
Page {currentPage} of {totalPages}
```
---
## Best Practices Checklist
When adding new code, ensure you follow these practices:
**TypeScript**:
- [ ] All interfaces defined in `/lib/types.ts`
- [ ] Proper typing for props, state, and API responses
- [ ] Use `WithRefs` pattern for aggregated data
**Components**:
- [ ] Use `'use client'` for interactive components
- [ ] Modal components follow standard prop interface
- [ ] Responsive design with Tailwind breakpoints
- [ ] Reusable class variables for consistent styling
**API Routes**:
- [ ] Proper HTTP methods (GET, POST, PUT, DELETE)
- [ ] Error handling with appropriate status codes
- [ ] Timestamps (`createdAt`, `updatedAt`) on write operations
- [ ] Use aggregation for joins when displaying related data
**Data Flow**:
- [ ] `useState` for component state
- [ ] `useEffect` for data fetching
- [ ] `useCallback` for memoized functions
- [ ] `useMemo` for derived/computed values
**Forms**:
- [ ] Client-side validation before API calls
- [ ] Loading states during submissions
- [ ] Success/error feedback to users
- [ ] Reset form after successful submission
**Code Organization**:
- [ ] Page components orchestrate, display components render
- [ ] API routes in `/app/api/[resource]/`
- [ ] Shared components in `/components/` (only if reused across multiple pages)
- [ ] Page-specific components stay in the page's folder, NOT in global `/components/`
- [ ] Utilities/types in `/lib/`
**Testing**:
- [ ] API route tests mock `getDb()` and test each HTTP method
- [ ] Component tests mock `fetch` and use `within(container)` queries
- [ ] Cover validation errors, edge cases, and error paths
- [ ] Call `cleanup()` in `afterEach` for component tests
- [ ] Run `npx vitest run` before committing to verify all tests pass
---
## Common Patterns Reference
### Auto-Generated Codes
```typescript
// Get next code number
const lastIngredient = await db.collection('ingredients')
.find({})
.sort({ code: -1 })
.limit(1)
.toArray()
const nextNumber = lastIngredient.length > 0
? parseInt(lastIngredient[0].code.split('-')[1]) + 1
: 1
const code = `ING-${String(nextNumber).padStart(3, '0')}`
```
### Price Calculations
```typescript
const netPrice = grossPrice * (1 + vat / 100)
// With discount
const effectiveGross = applyDiscountToGross
? grossPrice - discount
: grossPrice
const effectiveNet = applyDiscountToGross
? effectiveGross * (1 + vat / 100)
: netPrice - discount
```
### Conditional Rendering
```typescript
{loading ? (
Loading...
) : items.length === 0 ? (
No items found
) : (
)}
```
---
**Last Updated**: 2026-02-12
**Version**: 1.0