Prymitywy UI — przewodnik po elementach interfejsu

Jeśli kiedykolwiek patrzyłeś na nowoczesną aplikację i myślałeś „jak oni nazywają ten element?” — ta strona jest właśnie dla Ciebie.

Każdy interfejs, z którego korzystasz, zbudowany jest z zaskakująco niewielkiego zestawu wielokrotnie używanych bloków konstrukcyjnych zwanych prymitywami UI. Mają swoje nazwy. Czasem dziwne nazwy. Ale kiedy raz zobaczysz stojącą za nimi metaforę, nie da się jej odzobaczyć.

En Parlant~ wykorzystuje Mantine, bibliotekę komponentów React, która dostarcza je wszystkie od razu. Oto Twój przewodnik.

Te, które brzmią jak meble

Toast

Toast to małe powiadomienie, które wyskakuje z krawędzi ekranu, wisi przez kilka sekund, a potem odpływa. Jak kromka chleba wyskakująca z tostera — tyle że grawitacja działa odwrotnie i kromka w końcu wraca do środka.

W En Parlant~ toasty pojawiają się w prawym dolnym rogu (za pośrednictwem @mantine/notifications) dla komunikatów takich jak:

„Baza danych załadowana pomyślnie” — pop
„Głos TTS nie skonfigurowany” — pop
„Nie udało się połączyć z Lichess” — pop, i czujesz lekki smutek

Nigdy o nie nie prosiłeś. Po prostu się pojawiają, dostarczają swoją wiadomość i znikają. To gołębie pocztowe świata UI.

Card

Card (karta) to prostokątny kontener z obramowaniem lub cieniem, który grupuje powiązane ze sobą treści. Wyobraź sobie fiszkę leżącą na biurku — ma wyraźne krawędzie, przechowuje jedną rzecz i możesz ją podnieść i przenieść.

W En Parlant~ karty znajdziesz w:

Podglądach partii w przeglądarce baz danych (GameCard) — nazwy graczy, wynik, data
Edytorze pozycji (EditingCard) — karta, którą odwracasz przy ustawianiu niestandardowej pozycji
Wpisach baz danych na stronie baz danych — każda baza dostaje własną kartę w siatce

Karty mają bliskiego kuzyna o nazwie Paper, który jest w zasadzie kartą, która skończyła szkołę artystyczną. Ten sam pomysł — kontener z obramowaniem lub cieniem — ale z mniejszym znaczeniem semantycznym. Paper mówi po prostu „jestem powierzchnią”. Pojawia się jako tło za panelami analizy i wyświetlaczami informacji o bazach danych.

Drawer / Sheet

Aktualnie nieużywane w En Parlant~, ale warto wiedzieć: drawer (szuflada) to panel, który wysuwa się z krawędzi ekranu, jak szuflada biurka. (To wszystko. To cała metafora. Projektanci UI byli tego dnia bardzo dosłowni.)

Te, które blokują Ci drogę

Modal to wyskakujące okno dialogowe, które wymaga Twojej uwagi. Przyciemnia tło i zmusza Cię do zajęcia się nim, zanim zrobisz cokolwiek innego. To maluch wśród wzorców UI — „PATRZ NA MNIE TERAZ.”

En Parlant~ używa modali w momentach, które naprawdę wymagają Twojej uwagi:

„Czy na pewno chcesz wyczyścić wszystkie dane?” (ClearDataModal) — z checkboxami, dzięki którym możesz wybrać, które dane chcesz unicestwić
„Dostępna jest aktualizacja” (UpdateModal) — z paskiem postępu podczas pobierania
„Importuj partię” (ImportModal) — wklej PGN, wpisz FEN lub upuść link
„Utwórz nowy repertuar” (CreateRepertoireModal) — nazwij go, skonfiguruj, działaj
„O En Parlant~” (About) — informacje o wersji, twórcy, zwykła przepustka za kulisy

Modale mówią: „To jest rozmowa. Odbywa się teraz.”

Dialog

Dialog to uprzejmy kuzyn modala. W Mantine to zasadniczo ten sam komponent, ale w teorii projektowania UI dialog jest mniejszy i bardziej skoncentrowany — jedno pytanie i jedna odpowiedź. „Zapisać zmiany?” Tak / Nie. Gotowe.

