Primitive UI — Una guida pratica

Se hai mai guardato un’app moderna e pensato “ma come si chiama quella cosa?” — questa pagina è per te.

Ogni interfaccia che utilizzi è costruita a partire da un insieme sorprendentemente ridotto di blocchi riutilizzabili chiamati primitive UI. Hanno dei nomi. Nomi bizzarri, a volte. Ma una volta che cogli la metafora, non puoi più non vederla.

En Parlant~ usa Mantine, una libreria di componenti React che fornisce tutte queste primitive pronte all’uso. Ecco la tua guida pratica.

Quelle che sembrano nomi di mobili

Toast

Un toast è una piccola notifica che compare dal bordo dello schermo, resta visibile per qualche secondo e poi scivola via. Come una fetta di pane che salta fuori dal tostapane — solo che la gravità funziona al contrario e alla fine ci rientra dentro.

In En Parlant~, i toast appaiono nell’angolo in basso a destra (tramite @mantine/notifications di Mantine) per cose come:

“Database caricato con successo” — pop
“Voce TTS non configurata” — pop
“Impossibile connettersi a Lichess” — pop, e ti viene un po’ di tristezza

Non li hai chiesti. Semplicemente compaiono, consegnano il messaggio e se ne vanno. Sono i piccioni viaggiatori del mondo delle interfacce.

Card

Una card è un contenitore rettangolare con un bordo o un’ombra che raggruppa contenuti correlati. Immagina una scheda posata su una scrivania — ha un bordo definito, contiene una cosa sola, e puoi prenderla e spostarla.

In En Parlant~ troverai card per:

Anteprime delle partite nel browser del database (GameCard) — nomi dei giocatori, risultato, data
Editor della posizione (EditingCard) — la scheda che capovolgi quando imposti una posizione personalizzata
Voci del database nella pagina dei database — ogni database ha la propria card in una griglia

Le card hanno un cugino stretto chiamato Paper, che è fondamentalmente una card che ha frequentato una scuola d’arte. Stesso concetto — un contenitore con bordo o ombra — ma con meno significato semantico. Paper dice semplicemente “Sono una superficie.” Compare come sfondo dietro i pannelli di analisi e le visualizzazioni delle informazioni dei database.

Drawer / Sheet

Non attualmente usato in En Parlant~, ma vale la pena conoscerlo: un drawer è un pannello che scorre dentro dal bordo dello schermo, come il cassetto di una scrivania. (Tutto qui. Questa è tutta la metafora. I designer di interfacce quel giorno erano molto letterali.)

Quelle che ti bloccano il cammino

Un modal è una finestra di dialogo popup che pretende la tua attenzione. Oscura lo sfondo e ti obbliga a gestirlo prima di fare qualsiasi altra cosa. È il bambino piccolo dei pattern UI — “GUARDAMI SUBITO.”

En Parlant~ usa i modal per i momenti che richiedono genuinamente la tua attenzione:

“Sei sicuro di voler cancellare tutti i dati?” (ClearDataModal) — con checkbox per scegliere quali dati distruggere
“È disponibile un aggiornamento” (UpdateModal) — con una barra di progresso durante il download
“Importa una partita” (ImportModal) — incolla un PGN, inserisci un FEN, o trascina un link
“Crea un nuovo repertorio” (CreateRepertoireModal) — dagli un nome, configuralo, via
“Informazioni su En Parlant~” (About) — versione, crediti, il solito pass per il backstage

I modal dicono: “Questa è una conversazione. La stiamo avendo adesso.”

Dialog

Un dialog è il cugino educato del modal. In Mantine sono essenzialmente lo stesso componente, ma nella teoria del design UI un dialog è più piccolo e più focalizzato — una singola domanda e risposta. “Salvare le modifiche?” Sì / No. Fatto.

En Parlant~ usa ConfirmModal per questi rapidi momenti sì-o-no, come confermare che vuoi scartare le modifiche non salvate.

