🛒 Sistema Cart - Guida Rapida all'Integrazione

📦 File

Store

app/store/cart/cart.store.ts - Store Zustand con stato del carrello

Hooks

app/hooks/ui/useTopbarCart.ts - Comunicazione con iframe
app/hooks/sync/useCartSyncListener.ts - Sincronizzazione tra tab

Component

app/components/layout/topbar/cart.tsx - Componente UI del carrello

Tests

tests/cart.store.test.ts - Test dello store (20 test) ✅
tests/useCartSyncListener.test.ts - Test sincronizzazione (8 test) ✅
tests/useTopbarCart.test.ts - Test comunicazione (12+ test) ✅
tests/Cart.test.tsx - Test componente (15+ test) ✅

Documentazione

docs/cart/cart-implementation.md - Documentazione completa

🚀 Integrazione in 3 Passi

Passo 1: Montare gli Hooks (Layout Autenticato)

tsx

// app/components/layout/authenticated-layout.tsx
import { useTopbarCart } from "@/hooks/ui/useTopbarCart";
import { useCartSyncListener } from "@/hooks/sync/useCartSyncListener";

export function AuthenticatedLayout({ children }) {
    useTopbarCart();           // Gestisce comunicazione con iframe
    useCartSyncListener();     // Sincronizza tra tab

    return (
        <div>
            <Topbar />
            <main>{children}</main>
        </div>
    );
}

tsx

// app/components/layout/topbar/nav-actions.tsx
import { Cart } from "@/components/layout/topbar/cart";

export function NavActions() {
    return (
        <nav className="navbar">
            <ul className="nav-list">
                <Cart />
                {/* Altri elementi della topbar */}
            </ul>
        </nav>
    );
}

Passo 3: Configurare l'Iframe (legacy code)

javascript

// Nell'iframe (legacy PHP/JavaScript)

// Quando il carrello viene aggiornato
function updateCartCounter(count) {
    if (window.parent && window.parent.cart) {
        window.parent.cart.setCounter(count);
    }
}

// Dopo un'azione sul carrello
updateCartCounter(5); // Imposta contatore a 5

✅ Verifiche Post-Integrazione

1. Verifica Hook Montati

Apri la console del browser e controlla i log:

[useTopbarCart] Hook montato, registrazione cart...
[useTopbarCart] ✅ Oggetto cart registrato su window

2. Verifica Comunicazione Iframe

Nella console dell'iframe, esegui:

javascript

window.parent.cart.setCounter(5);

Dovresti vedere il badge del carrello aggiornarsi.

3. Verifica Sincronizzazione Multi-Tab

Apri due tab dello stesso sito
In una tab, modifica il carrello
Controlla che l'altra tab si sincronizzi automaticamente
Log atteso: [CartSyncListener] 🛒 Ricevuto aggiornamento carrello da altra tab

Clicca sul badge del carrello
Verifica che il dropdown si apra
Verifica che le voci siano visibili: Apri, Usa, Offline, Fastlabel, Svuota

5. Esegui i Test

bash

npm test -- cart

Dovresti vedere tutti i test passare (55+ test).

🔧 Configurazione Opzionale

Variabili Globali da Configurare

javascript

// Nel tuo layout HTML o script di inizializzazione
window.base_url = "https://your-domain.com";
window.commoncart_btn_offline = true;  // Mostra bottone Offline
window.commoncart_btn_fastlabel = true; // Mostra bottone Fastlabel

Implementare `common_cart` nell'Iframe

javascript

// Nell'iframe (legacy code)
window.common_cart = {
    read: function() {
        // Leggi e ritorna il contenuto del carrello
        console.log("read() chiamato dalla SPA");
    },

    open: function() {
        // Naviga alla pagina del carrello
        window.location.href = "/cart";
    },

    download: function() {
        // Avvia il download del carrello
        console.log("download() chiamato dalla SPA");
    },

    empty: function() {
        // Svuota il carrello
        console.log("empty() chiamato dalla SPA");
        // Dopo aver svuotato, aggiorna il contatore
        window.parent.cart.setCounter(0);
    },

    commoncart_clipboard_success: function() {
        // Callback dopo successo copia Fastlabel
        alert("Fastlabel copiato!");
    },

    commoncart_offline_clipboard_success: function() {
        // Callback dopo successo copia Offline
        alert("Dati offline copiati!");
    }
};

// Imposta le risposte per clipboard
window.fastlabel_response = "FASTLABEL-CODES-HERE";
window.offline_response = "OFFLINE-DATA-HERE";

📊 Funzionalità Implementate

✅ Tutte le funzionalità del legacy `Cart.js`