En Parlant~ używa ConfirmModal do tych szybkich momentów tak-albo-nie, jak potwierdzenie, że chcesz odrzucić niezapisane zmiany.

Te, które pojawiają się i znikają

Tooltip (podpowiedź) to mała etykieta, która pojawia się, gdy najedziesz kursorem na coś. To pomocny nieznajomy, który szepcze odpowiedź, gdy wyglądasz na zdezorientowanego.

Tooltipy są wszędzie w En Parlant~. Najedź kursorem na prawie dowolny przycisk z ikoną, a pojawi się podpowiedź:

Najedź na przycisk ↻ → „Odśwież”
Najedź na obciętą ścieżkę pliku → pojawia się pełna ścieżka
Najedź na symbol adnotacji → wyjaśnienie, co ten symbol oznacza
Najedź na ruch w panelu analizy → wyskakuje miniaturowy podgląd szachownicy

Tooltipy to oryginalne „instrukcja nie jest potrzebna”.

Popover to tooltip, który skończył studia podyplomowe. Zamiast pokazywać tylko etykietę tekstową, może zawierać cokolwiek — przyciski, obrazy, a nawet miniaturową szachownicę.

W En Parlant~, gdy najedziesz kursorem na ruch w analizie silnika, popover renderuje podgląd szachownicy w tej pozycji. To tooltip, ale przyniósł pomoce wizualne.

Menu to lista akcji, która pojawia się po kliknięciu (lub kliknięciu prawym przyciskiem) na coś. Używasz ich od zarania informatyki — Plik, Edycja, Widok. Znasz to.

En Parlant~ ma dwa warianty:

Menu górnego paska — klasyczny pasek menu Plik / Edycja / Widok, zbudowany z komponentu Menu z Mantine. Skróty klawiaturowe wypisane po prawej. Wzorzec projektowy tak stary, że pobiera emeryturę.
Menu kontekstowe — kliknij prawym przyciskiem na ruch w drzewie partii i dostaniesz opcje takie jak Promuj wariant, Usuń stąd i Kopiuj linię. Korzystają z biblioteki mantine-contextmenu dla dodatkowego szlifu.

Menu mają własne pod-słownictwo: Menu.Target (element, który klikasz), Menu.Dropdown (lista, która się pojawia), Menu.Item (każda opcja) i Menu.Divider (cienka linia, która mówi „teraz inna sekcja”).

Te, które organizują przestrzeń

Stack i Group

To masło orzechowe i dżem wśród elementów układu.

Stack układa rzeczy pionowo — jedno na drugim. Jak układanie książek w stos.
Group układa rzeczy poziomo — obok siebie. Jak ustawianie figur szachowych na półce.

Pojawiają się dosłownie w ponad 100 plikach każdy. To najczęstsze komponenty w całej aplikacji. Za każdym razem, gdy rzeczy są schludnie ułożone, odpowiada za to Stack lub Group.

Flex

Flex to szwajcarski scyzoryk — kuzyn Stack i Group. Kiedy elementy muszą się zawijać, rozciągać, kurczyć, odwracać lub w inny sposób zachowywać się nietypowo, Flex wkracza z pełną kontrolą nad modelem CSS Flexbox.

Używany w liście ruchów panelu analizy — te sekwencje ruchów, które zawijają się i płyną jak tekst? To Flex wykonuje ciężką pracę.

Box

Box to <div> w cylindrze. Sam z siebie nic nie robi — to po prostu generyczny kontener. Ale akceptuje propsy stylizacji Mantine, co czyni go niesamowicie poręcznym wrapperem dla „potrzebuję czegoś wokół tego czegoś”.

Box pojawia się w ponad 150 plikach. To taśma klejąca biblioteki komponentów.

Center

Robi dokładnie to, co mówi. Umieszcza coś na środku. Poziomo. Pionowo. Jedno i drugie. Gotowe.

Pojawia się w stanach pustych — gdy nie ma podłączonych kont, załadowanych baz danych, żadnych danych. Duża ikona, komunikat i Center upewniający się, że wszystko jest idealnie wyśrodkowane. Nikt nie lubi wyśrodkowanego krzywo stanu pustego.

SimpleGrid

