# מפרט Frontend — אתר ניהול מתכונים (Next.js App Router + TS + Tailwind, RTL)
---
## 1. עקרונות ארכיטקטורה
- **Server Components כברירת מחדל** לכל מה שהוא הצגת נתונים (SEO, TTFB, פחות JS ללקוח) — עמוד מתכון, דף תוצאות, דף בית.
- **Client Components** רק היכן שיש אינטראקציה: חיפוש, פאנל מסננים, שינוי כמויות, אשף היצירה, דיונים, פרופיל (טפסים).
- **React Query (TanStack Query)** בצד הלקוח לכל mutation / polling / cache אופטימי (לייקים, תגובות, autosave באשף). ל-Server Components שימוש ב-`fetch` עם `next: { revalidate }` / `tags` בלבד — **לא** React Query בשרת.
- **Zustand** (קליל מ-Redux) ל-state גלובלי בצד לקוח שאינו server-cache: מצב אשף היצירה (draft רב-שלבי), מסננים פתוחים/סגורים במובייל, מצב מנות נבחר בעמוד מתכון (יכול גם local state, ראה בהמשך).
- **URL כמקור אמת** לחיפוש ומסננים (searchParams) — מאפשר שיתוף קישור, ניווט אחורה, ו-SSR ידידותי ל-SEO.
```
package deps עיקריים:
next@14+, react, typescript, tailwindcss,
@tanstack/react-query, zustand,
@dnd-kit/core + @dnd-kit/sortable (drag&drop לאשף),
react-hook-form + zod (טפסים/ולידציה),
next/image, framer-motion (אנימציות עדינות),
radix-ui primitives (Dialog, Tabs, Accordion, Slider - accessible by default)
```
---
## 2. מבנה תיקיות
```
app/
├─ layout.tsx # RootLayout: , Providers
├─ globals.css
├─ providers.tsx # QueryClientProvider, ThemeProvider
├─ page.tsx # דף בית (/)
├─ (marketing)/
│ └─ loading.tsx / error.tsx
├─ search/
│ ├─ page.tsx # דף תוצאות /search?q=...&cat=...&time=...
│ ├─ SearchClient.tsx # קליינט: URL state, פאנל מסננים
│ └─ loading.tsx
├─ recipes/
│ ├─ [slug]/
│ │ ├─ page.tsx # עמוד מתכון (Server Component, generateMetadata)
│ │ ├─ opengraph-image.tsx
│ │ └─ loading.tsx
│ └─ new/
│ ├─ page.tsx # אשף יצירה - shell
│ └─ WizardClient.tsx
├─ profile/
│ ├─ page.tsx # פרופיל אישי (של המשתמש המחובר)
│ ├─ [username]/page.tsx # פרופיל ציבורי
│ └─ settings/page.tsx
├─ api/
│ ├─ recipes/route.ts
│ ├─ recipes/[id]/comments/route.ts
│ └─ upload/route.ts # presigned URL להעלאת תמונות
└─ not-found.tsx
components/
├─ ui/ # design-system גנרי (Button, Input, Badge, Skeleton...)
├─ home/
│ ├─ NaturalSearchBar.tsx
│ ├─ RecommendedCarousel.tsx
│ ├─ CategoryGrid.tsx
│ └─ RecipeCardMini.tsx
├─ search/
│ ├─ ResultCard.tsx
│ ├─ MatchReasonBadge.tsx
│ ├─ FiltersPanel.tsx
│ ├─ FilterChip.tsx
│ └─ SortDropdown.tsx
├─ recipe/
│ ├─ RecipeGallery.tsx
│ ├─ IngredientsList.tsx
│ ├─ ServingsStepper.tsx
│ ├─ StepsList.tsx
│ ├─ StepItem.tsx
│ ├─ DiscussionThread.tsx
│ ├─ CommentNode.tsx (רקורסיבי)
│ └─ NutritionPanel.tsx
├─ wizard/
│ ├─ WizardStepper.tsx
│ ├─ steps/
│ │ ├─ Step1Basics.tsx
│ │ ├─ Step2Photos.tsx # drag&drop
│ │ ├─ Step3Ingredients.tsx # drag&drop סדר
│ │ ├─ Step4Steps.tsx # drag&drop סדר שלבים
│ │ ├─ Step5NutritionTags.tsx
│ │ └─ Step6Review.tsx
│ ├─ AutosaveIndicator.tsx
│ └─ DraggableList.tsx (גנרי, @dnd-kit)
└─ profile/
├─ ProfileHeader.tsx
├─ MyRecipesGrid.tsx
├─ SavedCollections.tsx
└─ AccountSettingsForm.tsx
lib/
├─ api/ (fetchers: getRecipe, searchRecipes, ...)
├─ queryClient.ts
├─ store/ (zustand: wizardStore, uiStore)
├─ hooks/ (useServings, useDebouncedSearch, useAutosave)
├─ schemas/ (zod)
└─ types/
```
### Routing מסוכם
| Route | סוג | תיאור |
|---|---|---|
| `/` | Server | דף בית |
| `/search?q=&category=&time=&difficulty=&diet=` | Server + Client shell | תוצאות + מסננים ב-URL |
| `/recipes/[slug]` | Server | עמוד מתכון מלא |
| `/recipes/new` | Client (מוגן auth) | אשף 6 שלבים |
| `/recipes/[slug]/edit` | Client | עריכה — אותו אשף במצב edit |
| `/profile`, `/profile/[username]` | Server + Client parts | פרופיל |
---
## 3. דף הבית (`/`)
### קומפוננטות
- `NaturalSearchBar` (Client) — שדה חיפוש בשפה טבעית ("משהו קליל עם עוף בלי גלוטן") + debounce + הצעות autocomplete.
- `RecommendedCarousel` (Server data, Client לגלילה) — "מומלץ בשבילך" (מבוסס היסטוריה/מועדפים).
- `CategoryGrid` — קטגוריות (עוגות, צמחוני, ארוחת בוקר...) עם אייקון/תמונה.
- `RecipeCardMini` — כרטיס קטן משותף (משמש גם בקרוסלה וגם ב-grid).
### דוגמת קוד — `NaturalSearchBar`
```tsx
// components/home/NaturalSearchBar.tsx
'use client';
import { useState, useTransition, useDeferredValue } from 'react';
import { useRouter } from 'next/navigation';
import { Search } from 'lucide-react';
export function NaturalSearchBar() {
const [query, setQuery] = useState('');
const deferredQuery = useDeferredValue(query);
const [isPending, startTransition] = useTransition();
const router = useRouter();
function handleSubmit(e: React.FormEvent) {
e.preventDefault();
if (!query.trim()) return;
startTransition(() => {
router.push(`/search?q=${encodeURIComponent(query)}`);
});
}
return (
);
}
```
> שימו לב: `dir="rtl"` מוגדר ברמת ``, כך שהאייקון ממוקם אוטומטית מימין (`right-3`) — מומלץ להשתמש ב-Tailwind logical properties (`ps-`, `pe-`, `me-`, `ms-`) במקום `pr-`/`pl-` כדי שהעיצוב יהיה RTL-safe מקצה לקצה.
### דוגמת קוד — `page.tsx` (דף בית, Server Component)
```tsx
// app/page.tsx
import { NaturalSearchBar } from '@/components/home/NaturalSearchBar';
import { RecommendedCarousel } from '@/components/home/RecommendedCarousel';
import { CategoryGrid } from '@/components/home/CategoryGrid';
import { getRecommendedRecipes, getCategories } from '@/lib/api/home';
export const revalidate = 300; // ISR - 5 דקות
export default async function HomePage() {
const [recommended, categories] = await Promise.all([
getRecommendedRecipes(),
getCategories(),
]);
return (
);
}
```
---
## 4. דף תוצאות (`/search`)
### דפוס: Server Component קורא searchParams → מביא נתונים → מעביר ל-Client רק את הצורך
```tsx
// app/search/page.tsx
import { searchRecipes } from '@/lib/api/search';
import { ResultsGrid } from '@/components/search/ResultsGrid';
import { FiltersPanel } from '@/components/search/FiltersPanel';
interface Props {
searchParams: {
q?: string; category?: string; time?: string;
difficulty?: string; diet?: string; sort?: string; page?: string;
};
}
export default async function SearchPage({ searchParams }: Props) {
const results = await searchRecipes(searchParams); // Server fetch, כולל "match reasons"
return (
{results.total} תוצאות עבור "{searchParams.q ?? 'הכל'}"
);
}
```
### קומפוננטות
- `FiltersPanel` (Client) — Radix `Accordion`/`Checkbox`/`Slider`, כותב ל-URL (`router.push` עם `useSearchParams` + `URLSearchParams`), לא שומר state כפול.
- `ResultCard` — תמונה lazy, כותרת, "סיבת התאמה", תגיות (זמן, קושי, דיאטה).
- `MatchReasonBadge` — מסביר *למה* המתכון עלה (למשל "מכיל 4/5 מהמצרכים שחיפשת").
- `SortDropdown`.
### דוגמת קוד — `ResultCard` + `MatchReasonBadge`
```tsx
// components/search/ResultCard.tsx
import Image from 'next/image';
import Link from 'next/link';
import { MatchReasonBadge } from './MatchReasonBadge';
import { Clock, ChefHat } from 'lucide-react';
export interface ResultCardProps {
slug: string;
title: string;
imageUrl: string;
timeMinutes: number;
difficulty: 'קל' | 'בינוני' | 'מאתגר';
matchReason: string; // "כולל 4 מתוך 5 מרכיבים שחיפשת"
matchScore: number; // 0-100
}
export function ResultCard({
slug, title, imageUrl, timeMinutes, difficulty, matchReason, matchScore,
}: ResultCardProps) {
return (
{title}
{timeMinutes} דק'
{difficulty}
);
}
```
```tsx
// components/search/MatchReasonBadge.tsx
export function MatchReasonBadge({ score, reason }: { score: number; reason: string }) {
return (
✨
{reason}
{` (התאמה ${score}%)`}
);
}
```
### פאנל מסננים — כתיבה ל-URL בלי לאבד היסטוריית ניווט
```tsx
// components/search/FiltersPanel.tsx
'use client';
import { useRouter, useSearchParams, usePathname } from 'next/navigation';
import { useCallback } from 'react';
export function FiltersPanel({ initialFilters }: { initialFilters: Record }) {
const router = useRouter();
const pathname = usePathname();
const searchParams = useSearchParams();
const setFilter = useCallback((key: string, value: string | null) => {
const params = new URLSearchParams(searchParams.toString());
if (value) params.set(key, value); else params.delete(key);
params.delete('page'); // איפוס עימוד בעת שינוי מסנן
router.push(`${pathname}?${params.toString()}`, { scroll: false });
}, [router, pathname, searchParams]);
return (
);
}
```
---
## 5. עמוד מתכון (`/recipes/[slug]`)
### מבנה: Server Component טוען את המתכון + `generateMetadata` ל-SEO; חלקים אינטראקטיביים (מנות, דיון) הם Client Components "עלים" (islands).
```tsx
// app/recipes/[slug]/page.tsx
import { getRecipeBySlug } from '@/lib/api/recipes';
import { RecipeGallery } from '@/components/recipe/RecipeGallery';
import { IngredientsList } from '@/components/recipe/IngredientsList';
import { StepsList } from '@/components/recipe/StepsList';
import { DiscussionThread } from '@/components/recipe/DiscussionThread';
import { notFound } from 'next/navigation';
export async function generateMetadata({ params }: { params: { slug: string } }) {
const recipe = await getRecipeBySlug(params.slug);
if (!recipe) return {};
return { title: recipe.title, description: recipe.description };
}
export default async function RecipePage({ params }: { params: { slug: string } }) {
const recipe = await getRecipeBySlug(params.slug);
if (!recipe) notFound();
return (
{recipe.title}
{/* מרכיבים - Client עלה בגלל שינוי כמויות */}
דיון ותגובות ({recipe.commentCount})
);
}
```
### `RecipeGallery` — Lazy loading, תמונה ראשונה priority
```tsx
// components/recipe/RecipeGallery.tsx
'use client';
import Image from 'next/image';
import { useState } from 'react';
export function RecipeGallery({ images }: { images: { url: string; alt: string }[] }) {
const [active, setActive] = useState(0);
return (
{images.length > 1 && (
{images.map((img, i) => (
))}
)}
);
}
```
### `IngredientsList` + `ServingsStepper` — שינוי כמויות לפי מספר מנות
חישוב יחסי (scale factor), בלי לגעת בשרת:
```tsx
// components/recipe/IngredientsList.tsx
'use client';
import { useState, useMemo } from 'react';
import { ServingsStepper } from './ServingsStepper';
interface Ingredient {
id: string;
name: string;
quantity: number;
unit: string;
}
export function IngredientsList({
ingredients, baseServings,
}: { ingredients: Ingredient[]; baseServings: number }) {
const [servings, setServings] = useState(baseServings);
const scale = servings / baseServings;
const scaled = useMemo(
() => ingredients.map((ing) => ({
...ing,
displayQuantity: formatQuantity(ing.quantity * scale),
})),
[ingredients, scale]
);
return (
מרכיבים
{scaled.map((ing) => (
-
{ing.name}
{ing.displayQuantity} {ing.unit}
))}
);
}
// עיגול "יפה" (1/4, 1/2, 3/4) לצגית מתכונים
function formatQuantity(n: number): string {
const rounded = Math.round(n * 4) / 4;
const whole = Math.floor(rounded);
const frac = rounded - whole;
const fracMap: Record = { 0.25: '¼', 0.5: '½', 0.75: '¾' };
return `${whole || ''}${fracMap[frac] ?? ''}`.trim() || '0';
}
```
```tsx
// components/recipe/ServingsStepper.tsx
'use client';
export function ServingsStepper({
value, onChange, min = 1, max = 20,
}: { value: number; onChange: (v: number) => void; min?: number; max?: number }) {
return (
{value} מנות
);
}
```
### `DiscussionThread` / `CommentNode` — דיון מקונן, React Query + optimistic update
```tsx
// components/recipe/DiscussionThread.tsx
'use client';
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { CommentNode } from './CommentNode';
import { fetchComments, postComment } from '@/lib/api/comments';
import { useState } from 'react';
export function DiscussionThread({
recipeId, initialComments,
}: { recipeId: string; initialComments: Comment[] }) {
const queryClient = useQueryClient();
const [text, setText] = useState('');
const { data: comments } = useQuery({
queryKey: ['comments', recipeId],
queryFn: () => fetchComments(recipeId),
initialData: initialComments,
staleTime: 30_000,
});
const mutation = useMutation({
mutationFn: (payload: { text: string; parentId?: string }) =>
postComment(recipeId, payload),
onMutate: async (payload) => {
await queryClient.cancelQueries({ queryKey: ['comments', recipeId] });
const previous = queryClient.getQueryData(['comments', recipeId]);
const optimistic: Comment = {
id: `temp-${crypto.randomUUID()}`,
text: payload.text,
parentId: payload.parentId ?? null,
author: { name: 'אני', avatarUrl: '' },
replies: [],
createdAt: new Date().toISOString(),
pending: true,
};
queryClient.setQueryData(['comments', recipeId], (old) =>
insertComment(old ?? [], optimistic));
return { previous };
},
onError: (_err, _payload, context) => {
if (context?.previous) {
queryClient.setQueryData(['comments', recipeId], context.previous);
}
},
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['comments', recipeId] });
},
});
return (