[x] Contatore articoli con badge
[x] Evidenziazione quando hasItems = true
[x] Dropdown con azioni
[x] Azione "Apri" (apre carrello nell'iframe)
[x] Azione "Usa" (scarica/usa carrello)
[x] Azione "Offline" (copia dati offline in clipboard)
[x] Azione "Fastlabel" (copia fastlabel in clipboard)
[x] Azione "Svuota" (svuota carrello)
[x] Gestione click esterni (chiude dropdown)
[x] Comunicazione bidirezionale con iframe
[x] Titolo dinamico basato su contatore

✅ Nuove funzionalità moderne

[x] Sincronizzazione multi-tab (BroadcastChannel)
[x] TypeScript con type safety completo
[x] Store Zustand (stato globale persistente)
[x] React hooks moderni
[x] Clipboard API nativa (no dipendenze esterne)
[x] Test coverage completo (55+ test)
[x] Logging dettagliato per debug
[x] Gestione errori robusta
[x] Documentazione completa

🎯 Differenze con il Legacy

Feature	Legacy Cart.js	Nuovo Cart
Framework	Class Component	Function Component + Hooks
State Management	Local state	Zustand (global)
Multi-tab Sync	❌ No	✅ Sì (BroadcastChannel)
TypeScript	❌ No	✅ Sì (strict mode)
Testing	❌ No test	✅ 55+ test
Clipboard	react-clipboard.js	Clipboard API nativa
Documentation	❌ No	✅ Completa
Examples	❌ No	✅ 12 esempi

🐛 Troubleshooting

Il carrello non appare

Causa: Componente <Cart /> non montato Soluzione: Verifica di aver aggiunto <Cart /> alla topbar

Il contatore non si aggiorna

Causa: Hook useTopbarCart non montato Soluzione: Verifica di aver aggiunto useTopbarCart() nel layout

Sincronizzazione non funziona

Causa: Hook useCartSyncListener non montato Soluzione: Verifica di aver aggiunto useCartSyncListener() nel layout

Azioni non funzionano

Causa: common_cart non definito nell'iframe Soluzione: Implementa window.common_cart nell'iframe (vedi sopra)

Offline/Fastlabel non visibili

Causa: Flag globali non impostati Soluzione: Imposta window.commoncart_btn_offline e window.commoncart_btn_fastlabel

📚 Documentazione Completa

Per maggiori dettagli consulta:

docs/cart/cart-implementation.md - Documentazione completa

🎉 Riepilogo

✅ Store Zustand: Gestione stato globale ✅ Sincronizzazione: Automatica tra tab ✅ Comunicazione: Bidirezionale con iframe ✅ Componente: UI moderna e responsive ✅ Test: 55+ test passati ✅ TypeScript: Type safety completo ✅ Documentazione: Completa ed esaustiva

Il sistema è pronto per essere integrato! 🚀

🛒 Sistema Cart - Guida Rapida all'Integrazione ​

📦 File ​

Store ​

Hooks ​

Component ​

Tests ​

Documentazione ​

🚀 Integrazione in 3 Passi ​

Passo 1: Montare gli Hooks (Layout Autenticato) ​

Passo 2: Aggiungere il Componente alla Topbar ​

Passo 3: Configurare l'Iframe (legacy code) ​

✅ Verifiche Post-Integrazione ​

1. Verifica Hook Montati ​

2. Verifica Comunicazione Iframe ​

3. Verifica Sincronizzazione Multi-Tab ​

4. Verifica Dropdown ​

5. Esegui i Test ​

🔧 Configurazione Opzionale ​

Variabili Globali da Configurare ​

Implementare common_cart nell'Iframe ​

📊 Funzionalità Implementate ​

✅ Tutte le funzionalità del legacy Cart.js ​

✅ Nuove funzionalità moderne ​

🎯 Differenze con il Legacy ​

🐛 Troubleshooting ​

Il carrello non appare ​

Il contatore non si aggiorna ​

Sincronizzazione non funziona ​

Azioni non funzionano ​

Offline/Fastlabel non visibili ​

📚 Documentazione Completa ​

🎉 Riepilogo ​

🛒 Sistema Cart - Guida Rapida all'Integrazione

📦 File

Store

Hooks

Component

Tests

Documentazione

🚀 Integrazione in 3 Passi

Passo 1: Montare gli Hooks (Layout Autenticato)

Passo 2: Aggiungere il Componente alla Topbar

Passo 3: Configurare l'Iframe (legacy code)

✅ Verifiche Post-Integrazione

1. Verifica Hook Montati

2. Verifica Comunicazione Iframe

3. Verifica Sincronizzazione Multi-Tab

4. Verifica Dropdown

5. Esegui i Test

🔧 Configurazione Opzionale

Variabili Globali da Configurare

Implementare `common_cart` nell'Iframe

📊 Funzionalità Implementate

✅ Tutte le funzionalità del legacy `Cart.js`

✅ Nuove funzionalità moderne

🎯 Differenze con il Legacy

🐛 Troubleshooting

Il carrello non appare

Il contatore non si aggiorna

Sincronizzazione non funziona

Azioni non funzionano

Offline/Fastlabel non visibili

📚 Documentazione Completa

🎉 Riepilogo