‏beautiful-mermaid: رندر دیاگرام‌های Mermaid بدون دردسر

تیم Craft یه کتابخونه به اسم beautiful-mermaid ساخته که مشکلات رندرر پیش‌فرض Mermaid رو حل می‌کنه. Mermaid یه استاندارد متنی برای رسم دیاگرام‌هاست (فلوچارت، state machine، sequence و...) ولی رندرر اصلیش وابستگی سنگین داره، تم‌بندیش با CSS پیچیده‌ست و خروجی ترمینالی نداره. beautiful-mermaid این سه مشکل رو یکجا حل می‌کنه.

مهم‌ترین ویژگی فنی این کتابخونه اینه که رندر کاملاً synchronous هست — نه await، نه Promise. این یعنی توی React می‌شه مستقیم از useMemo() استفاده کرد و دیاگرام بدون هیچ flash یا تأخیری نمایش داده می‌شه:

const { svg } = React.useMemo(() => {
  try {
    return {
      svg: renderMermaidSVG(code, {
        bg: 'var(--background)',
        fg: 'var(--foreground)',
        transparent: true,
      }),
      error: null,
    }
  } catch (err) {
    return { svg: null, error: err instanceof Error ? err : new Error(String(err)) }
  }
}, [code])

سیستم تم‌بندی روی یه ایده ساده بنا شده: فقط دو رنگ bg (پس‌زمینه) و fg (پیش‌زمینه) کافیه. بقیه رنگ‌های دیاگرام — لبه‌ها، متن‌های فرعی، پر کردن گره‌ها — همه با color-mix() از همین دو رنگ مشتق می‌شن. این حالت «Mono Mode» نام داره. اگه بخوای رنگ‌های بیشتری بدی، می‌تونی با پارامترهای اختیاری مثل accent، line، muted و surface تم رو غنی‌تر کنی.

همه رنگ‌ها به‌صورت CSS custom property روی المان تعریف می‌شن، یعنی تغییر تم بدون re-render اعمال می‌شه — فقط کافیه متغیر CSS رو آپدیت کنی. ۱۵ تم آماده مثل tokyo-night، catppuccin-mocha، dracula، github-dark و... هم از قبل داخل کتابخونه‌ست. علاوه بر این، با تابع fromShikiTheme() می‌شه هر تم VS Code از کتابخونه Shiki رو مستقیم روی دیاگرام اعمال کرد.

برای محیط‌های ترمینالی، تابع renderMermaidASCII() دیاگرام رو به کاراکترهای Unicode یا ASCII خالص تبدیل می‌کنه. موتور ASCII از پروژه متن‌باز mermaid-ascii نوشته Alexander Grooff الهام گرفته و از Go به TypeScript پورت شده. شش نوع دیاگرام پشتیبانی می‌شه: Flowchart، State، Sequence، Class، ER و نمودارهای XY (میله‌ای، خطی، ترکیبی).

نکات کلیدی:

• رندر کاملاً synchronous — سازگار با useMemo() در React
• خروجی دوگانه: SVG برای رابط گرافیکی، ASCII/Unicode برای ترمینال
• سیستم تم دو-رنگی (Mono Mode) با امکان افزودن رنگ‌های اختیاری
• ۱۵ تم آماده + پشتیبانی از تم‌های Shiki (هر تم VS Code)
• تغییر تم زنده از طریق CSS custom properties بدون re-render
• صفر وابستگی به DOM — قابل استفاده در هر محیط TypeScript
• رندر بیش از ۱۰۰ دیاگرام در کمتر از ۵۰۰ میلی‌ثانیه