Chaeditor

Un package d'éditeur Markdown combiné que l'application hôte peut contrôler directement

chaeditor est né du travail visant à extraire l'éditeur markdown interne du projet chaen en un package indépendant.

La partie la plus soignée a été de combien de contrôle l'application hôte peut-elle conserver, tout en extrayant les fonctionnalités d'édition en tant que package.

Les éditeurs markdown existants avaient souvent tendance à pencher d'un côté ou de l'autre. Ils étaient soit dépouillés au point de devoir être combinés entièrement, soit, à l'inverse, proposaient de nombreuses fonctionnalités mais une interface utilisateur et un mode de fonctionnement fortement figés, rendant difficile leur intégration naturelle dans un service. En réalité, chaque hôte a des besoins différents en termes de fonctionnalités et les points tels que l'aperçu des liens, le téléchargement de fichiers et le rendu d'images doivent être immédiatement connectés aux API existantes.

chaeditor regroupe l'expérience d'écriture jugée utile sur velog, Naver Blog, Discord et Notion en une implémentation de base, tout en permettant à l'application hôte de conserver la responsabilité de l'interface utilisateur, des métadonnées, du téléchargement et du rendu. Plutôt que d'être entièrement sans tête, notre objectif est de proposer un éditeur qui soit directement utilisable avec ses valeurs par défaut, mais que l'on peut décomposer, remplacer et connecter à la structure du service existant si nécessaire.

Nous n'avons pas seulement ajouté des fonctionnalités, mais avons également organisé la surface publique pouvant être utilisée par d'autres applications, ainsi que le flux opérationnel.

Structure de conception

Couche FSD

Nous avons structuré l'intérieur en couches FSD (Feature-Sliced Design). En séparant l'interface utilisateur d'édition, les fonctionnalités de rédaction, le modèle pur et les primitifs de base par couche, il est plus facile de déterminer où interrompre l'API publique après extraction du package.

Grâce à cette structure, nous avons pu diviser naturellement des points d'entrée comme core, react, panda-primitives.

Adaptateurs Hôtes

Les parts de service avec des politiques variables, telles que l'API de téléchargement, l'aperçu des liens et le rendu des images, sont séparées en adaptateurs pour éviter de les fixer dans le package.

Si aucun adaptateur n'est fourni, l'action de la barre d'outils est automatiquement désactivée. Le point d'entrée chaeditor/default-host fournit une implémentation de base qui appelle , , , et intègre l'optimisation d'image avant le téléchargement (1600×1600px / 84 % de qualité).

MarkdownRenderer est aligné pour le rendu côté serveur, la surface de l'éditeur est un composant client et l'aperçu des liens et le téléchargement sont liés aux politiques des gestionnaires de routes ou des actions serveur. Lors de la réintégration dans chaen, seule la surface de l'éditeur a été remplacée par le package, tandis que l'API de téléchargement, le rendu basé sur , l'aperçu des liens et la coque primitive ont été conservés côté hôte.

Registre des Primitifs

C'est une structure pour appliquer de manière cohérente le système de conception de l'application hôte au sein de l'éditeur. Les composants , , , , , sont laissés ouverts comme des slots pour permettre à l'application hôte de les remplacer par ses propres composants.

Les slots non injectés se rabattent sur l'implémentation de base de panda-primitives. Injecté au sommet de l'arbre avec MarkdownPrimitiveProvider, il peut être utilisé partout à l'intérieur avec . En remplaçant les primitifs, les helpers de lien/image/équation et l'interface de superposition au sein de l'éditeur fonctionnent sur le même système de conception.

Contrat de Thème

Les points de changement de style sont laissés comme propriétés personnalisées CSS. En laissant seulement les tokens Panda CSS ouverts, il est difficile pour l'application hôte de les réutiliser dans des environnements comme Tailwind, Emotion, styled-components, vanilla-extract. Ainsi, les variables CSS sont considérées comme le contrat extérieur, Panda restant simplement comme implémentation de base.

Déploiement et qualité

verify-package-surface

Le succès de la build ne suffit pas. Cela peut être dû au fait que l’alias @/ n’est pas interprété après la build, que le fichier de déclaration de type manque, ou que des dépendances internes soient éliminées de manière inattendue via treeshaking. Il est nécessaire de décompresser le véritable package npm tarball et de vérifier jusqu’à l’étape d’importation par un consommateur temporaire pour savoir si les exports du package, les déclarations de type, et la surface CJS/ESM sont fonctionnels.

Fichier : scripts/verify-package-surface.mjs

Stratégie Vitest

Nous gérons seulement deux groupes de test.

Mock SVG en trois types :

Les helpers markdown purs et les utilitaires de sélection vont vers les tests node, tandis que les zones nécessitant des interactions DOM comme l'éditeur · barre d'outils · visualiseur restent dans dom-ui.

Chromatic et documentation

Nous relions Storybook 10 + Chromatic pour vérifier si les modifications CSS dans chaque PR se diffusent sur d’autres surfaces via diff visuel. Lors de la mise à jour de version, le build Storybook et le déploiement Chromatic suivent automatiquement dans le script version.

