@wakastellar/ui

Bibliothèque de 200+ composants React professionnels pour applications Next.js modernes

Quick Start • CLI • Tailwind v3/v4 • Composants • Thèmes • i18n

Caractéristiques

• 200+ composants - UI complète basée sur Radix UI
• Tailwind v3 & v4 - Compatible avec les deux versions, zero-config
• DataTable avancé - TanStack Table v8 avec tri, filtres, pagination, édition inline, export
• Système de thèmes - Format shadcn/ui registry-item, chargement dynamique JSON
• Internationalisation - i18next intégré avec chargement JSON à la volée
• TypeScript strict - API 100% typée
• SSR/Next.js 15+ - Compatible App Router et React 18+
• Accessible - WCAG compliant via Radix UI

Quick Start

Option 1 : Package complet (recommandé)

pnpm add @wakastellar/ui
# ou
npm install @wakastellar/ui

import { Button, Card, CardHeader, CardTitle, CardContent } from "@wakastellar/ui"

export default function Page() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello World</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Click me</Button>
      </CardContent>
    </Card>
  )
}

Option 2 : CLI (composants individuels)

# Initialiser votre projet
npx wakastellar-ui init

# Ajouter des composants
npx wakastellar-ui add button card input

# Lister les composants disponibles
npx wakastellar-ui list

# Rechercher un composant
npx wakastellar-ui search "date picker"

Voir la section CLI pour plus de détails.

Compatibilité Tailwind v3 / v4

La librairie supporte Tailwind CSS v3 et v4 avec une configuration minimale.

Tailwind v4 (zero-config)

Pour les projets utilisant Tailwind CSS v4, aucune configuration supplémentaire n'est nécessaire :

// app/globals.css (ou app/layout.tsx)
import "@wakastellar/ui/styles"

C'est tout ! Les composants fonctionnent immédiatement.

Tailwind v3

Pour les projets utilisant Tailwind CSS v3, deux étapes simples :

1. Import du CSS v3 :

// app/globals.css (ou app/layout.tsx)
import "@wakastellar/ui/styles/v3"

2. Configuration Tailwind :

// tailwind.config.js
module.exports = {
  presets: [require("@wakastellar/ui/tailwind-preset")],
  content: [
    "./app/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@wakastellar/ui/**/*.{js,ts,jsx,tsx}",
  ],
  // ... votre configuration
}

Résumé

| Version | CSS Import | Config Tailwind | |---------|------------|-----------------| | v4 | @wakastellar/ui/styles | Aucune | | v3 | @wakastellar/ui/styles/v3 | 1 ligne (preset) |

Exports disponibles

// Styles v4 (défaut)
import "@wakastellar/ui/styles"
import "@wakastellar/ui/styles/v4"  // alias

// Styles v3
import "@wakastellar/ui/styles/v3"

// Variables CSS de base uniquement
import "@wakastellar/ui/styles/base"

// Preset Tailwind pour v3
const preset = require("@wakastellar/ui/tailwind-preset")

CLI

Le CLI permet d'ajouter des composants individuels à votre projet, similaire à shadcn/ui.

Commandes

# Initialiser un projet
npx wakastellar-ui init
npx wakastellar-ui init --defaults  # Utilise les paramètres par défaut

# Ajouter des composants
npx wakastellar-ui add button
npx wakastellar-ui add button card input dialog
npx wakastellar-ui add waka-datatable --overwrite

# Lister les composants
npx wakastellar-ui list
npx wakastellar-ui list --type ui
npx wakastellar-ui list --category gamification

# Rechercher
npx wakastellar-ui search button
npx wakastellar-ui search "date picker"

Configuration (components.json)

Le fichier components.json est créé par init et configure votre projet :

{
  "$schema": "https://wakastellar.dev/schema.json",
  "style": "default",
  "tailwind": {
    "version": "v4",
    "css": "app/globals.css"
  },
  "aliases": {
    "components": "@/components/ui",
    "utils": "@/lib/utils"
  }
}

Résolution des dépendances

Le CLI installe automatiquement les dépendances internes. Par exemple, ajouter waka-modal installera aussi button s'il n'est pas déjà présent.

Composants

Catégories principales

