# 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.

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](https://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](https://ui.shadcn.com) 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`.

| Famille | Exemples |
|---|---|
| Base | `Button`, `Card`, `Badge`, `Avatar`, `Tabs`, `Accordion`, `Separator`, `Skeleton` |
| Formulaires | `Input`, `Textarea`, `Select`, `Checkbox`, `Switch`, `Form`, `WakaDateTimePicker`, `WakaPhoneInput`, `WakaFileUpload` |
| Fenêtres et menus | `Dialog`, `Sheet`, `Popover`, `DropdownMenu`, `Tooltip`, `Command` |
| Navigation | `WakaBreadcrumb`, `WakaStepper`, `WakaPagination`, `WakaBottomTabBar` |
| Retours | `useToast` et `Toaster`, `Alert`, `WakaEmptyState`, `WakaSpinner` |
| Données | `DataTable`, `DataTableAdvanced`, `WakaTimeline`, `WakaKanban`, `WakaTree` |
| Graphiques | `WakaBarChart`, `WakaLineChart`, `WakaPieChart`, `WakaAreaChart` |
| Thème et langue | `ThemeSelector`, `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](https://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.

| Usage | Exemples |
|---|---|
| Structure de l'application | `WakaHeader`, `WakaSidebar`, `SidebarLayout`, `Footer`, `Layout` |
| Compte et organisation | profil, paramètres, gestion des utilisateurs, formulaire d'équipe, `WakaApiKeysManager` |
| États et erreurs | `WakaErrorPage`, `Error404Page`, `NoDataState`, `NoResultsState`, `ErrorState` |
| Tableaux de bord | tableaux de bord, indicateurs clés, calendrier, Kanban |
| Contenus | FAQ, 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](/v1.0/cles-api/proposer-les-cles-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](/v1.0/authentification) pour la connexion, et personnalisez cette page avec un [thème de connexion](/v1.0/page-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ée | Contenu | À installer |
|---|---|---|
| `@wakastellar/ui/charts` | graphiques `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/export` | export et import des tableaux : `useDataTableExport`, `useDataTableImport` | `exceljs` pour le format xlsx ; `jspdf` et `jspdf-autotable` pour le PDF. CSV, JSON et XML sans dépendance |
| `@wakastellar/ui/doc` | rendu 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 Plate | `platejs`, `@platejs/basic-nodes`, `@platejs/table`, `@platejs/layout`, `@platejs/callout` (52 ou plus) |
| `@wakastellar/ui/md-editor` | éditeur Markdown `WakaMdEditor` | rien : 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

- [ui.wakastart.app](https://ui.wakastart.app) : le catalogue des composants et des blocks, avec des exemples interactifs.
- [Référence de waka-ui](/v1.0/interface-waka-ui/reference) : tous les points d'entrée du paquet.
- [Appliquer le thème](/v1.0/interface-waka-ui/appliquer-le-theme)
