@synapxlab/wysiwyg

Démo interactive

🚀 Installation

npm install @synapxlab/wysiwyg

yarn add @synapxlab/wysiwyg

Modules optionnels :

# Diagrammes Mermaid
npm install mermaid

# Formules mathématiques KaTeX
npm install katex

# Dessins Excalidraw (nécessite React 18)
npm install @excalidraw/excalidraw react react-dom --legacy-peer-deps

Ou via CDN (ESM) :

<script type="module">
  import { WysiwygEditor } from 'https://cdn.jsdelivr.net/npm/@synapxlab/wysiwyg/dist/wysiwyg.es.js';
  import 'https://cdn.jsdelivr.net/npm/@synapxlab/wysiwyg/dist/style.css';
</script>

⚡ Démarrage rapide

import { WysiwygEditor } from '@synapxlab/wysiwyg';
import '@synapxlab/wysiwyg/style.css';

const editor = new WysiwygEditor({
  upload: async (file) => {
    const fd = new FormData();
    fd.append('file', file);
    return (await (await fetch('/upload', { method:'POST', body:fd })).json()).url;
  },
});
document.getElementById('app').appendChild(editor.el);

editor.setValue('<p>Bonjour <strong>monde</strong></p>');
editor.onChange = () => console.log(editor.getValue());

const { WysiwygEditor } = require('@synapxlab/wysiwyg');

const editor = new WysiwygEditor();
document.getElementById('app').appendChild(editor.el);

🔧 Options toolbar

Tous les groupes sont activés par défaut. Passez false pour désactiver.

new WysiwygEditor({
  toolbar: { mermaid: true, math: true, draw: true, excalidraw: true, twig: false }, // opt-in
  wordCount: true,
  upload: async (file: File) => 'https://…/url.jpg',
  mermaid: mermaidInstance,     // requis si toolbar.mermaid: true
  katex: katexInstance,         // requis si toolbar.math: true
  excalidraw: { Excalidraw, exportToSvg, React, ReactDOM }, // requis si toolbar.excalidraw: true
});

{
  source, formatHtml, history, fullscreen,
  lists, align, direction,
  link, image, table, grid,
  heading, font, textColor,
  blockquote, divider, specialChars,
  mermaid,    // opt-in — passer opts.mermaid aussi
  math,       // opt-in — passer opts.katex aussi
  draw,       // opt-in — éditeur vectoriel natif, zéro dépendance
  excalidraw, // opt-in — passer opts.excalidraw aussi
  twig,       // opt-in — 27 snippets Twig prêts
}

📖 API publique

editor.getValue(): string       // HTML courant
editor.setValue(html: string)   // Injecter du contenu
editor.focus(): void            // Placer le curseur
editor.onChange?: () => void   // Appelé à chaque modif
editor.el: HTMLElement          // Élément racine à monter

Types TypeScript

import type { WysiwygOptions, WysiwygToolbarConfig } from '@synapxlab/wysiwyg';

🧩 Mermaid (opt-in)

Injectez votre propre instance Mermaid v10+. Zéro impact bundle si non utilisé.

import mermaid from 'mermaid';
mermaid.initialize({ startOnLoad: false });

new WysiwygEditor({ mermaid, toolbar: { mermaid: true } });

• Flowchart, sequence, gantt, pie, stateDiagram, erDiagram
• Cliquez un diagramme existant pour le ré-éditer
• Erreurs affichées inline dans la modale
• Blocs ```mermaid``` dans le source HTML strippés automatiquement

∑ KaTeX — Formules mathématiques (opt-in)

Injectez votre propre instance KaTeX. Zéro impact bundle si non utilisé. Chargez le CSS KaTeX séparément.

import katex from 'katex';
import 'katex/dist/katex.min.css';

new WysiwygEditor({ katex, toolbar: { math: true } });

• Cliquez le bouton Σ → saisissez la formule LaTeX (ex. \frac{a}{b})
• Mode bloc (centré, $$...$$) ou mode inline (dans le texte, $...$)
• Les délimiteurs $$...$$ / $...$ sont retirés automatiquement
• Cliquez une formule existante → rouvre la modale avec le code pré-rempli
• Stocké sous <div|span class="be-math" data-math-code="...">

