@matteoaliano/forest-ui 0.2.9 → 0.2.11

package/dist/theme.mjs

@@ -1,3 +1,3 @@
-export { alkemyPlusPreset, alpha, avatarColors, bg, border, breadcrumbColors, buildTheme, buildThemeOptions, buttonColors, chartColors, colors, components, container, display, fg, focusRings, fontFamily, fontSize, fontWeight, forestPreset, forestTheme, forestThemeOptions, getAvailablePresets, getPreset, iconColors, lineHeight, navColors, palette, radius, registerPreset, shadows2 as shadows, sliderColors, spacing, text, toggleColors, typography, widths } from './chunk-QF5T6J4D.mjs';
+export { alkemyPlusPreset, alpha, avatarColors, bg, border, breadcrumbColors, buildTheme, buildThemeOptions, buttonColors, chartColors, colors, components, container, display, fg, focusRings, fontFamily, fontSize, fontWeight, forestPreset, forestTheme, forestThemeOptions, getAvailablePresets, getPreset, iconColors, lineHeight, navColors, palette, radius, registerPreset, shadows2 as shadows, sliderColors, spacing, text, toggleColors, typography, widths } from './chunk-6W3RIXXY.mjs';
 //# sourceMappingURL=theme.mjs.map
 //# sourceMappingURL=theme.mjs.map

package/guidelines/FOREST_BE_GUIDELINES.md