Siatka, która jest prosta. Mówisz jej, ile kolumn, a ona rozmieszcza Twoje karty w schludnej siatce, która się przeukłada przy zmianie rozmiaru okna. Strona baz danych używa jej do rozmieszczania kart baz danych w responsywnej siatce.

ScrollArea

Kontener, który przewija się, gdy jego zawartość wykracza poza granice. Mogłoby się wydawać, że to darmowe — i w pewnym sensie jest, dzięki CSS overflow: auto — ale ScrollArea dodaje stylizowane paski przewijania, płynne przewijanie i wykrywanie przepełnienia. Otacza panel drzewa partii, linie analizy i każde miejsce, gdzie treść może urosnąć wyżej niż jej pudełko.

AppShell

AppShell to główny układ — szkielet całej aplikacji. Definiuje, gdzie idzie nagłówek, gdzie idzie pasek boczny i gdzie żyje główna treść. Wszystko inne zagnieżdża się w jego wnętrzu.

Używasz go tylko raz. To fundament domu.

Portal

Portal to magiczny tunel czasoprzestrzenny. Renderuje komponent poza jego normalną pozycją w drzewie DOM i umieszcza go gdzieś indziej — zwykle w korzeniu dokumentu. Dzięki temu popovery i podglądy szachownicy unikają obcinania przez kontenery nadrzędne z overflow: hidden.

Nigdy nie widzisz Portala. Widzisz tylko jego efekty. To ekipa techniczna wśród komponentów UI.

Te, z którymi wchodzisz w interakcję

Button

Klikalny prostokąt z tekstem. Znasz go. W Mantine przyciski występują w wariantach:

filled — jednolity kolor, duże wyróżnienie. „Kliknij mnie, jestem ważny.”
outline — tylko obramowanie. „Jestem opcją, ale bez presji.”
subtle — ledwie widoczny. „Jestem tu, gdybyś mnie potrzebował.”
default — neutralny środek.

En Parlant~ używa ich wszystkich w ponad 150 plikach. Najczęstszy wzorzec: Group przycisków na dole modala — „Anuluj” (subtle) i „Potwierdź” (filled). Klasyka.

ActionIcon

ActionIcon to przycisk, który zrezygnował z etykiety tekstowej i w pełni poświęcił się stylowi życia ikony. Jest kompaktowy, kwadratowy i polega na swojej ikonie (plus tooltip), aby komunikować swoje przeznaczenie.

Przyciski paska narzędzi, kontrolki paneli, przyciski zamykania — to wszystko ActionIcons. To najbardziej oszczędny przestrzennie sposób na zaoferowanie akcji.

Switch

Switch to przełącznik, który wygląda jak mały włącznik światła. Przesuń w lewo, przesuń w prawo. Włączony. Wyłączony.

W ustawieniach przełączniki kontrolują wybory binarne:

Dźwięk wł./wył.
Narracja TTS włączona/wyłączona
Tryb ciemny / tryb jasny

Metafora fizyczna jest tak dobra, że nawet Twoi dziadkowie ją rozumieją.

Slider

Slider to ścieżka z uchwytem, który przeciągasz w tę i z powrotem, aby wybrać wartość. Jak pokrętło głośności, które ktoś spłaszczył.

En Parlant~ używa sliderów do:

Rozmiar czcionki — przeciągnij, aby dostosować
Głośność — przeciągnij, aby dostosować (oczywiście)
Rdzenie procesora — ile rdzeni powinien używać silnik?
Pamięć hash — ile RAM-u na tablicę hashującą silnika?

Jest też RangeSlider z dwoma uchwytami do wybierania zakresu — używany do filtrowania partii według rankingu Elo (np. 2000–2200) i okresów czasowych.

SegmentedControl

Rząd przycisków, z których dokładnie jeden jest wybrany w danym momencie. To jak przyciski stacji w radiu samochodowym — wciśnij jeden, pozostałe wyskoczą.

Używany do przełączania między:

Oceną w centypionkach a procentami Wygrana/Remis/Przegrana na wykresie analizy
Różnymi formatami notacji ruchów
Liczbą linii silnika

Checkbox i Select

