Implementazione Sistema Messaggi - Riepilogo

Data Implementazione

20 Ottobre 2025

Obiettivo

Reimplementare le funzioni presenti nel file legacy/Messages.js per gestire l'icona dei messaggi non letti nella topbar, utilizzando il nuovo sistema di comunicazione iframe-parent.

File Creati

1. app/hooks/useTopbarMessages.ts

Hook che gestisce la comunicazione dei messaggi tra iframe e parent window.

Funzionalità:

• Registra l'oggetto window.messages con 3 metodi:
  • readMessage() - Decrementa il contatore (-1)
  • addMessage() - Incrementa il contatore (+1)
  • setMessages(n_msg) - Imposta il contatore dal formato "count-flag"
• Gestisce lo stato dei messaggi (counter e hasUnread)
• Mostra automaticamente il modal nell'iframe quando flag < 1
• Cleanup automatico quando il componente viene smontato

Stato restituito:

{
  counter: number,      // Numero messaggi non letti
  hasUnread: boolean    // true se ci sono messaggi
}

2. tests/useTopbarMessages.test.ts

Test completi per l'hook useTopbarMessages.

Copertura:

• ✅ Registrazione/rimozione oggetto window.messages
• ✅ Stato iniziale
• ✅ Tutte e 3 le funzioni (readMessage, addMessage, setMessages)
• ✅ Comportamento del modal
• ✅ Scenario completo di operazioni
• ✅ Stabilità delle funzioni

Risultato: 15 test, tutti passati ✅

3. docs/iframe/iframe-messages-communication.md

Documentazione completa del sistema messaggi.

Contenuto:

• Architettura e utilizzo
• Esempi pratici (PHP e JavaScript)
• Migrazione dal legacy
• Test e best practices
• Note sulla sicurezza

File Modificati

1. app/types/window.d.ts

Aggiunto il tipo messages all'interfaccia Window:

messages?: {
    readMessage: () => void;
    addMessage: () => void;
    setMessages: (n_msg: string) => void;
};

2. app/components/auth/AuthenticatedLayout.tsx

• Importato useTopbarMessages
• Aggiunto const messageState = useTopbarMessages()
• Aggiunta icona messaggi nell'header con:
  • Badge con contatore quando > 0
  • Sfondo rosso quando ci sono messaggi non letti
  • Tooltip dinamico

3. app/routes/test-iframe.tsx

• Aggiornata descrizione per includere i test dei messaggi
• Aggiornato logging per verificare window.messages

4. public/test-iframe.html

Aggiunta sezione "Test Messages" con 6 pulsanti:

• Imposta 5 messaggi (con modal)
• Imposta 3 messaggi (senza modal)
• Leggi messaggio (-1)
• Aggiungi messaggio (+1)
• Reset messaggi (0)
• Verifica messages

Implementate 6 funzioni JavaScript per i test.

5. docs/README.md

Aggiunto riferimento a iframe-messages-communication.md.

Comparazione Legacy vs Nuovo Sistema

Legacy (Messages.js)

class Messages extends Component {
  // State locale
  state = { evid: false, counter: 0 };

  // Metodi chiamati esternamente
  readMessage = () => { ... }
  addMessage = () => { ... }
  setMessages = (n_msg) => { ... }

  // Render con MobX
  render() { ... }
}

Nuovo Sistema

// Hook con comunicazione iframe
export function useTopbarMessages() {
  const [messageState, setMessageState] = useState({
    counter: 0,
    hasUnread: false
  });

  // Registra window.messages
  window.messages = {
    readMessage: () => { ... },
    addMessage: () => { ... },
    setMessages: (n_msg) => { ... }
  };

  return messageState;
}

Vantaggi del Nuovo Sistema

• ✅ Comunicazione standardizzata iframe-parent
• ✅ Type-safe con TypeScript
• ✅ Hook moderno invece di class component
• ✅ Stato gestito con useState invece di MobX
• ✅ Test completi con Vitest
• ✅ Documentazione dettagliata
• ✅ Pagina di test interattiva

Utilizzo

Nel Parent (React)

// AuthenticatedLayout
const messageState = useTopbarMessages();

// Icona con badge
<button className={messageState.hasUnread ? "bg-red-600" : ""}>
  ✉️
  {messageState.counter > 0 && <span>{messageState.counter}</span>}
</button>

Nell'Iframe (PHP/JS)

// Imposta messaggi
window.parent.messages.setMessages('5-0');  // 5 msg + mostra modal

// Leggi messaggio
window.parent.messages.readMessage();

// Nuovo messaggio
window.parent.messages.addMessage();

Test Manuali

1. Avviare il dev server: npm run dev
2. Login e navigare a /test-iframe
3. Testare i pulsanti della sezione "Test Messages"
4. Verificare:
   • Icona si illumina di rosso quando ci sono messaggi
   • Badge mostra il numero corretto
   • Contatore aumenta/diminuisce correttamente
   • Non va mai sotto 0

Note Tecniche

Formato setMessages

"count-flag"
├─ count: numero messaggi (es. "5")
└─ flag: 0 = mostra modal, 1+ = non mostrare

Modal Automatico

Quando flag < 1:

1. Cerca iframe con id main-iframe
2. Controlla iframe.contentWindow.messages
3. Chiama showModal() se disponibile
4. Altrimenti aggiunge listener per il load

Sicurezza

• Contatore protetto con Math.max(0, ...)
• Try/catch su accesso contentWindow
• Cleanup automatico su unmount
• Same-origin policy rispettata

Persistenza e Sincronizzazione Cross-Tab

Implementato store Zustand per persistere lo stato.

File creati:

• app/store/messages/messages.store.ts - Store Zustand
• tests/messages.store.test.ts - Test store (11 test ✅)

Sincronizzazione Cross-Tab

Quando una tab aggiorna il contatore, tutte le altre tab si sincronizzano automaticamente.

Implementato useMessagesSyncListener con BroadcastChannel.

File creati:

• app/hooks/useMessagesSyncListener.ts - Hook per sincronizzazione
• tests/useMessagesSyncListener.test.ts - Test sincronizzazione (7 test ✅)

File aggiornati:

• app/hooks/useTopbarMessages.ts - Usa lo store invece di useState
• app/components/auth/AuthenticatedLayout.tsx - Aggiunto useMessagesSyncListener
• docs/iframe/iframe-messages-communication.md - Documentazione sincronizzazione