Configuration

EditorConfig et RendererConfig sont les points d'entrée de toute personnalisation. Passez l'un ou l'autre à Editor.create() ou Renderer.render() respectivement. Seuls containerId (et data pour le renderer) sont obligatoires ; toutes les autres options ont des valeurs par défaut sûres.

EditorConfig

Passez EditorConfig comme seul argument à Editor.create(). Le containerId requis doit correspondre à un id d'élément DOM existant.

Option	Type	Requis	Description
containerId	string	Oui	Identifiant de l'élément DOM qui hébergera l'éditeur. Doit exister dans le DOM avant l'appel à Editor.create().
maxHeight	number	Non	Hauteur maximale de l'éditeur en pixels. Définissez à 0 (la valeur par défaut) pour ne pas limiter la hauteur.
minHeight	number	Non	Hauteur minimale de l'éditeur en pixels. Vaut 300 par défaut.
onChange	(data: EditorData) => void	Non	Rappel déclenché à chaque modification du document. Reçoit la capture complète de l'EditorData.
onReady	() => void	Non	Rappel déclenché une fois que l'éditeur est entièrement initialisé et prêt à recevoir des appels API.
placeholder	string	Non	Texte de remplacement affiché quand l'éditeur est vide. Vaut « Start writing... » par défaut.
initialData	EditorData	Non	EditorData préremplie à charger lors du montage de l'éditeur.
initialView	'edit' \| 'preview' \| 'json'	Non	Mode d'affichage initial. L'une des valeurs : edit, preview, json. Vaut 'edit' par défaut.
allowJsonViewEditing	boolean	Non	Lorsque true, la vue JSON est modifiable et les modifications se propagent dans le document. Vaut false par défaut.
hasViewSwitcher	boolean	Non	Lorsque false, les boutons modifier, aperçu et JSON sont retirés de la barre d'actions. Vaut true par défaut.
hasDocumentActions	boolean	Non	Lorsque false, les boutons copier, télécharger et vider sont retirés de la barre d'actions. Si hasViewSwitcher vaut aussi false, aucune barre d'actions n'est dessinée. Vaut true par défaut.
onClearRequest	() => Promise<boolean>	Non	Appelé quand on appuie sur Vider. La page n'est vidée que si la promesse se résout à true ; un rejet laisse la page intacte. Absent, Vider vide aussitôt.
margins	BlockMargins	Non	Marge supérieure et inférieure globale (en pixels) appliquée à chaque bloc. Les configurations par bloc ont la priorité.
styles	EditorStyles	Non	Objet EditorStyles pour une personnalisation CSS fine de l'interface de l'éditeur (barres d'outils, boîtes de dialogue, contrôles).
classNames	EditorClassNames	Non	Objet EditorClassNames pour attacher des noms de classes CSS aux éléments de l'interface de l'éditeur.
imageUploader	UploadFunction	Non	Fonction asynchrone qui télécharge un fichier image et renvoie une URL publique sous forme de chaîne.
audioUploader	UploadFunction	Non	Fonction asynchrone qui télécharge un fichier audio et renvoie une URL publique sous forme de chaîne.
videoUploader	UploadFunction	Non	Fonction asynchrone qui télécharge un fichier vidéo et renvoie une URL publique sous forme de chaîne.
fileUploader	UploadFunction	Non	Fonction d'upload qui déplace les pièces jointes du bloc fichier vers votre stockage.
locale	string	Non	L'unique locale que l'éditeur édite. Les blocs multilingues sont aplatis vers cette locale.
defaultLocale	string	Non	Locale de repli utilisée quand un bloc n'a pas de contenu pour la locale demandée.
onLocaleFallback	(info: { blockId: string; locale: string }) => void	Non	Appelé quand un bloc retombe sur une autre locale, pour que l'hôte affiche un indicateur.
onInlineRewrite	(selection: string, action: InlineRewriteAction) => Promise<string \| null>	Non	Fonction qui réécrit le texte sélectionné avec l'IA ; si définie, la barre d'outils affiche le bouton de réécriture.
inlineRewriteLabels	Partial<Record<InlineRewriteAction, string>>	Non	Remplace les libellés des actions du menu de réécriture, pour la localisation.
inlineRewriteTooltip	string	Non	Remplace l’infobulle de la baguette de réécriture de la barre d’outils en ligne, pour la localisation.
blockToolLabels	Partial<Record<BlockToolType, string>>	Non	Remplace les libellés des outils de bloc dans la boîte à outils et le menu slash, pour la localisation.
blockToolbarLabels	Partial<Record<BlockToolbarLabel, string>>	Non	Remplace les textes de la barre d'outils de bloc (ajouter, déplacer, supprimer, etc.) et les indications affichées dans les champs de bloc vides, pour la localisation.
controlLabels	Partial<Record<ControlLabel, string>>	Non	Remplace les noms des boutons de la barre d'actions (modifier, aperçu, JSON, copier, télécharger, vider), utilisés comme noms accessibles et infobulles, pour la localisation.
dialogLabels	Partial<Record<DialogLabel, string>>	Non	Les mots des boîtes de dialogue lien, info-bulle et statut, indexés par nom : titres, libellés des champs, textes indicatifs, styles de statut, Annuler et Appliquer. En anglais s'ils sont absents.
resolveLink	(url: string) => Promise<Partial<EmbedData>>	Non	Remplit l’instantané d’un embed collé depuis votre serveur : titre, fichier Drive, fichiers du gist ou raison pour laquelle la vue en direct est impossible. Une recherche qui échoue dessine la carte comme si l’outil n’avait pas répondu, avec Réessayer à côté.
onEmbedAction	(action: EmbedAction, blockId: string) => void	Non	Le correctif à côté de la raison d’une carte que seul l’hôte peut effectuer : connectGoogle envoie le membre connecter son compte Google ; retry est géré par l’éditeur lui-même.
disabledEmbedProviders	readonly string[]	Non	Les outils d’intégration désactivés par l’espace de travail, par clé (figma, miro, loom, google_drive, github_gist) ; leurs liens s’affichent en cartes qui en donnent la raison.
pasteEmbeds	'live' \| 'offer' \| 'card'	Non	Ce que fait le collage d’un lien pris en charge : l’afficher en direct (par défaut), le proposer, ou afficher une carte.
embedLabels	Partial<Record<EmbedLabel, string>>	Non	Mots traduits pour les lignes de raison, les actions et les libellés de gist du bloc embed, indexés par EmbedLabel ; anglais par défaut sinon.
resolveIssues	(urls: string[]) => Promise<Record<string, IssueSnapshot>>	Non	Répond aux liens de tickets d’une page par leurs instantanés, indexés par URL. Absent, puces et cartes gardent ce que le document a stocké et rien ne se rafraîchit.
onIssueAction	(action: IssueAction, tool: string) => void	Non	Le correctif à côté d’une raison de ticket que seul l’hôte peut effectuer : connecter l’outil, ce qui mène à la page Intégrations de l’hôte.
issueCards	'off' \| 'on'	Non	Si un lien de ticket collé sur sa propre ligne devient une carte ; off par défaut. Une puce dans une phrase reste toujours une puce.
issueChip	{ assignee: boolean; status: boolean }	Non	Les deux interrupteurs de puce du membre : la pastille de statut et le responsable. Les deux actifs par défaut.
issueLabels	Partial<Record<IssueLabel, string>>	Non	Mots traduits pour la puce de ticket, la carte et le tableau des tickets liés, indexés par IssueLabel ; anglais par défaut sinon.
jiraSites	readonly string[]	Non	Les URL des sites Jira que les connexions de l’espace de travail atteignent, pour qu’un lien sur le domaine propre d’un site soit reconnu comme ticket.
allowedBlockTools	readonly BlockToolType[]	Non	Les types de blocs que l’éditeur propose dans le menu des blocs, sa recherche, le menu de conversion et au collage. Chaque bloc enregistré en son absence ; un bloc stocké hors de la liste s’affiche toujours.
allowedInlineTools	readonly InlineToolType[]	Non	Les marques que la barre d’outils en ligne propose. Chaque marque enregistrée en son absence.
theme	'auto' \| 'light' \| 'dark'	Non	Schéma de couleurs. L'une des valeurs : auto (suit le système), light, dark. Vaut auto par défaut.
themeOverrides	{ light?: ThemeTokens; dark?: ThemeTokens }	Non	Substitutions de jetons par mode. Fournissez des cartes de jetons light et/ou dark pour personnaliser les couleurs sans remplacer le thème complet.

TypeScript

import { Editor } from '@clepit/core';

const editor = Editor.create({
  containerId: 'editor',
  minHeight: 400,
  placeholder: 'Start writing...',
  theme: 'auto',
  onChange: data => console.log(data),
  onReady: () => console.log('Editor ready'),
  imageUploader: async file => {
    const form = new FormData();
    form.append('file', file);
    const res = await fetch('/api/upload', { body: form, method: 'POST' });
    const { url } = await res.json();
    return url;
  },
});

RendererConfig

Passez RendererConfig comme seul argument à Renderer.render(). containerId et data sont tous les deux obligatoires.

Option	Type	Requis	Description
containerId	string	Oui	Identifiant de l'élément DOM où sera injecté le rendu.
data	EditorData	Oui	Le document EditorData à rendre. Obligatoire.
margins	BlockMargins	Non	Marge supérieure et inférieure globale (en pixels) appliquée à chaque bloc rendu.
styles	BlockStyles	Non	Carte BlockStyles pour la personnalisation CSS par type de bloc du rendu.
classNames	BlockClassNames	Non	Carte BlockClassNames pour les noms de classes CSS par type de bloc dans le rendu.
editorClassNames	EditorClassNames	Non	EditorClassNames transmis aux blocs qui rendent des composants interactifs (ex. : noms de classes tooltip pour les paragraphes).
configs	Partial<BlockTypeOutputConfigs>	Non	Carte partielle d'objets OutputConfig par bloc. Chaque entrée peut définir des marges au niveau du bloc et des noms de classes tooltip.
theme	'auto' \| 'light' \| 'dark'	Non	Schéma de couleurs. L'une des valeurs : auto, light, dark.
themeOverrides	{ light?: ThemeTokens; dark?: ThemeTokens }	Non	Substitutions de jetons par mode pour le rendu.

TypeScript

import { Renderer } from '@clepit/core';
import type { EditorData } from '@clepit/core';

const data: EditorData = await fetch('/api/content/123').then(r => r.json());

Renderer.render({
  containerId: 'output',
  data,
  theme: 'auto',
  margins: { bottom: 16, top: 16 },
});

Style au niveau du bloc

EditorConfig et RendererConfig acceptent tous les deux styles, classNames et configs indexés par type de bloc. Utilisez-les pour des substitutions ciblées ; consultez la page Thèmes pour la référence complète par jeton.

TypeScript

import { Editor, Renderer } from '@clepit/core';
import type { BlockStyles, BlockClassNames, EditorStyles } from '@clepit/core';

const editorStyles: EditorStyles = {
  blockToolbar: { container: { borderRadius: '8px' } },
};

const blockStyles: BlockStyles = {
  header: { h1: { fontFamily: 'Georgia, serif' } },
  paragraph: { lineHeight: '1.75' },
  table: { cell: { padding: '8px 12px' } },
};

const blockClassNames: BlockClassNames = {
  paragraph: 'prose-paragraph',
  header: { h1: 'prose-h1', h2: 'prose-h2' },
  alert: { info: 'alert-info', error: 'alert-error' },
};

Editor.create({
  containerId: 'editor',
  styles: editorStyles,
});

Renderer.render({
  containerId: 'output',
  data,
  styles: blockStyles,
  classNames: blockClassNames,
});

Référence

Paquets

Configuration

EditorConfig

RendererConfig

Style au niveau du bloc