Approfondimento Tecnico — Libro Portfolio 3D

Il problema di partenza

Realizzare un “libro sfogliabile” è semplice se si accetta un effetto base. Il problema reale emerge quando l’obiettivo diventa esperienza credibile e controllata:

• mantenere una sensazione “fisica” nello sfoglio, senza scatti o glitch;
• gestire animazioni stratificate (ombre, glow, fumo) senza sporcare il layout;
• evitare rotture su mobile con viewport dinamica e change di orientamento;
• mantenere il progetto statico e deployabile senza build e senza dipendenze runtime pesanti.

Il “Libro Portfolio” nasce per risolvere questi punti con un approccio diretto: DOM controllato, CSS 3D, logica JavaScript minimale ma precisa.

La soluzione: rendering controllato (CSS 3D + JS state)

Il cuore del progetto è un’idea semplice: separare interazione e resa visiva.

Turn.js gestisce lo sfoglio (fisica, pagine, input), mentre la parte “cinematica” viene gestita da CSS e JavaScript tramite:
• classi “state-based” (es. is-entering, is-ready, is-turning);
• transizioni e keyframes CSS per effetti visivi;
• sincronizzazione del timing con listener e micro-delay controllati.

Risultato: l’interazione resta stabile e la parte visiva rimane estendibile senza rompere la logica.

Snippet di codice

// Esempio: stato UI -> animazioni CSS
function setStage(stage) {
  document.documentElement.dataset.stage = stage;
  // stages: "boot" | "enter" | "ready" | "turning"
}

// Boot -> Enter -> Ready
document.addEventListener("DOMContentLoaded", () => {
  setStage("boot");

  requestAnimationFrame(() => {
    setStage("enter");
    // evita race-condition su alcuni device
    setTimeout(() => setStage("ready"), 350);
  });
});

// Edge case mobile: ricalcolo layout con debounce su resize/orientation
function debounce(fn, ms = 180) {
  let t;
  return (...args) => {
    clearTimeout(t);
    t = setTimeout(() => fn(...args), ms);
  };
}

function applyResponsiveLayout() {
  const w = window.innerWidth;
  const h = window.innerHeight;
  const isLandscape = w > h;

  // calcola dimensioni libro in base al viewport
  // e aggiorna CSS variables usate da trasformazioni 3D
  document.documentElement.style.setProperty("--vw", w + "px");
  document.documentElement.style.setProperty("--vh", h + "px");
  document.documentElement.dataset.orientation = isLandscape ? "landscape" : "portrait";
}

window.addEventListener("resize", debounce(applyResponsiveLayout));
window.addEventListener("orientationchange", () => setTimeout(applyResponsiveLayout, 150));
applyResponsiveLayout();

Perché un progetto statico (GitHub + Vercel)?

L’esperienza è volutamente costruita come progetto statico perché:

• non richiede backend, database o build;
• si avvia ovunque con un server HTTP;
• si deploya in modo immediato e affidabile su Vercel;
• riduce i punti di rottura (dipendenze, versioni, build tools).

Questo approccio è ideale per un case study: mostra controllo tecnico, semplicità e capacità di consegnare un prodotto stabile in cloud.

Architettura del sistema

L’architettura è intenzionalmente modulare pur restando vanilla:

1. Core “Book Engine”
Inizializza Turn.js, gestisce gli eventi di sfoglio e comunica lo stato (turning/idle).

2. “Stage Controller”
Governa gli stati dell’esperienza (boot/enter/ready) e attiva gli effetti CSS senza introdurre dipendenze.

3. Responsive Manager
Calcola dimensioni e scale del libro; gestisce resize e orientamento evitando ricalcoli inutili.

4. Asset Pipeline (statica)
Immagini e texture ottimizzate (WebP/JPG/PNG) con organizzazione prevedibile e caching automatico in CDN.

Flusso di lavoro

1. 1. Preload essenziale degli asset critici (per evitare flash e glitch).
2. 2. Inizializzazione Turn.js e binding degli eventi principali.
3. 3. Setup delle variabili CSS (dimensioni/scale/3D) in base al viewport.
4. 4. Attivazione progressiva dell’esperienza (boot → enter → ready) per ridurre race-condition su mobile.
5. 5. Durante lo sfoglio: aggiornamento stato UI (turning) e attivazione di effetti visivi controllati.

Sicurezza

Il progetto include un sistema di accesso con password lato client. È una scelta consapevole e dichiarata: serve come protezione leggera per una demo pubblica, non come autenticazione robusta.

In una versione production, l’accesso verrebbe gestito con:
• autenticazione server-side o token firmati;
• protezione delle risorse tramite backend / middleware;
• rate limiting e logging.

Qui l’obiettivo è dimostrare UX e flusso, mantenendo il progetto statico.

Possibili sviluppi futuri

• • Modalità “performance” con riduzione automatica degli effetti su device lenti
• • Preload intelligente delle pagine successive per sfoglio più fluido
• • Supporto accessibilità: riduzione motion, navigazione da tastiera, focus states
• • Versione “content-driven” con JSON per generare pagine e contenuti
• • Protezione demo con middleware (versione Next) o endpoint tokenizzato