DriftWood Module SDK

SDK TypeScript pour créer des modules DriftWood avec autocomplétion et structure organisée.

Installation

npm install @taistudio/driftwood-module-sdk

Fonctionnalités

• ✅ Autocomplétion TypeScript complète
• ✅ Validation des types stricte
• ✅ Gestion des permissions intégrée
• ✅ Helpers pour composants, pages et thèmes
• ✅ API fluide et intuitive
• ✅ Support des hooks et routes API
• ✅ Validation des modules intégrée

Démarrage Rapide

Créer un module simple

import { createModule, ComponentHelper, PageHelper } from '@driftwood/module-sdk';

const myModule = createModule({
  name: 'my-awesome-module',
  version: '1.0.0',
  description: 'Mon premier module DriftWood'
})
  .addComponent(
    ComponentHelper.createElement(
      'my-element',
      'Mon Élément',
      <div>Contenu de mon élément</div>,
      {
        category: 'custom',
        icon: 'star'
      }
    )
  )
  .addPage(
    PageHelper.createAdminPage(
      '/admin/my-module',
      'Mon Module',
      <div>Page d'administration</div>
    )
  )
  .build();

export default myModule;

Utilisation avec CMS Helper

import { CMSHelper, ModulePermission } from '@driftwood/module-sdk';

// Dans votre composant ou hook
const cmsHelper = new CMSHelper(context);

// Vérifier les permissions
if (cmsHelper.hasPermission(ModulePermission.READ_CONTENT)) {
  const content = await cmsHelper.getContent();
  console.log(content);
}

// Créer du contenu
const newContent = await cmsHelper.saveContent({
  type: 'article',
  title: 'Mon Article',
  content: 'Contenu de l\'article...'
});

API Reference

ModuleBuilder

Classe principale pour construire des modules DriftWood.

Méthodes

• addComponent(component, config) - Ajoute un composant
• addComponents(components) - Ajoute plusieurs composants
• addPage(component, config) - Ajoute une page
• addPages(pages) - Ajoute plusieurs pages
• addTheme(theme) - Ajoute un thème
• addThemes(themes) - Ajoute plusieurs thèmes
• addHook(config) - Ajoute un hook
• addAPIRoute(config) - Ajoute une route API
• onInitialize(handler) - Définit l'initialisation
• onDestroy(handler) - Définit la destruction
• build() - Construit le module final

ComponentHelper

Helper pour créer des composants DriftWood.

// Créer un élément
ComponentHelper.createElement(
  'element-id',
  'Nom de l\'élément',
  <MonComposant />,
  {
    category: 'custom',
    icon: 'star',
    props: { /* props par défaut */ },
    styles: { /* styles par défaut */ }
  }
);

// Créer un layout
ComponentHelper.createLayout('layout-id', 'Nom', <MonLayout />, options);

// Créer une section
ComponentHelper.createSection('section-id', 'Nom', <MaSection />, options);

PageHelper

Helper pour créer des pages DriftWood.

// Page publique
PageHelper.createPublicPage(
  '/ma-page',
  'Titre de la page',
  <MonComposant />,
  {
    description: 'Description de la page',
    middleware: ['auth']
  }
);

// Page admin
PageHelper.createAdminPage(
  '/admin/ma-page',
  'Titre Admin',
  <MonComposantAdmin />,
  options
);

// Page de configuration automatique
PageHelper.createConfigPage('module-name', <ConfigComponent />);

ThemeHelper

Helper pour créer des thèmes DriftWood.

// Thème clair
ThemeHelper.createLightTheme('mon-theme-clair');

// Thème sombre
ThemeHelper.createDarkTheme('mon-theme-sombre');

// Thème personnalisé
ThemeHelper.createTheme(
  'mon-theme',
  {
    primary: '#3b82f6',
    secondary: '#64748b',
    // ... autres couleurs
  },
  {
    fonts: {
      sans: 'Inter, sans-serif'
    }
  }
);

// Variante de thème
const baseTheme = ThemeHelper.createLightTheme('base');
ThemeHelper.createThemeVariant(
  baseTheme,
  'variante-bleue',
  { primary: '#2563eb' }
);

CMSHelper

Helper pour interagir avec le CMS DriftWood.

const cms = new CMSHelper(context);

// Permissions
cms.hasPermission(ModulePermission.READ_CONTENT);
cms.hasAnyPermission([ModulePermission.READ_CONTENT, ModulePermission.WRITE_CONTENT]);
cms.isAdmin();

// Contenu
await cms.getContent('article', 10);
await cms.saveContent({ title: 'Nouveau', content: '...' });
await cms.deleteContent('content-id');

// Utilisateurs
await cms.getUsers();

// Thème
cms.getCurrentTheme();
await cms.updateTheme({ colors: { primary: '#ff0000' } });

// Informations
cms.getSiteInfo();
cms.getCurrentUser();

Permissions

Les modules peuvent demander les permissions suivantes :

• READ_CONTENT - Lire le contenu
• WRITE_CONTENT - Modifier le contenu
• READ_USERS - Lire les utilisateurs
• WRITE_USERS - Modifier les utilisateurs
• READ_THEME - Lire le thème
• WRITE_THEME - Modifier le thème
• ACCESS_ADMIN - Accéder à l'administration
• MODIFY_COMPONENTS - Modifier les composants
• ACCESS_ANALYTICS - Accéder aux analytics

Types Principaux

DriftWoodModuleConfig

interface DriftWoodModuleConfig {
  name: string;
  version: string;
  description?: string;
  author?: string;
  permissions?: ModulePermission[];
}

ComponentConfig

interface ComponentConfig {
  id: string;
  type: 'element' | 'layout' | 'page' | 'section';
  name: string;
  category: string;
  icon?: string;
  props?: Record<string, any>;
  styles?: Record<string, any>;
  permissions?: ModulePermission[];
}

PageConfig

interface PageConfig {
  path: string;
  type: 'public' | 'admin';
  title: string;
  description?: string;
  permissions?: ModulePermission[];
  middleware?: string[];
}

Validation

Le SDK inclut un système de validation pour vérifier la conformité des modules :

import { validateModule } from '@driftwood/module-sdk';

const result = validateModule(myModule);

if (!result.isValid) {
  console.error('Erreurs:', result.errors);
  console.warn('Avertissements:', result.warnings);
}

Structure d'un Module

Un module DriftWood complet peut contenir :

• Composants : Éléments, layouts, pages, sections
• Pages : Pages publiques et d'administration
• Thèmes : Thèmes et variantes
• Hooks : Écouteurs d'événements
• Routes API : Endpoints API personnalisés
• Permissions : Droits d'accès requis
• Cycle de vie : Initialisation et destruction

Exemples

Voir le dossier examples/ pour des exemples complets :

• basic-module.tsx - Module simple avec composants et pages
• advanced-module.tsx - Module avancé avec hooks et API

Développement

# Installer les dépendances
npm install

# Compiler le SDK
npm run build

# Mode développement
npm run dev

# Nettoyer
npm run clean

Contribuer

1. Fork le projet
2. Créer une branche (git checkout -b feature/amazing-feature)
3. Commit les changements (git commit -m 'Add amazing feature')
4. Push vers la branche (git push origin feature/amazing-feature)
5. Ouvrir une Pull Request

Licence

MIT License - voir le fichier LICENSE pour les détails.

Support

Pour toute question ou problème, veuillez ouvrir une issue sur le repository GitHub.