| Catégorie | Nombre | Exemples | |-----------|--------|----------| | Base | 45+ | Button, Card, Input, Dialog, Tabs... | | Gamification | 35+ | Achievements, Leaderboards, XP bars, Quests... | | Infrastructure | 25+ | Pipelines, Server racks, Network topology... | | Sécurité | 15+ | 2FA, Biometrics, Permission matrix... | | Communication | 10+ | Chat bubbles, Video calls, Reactions... | | Analytics | 12+ | KPI dashboards, Funnels, Cohorts... | | E-commerce | 15+ | Product cards, Cart, Checkout, Pricing... | | Onboarding | 10+ | Tour guide, Hotspot, Checklist... |

Composants de Base

| Composant | Description | |-----------|-------------| | Button | Boutons avec variantes et tailles | | Input | Champs de saisie texte | | Textarea | Zones de texte multilignes | | Checkbox | Cases à cocher | | RadioGroup | Groupes de boutons radio | | Switch | Interrupteurs toggle | | Select | Listes déroulantes | | Slider | Curseurs de sélection | | Dialog | Modales | | Sheet | Panneaux latéraux | | Tabs | Onglets | | Card | Conteneur avec header/content/footer |

Composants Avancés

| Composant | Description | |-----------|-------------| | WakaDateTimePicker | Sélecteur date/heure complet | | WakaAutocomplete | Autocomplete avec recherche | | WakaColorPicker | Sélecteur de couleurs | | WakaFileUpload | Upload de fichiers avec preview | | WakaRichTextEditor | Éditeur WYSIWYG (TipTap) | | DataTableAdvanced | Table avancée avec tri, filtres, pagination, export | | WakaKanban | Tableau Kanban drag & drop | | WakaCarousel | Carousel d'images |

Composants Gamification

| Composant | Description | |-----------|-------------| | WakaAchievementUnlock | Animation de déblocage d'achievement | | WakaLeaderboard | Classement des joueurs | | WakaXPBar | Barre d'expérience | | WakaQuestCard | Carte de quête avec objectifs | | WakaStreakCounter | Compteur de série | | WakaBadgeShowcase | Vitrine de badges | | WakaLevelProgress | Progression de niveau | | WakaSpinWheel | Roue de la fortune |

Composants Infrastructure

| Composant | Description | |-----------|-------------| | WakaPipelineView | Vue de pipeline CI/CD | | WakaServerRack | Visualisation de rack serveur | | WakaNetworkTopology | Topologie réseau interactive | | WakaHealthPulse | Indicateur de santé système | | WakaTerminalOutput | Sortie terminal stylisée | | WakaAlertStack | Pile d'alertes avec sévérités | | WakaDeploymentLane | Ligne de déploiement |

Composants Sécurité

| Composant | Description | |-----------|-------------| | WakaTwoFactorSetup | Configuration 2FA | | WakaBiometricPrompt | Invite biométrique | | WakaPermissionMatrix | Matrice de permissions | | WakaAuditLog | Journal d'audit | | WakaSecurityScore | Score de sécurité | | WakaSessionManager | Gestionnaire de sessions |

Composants Analytics

| Composant | Description | |-----------|-------------| | WakaFunnelChart | Graphique en entonnoir | | WakaCohortTable | Tableau de cohortes | | WakaKPIDashboard | Dashboard KPI | | WakaHeatmap | Carte de chaleur | | WakaSankeyDiagram | Diagramme Sankey | | WakaTreemapChart | Graphique Treemap |

Système de Thèmes

Format shadcn/ui registry-item

Le ThemeProvider supporte le format standard shadcn/ui pour les thèmes :

import { ThemeProvider, useTheme } from "@wakastellar/ui"

<ThemeProvider
  themes={[
    {
      id: "custom",
      label: "Mon Thème",
      previewColor: "#8b5cf6",
      registryItem: {
        name: "custom",
        type: "registry:style",
        cssVars: {
          light: {
            background: "0 0% 100%",
            foreground: "240 10% 3.9%",
            primary: "262 83% 58%",
            "primary-foreground": "0 0% 100%",
          },
          dark: {
            background: "240 10% 3.9%",
            foreground: "0 0% 98%",
            primary: "263 70% 50%",
            "primary-foreground": "0 0% 100%",
          },
        },
      },
    },
  ]}
  defaultTheme="custom"
>
  <App />
</ThemeProvider>

Chargement dynamique de thèmes JSON

import { useTheme } from "@wakastellar/ui"

