@matteoaliano/forest-ui 0.4.0 → 0.4.2

package/guidelines/FOREST_FE_GUIDELINES.md

@@ -1,543 +0,0 @@
-# Forest UI — Development Best Practices
-
-> **forest-ui v0.4.0**
-
-> **This file is synced by the `forest-ui` package.**
-> Run `npx forest-ui sync` to update it.
-
-# Next.js Code Agent - v2.0
-
-## CORE PHILOSOPHY
-
-1. **Server First**: Default Server Components, `'use client'` solo quando necessario
-2. **Type Everything**: TypeScript strict, zero `any`
-3. **Single Responsibility**: Ogni file = 1 job, pagine = orchestratori puri
-4. **Separation of Concerns**: Logica separata da presentazione, data access isolato
-5. **Explicit > Implicit**: Codice auto-documentante, no magic
-
----
-
-## 1. ARCHITETTURA & STRUTTURA
-
-### File System Organization
-```
-/app                    # App Router (Next.js 13+)
-  /(routes)/           # Route groups
-  /api/                # API routes
-  /[route]/
-    page.tsx           # Pagina (max 20 righe, solo orchestrazione)
-    layout.tsx         # Layout condiviso
-    loading.tsx        # Loading UI
-    error.tsx          # Error handling
-/components
-  /ui/                # Design system base (Button, Card, Input...)
-  /features/          # Feature-specific (UserCard, ProductGrid...)
-/lib
-  /actions/           # Server Actions (mutations)
-  /queries/           # Data fetching (read operations)
-  /hooks/             # Custom React hooks
-  /utils/             # Pure utility functions
-  /services/          # Business logic complessa
-  /parsers/           # URL params & form data parsing
-  /validations/       # Zod schemas
-/types                # TypeScript interfaces/types
-/public               # Static assets
-```
-
-### Naming Conventions
-- **Componenti**: `PascalCase.tsx` (UserCard.tsx)
-- **Hooks**: `use[Name].ts` (useDebounce.ts)
-- **Actions**: `[entity].actions.ts` (user.actions.ts)
-- **Queries**: `[entity].queries.ts` (user.queries.ts)
-- **Utils**: `[entity].util.ts` (format.util.ts)
-- **Parsers**: `[entity].parser.ts` (product.parser.ts)
-- **Services**: `[entity].service.ts` (analytics.service.ts)
-
----
-
-## 2. SINGLE RESPONSIBILITY - PAGE LEVEL
-
-### Regola d'Oro
-**Una pagina Next.js ha 1 sola responsabilità: "Comporre UI per questa route"**
-
-### Pagina Ideale (Template)
-```typescript
-// app/products/page.tsx - Max 20 righe
-import { getProducts } from '@/lib/queries/product.queries';
-import { ProductGrid } from '@/components/features/products/ProductGrid';
-
-export default async function ProductsPage() {
-  const products = await getProducts(); // Delega fetch
-  return <ProductGrid products={products} />; // Delega UI
-}
-```
-
-### ❌ Una pagina NON deve:
-- Costruire query complesse (>5 righe di logic)
-- Fare trasformazioni dati (.map/.filter/.reduce con logica)
-- Validare o parsare parametri inline
-- Gestire errori con try/catch (usa error.tsx)
-- Contenere JSX >50 righe (estrai componenti)
-- Avere calcoli o aggregazioni
-- Gestire state (useState, useReducer)
-
-### ✅ Una pagina deve:
-- Chiamare 1-3 funzioni di data fetching (in parallelo con Promise.all se >1)
-- Comporre componenti feature
-- Passare props ai componenti
-- **Nient'altro**
-
----
-
-## 3. SEPARATION OF CONCERNS - EXTRACTION PATTERNS
-
-### Data Fetching → lib/queries/
-**Responsabilità:** Read operations, DB access, API calls
-```typescript
-// lib/queries/product.queries.ts
-'use server'
-
-export async function getProducts(): Promise<Product[]> {
-  return await db.product.findMany({
-    where: { status: 'active' },
-    orderBy: { createdAt: 'desc' }
-  });
-}
-
-export async function getProductById(id: string): Promise<Product | null> {
-  return await db.product.findUnique({ where: { id } });
-}
-```
-
-### Mutations → lib/actions/
-**Responsabilità:** Create, Update, Delete operations
-```typescript
-// lib/actions/product.actions.ts
-'use server'
-
-import { revalidatePath } from 'next/cache';
-import { productSchema } from '@/lib/validations/product.schema';
-
-export async function createProduct(formData: FormData) {
-  const parsed = productSchema.safeParse(Object.fromEntries(formData));
-  if (!parsed.success) return { error: parsed.error };
-
-  const product = await db.product.create({ data: parsed.data });
-  revalidatePath('/products');
-
-  return { success: true, product };
-}
-```
-
-### URL Parsing → lib/parsers/
-**Responsabilità:** Validare e parsare searchParams, form data
-```typescript
-// lib/parsers/product.parser.ts
-import { z } from 'zod';
-
-const filterSchema = z.object({
-  category: z.string().default('all'),
-  sort: z.enum(['asc', 'desc']).default('desc'),
-  page: z.coerce.number().int().min(1).default(1)
-});
-
-export function parseProductFilters(params: Record<string, string | undefined>) {
-  return filterSchema.parse(params);
-}
-```
-
-### Pure Logic → lib/utils/
-**Responsabilità:** Funzioni pure (input → output, no side effects)
-```typescript
-// lib/utils/product.util.ts
-
-export function calculateDiscount(price: number, discountPercent: number): number {
-  return price * (1 - discountPercent / 100);
-}
-
-export function formatPrice(amount: number): string {
-  return new Intl.NumberFormat('it-IT', {
-    style: 'currency',
-    currency: 'EUR'
-  }).format(amount);
-}
-
-export function isRecentProduct(createdAt: Date): boolean {
-  const daysSinceCreation = (Date.now() - createdAt.getTime()) / (1000 * 60 * 60 * 24);
-  return daysSinceCreation <= 30;
-}
-```
-
-### Complex Business Logic → lib/services/
-**Responsabilità:** Orchestrazione multi-entity, calcoli complessi, aggregazioni
-```typescript
-// lib/services/analytics.service.ts
-'use server'
-
-import { getOrders } from '@/lib/queries/order.queries';
-import { getProducts } from '@/lib/queries/product.queries';
-
-export async function calculateDashboardStats(userId: string) {
-  const [orders, products] = await Promise.all([
-    getOrders(userId),
-    getProducts()
-  ]);
-
-  return {
-    totalRevenue: orders.reduce((sum, o) => sum + o.total, 0),
-    avgOrderValue: orders.length > 0 ? orders.reduce((sum, o) => sum + o.total, 0) / orders.length : 0,
-    topProducts: calculateTopProducts(orders, products),
-    conversionRate: calculateConversionRate(orders, products)
-  };
-}
-```
-
-### Client Logic → lib/hooks/
-**Responsabilità:** Stateful logic riutilizzabile, side effects
-```typescript
-// lib/hooks/useProductFilters.ts
-'use client'
-
-import { useState, useMemo } from 'react';
-
-export function useProductFilters(products: Product[]) {
-  const [search, setSearch] = useState('');
-  const [category, setCategory] = useState<string>('all');
-
-  const filtered = useMemo(() => {
-    return products.filter(p => {
-      const matchesSearch = p.name.toLowerCase().includes(search.toLowerCase());
-      const matchesCategory = category === 'all' || p.category === category;
-      return matchesSearch && matchesCategory;
-    });
-  }, [products, search, category]);
-
-  return { filtered, search, setSearch, category, setCategory };
-}
-```
-
-### Validation → lib/validations/
-**Responsabilità:** Zod schemas, validation rules
-```typescript
-// lib/validations/product.schema.ts
-import { z } from 'zod';
-
-export const productSchema = z.object({
-  name: z.string().min(3).max(100),
-  price: z.number().positive(),
-  category: z.enum(['electronics', 'clothing', 'food']),
-  description: z.string().max(500).optional()
-});
-
-export type ProductInput = z.infer<typeof productSchema>;
-```
-
----
-
-## 4. REFACTORING MODE
-
-### Auto-Trigger Refactoring quando:
-- File pagina >50 righe
-- File componente >150 righe
-- Più di 1 await non in Promise.all
-- Try/catch in pagina (usa error.tsx)
-- Logica trasformazione dati in pagina (.map/.filter con >1 riga)
-- Duplicazione codice (>2 occorrenze stesso pattern)
-
-### Processo Refactoring (3 Fasi)
-
-#### FASE 1: AUDIT
-```markdown
-Analizza file e identifica:
-
-🔴 CRITICAL (Refactoring obbligatorio):
-- [ ] Mixing concerns (fetch + validation + UI stesso file)
-- [ ] Logica business in componenti UI
-- [ ] File >200 righe
-- [ ] Funzioni >50 righe
-- [ ] `any` types presenti
-- [ ] Prop drilling >3 livelli
-
-🟡 WARNINGS (Miglioramento consigliato):
-- [ ] Codice duplicato (>2 occorrenze)
-- [ ] Nomi generici (data, item, temp)
-- [ ] Magic numbers/strings
-- [ ] Nessun error handling
-
-Genera report: problemi + metriche + priorità
-```
-
-#### FASE 2: PLAN
-```markdown
-Proponi struttura target:
-
-Before (PROBLEMA):
-❌ app/products/page.tsx (250 righe)
-   ├─ Fetch + trasformazioni
-   ├─ Validazione
-   ├─ Logica filtri
-   └─ UI rendering
-
-After (SOLUZIONE):
-✅ app/products/page.tsx (15 righe) - Orchestrazione
-✅ lib/queries/product.queries.ts (60 righe) - Data access
-✅ lib/utils/product.util.ts (30 righe) - Trasformazioni
-✅ lib/parsers/product.parser.ts (20 righe) - Validation
-✅ components/features/products/ProductGrid.tsx (80 righe) - UI
-✅ lib/hooks/useProductFilters.ts (40 righe) - Client logic
-```
-
-#### FASE 3: REFACTOR (Step-by-Step)
-```markdown
-Implementa in questo ordine:
-
-1. Types & Validation → types/ + validations/
-2. Pure Utils → lib/utils/
-3. Parsers → lib/parsers/
-4. Queries → lib/queries/
-5. Actions → lib/actions/
-6. Services → lib/services/ (se necessario)
-7. Hooks → lib/hooks/ (client logic)
-8. Components → components/features/
-9. Page Rebuild → app/[route]/page.tsx (minimalista)
-10. Error/Loading → error.tsx, loading.tsx
-
-Ogni step: commit separato, testabile incrementalmente
-```
-
-### SRP Compliance Score
-```
-Score = 100 - penalità
-
-Penalità pagine:
-- Righe codice: -1 ogni 10 oltre 20
-- Await multipli: -5 se >1 (non in Promise.all)
-- Nesting depth: -10 ogni livello oltre 2
-- Inline JSX: -2 ogni 10 righe oltre 30
-- Try/catch: -15
-- Transformazioni: -5 per ogni .map/.filter/.reduce
-- Validazioni inline: -10
-
-Target: Score ≥ 80
-```
-
----
-
-## 5. COMPONENT PATTERNS
-
-### Server Components (Default)
-```typescript
-// ✅ Server Component - Fetch diretto
-export default async function ProductPage({ params }: { params: { id: string } }) {
-  const product = await getProductById(params.id);
-  return <ProductDetail product={product} />;
-}
-```
-
-### Client Components
-```typescript
-// ✅ Client Component - Solo quando necessario
-'use client'
-
-export function ProductFilters({ onFilterChange }: Props) {
-  const [search, setSearch] = useState('');
-  // Interattività, hooks, browser APIs
-}
-```
-
-### Composition Over Configuration
-```typescript
-// ✅ Preferisci
-<Card>
-  <CardHeader>{title}</CardHeader>
-  <CardContent>{children}</CardContent>
-</Card>
-
-// ❌ Evita props drilling
-<Card title={title} content={content} footer={footer} />
-```
-
----
-
-## 6. TYPESCRIPT STRICT
-```typescript
-// ✅ Type safety completo
-interface UserCardProps {
-  user: User;
-  onEdit?: (id: string) => Promise<void>;
-}
-
-export function UserCard({ user, onEdit }: UserCardProps) {
-  // Implementation
-}
-
-// ❌ Evita any
-function Component({ data }: { data: any }) { ... }
-
-// ✅ Usa unknown + narrowing se tipo incerto
-function processData(data: unknown) {
-  if (typeof data === 'object' && data !== null && 'id' in data) {
-    // Safe to use data.id
-  }
-}
-```
-
----
-
-## 7. PERFORMANCE
-```typescript
-// ✅ Dynamic imports
-const HeavyChart = dynamic(() => import('./HeavyChart'), {
-  loading: () => <Skeleton />,
-  ssr: false
-});
-
-// ✅ Parallel data fetching
-const [products, categories] = await Promise.all([
-  getProducts(),
-  getCategories()
-]);
-
-// ✅ Image optimization
-import Image from 'next/image';
-<Image src={src} alt={alt} width={500} height={300} />
-
-// ❌ Mai
-<img src={src} alt={alt} />
-```
-
----
-
-## 8. ERROR HANDLING
-```typescript
-// ✅ Error boundaries dedicated
-// app/products/error.tsx
-'use client'
-
-export default function Error({ error, reset }: {
-  error: Error;
-  reset: () => void;
-}) {
-  return <ErrorBoundary error={error} onReset={reset} />;
-}
-
-// ✅ Safe data access
-const userName = user?.profile?.name ?? 'Guest';
-
-// ✅ Server Action error handling
-export async function createUser(formData: FormData) {
-  const parsed = userSchema.safeParse(Object.fromEntries(formData));
-  if (!parsed.success) {
-    return { error: parsed.error.format() };
-  }
-  // ... resto logica
-}
-```
-
----
-
-## 9. OUTPUT STANDARDS
-
-Quando generi codice, fornisci sempre:
-
-1. **File Path** completo
-2. **Imports** ordinati (external → @/ → relative)
-3. **Types/Interfaces** prima dell'implementazione
-4. **Implementation** con commenti su logica complessa
-5. **Usage Example** se non ovvio
-```typescript
-// File: lib/queries/user.queries.ts
-
-import { db } from '@/lib/db';
-import type { User } from '@/types/user.types';
-
-/**
- * Recupera utenti attivi con i loro profili
- * @returns Array di utenti con relazioni caricate
- */
-export async function getActiveUsers(): Promise<User[]> {
-  return await db.user.findMany({
-    where: { status: 'active' },
-    include: { profile: true }
-  });
-}
-```
-
----
-
-## 10. PRE-DELIVERY CHECKLIST
-
-Prima di consegnare codice, verifica:
-
-**TypeScript:**
-- [ ] Zero errori TS
-- [ ] Zero `any` (usa `unknown` se necessario)
-- [ ] Tutte props/functions tipizzate
-
-**Architecture:**
-- [ ] Server Components dove possibile
-- [ ] Pagine <20 righe (solo orchestrazione)
-- [ ] Zero logica business in componenti UI
-- [ ] File <150 righe (split se necessario)
-
-**Code Quality:**
-- [ ] Import ordinati (external → @ → relative)
-- [ ] Naming conventions rispettate
-- [ ] Single responsibility rispettata
-- [ ] Zero codice duplicato
-- [ ] Nomi espliciti (no `data`, `temp`, `x`)
-
-**Safety:**
-- [ ] Error handling presente
-- [ ] Safe data access (optional chaining)
-- [ ] Input validation (Zod per form/API)
-- [ ] No magic numbers/strings
-
-**Performance:**
-- [ ] `next/image` per immagini
-- [ ] Dynamic imports per componenti pesanti
-- [ ] Parallel fetch con Promise.all
-
----
-
-## CONTEXT LOADING (Per documentazione dettagliata)
-
-Se task coinvolge:
-- **Refactoring pagine** → Rileggi questa sezione 3
-- **Separation of concerns** → Rileggi sezione 3 + esempi
-- **Performance optimization** → Focus su sezione 7
-- **Error handling** → Focus su sezione 8
-
----
-
-## QUICK REFERENCE
-```typescript
-// ✅ PAGINA IDEALE
-export default async function Page() {
-  const data = await getData();
-  return <Feature data={data} />;
-}
-
-// ✅ SERVER ACTION
-'use server'
-export async function createItem(formData: FormData) {
-  const parsed = schema.safeParse(...);
-  if (!parsed.success) return { error: ... };
-  const item = await db.create(...);
-  revalidatePath('/items');
-  return { success: true, item };
-}
-
-// ✅ CUSTOM HOOK
-'use client'
-export function useFilters<T>(items: T[], filterFn: (item: T) => boolean) {
-  const [filtered, setFiltered] = useState(items);
-  // Logic...
-  return { filtered, /* ... */ };
-}
-```
-
----
-
-**Versione:** 2.0
-**Focus:** SRP + Separation of Concerns + Context Efficiency