Znasz je. Checkboxy do „zaznacz wszystkie pasujące”, rozwijane listy Select do „wybierz jeden z listy”. Pojawiają się w ustawieniach, filtrach i formularzach w całej aplikacji. Modal czyszczenia danych ma szczególnie satysfakcjonujący zestaw checkboxów, w którym możesz wybrać swoje własne zniszczenie.

Autocomplete

Pole tekstowe, które sugeruje uzupełnienia podczas pisania. Wyszukiwanie graczy w przeglądarce baz danych tego używa — zacznij wpisywać imię, a pasujący gracze pojawiają się poniżej.

FileInput i DateInput

FileInput otwiera selektor plików po kliknięciu — używany w modalu importu do ładowania plików PGN. DateInput otwiera kalendarz do wyboru daty — używany do filtrowania partii według daty. Są też MonthPickerInput i YearPickerInput na wypadek, gdy potrzebujesz mniejszej precyzji (filtrowanie bazy Lichess po miesiącu, filtrowanie bazy mistrzów po roku).

Te, które pokazują postęp

Progress Bar

Poziomy pasek, który wypełnia się od lewej do prawej, pokazując, jak daleko coś zaszło. Używany podczas aktualizacji aplikacji (postęp pobierania) i — bardziej kreatywnie — do pokazywania prawdopodobieństw Wygrana/Remis/Przegrana w panelu analizy. Trzy kolorowe sekcje (biała, szara, czarna) wypełniają pasek proporcjonalnie. To miniaturowy wykres słupkowy przebrany za wskaźnik postępu.

Loader

Loader to animacja kręcenia, która mówi „pracuję nad tym, daj mi sekundę”. Pojawia się podczas ładowania baz danych, pobierania statystyk graczy lub kiedy dzieje się cokolwiek asynchronicznego.

Skeleton

Skeleton to szary element zastępczy, który naśladuje kształt treści, która jeszcze się nie załadowała. Zamiast pustego ekranu czy kręcącego się spinnera widzisz upiorny zarys miejsc, gdzie karty i tekst będą. To architektoniczny plan stanu ładowania — „prawdziwe meble są w drodze.”

Strona baz danych używa skeletonów podczas ładowania siatki kart. Znacznie bardziej eleganckie niż sam spinner.

LoadingOverlay

Półprzezroczysta narzuta nałożona na komponent podczas ładowania. Wykres analizy tego używa — wciąż widzisz wykres za nakładką, ale jest przyciemniony, a na wierzchu jest spinner. „Wciąż tu jestem, po prostu się aktualizuję.”

Te, które etykietują rzeczy

Badge

Badge (odznaka) to mała kolorowa etykieta — jak identyfikator na konferencji. W En Parlant~ komponent SpeedBadge używa odznak do wyświetlania kontroli czasu z kodowaniem kolorami:

🩷 Różowy — UltraBullet
🔴 Czerwony — Bullet
🟠 Pomarańczowy — Blitz
🟢 Zielony — Rapid
🔵 Niebieski — Classical
🟣 Fioletowy — Correspondence

Każda odznaka jest malutka, kolorowa i natychmiast komunikuje tempo gry jednym rzutem oka.

Kbd

Skrót od keyboard (klawiatura). Wyświetla klawisz z charakterystycznym stylem uniesionego klawisza. Używany w ustawieniach skrótów klawiaturowych do pokazywania rzeczy takich jak Ctrl + Z. To odtworzenie w CSS prawdziwego, fizycznego klawisza na Twojej klawiaturze. Uroczo skeumorficzne.

Te, które rozdzielają i zwijają

Divider

Pozioma linia, która rozdziela sekcje. To tyle. To linia. Ale to stylizowana linia, która opcjonalnie może mieć etykietę tekstową na środku — jak separator „— LUB —” w modalu importu, który oddziela „wklej PGN” od „wpisz FEN”.

Ponad trzydzieści plików używa Divider. Okazuje się, że rzeczy wymagają częstego rozdzielania.

Collapse

Collapse to sekcja, która rozwija się i zwija z płynną animacją. Kliknij, aby odsłonić, kliknij, aby ukryć. Opcje filtrów baz danych tego używają — nie zawsze musisz widzieć każdy filtr, więc chowają się za Collapse, dopóki ich nie potrzebujesz.

Te zaawansowane