Quelle che vanno e vengono

Un tooltip è una piccola etichetta che appare quando passi il mouse sopra qualcosa. È lo sconosciuto gentile che ti sussurra la risposta quando sembri confuso.

I tooltip sono ovunque in En Parlant~. Passa il mouse su quasi qualsiasi pulsante a icona e ne otterrai uno:

Passa il mouse sul pulsante ↻ → “Ricarica”
Passa il mouse su un percorso file troncato → appare il percorso completo
Passa il mouse su un simbolo di annotazione → cosa significa quel simbolo
Passa il mouse su una mossa nel pannello di analisi → compare un’anteprima in miniatura della scacchiera

I tooltip sono l’originale “nessun manuale necessario.”

Un popover è un tooltip che ha preso una laurea specialistica. Invece di mostrare solo un’etichetta di testo, può contenere qualsiasi cosa — pulsanti, immagini, persino una piccola scacchiera.

In En Parlant~, quando passi il mouse su una mossa nell’analisi del motore, un popover mostra un’anteprima della scacchiera in quella posizione. È un tooltip, ma ha portato sussidi visivi.

Un menu è un elenco di azioni che appare quando fai clic (o clic destro) su qualcosa. Li usi dall’alba dell’informatica — File, Modifica, Visualizza. Conosci il copione.

En Parlant~ ne ha due varietà:

Menu della barra superiore — la classica barra dei menu File / Modifica / Visualizza, costruita con il componente Menu di Mantine. Scorciatoie da tastiera elencate sulla destra. Un pattern di design così vecchio che è andato in pensione.
Menu contestuali — fai clic destro su una mossa nell’albero della partita e ottieni opzioni come Promuovi Variante, Elimina da Qui e Copia Linea. Questi usano la libreria mantine-contextmenu per una rifinitura extra.

I menu hanno un sotto-vocabolario tutto loro: Menu.Target (la cosa su cui fai clic), Menu.Dropdown (la lista che appare), Menu.Item (ogni opzione) e Menu.Divider (la linea sottile che dice “adesso inizia una sezione diversa”).

Quelle che organizzano lo spazio

Stack & Group

Sono il pane e la marmellata del layout.

Stack dispone gli elementi verticalmente — uno sopra l’altro. Come impilare libri.
Group dispone gli elementi orizzontalmente — fianco a fianco. Come allineare pezzi degli scacchi su una mensola.

Compaiono letteralmente in più di 100 file ciascuno. Sono i componenti più comuni dell’intera applicazione. Ogni volta che le cose sono disposte ordinatamente, un Stack o un Group ne è responsabile.

Flex

Flex è il coltellino svizzero cugino di Stack e Group. Quando gli elementi devono andare a capo, allargarsi, restringersi, invertirsi o comportarsi in modo imprevedibile, Flex interviene con il pieno controllo sul modello CSS Flexbox.

Usato nella lista delle mosse del pannello di analisi — quelle sequenze di mosse che si avvolgono e scorrono come testo? È Flex che fa il lavoro pesante.

Box

Un Box è un <div> con il cilindro in testa. Non fa nulla da solo — è solo un contenitore generico. Ma accetta le prop di stile di Mantine, il che lo rende un wrapper incredibilmente pratico per “ho bisogno di una cosa attorno a quest’altra cosa.”

Box compare in più di 150 file. È il nastro adesivo della libreria di componenti.

Center

Fa esattamente quello che dice. Mette qualcosa al centro. Orizzontalmente. Verticalmente. Entrambi. Fatto.

Compare negli stati vuoti — quando non ci sono account collegati, nessun database caricato, nessun dato ancora. Una grande icona, un messaggio, e Center che si assicura che sia posizionato perfettamente. A nessuno piace uno stato vuoto fuori centro.

SimpleGrid

