Aller au contenu

Composants et blocks

Les familles de composants de waka-ui, les blocks prêts à l'emploi, les façons de les importer et les points d'entrée qui demandent une dépendance en plus.

ConceptDéveloppeur
Voir en Markdown

waka-ui contient plus de 250 composants et plus de 50 blocks. Cette page en donne la carte ; le détail de chaque composant, avec ses variantes et ses propriétés, se consulte sur le design system ui.wakastart.app.

Composants

Un composant est une brique d'interface : un bouton, un champ, une fenêtre. Les composants de base reprennent les noms et le fonctionnement de shadcn/ui et s'appuient sur Radix UI pour l'accessibilité : navigation au clavier, gestion du focus, attributs ARIA. Les composants propres à waka-ui portent le préfixe Waka.

FamilleExemples
BaseButton, Card, Badge, Avatar, Tabs, Accordion, Separator, Skeleton
FormulairesInput, Textarea, Select, Checkbox, Switch, Form, WakaDateTimePicker, WakaPhoneInput, WakaFileUpload
Fenêtres et menusDialog, Sheet, Popover, DropdownMenu, Tooltip, Command
NavigationWakaBreadcrumb, WakaStepper, WakaPagination, WakaBottomTabBar
RetoursuseToast et Toaster, Alert, WakaEmptyState, WakaSpinner
DonnéesDataTable, DataTableAdvanced, WakaTimeline, WakaKanban, WakaTree
GraphiquesWakaBarChart, WakaLineChart, WakaPieChart, WakaAreaChart
Thème et langueThemeSelector, LanguageSelector, WakaFlagIcon

D'autres familles couvrent des besoins métier plus spécifiques : crédits et paiement, sécurité, supervision technique, gamification. Parcourez-les sur ui.wakastart.app avant de développer un écran : il existe peut-être déjà.

Tableaux de données

DataTable affiche une liste paginée, triable et filtrable à partir d'un tableau d'objets et d'une définition de colonnes. Le type ColumnDef est exporté par @wakastellar/ui : vous n'avez pas à installer TanStack Table vous-même.

TSX
"use client";

import { DataTable, type ColumnDef } from "@wakastellar/ui";

type Member = { name: string; email: string; role: string };

const columns: ColumnDef<Member>[] = [
  { accessorKey: "name", header: "Nom" },
  { accessorKey: "email", header: "E-mail" },
  { accessorKey: "role", header: "Rôle" },
];

export function MembersTable({ members }: { members: Member[] }) {
  return (
    <DataTable
      data={members}
      columns={columns}
      pagination={{ mode: "client", pageSize: 20 }}
      toolbar={{ showSearch: true, showColumnToggle: true }}
    />
  );
}

Pour une pagination côté serveur, passez mode: "server" avec totalItems, currentPage et onPageChange. DataTableAdvanced ajoute l'édition en ligne, le regroupement et l'export.

Blocks

Un block est un écran ou une grande section d'écran, assemblé à partir de composants : un en-tête, une barre latérale, une page de profil. Vous lui passez des données et des fonctions de rappel ; il ne charge rien lui-même.

UsageExemples
Structure de l'applicationWakaHeader, WakaSidebar, SidebarLayout, Footer, Layout
Compte et organisationprofil, paramètres, gestion des utilisateurs, formulaire d'équipe, WakaApiKeysManager
États et erreursWakaErrorPage, Error404Page, NoDataState, NoResultsState, ErrorState
Tableaux de bordtableaux de bord, indicateurs clés, calendrier, Kanban
ContenusFAQ, page d'accueil, grille tarifaire, notes de version

Un block se branche sur vos données Wakastart par ses propriétés. Par exemple, WakaApiKeysManager affiche une liste de clés et appelle onCreate, onRevoke et onRotate : c'est à votre application d'appeler l'API, comme décrit dans Proposer les clés dans votre wakapp.

Important

Le block Login dessine un formulaire e-mail et mot de passe. Avec Wakastart, l'utilisateur saisit son mot de passe sur la page de connexion de la plateforme, jamais dans votre application : suivez Authentification pour la connexion, et personnalisez cette page avec un thème de connexion.

Importer un composant

Trois écritures sont possibles :

TSX
// 1. Le point d'entrée principal : tous les composants, blocks, fournisseurs et hooks.
import { Button, DataTable, WakaProvider } from "@wakastellar/ui";

// 2. Un composant seul, par le nom de son dossier.
import { Button } from "@wakastellar/ui/components/button";

// 3. Un block seul.
import { WakaErrorPage } from "@wakastellar/ui/blocks/error-pages";

Le point d'entrée principal est le plus simple ; c'est lui qui demande recharts et react-hook-form à l'installation. Les imports par composant ne chargent que le composant visé.

Tous les modules de waka-ui sont marqués "use client" : vous pouvez les utiliser depuis un composant serveur, ils deviennent des composants client à cet endroit. Une propriété qui reçoit une fonction (onClick, onPageChange) impose en revanche que le composant parent soit lui-même un composant client.

Points d'entrée dédiés

Les composants les plus lourds ont leur propre point d'entrée. Installez la dépendance indiquée avant de les importer.

Point d'entréeContenuÀ installer
@wakastellar/ui/chartsgraphiques WakaBarChart, WakaLineChart, WakaPieChart…recharts@^2
@wakastellar/ui/rich-textéditeur de texte riche WakaRichTextEditor@tiptap/react, @tiptap/starter-kit, @tiptap/extension-link, @tiptap/extension-text-align, @tiptap/extension-underline (3.30.5 ou plus, avant 4)
@wakastellar/ui/exportexport et import des tableaux : useDataTableExport, useDataTableImportexceljs pour le format xlsx ; jspdf et jspdf-autotable pour le PDF. CSV, JSON et XML sans dépendance
@wakastellar/ui/docrendu de documentation : WakaDocRenderer, WakaDocShell…react-markdown, remark-gfm, rehype-slug, rehype-raw ; pour l'édition, en plus les paquets tiptap et tiptap-markdown
@wakastellar/ui/editoréditeur de blocs WakaEditor, sur Plateplatejs, @platejs/basic-nodes, @platejs/table, @platejs/layout, @platejs/callout (52 ou plus)
@wakastellar/ui/md-editoréditeur Markdown WakaMdEditorrien : moteur et styles inclus

@wakastellar/ui/md-editor embarque son moteur complet (formules, diagrammes, coloration syntaxique) : chargez-le à la demande, côté navigateur seulement.

TSX
"use client";

import dynamic from "next/dynamic";

const WakaMdEditor = dynamic(
  () => import("@wakastellar/ui/md-editor").then((m) => m.WakaMdEditor),
  { ssr: false },
);

export function NoteEditor({ initial, onChange }: { initial: string; onChange: (md: string) => void }) {
  return <WakaMdEditor defaultValue={initial} onChange={onChange} />;
}

Pour aller plus loin