🖊️ Éditeur vectoriel natif (opt-in)

Dessinez et annotez directement dans le contenu. L'éditeur SVG est désormais un package autonome — installez-le séparément puis injectez-le comme dépendance.

Installation

npm install @synapxlab/draw

Intégration

import { WysiwygEditor } from '@synapxlab/wysiwyg';
import { DrawEditor } from '@synapxlab/draw';
import '@synapxlab/draw/style.css';

new WysiwygEditor({
  draw: DrawEditor,
  toolbar: { draw: true },
});

• 7 outils — sélection, crayon, rectangle, ellipse, ligne, flèche, texte multiligne
• Sélection → 8 poignées de redimensionnement + rotation libre
• Support tactile — fonctionne sur tablette et mobile
• Double-clic sur un texte → édition en place
• Panneau propriétés : couleur, arrière-plan, style texte, transparence, z-order
• Annuler Ctrl+Z, supprimer Suppr
• Clic sur un dessin inséré → panneau style + bouton Modifier le dessin

Documentation complète @synapxlab/draw →

▣ QR Code (opt-in)

Insérez et modifiez des QR codes SVG directement dans le contenu — couleurs, taille, correction d'erreur. Basé sur @synapxlab/qrcode, zéro dépendance runtime.

Installation

npm install @synapxlab/qrcode

Intégration

import { WysiwygEditor } from '@synapxlab/wysiwyg';
import { QRCode } from '@synapxlab/qrcode';

new WysiwygEditor({
  qrcode: QRCode,
  toolbar: { qrcode: true },
});

• Génération SVG inline — retaillable à l'infini, zéro canvas
• Couleur des modules, couleur de fond, marge, niveau de correction L/M/Q/H
• Clic sur un QR inséré → modale de modification (toutes les options)
• Données stockées en data-qr-* — re-générables côté serveur

Documentation complète @synapxlab/qrcode →

🌿 Twig snippets (opt-in)

Activez le panneau de snippets Twig pour insérer rapidement des variables, structures et filtres dans le contenu. Les snippets sont insérés en texte brut — traités nativement par votre moteur Twig côté serveur.

new WysiwygEditor({
  toolbar: { twig: true },
});

• Cliquez le bouton { } → panneau latéral avec snippets groupés par catégorie
• 6 catégories intégrées : Variable, Structure, Filtre, Client, Facture, Système
• Coloration syntaxique Twig en mode source (variables {{ }} et blocs {% %})
• Snippets personnalisés injectables via twigSnippets: [ { cat, label, code } ]

Variables & structures

Accès aux données du contexte, conditions et boucles :