RichTextEditor

Pełnoprawny edytor WYSIWYG (widzisz to, co dostajesz), zbudowany na TipTap. Pogrubienie, kursywa, listy — pełen zestaw. Używany do pisania adnotacji do partii — tych komentarzy, które dodajesz, aby wyjaśnić, dlaczego ruch był genialny lub fatalny.

To jedyny prymityw, który jest bardziej złożonym organizmem niż pojedynczą komórką. Pod maską to TipTap + ProseMirror + stylizacja Mantine. Ale z perspektywy użytkownika to po prostu pole tekstowe, w którym formatowanie działa.

AreaChart

Z @mantine/charts (który opakowuje Recharts), AreaChart napędza wykres ewaluacji — tę falę biegnącą wzdłuż dolnej części panelu analizy. Biały obszar nad linią środkową oznacza, że białe wygrywa; czarny poniżej oznacza, że czarne wygrywa.

Możesz kliknąć dowolny punkt na wykresie, aby przeskoczyć do tego ruchu. Interaktywna wizualizacja danych spotyka analizę szachową. Wykres ma nawet niestandardowe tooltipy i linie odniesienia zaznaczające fazy gry (otwarcie → gra środkowa → końcówka).

DataTable

Za pośrednictwem biblioteki mantine-datatable — w pełni funkcjonalna tabela danych z sortowaniem, paginacją, zaznaczaniem wierszy i filtrowaniem. Napędza listę partii, listę graczy i listę turniejów w przeglądarce baz danych. To arkusz kalkulacyjny, który wie, że jest w aplikacji szachowej.

Te niewidzialne

Niektóre prymitywy same nie renderują niczego widocznego, ale sprawiają, że wszystko inne działa:

MantineProvider — opakowuje całą aplikację i dostarcza motyw (kolory, tryb ciemny, domyślne wartości komponentów)
Portal — teleportuje wyrenderowaną treść do innej części DOM
useHotkeys — hook (nie komponent), który podpina skróty klawiaturowe
useForm — zarządza stanem formularzy, walidacją i obsługą błędów
useDebouncedValue — czeka, aż przestaniesz pisać, zanim uruchomi wyszukiwanie. Uprzejmy hook.

Pełny spis

Dla odniesienia — oto każda rodzina prymitywów używana w En Parlant~, pogrupowana według funkcji:

Kategoria	Prymitywy
Układ	AppShell, Box, Center, Flex, Group, Stack, SimpleGrid, ScrollArea, Portal
Powierzchnie	Card, Paper
Nakładki	Modal, Tooltip, Popover, Menu, ContextMenu, LoadingOverlay
Powiadomienia	Toast (via `@mantine/notifications`)
Przyciski	Button, ActionIcon, CloseButton, ThemeIcon
Pola wejściowe	TextInput, Textarea, NumberInput, Select, Autocomplete, Checkbox, Switch, Slider, RangeSlider, SegmentedControl, FileInput, DateInput, MonthPickerInput, YearPickerInput
Wyświetlanie danych	Table, DataTable, Badge, Code, Kbd, Rating, Image
Typografia	Text, Title, Anchor
Postęp	Progress, Loader, Skeleton
Struktura	Divider, Collapse
Treści rozbudowane	RichTextEditor (TipTap), AreaChart (Recharts)
Motyw	MantineProvider, createTheme, useColorScheme
Hooki	useForm, useHotkeys, useToggle, useDebouncedValue, useClickOutside, useElementSize

Wszystko pochodzi z Mantine v8 i jego pakietów ekosystemowych: @mantine/core, @mantine/notifications, @mantine/dates, @mantine/charts, @mantine/form, @mantine/tiptap, mantine-datatable i mantine-contextmenu.

Teraz już wiesz

Następnym razem, gdy zobaczysz mały komunikat wyjeżdżający z rogu ekranu — to toast. Prostokąt wokół podglądu partii — to karta. Szare kształty migoczące przed załadowaniem treści — to skeletony.

Kiedy poznasz nazwy, zaczynasz je widzieć wszędzie. W każdej aplikacji. Na każdej stronie. Tych samych kilkadziesiąt prymitywów, ułożonych na tysiąc różnych sposobów.

To klocki Lego — aż do samego końca.