Una griglia che è semplice. Gli dici quante colonne e dispone le tue card in una griglia ordinata che si riorganizza al ridimensionamento della finestra. La pagina dei database la usa per disporre le card dei database in una griglia responsive.

ScrollArea

Un contenitore che scorre quando il suo contenuto trabocca. Penseresti che sia gratuito — e in un certo senso lo è, con CSS overflow: auto — ma ScrollArea aggiunge barre di scorrimento stilizzate, scorrimento con inerzia e rilevamento dell’overflow. Avvolge il pannello dell’albero della partita, le linee di analisi, e ovunque il contenuto possa crescere più in alto del suo contenitore.

AppShell

L’AppShell è il layout principale — lo scheletro dell’intera applicazione. Definisce dove va l’header, dove va la sidebar e dove vive il contenuto principale. Tutto il resto si annida al suo interno.

Lo usi una sola volta. È la fondazione della casa.

Portal

Un Portal è un tunnel spaziale magico. Renderizza un componente al di fuori della sua posizione normale nell’albero DOM e lo posiziona altrove — di solito alla radice del documento. È così che popover e anteprime della scacchiera evitano di essere tagliati da contenitori genitore con overflow: hidden.

Non vedi mai un Portal. Ne vedi solo gli effetti. È la troupe di palcoscenico dei componenti UI.

Quelle con cui interagisci

Button

Un rettangolo cliccabile con del testo. Questo lo conosci. In Mantine, i pulsanti sono disponibili in varianti:

filled — colore pieno, alta enfasi. “Cliccami, sono importante.”
outline — solo un bordo. “Sono un’opzione, ma senza pressione.”
subtle — quasi invisibile. “Sono qui se hai bisogno.”
default — una via di mezzo neutra.

En Parlant~ li usa tutti in più di 150 file. Il pattern più comune: un Group di pulsanti in fondo a un modal — “Annulla” (subtle) e “Conferma” (filled). Un classico.

ActionIcon

Un ActionIcon è un pulsante che ha rinunciato alla sua etichetta di testo e si è dedicato completamente allo stile a icona. È compatto, quadrato, e si affida alla sua icona (più un tooltip) per comunicare il suo scopo.

Pulsanti della toolbar, controlli dei pannelli, pulsanti di chiusura — tutti ActionIcon. Sono il modo più efficiente in termini di spazio per offrire un’azione.

Switch

Uno Switch è un interruttore che sembra un piccolo interruttore della luce. Spostalo a sinistra, spostalo a destra. Acceso. Spento.

Nelle impostazioni, gli switch controllano scelte binarie:

Suono attivato/disattivato
Narrazione TTS abilitata/disabilitata
Modalità scura / modalità chiara

La metafora fisica è così efficace che persino i tuoi nonni la capiscono.

Slider

Uno Slider è una traccia con una maniglia che trascini avanti e indietro per selezionare un valore. Come una manopola del volume che è stata appiattita.

En Parlant~ usa gli slider per:

Dimensione del carattere — trascina per regolare
Volume — trascina per regolare (ovviamente)
Core CPU — quanti core deve usare il motore?
Memoria hash — quanta RAM per la tabella hash del motore?

C’è anche un RangeSlider con due maniglie per selezionare un intervallo — usato per filtrare le partite per punteggio Elo (es. 2000–2200) e periodi temporali.

SegmentedControl

Una fila di pulsanti in cui esattamente uno è selezionato alla volta. È come i preset di un’autoradio — premi uno, gli altri saltano fuori.

Usato per alternare tra:

Valutazione in centipedone vs. percentuali Vittoria/Patta/Sconfitta nel grafico di analisi
Diversi formati di notazione delle mosse
Numero di linee del motore

Checkbox & Select

Li conosci. Checkbox per “seleziona tutti quelli che si applicano,” menu a tendina Select per “scegline uno da questa lista.” Compaiono nelle impostazioni, nei filtri e nei moduli in tutta l’app. Il modal di cancellazione dati ha un set di checkbox particolarmente soddisfacente dove puoi scegliere la tua stessa distruzione.