{{ customer.company }}           {# Société #}
{{ invoice.date|date('d/m/Y') }} {# Date formatée #}
{{ invoice.total_ttc|number_format(2, ',', ' ') }} €

{% if invoice.status == 'PAID' %}
  Facture réglée ✓
{% else %}
  En attente de paiement
{% endif %}

{% for line in invoice.lines %}
  {{ line.label }} — {{ line.qty }} × {{ line.unit_price }} €
{% endfor %}

Filtres natifs Twig

{{ texte|upper }}                     {# MAJUSCULES #}
{{ texte|lower }}                     {# minuscules #}
{{ texte|nl2br }}                     {# Sauts de ligne → 
 #}
{{ variable|default('N/A') }}         {# Valeur par défaut #}
{{ tableau|length }}                  {# Nombre d'éléments #}
{{ date|date('d/m/Y') }}              {# Format date #}
{{ nombre|number_format(2,',',' ') }} {# 1 234,56 #}

Filtres d'extension Twig personnalisés

Injectez vos propres filtres métier via twigSnippets — ils restent dans votre projet et ne sont pas embarqués dans le package :

{# Montant en lettres → "MILLE DEUX CENTS EUROS" #}
{{ invoice.total_ttc|asLetters }}

{# Date en lettres → "le 24 mars 2026" #}
{{ invoice.date|asLetters }}

{# Expressions de date dynamiques résolues à l'exécution #}
{{ "Rapport de {{mount/year}}"|dateExpression(invoice.date) }}
{# → "Rapport de Mars 2026" #}

{# Traduction de valeurs BDD (DRAFT, PAID, BANK_TRANSFER…) #}
{{ "Statut : {{status}}"|Expression('status', invoice.status) }}
{# → "Statut : Payé" #}

{# JSON sécurisé pour attributs HTML #}


{# Traduction i18n #}
{{ __('invoice.title') }}

Injection de snippets personnalisés

Passez vos filtres métier via l'option twigSnippets — chaque entrée a une catégorie, un libellé et le code à insérer :

new WysiwygEditor({
  toolbar: { twig: true },
  twigSnippets: [
    { cat: 'Mon ERP', label: '|asLetters',     code: 'montant en lettres' },
    { cat: 'Mon ERP', label: '|dateExpression', code: 'expression de date' },
    { cat: 'Mon ERP', label: '|jsonAttr',       code: 'json pour attribut HTML' },
  ],
});

🎨 Thème CSS vars

Toutes les couleurs dans des variables CSS scopées à .be-wysiwyg.

.be-wysiwyg {
  --be-primary:    #4f46e5;
  --be-bg:         #f8f9fa;
  --be-surface:    #ffffff;
  --be-border:     #e5e7eb;
  --be-text:       #111827;
  --be-radius:     6px;
  --be-font:       system-ui, sans-serif;
  --be-font-mono:  'Courier New', monospace;
}

.be-wysiwyg {
  --be-primary:    #6366f1;
  --be-bg:         #0f172a;
  --be-surface:    #1e293b;
  --be-border:     #334155;
  --be-text:       #f1f5f9;
}

🔧 Boutons personnalisés

Injectez vos propres boutons en fin de toolbar via l'option customButtons. Chaque bouton reçoit le HTML courant de l'éditeur au clic — idéal pour sauvegarder, exporter, envoyer, etc.

La démo ci-dessus en contient un : le bouton ↓ (Télécharger le HTML) en fin de toolbar.

new WysiwygEditor({
  customButtons: [
    {
      icon: 'REC',           // texte court ou SVG string
      title: 'Enregistrer',
      onClick: (html, editor) => {
        fetch('/save', { method: 'POST', body: html });
      },
    },
    {
      icon: '<svg …/>',     // SVG inline
      title: 'Télécharger le HTML',
      onClick: (html) => {
        const blob = new Blob([html], { type: 'text/html' });
        const a = document.createElement('a');
        a.href = URL.createObjectURL(blob);
        a.download = 'export.html';
        a.click();
      },
    },
  ],
});

Interface WysiwygCustomButton

👁 Rendu final

Le bouton Afficher sous l'éditeur ouvre une modale qui affiche le HTML généré en rendu final, encapsulé dans un conteneur .wysiwyg_view.

Ce rendu correspond à un affichage dans une page HTML classique — identique à ce que produirait $twig->createTemplate($html) côté serveur.

• ✅ Typographie complète : titres, paragraphes, listes, blockquote, code
• ✅ Tableaux avec zebra-stripes
• ✅ Diagrammes Mermaid (SVG inline)
• ✅ Formules KaTeX (HTML déjà rendu + CSS chargé)
• ✅ QR codes (SVG inline)
• ✅ Dessins vectoriels (SVG inline)
• ✅ Grilles flexbox et mises en page multi-colonnes

Pour intégrer le rendu dans votre projet, ajoutez la classe .wysiwyg_view sur le conteneur qui reçoit le HTML, et chargez le CSS KaTeX si des formules mathématiques sont présentes.

<div class="wysiwyg_view">
  
</div>

// PHP
$twig->createTemplate($html);

🌐 Compatibilité

• ✅ Navigateurs modernes (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
• ✅ Node.js ≥ 18 (SSR : importez, n'instanciez pas côté serveur)
• ✅ React, Vue, Angular, Svelte — montez editor.el dans un ref/onMount
• ✅ Vite, Webpack, Rollup, ESBuild
• ❌ IE11 non supporté

Licence

MIT — Utilisez, modifiez, redistribuez librement.
Code source : github.com/synapxLab/wysiwyg