Le Storybook est structuré comme référence pour comparer ce qui change et ce qui continue à être conforme dans le flux workflow d'éditeur / barre d'outils / renderer / embed, et non comme un « recueil de composants ». Le README, le wiki, et la documentation des presets de l’hôte sont également divisés de la même manière. Le Storybook sert à vérifier rapidement l’état visuel et les interactions, tandis que le wiki rassemble des guides et références intégrés en anglais/coréen, et la documentation des presets de l’hôte est conçue pour permettre de récupérer instantanément des exemples de connexion réels.

Problèmes rencontrés en application réelle

Bug du SVG clipPath

chaeditor a été conçu pour pouvoir être utilisé à la fois dans des applications React et Next.js. Par conséquent, les icônes SVG ne dépendent pas de composants spécifiques à un bundler particulier. Nous avons choisi de recevoir une chaîne SVG brute, de l'organiser à l'exécution et de la rendre en SVG inline. Ce choix, bien que flexible dans l'environnement source, a entraîné des bugs se manifestant uniquement lorsqu'il existe une différence entre le chemin dev et le chemin dist.

Juste après avoir connecté chaeditor à chaen, il y a eu un problème où l'icône Quote de la barre d'outils ne s'affichait pas. Elle apparaissait normalement dans Storybook, mais disparaissait uniquement dans l'environnement de production.

Storybook lit les fichiers sources directement sur le serveur de développement Vite, alors que l'application hôte réelle référence dist/ comme un paquet npm. Le composant icône récupère le fichier SVG sous forme de chaîne avec ?raw, le passe par à l'exécution pour le rendre en SVG inline.

normalizeSvgMarkup comprenait une étape de normalisation pour adapter le SVG à la taille de l'icône.

Ce regex s'applique globalement (g) à toute la chaîne SVG. quote.svg contenait une définition de clipPath exportée depuis Figma.

Le regex global a supprimé width et de , transformant ainsi en , rendant la zone de clip 0×0, ce qui a masqué toute l'icône.

Les SVG comportant un clipPath étaient uniquement quote.svg et github.svg. github.svg avait le même problème mais comme il était utilisé comme icône de lien, il a été découvert plus tard.

La correction consistait à limiter la correspondance externe à la seule balise ouverte <svg>.

Cette correction a conduit à l'ajout d'un test de régression pour gérer le cas de clipPath.

Amélioration du délai de réponse de la barre d'outils

Lors de l'édition d'un article existant dans chaen, même l'application d'une seule fonction de la barre d'outils entraînait un délai visible dans les changements de l'interface utilisateur.

Cause 1 — execCommand remplace l'intégralité du document

L'action de la barre d'outils est une opération simple qui applique seulement un format Markdown à la sélection. Cependant, l'implémentation interne sélectionnait toujours de 0 à la fin, remplaçant tout le document avec insertText.

Bien que document.execCommand('insertText') soit une API obsolète, c’est la seule méthode permettant d’enregistrer les modifications dans la pile native undo du navigateur. Lorsque l'on appuyait sur gras dans un article de 50 000 caractères, le navigateur enregistrait les 50 000 dans la pile undo puis traitait de manière synchrone une mutation DOM pour réécrire les 50 000.

J'ai modifié pour calculer le préfixe et le suffixe commun entre l'ancienne et la nouvelle valeur, et ne remplacer que la section modifiée.

Dans un article de 50 000 caractères, lorsque vous appliquez le formatage en gras, seule la portion de texte de **text** 10 caractères environ est remplacée. Le coût de execCommand passe de O(n) à O(quantité de changement), et l'annulation ne rétablit que la portion effectivement modifiée.

Cause 2 — Rendu de l'aperçu exécuté de manière synchrone à chaque entrée

Lorsque est appelé, le panneau d'aperçu est également re-rendu de manière synchrone. (scan du document complet), (parsing des blocs personnalisés), (mise en surbrillance du code) étaient tous exécutés de manière synchrone à chaque modification de .

La valeur dédiée à l’aperçu a été séparée à l’aide de React.useDeferredValue.

Dans React 19, useDeferredValue gère d'abord les mises à jour urgentes telles que les entrées utilisateur, et reporte le rendu de l'aperçu à une priorité plus basse. Le textarea réagit immédiatement et l’aperçu est mis à jour par React lorsque le temps le permet.

L'essentiel était que le coût était « bien trop élevé par rapport à une petite opération de formatage ». Plus le document devient long, plus ce type de problème devient apparent. Par conséquent, le chemin de transformation de la barre d'outils et de rendu de l'aperçu a été allégé en priorité. Il reste encore de la marge pour réduire davantage, mais les goulets d'étranglement urgents qui entravent réellement le flux d'édition ont été rapidement résolus et déployés à cette étape.

Conclusion

En rendant le package open-source, l'accent a été mis sur la délimitation claire des responsabilités et sur la documentation. Dans une structure étendue, si les responsabilités entre le package et l'application hôte sont floues, il est difficile pour l'intégrateur de savoir où intervenir. L'adaptateur hôte, le registre primitif et le contrat de variables CSS expriment tous ces limites en code, tandis que le README et Storybook les expliquent en tant que documents.

En le réintégrant dans « chaen », nous avons pu vérifier si ces frontières sont réellement maintenues et, au cours de ce processus, nous avons corrigé les bugs et les problèmes de performance au niveau du package.