Autocomplete

Un campo di testo che suggerisce completamenti mentre digiti. La ricerca giocatori nel browser del database lo usa — inizia a digitare un nome e i giocatori corrispondenti appaiono sotto.

FileInput & DateInput

FileInput apre un selettore di file quando viene cliccato — usato nel modal di importazione per caricare file PGN. DateInput apre un calendario per selezionare una data — usato per filtrare le partite per data. Ci sono anche MonthPickerInput e YearPickerInput per quando serve meno precisione (filtraggio del database Lichess per mese, filtraggio del database Masters per anno).

Quelle che mostrano il progresso

Progress Bar

Una barra orizzontale che si riempie da sinistra a destra per mostrare a che punto siamo. Usata durante gli aggiornamenti dell’app (progresso del download) e — in modo più creativo — per mostrare le probabilità Vittoria/Patta/Sconfitta nel pannello di analisi. Tre sezioni colorate (bianco, grigio, nero) riempiono la barra proporzionalmente. È un piccolo grafico a barre travestito da indicatore di progresso.

Loader

Un Loader è un’animazione rotante che dice “Ci sto lavorando, dammi un secondo.” Compare mentre i database si caricano, le statistiche dei giocatori vengono recuperate, o qualsiasi operazione asincrona è in corso.

Skeleton

Uno Skeleton è un segnaposto grigio che imita la forma del contenuto che non è ancora stato caricato. Invece di una schermata vuota o uno spinner, vedi i contorni fantasma di dove card e testo saranno. È il progetto architettonico di uno stato di caricamento — “i mobili veri sono in arrivo.”

La pagina dei database usa gli skeleton mentre la griglia di card si carica. Molto più elegante di uno spinner da solo.

LoadingOverlay

Una coperta semitrasparente gettata sopra un componente mentre si sta caricando. Il grafico di analisi lo usa — puoi ancora vedere il grafico dietro l’overlay, ma è oscurato, e c’è uno spinner sopra. “Sono ancora qui, mi sto solo aggiornando.”

Quelle che etichettano le cose

Badge

Un Badge è una piccola etichetta colorata — come un badge con il nome a una conferenza. In En Parlant~, il componente SpeedBadge usa i badge per mostrare i controlli di tempo con codifica a colori:

🩷 Rosa — UltraBullet
🔴 Rosso — Bullet
🟠 Arancione — Blitz
🟢 Verde — Rapid
🔵 Blu — Classical
🟣 Viola — Correspondence

Ogni badge è piccolo, colorato, e comunica istantaneamente la velocità della partita a colpo d’occhio.

Kbd

Abbreviazione di keyboard. Mostra un tasto della tastiera con quel caratteristico stile a tasto rialzato. Usato nelle impostazioni delle scorciatoie per mostrare cose come Ctrl + Z. È una ricreazione CSS di un vero tasto fisico sulla tastiera. Deliziosamente scheumorfismo.

Quelle che separano e comprimono

Divider

Una linea orizzontale che separa le sezioni. Tutto qui. È una linea. Ma è una linea stilizzata, e può facoltativamente avere un’etichetta di testo al centro — come il separatore ”— OPPURE —” nel modal di importazione che separa “incolla un PGN” da “inserisci un FEN.”

Più di trenta file usano Divider. A quanto pare, le cose hanno spesso bisogno di essere separate.

Collapse

Un Collapse è una sezione che si espande e si contrae con un’animazione fluida. Clicca per rivelare, clicca per nascondere. Le opzioni di filtro del database lo usano — non hai sempre bisogno di vedere ogni filtro, quindi si nascondono dietro un Collapse finché non li vuoi.

Quelle sofisticate

RichTextEditor