@@ -0,0 +1,90 @@
+# FastAPI API Project: Requirements & Best Practices
+
+> **forest-ui v0.2.11**
+
+> **This file is synced by the `forest-ui` package.**
+> Run `npx forest-ui sync` to update it.
+
+---
+
+**Stack:** FastAPI (with dependency injection), Python >=3.9 (via Poetry), PostgreSQL/SQL Server, Redis cache, OpenTelemetry, on-prem Kubernetes. Frontend on Vercel, authentication via Clerk, CI/CD with GitHub Actions, Docker images in Azure Container Registry (ACR) deployed to the cluster.
+
+FastAPI is a modern Python web framework built on Starlette and Pydantic. It offers an intuitive dependency-injection system for shared components like DB sessions or auth. Pydantic models automatically validate and parse request data. Organize code into an `app` Python package (with `app/main.py`, sub-packages for routers and a `dependencies.py`) so that imports work cleanly. Use **APIRouters** to group related endpoints and share tags/dependencies. Declare shared logic (auth checks, DB, etc.) as FastAPI dependencies (`Depends(...)`) in `app/dependencies.py` for reuse. Keep path operations concise by leveraging DI: for example, inject database sessions or authorization checks into endpoints rather than repeating code.
+
+## Environment & Packaging (Poetry)
+
+- **Python & Poetry:** Use Python 3.9+. Manage dependencies with [Poetry](https://python-poetry.org) and define metadata in `pyproject.toml` (PEP 621). Poetry creates isolated virtualenvs and a lockfile for reproducible installs.
+- **Dependency Best Practices:** Initialize with `poetry init` to generate `pyproject.toml`. Add packages with `poetry add <pkg>` so they're recorded in both `pyproject.toml` and `poetry.lock`. Separate dev dependencies (e.g. pytest, linters) using `poetry add --dev`. Commit `poetry.lock` to source control to ensure all installs use exact versions. Regularly run `poetry update` and test to keep dependencies current. Use multi-stage Docker builds to minimize image size (install only production deps).
+- **Project Layout:** Follow a logical package structure: e.g.
+  ```
+  app/
+    __init__.py
+    main.py          # app startup
+    dependencies.py  # shared Depends (DB sessions, auth checks, etc.)
+    routers/         # API route modules
+      __init__.py
+      items.py
+      users.py
+    models/          # SQLModel/Pydantic models
+    services/        # business logic if needed
+  ```
+  Keep code organized into modules; use semantic imports like `from app.routers import items`. Use `Annotated` dependencies where possible for clarity (e.g. `session: Session = Depends(get_session)`).
+
+## Databases (PostgreSQL, SQL Server)
+
+- **SQL Databases:** FastAPI works with any SQL DB via SQLAlchemy/SQLModel. For example, [SQLModel](https://github.com/tiangolo/sqlmodel) (built on SQLAlchemy and Pydantic) can connect to PostgreSQL or SQL Server (via `pyodbc` or `pymssql`). In development you might use SQLite for simplicity, but **production** should use a dedicated DB server (e.g. PostgreSQL).
+- **Connection Handling:** Use one DB **session/connection per request** via a FastAPI dependency (`yield session` pattern). Configure SQLAlchemy connection pools to match workload (avoid re-creating engine per query). Use environment variables (or Kubernetes Secrets) for DB URLs/credentials. Use alembic or similar for migrations, rather than auto-creating tables in prod. Ensure proper indexes and foreign keys in schema.
+- **Security:** Never embed credentials in code. Use TLS to connect to the DB if supported. Sanitize inputs (Pydantic prevents SQL injection by type-checking and requiring parameters).
+
+## Caching (Redis)
+
+- **Redis Usage:** Use Redis for caching or session data. Access via a Redis client (e.g. [redis-py](https://pypi.org/project/redis/) or `aioredis` for async). Store only non-sensitive, expirable data with appropriate TTLs. Abstract Redis access behind a service layer or dependency.
+- **Configuration:** Run Redis in a secured network (not public-facing). Require strong passwords and/or disable the default user. Enable TLS if possible to encrypt in-flight cache traffic. Set memory limits and eviction policies. Monitor usage and consider using Redis clusters for high availability.
+- **Best Practices:** Use Redis only as a cache; do not rely on it for permanent storage unless using Redis persistence properly. Use mature caching patterns (e.g. cache-aside). Flush or handle stale caches on deploy as needed.
+
+## Observability (OpenTelemetry)
+
+- **Instrumentation:** Use [OpenTelemetry for Python](https://opentelemetry.io/docs/languages/python/) to collect traces and metrics. The Python SDK supports Python 3.9+. Install via pip: `pip install opentelemetry-api opentelemetry-sdk` and any needed instrumentations/exporters.
+- **Tracing & Metrics:** Auto-instrument FastAPI (there are middleware or instrumentation libs for ASGI frameworks) to trace HTTP requests. Instrument database calls (SQLAlchemy) and Redis calls. Export telemetry using OTLP or a vendor (Jaeger, Zipkin, Prometheus). Use trace data to diagnose latency; use metrics (like request rate, DB latency) to monitor health.
+- **Deployment:** Ensure an OpenTelemetry Collector or compatible backend is running to receive data. Tag telemetry with the service name and environment. Use semantic conventions for naming.
+
+## Frontend (Vercel) & Authentication (Clerk)
+
+- **Vercel Deployment:** Host the frontend on Vercel (typically a Next.js or static SPA). Configure environment variables in Vercel for the API base URL. Use custom domains and automatic HTTPS. Restrict API CORS to the frontend domain using FastAPI's `CORSMiddleware` so only your front-end origin can access endpoints.
+- **Clerk Authentication:** Use [Clerk](https://clerk.com) to handle user signup/sign-in and sessions. Clerk provides UI components (for React/Next) and issues JWT tokens for authenticated users. In the FastAPI backend, verify these JWTs on each request. For example, use the [fastapi-clerk-auth](https://pypi.org/project/fastapi-clerk-auth/) middleware to automatically validate Clerk JWTs via Clerk's JWKS. This cleanly integrates with FastAPI's DI: endpoints requiring auth simply depend on the token guard.
+- **Auth Best Practices:** Enforce HTTPS so tokens can't be stolen in transit. Use Clerk's features (MFA, password policies, session limits) to harden accounts. Never expose backend secrets (like Clerk API keys) to the frontend. Use short-lived JWTs or session tokens.
+
+## Security Considerations
+
+- **Transport & API Security:** Serve all traffic over HTTPS (TLS). Validate all inputs using Pydantic models to prevent injection or malformed data. Implement CORS rules to only allow trusted origins. Use FastAPI's security dependencies (e.g. `OAuth2PasswordBearer`, HTTP Bearer) to enforce auth on endpoints. Consider rate-limiting and IP blocking for brute-force protection.
+- **Kubernetes & Infrastructure:** Secure the on-prem cluster using Kubernetes best practices. Ensure the API server and etcd have TLS in-transit and (if needed) at-rest encryption. Use Role-Based Access Control (RBAC) to limit cluster operations. Enforce Pod Security Standards: run containers as non-root, use read-only filesystems, drop Linux capabilities. Define NetworkPolicies so Pods can only talk to required services (e.g. API Pod talks to DB/Redis, but not to other namespaces). Use secrets or a vault for all credentials (K8s Secrets should be encrypted at rest by enabling encryption). Audit and log all access (enable Kubernetes audit logs). Keep nodes patched and minimize host privileges.
+- **Container Image Security:** Scan images for vulnerabilities before deployment. Use minimal base images (e.g. Alpine or slim variants) to reduce attack surface. Do not run the application as root inside the container.
+- **Redis Security:** Only allow Redis access from internal service accounts. Use Redis AUTH and TLS. Restrict Redis CLI or admin interfaces.
+- **Clerk/Authentication:** Rely on standard protocols. Verify the `iat` and `exp` claims in JWTs to prevent replay. Synchronize clocks or add leeway if needed. Restrict token scopes so that clients only have the privileges they need.
+- **Secrets Management:** Store sensitive config (DB passwords, JWT keys) outside code. In Kubernetes, use Secrets and mount them into pods. In GitHub Actions, use encrypted secrets (do NOT hardcode credentials). Consider using OpenID Connect (OIDC) in GitHub Actions to avoid long-lived secrets when deploying to Azure.
+- **Audit & Compliance:** Log all significant events (logins, errors, deployments). Regularly review audit logs. Follow principle of least privilege for all services.
+
+## Deployment & CI/CD Pipeline
+
+- **Docker & ACR:** Dockerize the app with a multi-stage `Dockerfile`: install Poetry and build the app, then copy only the `venv/lib/python...` and app code into a smaller final image. Tag images by commit/PR. Push images to Azure Container Registry in the same region as your cluster for low latency. Use a dedicated ACR per environment or namespace. In ACR, enable Azure RBAC: assign a service principal (for CI/CD) push rights and another identity pull rights. Disable the ACR admin user if not needed.
+- **GitHub Actions:** Automate CI/CD with Actions:
+  - **CI (on push/PR):** Steps include `actions/checkout`, `actions/setup-python@v3` (choose Python 3.10+), `poetry install` (or `poetry install --no-dev` for quick CI), run linter (flake8/mypy) and tests. Cache the Poetry virtualenv or pip cache to speed up builds. Fail on test or lint errors.
+  - **Build & Push (on main):** After CI passes, build the Docker image. Use `azure/login@v1` (or OIDC) to authenticate to Azure using a service principal stored in a GitHub secret. Then use `azure/CLI` or `docker/login-action` and `docker/build-push-action` to push the image to ACR. Tag images by semantic version or commit SHA.
+  - **Deploy to K8s:** After pushing, use `azure/k8s-set-context` (or `kubectl` inside `azure/CLI`) to point to the on-prem cluster (this may require a kubeconfig stored securely). Apply updated Kubernetes manifests (using `kubectl apply` or `helm upgrade`). You can use Helm or Kustomize; store manifests alongside code or in a separate repo.
+  - **Checks:** Include branch protection so only successful checks (lint/tests) allow merging to main. Use pull request previews (deploy to a test namespace) before production. Use Actions cache for Docker layers and Poetry packages.
+
+## Kubernetes Deployment Patterns
+
+- **Manifests:** Define Deployments and Services in YAML. Always create a Service *before* pods that use it, so environment variables get injected correctly. Use DNS service names for inter-service calls. Avoid `hostPort`/`hostNetwork` (it ties pods to nodes); use a NodePort or Ingress for external access. For internal-only services, use ClusterIP or headless Services as needed.
+- **Labels & Configuration:** Use semantic, standardized labels (`app.kubernetes.io/name`, `component`, `tier`, etc.) to identify workloads. Store app config (like DB URLs or feature flags) in ConfigMaps/Secrets and mount them as env vars or files. Keep resource limits/requests set on pods. Use liveness/readiness probes to restart unhealthy pods. Consider HorizontalPodAutoscalers based on CPU/memory or custom metrics (if cluster has VPA/HPA enabled).
+- **Secrets:** Load Kubernetes Secrets (e.g. database credentials, JWT secret) into pods. Optionally use a tool like SealedSecrets or Vault for rotation.
+- **Ingress & Networking:** Expose the API via an Ingress or LoadBalancer with TLS. Ensure the TLS certificate is valid (use internal CA or Let's Encrypt).
+- **Monitoring:** Run a Prometheus/Alertmanager stack (or other monitoring) in the cluster. Configure probes and health endpoints for FastAPI. Forward logs to a central system (ELK/EFK or Grafana Loki). Use OpenTelemetry collector if needed.
+
+## Final Checklist
+
+- **Code Quality:** Follow PEP 8 and Pylint/myPy linting. Ensure unit and integration tests cover key logic. Use `@pytest` with the TestClient for endpoint tests.
+- **Dependency Audit:** Before each release, run a security scan on Python packages (e.g. `poetry audit` or `safety`) and on container images. Update vulnerable dependencies promptly.
+- **Review Configuration:** Verify all environment variables and secrets are properly set in production. Check that no debug or verbose logging is enabled.
+- **Performance Checks:** Ensure Redis and database are configured for expected load. Benchmark API endpoints and add indexes or cache hot queries as needed.
+- **Security Review:** Confirm TLS is enforced (no HTTP allowed). Test auth flows (invalid tokens are rejected, access is limited by role). Ensure network policies isolate components.

package/guidelines/FOREST_FE_GUIDELINES.md

@@ -0,0 +1,543 @@
+# Forest UI — Development Best Practices
+
+> **forest-ui v0.2.11**
+
+> **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