function ThemeLoader() {
  const { loadThemeFromJSON } = useTheme()

  const loadCustomTheme = async () => {
    const response = await fetch("/api/themes/custom.json")
    const themeData = await response.json()
    await loadThemeFromJSON("custom", themeData)
  }

  return <Button onClick={loadCustomTheme}>Charger thème</Button>
}

ThemeSelector

import { ThemeSelector } from "@wakastellar/ui"

<ThemeSelector variant="compact" />  // Icône
<ThemeSelector variant="select" />   // Dropdown
<ThemeSelector variant="full" />     // Grille

Internationalisation

Configuration avec traductions inline

<WakaProvider
  config={{
    language: {
      defaultLanguage: "fr",
      supportedLanguages: ["fr", "en"],
      languages: [
        {
          code: "fr",
          label: "Français",
          flagEmoji: "🇫🇷",
          translations: {
            common: { save: "Enregistrer", cancel: "Annuler" },
          },
        },
        {
          code: "en",
          label: "English",
          flagEmoji: "🇬🇧",
          jsonUrl: "https://cdn.example.com/i18n/en.json",
        },
      ],
    },
  }}
>
  {children}
</WakaProvider>

Utilisation

import { useTranslation, useLanguage } from "@wakastellar/ui"

function MyComponent() {
  const { t } = useTranslation()
  const { changeLanguage, currentLanguage } = useLanguage()

  return (
    <div>
      <p>{t("common.save")}</p>
      <Button onClick={() => changeLanguage("en")}>English</Button>
    </div>
  )
}

DataTable Avancé

import { DataTableAdvanced } from "@wakastellar/ui"
import type { ColumnDef } from "@tanstack/react-table"

const columns: ColumnDef<User>[] = [
  { accessorKey: "name", header: "Nom" },
  { accessorKey: "email", header: "Email" },
  { accessorKey: "role", header: "Rôle" },
]

<DataTableAdvanced
  data={users}
  columns={columns}
  pagination={{ mode: "client", pageSize: 10 }}
  filters={[
    { id: "name", label: "Nom", type: "text", column: "name" },
    { id: "role", label: "Rôle", type: "select", column: "role", options: [...] },
  ]}
  selection={{ mode: "multiple" }}
  export={{ enabled: true, formats: ["csv", "json", "excel"] }}
  edit={{
    editableColumns: [{ field: "name", config: { type: "text" } }],
    onSave: async (rowId, data) => await updateUser(rowId, data),
  }}
  virtualization={{ enabled: true }}
/>

Hooks Utiles

// Thème
const { currentTheme, changeTheme, themes, isDarkMode, toggleDarkMode } = useTheme()

// Langue
const { currentLanguage, changeLanguage, languages, loadLanguageFromJSON } = useLanguage()

// Traductions
const { t, i18n } = useTranslation()

// Toast
const { toast } = useToast()
toast({ title: "Succès", description: "Action réussie" })

Peer Dependencies

{
  "react": ">=18.0.0",
  "react-dom": ">=18.0.0",
  "next": ">=14.0.0",
  "tailwindcss": ">=3.4.0 || >=4.0.0",
  "react-hook-form": "^7.0.0",     // optionnel
  "recharts": ">=2.0.0",           // optionnel (charts)
  "xlsx": ">=0.18.0",              // optionnel (export Excel)
  "jspdf": ">=2.5.0",              // optionnel (export PDF)
  "@tiptap/*": ">=2.0.0"           // optionnel (rich text editor)
}

Structure du Package

@wakastellar/ui
├── dist/
│   ├── index.es.js        # ESM bundle
│   ├── index.cjs.js       # CommonJS bundle
│   ├── index.d.ts         # TypeScript definitions
│   └── ui.css             # Styles compilés
└── src/styles/
    ├── globals.css        # Entry point Tailwind v4
    ├── globals-v3.css     # Entry point Tailwind v3
    ├── base.css           # Variables CSS universelles
    └── tailwind.preset.js # Preset pour Tailwind v3

Entry Points

// Import principal
import { Button, Card, DataTableAdvanced } from "@wakastellar/ui"

// Styles (choisir selon votre version de Tailwind)
import "@wakastellar/ui/styles"     // v4
import "@wakastellar/ui/styles/v3"  // v3

// Types
import type { ColumnDef } from "@tanstack/react-table"
import type { ThemeConfig, LanguageConfig } from "@wakastellar/ui"

Licence

Ce projet est publié sous licence AGPL-3.0. Voir LICENSE.

Fait avec ❤️ par Wakastellar

Documentation • Issues