Un editor di testo completo con formattazione visuale (WYSIWYG), costruito su TipTap. Grassetto, corsivo, elenchi, tutto il necessario. Usato per scrivere annotazioni alle partite — quelle note di commento che aggiungi per spiegare perché una mossa era brillante o terribile.

Questa è l’unica primitiva che è più un organismo composto che una singola cellula. Sotto il cofano è TipTap + ProseMirror + stile Mantine. Ma dal punto di vista dell’utente, è semplicemente un campo di testo dove la formattazione funziona.

AreaChart

Da @mantine/charts (che fa da wrapper per Recharts), l’AreaChart alimenta il grafico di valutazione — quella forma d’onda che corre lungo la parte inferiore del pannello di analisi. L’area bianca sopra la linea mediana significa che il Bianco sta vincendo; il nero sotto significa che il Nero sta vincendo.

Puoi cliccare su qualsiasi punto del grafico per saltare a quella mossa. Visualizzazione interattiva dei dati che incontra l’analisi scacchistica. Ha persino tooltip personalizzati e linee di riferimento che segnano le fasi della partita (apertura → mediogioco → finale).

DataTable

Tramite la libreria mantine-datatable — una tabella dati completa con ordinamento, paginazione, selezione delle righe e filtraggio. Alimenta la lista delle partite, la lista dei giocatori e la lista dei tornei del browser del database. È un foglio di calcolo che sa di essere in un’app di scacchi.

Quelle invisibili

Alcune primitive non renderizzano nulla di visibile da sole, ma fanno funzionare tutto il resto:

MantineProvider — avvolge l’intera app e fornisce il tema (colori, modalità scura, valori predefiniti dei componenti)
Portal — teletrasporta il contenuto renderizzato in una parte diversa del DOM
useHotkeys — un hook (non un componente) che collega le scorciatoie da tastiera
useForm — gestisce lo stato dei moduli, la validazione e la gestione degli errori
useDebouncedValue — aspetta che tu smetta di digitare prima di lanciare una ricerca. L’hook educato.

L’inventario completo

Per riferimento, ecco ogni famiglia di primitive usata in En Parlant~, raggruppata per funzione:

Categoria	Primitive
Layout	AppShell, Box, Center, Flex, Group, Stack, SimpleGrid, ScrollArea, Portal
Superfici	Card, Paper
Overlay	Modal, Tooltip, Popover, Menu, ContextMenu, LoadingOverlay
Notifiche	Toast (tramite `@mantine/notifications`)
Pulsanti	Button, ActionIcon, CloseButton, ThemeIcon
Input	TextInput, Textarea, NumberInput, Select, Autocomplete, Checkbox, Switch, Slider, RangeSlider, SegmentedControl, FileInput, DateInput, MonthPickerInput, YearPickerInput
Visualizzazione dati	Table, DataTable, Badge, Code, Kbd, Rating, Image
Tipografia	Text, Title, Anchor
Progresso	Progress, Loader, Skeleton
Struttura	Divider, Collapse
Contenuti ricchi	RichTextEditor (TipTap), AreaChart (Recharts)
Temi	MantineProvider, createTheme, useColorScheme
Hook	useForm, useHotkeys, useToggle, useDebouncedValue, useClickOutside, useElementSize

Tutto proviene da Mantine v8 e dai suoi pacchetti dell’ecosistema: @mantine/core, @mantine/notifications, @mantine/dates, @mantine/charts, @mantine/form, @mantine/tiptap, mantine-datatable e mantine-contextmenu.

Ora lo sai

La prossima volta che vedi un piccolo messaggio scorrere dall’angolo dello schermo — quello è un toast. Il rettangolo attorno a un’anteprima di partita — quella è una card. Le sagome grigie che tremolano prima che il contenuto si carichi — quelli sono skeleton.

Una volta che impari i nomi, inizi a vederli ovunque. In ogni app. In ogni sito web. Le stesse due dozzine di primitive, riorganizzate in mille modi diversi.

Sono mattoncini Lego, fino in fondo.