Status Presentation
Pattern canonico per trasformare uno stato di dominio in una rappresentazione umana, coerente e operativa senza esporre il modello tecnico sottostante.
Lo stato di backend non è copy finale
Ogni superficie riceve una presentazione tipizzata con label e tono già definiti nel contesto di dominio. Descrizione e icona sono facoltative; la prossima azione resta separata e deriva soltanto dalle capability realmente disponibili per ruolo, stato e dati correnti.
Lo stesso valore tecnico può descrivere entità diverse. Per questo la traduzione è specifica del contesto e non una conversione generica del nome ricevuto dal backend.
Una sola fonte per stato e azioni
Nel Workspace il presenter di stato produce label, tono ed eventuale descrizione. I consumer, comeWorkspaceState, si limitano a renderizzare quell’output. Le azioni arrivano invece dai servizi e dalle viste che conoscono capability e ruolo. Sirio documenta output verificati: non importa il dominio del Workspace e non mantiene un mapper parallelo.
Anatomia della presentazione
La label comunica sempre il significato. Gli altri elementi aggiungono contesto soltanto quando servono.
- Label
- Traduce lo stato nel linguaggio del prodotto e descrive fedelmente la condizione corrente.
- Tono
- Sceglie una variante semantica coerente: positivo, attenzione, informazione, errore o neutro.
- Descrizione
- Aggiunge una frase breve solo quando chiarisce attesa, conseguenza o contesto.
- Icona
- Rafforza il significato quando utile, senza sostituire la label e senza diventare rumore decorativo.
- Prossima azione
- Compare solo quando capability e contesto reali indicano che l’utente può agire adesso.
Stati reali, presentati per le persone
Gli specimen usano output già definiti dal presentation layer del Workspace. Le frasi di supporto e l’azione mostrate appartengono ai contesti reali indicati, non vengono dedotte dal tono.
Il riepilogo è stato pubblicato e il cliente deve confermarlo.
- Prossima azione:
- Controlla il riepilogo
Il lavoro non richiede azioni operative. Riepilogo e storico restano consultabili.
Fallback neutro e senza leakage
Un valore non riconosciuto non viene interpretato, trasformato o mostrato. Il presenter restituisce una label neutra, non assegna descrizioni o azioni inventate e lascia visibile il contesto dell’elemento.
Badge, testo o composizione
Il presenter definisce il significato; il consumer sceglie la forma adatta alla densità e all’importanza del contesto.
- Badge
- Per uno stato compatto accanto a titolo, elemento di lista o riepilogo.
- Testo di stato
- Quando la frase deve entrare naturalmente nel contenuto o lo spazio è molto denso.
- Badge e descrizione
- Per attese, stati poco familiari o condizioni che richiedono una spiegazione immediata.
- Stato e azione
- Solo quando il consumer riceve anche un’azione disponibile dal servizio o dalla vista corrente.
Per API, dimensioni e varianti visuali della primitiva consulta la pagina Badge.
Responsive e accessibilità
La comprensione dello stato deve restare invariata senza colore, senza icone e su ogni viewport.
- Mantieni sempre una label testuale visibile: colore, bordo e icona non comunicano lo stato da soli.
- Nascondi l’icona allo screen reader quando ripete il significato già espresso dalla label.
- Non affidare una descrizione importante al solo attributo title, all’hover o a un tooltip.
- Usa i token semantici del design system, verificati per contrasto in light e dark mode.
- Su viewport stretti consenti a label e descrizione di andare a capo senza troncare contenuto o focus ring.
- Annuncia un cambiamento con una live region solo se avviene dinamicamente e richiede davvero attenzione immediata.
Errori da evitare
La presentazione non deve ricostruire il dominio né sostituirsi alla sorgente che determina le azioni.
- Renderizzare il valore ricevuto dal backend o trasformarlo meccanicamente sostituendo underscore e maiuscole.
- Usare un solo dizionario globale quando lo stesso valore assume significati diversi in contesti diversi.
- Dedurre priorità, permessi o prossime azioni dal colore del badge.
- Aggiungere descrizioni, conseguenze o urgenze che il dominio non dimostra.
- Creare mapping locali nelle singole pagine o una seconda mappa di dominio dentro Sirio.