astro-d2 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # astro-d2
 
+## 0.9.0
+
+### Minor Changes
+
+- [#49](https://github.com/HiDeoo/astro-d2/pull/49) [`68bfe04`](https://github.com/HiDeoo/astro-d2/commit/68bfe04b6098c748beb4ffc24c595419917d5a4c) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds new `inline` attribute to override the global `inline` configuration for a specific diagram.
+
+- [#49](https://github.com/HiDeoo/astro-d2/pull/49) [`68bfe04`](https://github.com/HiDeoo/astro-d2/commit/68bfe04b6098c748beb4ffc24c595419917d5a4c) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for customizing the semibold font in diagrams.
+
+- [#49](https://github.com/HiDeoo/astro-d2/pull/49) [`68bfe04`](https://github.com/HiDeoo/astro-d2/commit/68bfe04b6098c748beb4ffc24c595419917d5a4c) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds experimental support for using [D2.js](https://www.npmjs.com/package/@terrastruct/d2) to render diagrams.
+
+  By default, the integration requires the D2 binary to be installed on the system to generate diagrams. Enabling this option allows generating diagrams using D2.js, a JavaScript wrapper around D2 to run it through WebAssembly.
+
+  To enable this feature, add the experimental flag in your Astro D2 integration configuration:
+
+  ```js
+  astroD2({
+    experimental: {
+      useD2js: true,
+    },
+  })
+  ```
+
 ## 0.8.1
 
 ### Patch Changes

package/config.ts

@@ -9,6 +9,25 @@ export const AstroD2ConfigSchema = z
      * @see https://d2lang.com/tour/interactive/
      */
     appendix: z.boolean().default(false),
+    /**
+     * Available experimental flags.
+     *
+     * Note that experimental flags are not guaranteed to be stable and may change or be removed in any future release.
+     */
+    experimental: z
+      .object({
+        /**
+         * Whether to use D2.js to generate the diagrams instead of the D2 binary.
+         *
+         * By default, the integration requires the D2 binary to be installed on the system to generate diagrams.
+         * Enabling this option allows generating diagrams using D2.js, a JavaScript wrapper around D2 to run it through
+         * WebAssembly.
+         *
+         * @default false
+         */
+        useD2js: z.boolean().default(false),
+      })
+      .default({}),
     /**
      * Defines the fonts to use for the generated diagrams.
      *
@@ -28,6 +47,10 @@ export const AstroD2ConfigSchema = z
          * The relative path from the project's root to the .ttf font file to use for the bold font.
          */
         bold: z.string().optional(),
+        /**
+         * The relative path from the project's root to the .ttf font file to use for the semibold font.
+         */
+        semibold: z.string().optional(),
       })
       .optional(),
     /**
@@ -96,6 +119,10 @@ export const AstroD2ConfigSchema = z
       })
       .default({}),
   })
+  .refine((config) => config.layout !== 'tala' || !config.experimental.useD2js, {
+    // TODO(HiDeoo) test
+    message: 'The `tala` layout engine is not supported when using the `experimental.useD2js` option.',
+  })
   .default({})
 
 export type AstroD2UserConfig = z.input<typeof AstroD2ConfigSchema>

package/index.ts

@@ -5,7 +5,7 @@ import type { AstroIntegration } from 'astro'
 
 import { AstroD2ConfigSchema, type AstroD2UserConfig } from './config'
 import { clearContentLayerCache } from './libs/astro'
-import { isD2Installed } from './libs/d2'
+import { isD2BinaryInstalled } from './libs/d2'
 import { throwErrorWithHint } from './libs/integration'
 import { remarkAstroD2 } from './libs/remark'
 
@@ -33,7 +33,7 @@ export default function astroD2Integration(userConfig?: AstroD2UserConfig): Astr
         if (config.skipGeneration) {
           logger.warn("Skipping generation of D2 diagrams as the 'skipGeneration' option is enabled.")
         } else {
-          if (!(await isD2Installed())) {
+          if (!config.experimental.useD2js && !(await isD2BinaryInstalled())) {
             throwErrorWithHint(
               'Could not find D2. Please check the installation instructions at https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md',
             )

package/libs/attributes.ts

@@ -15,9 +15,9 @@ export const AttributesSchema = z
       .optional()
       .transform((value) => value === 'true'),
     /**
-     * The dark theme to use for the diagrams when the user's system preference is set to dark mode.
+     * The dark theme to use for the diagram when the user's system preference is set to dark mode.
      *
-     * To disable the dark theme and have all diagrams look the same, set this attribute to `'false'`.
+     * To disable the dark theme, set this attribute to `'false'`.
      *
      * @see https://d2lang.com/tour/themes
      */
@@ -25,6 +25,13 @@ export const AttributesSchema = z
       .string()
       .optional()
       .transform((value) => (value === 'false' ? false : value)),
+    /**
+     * Overrides the global `inline` configuration for the diagram.
+     */
+    inline: z
+      .union([z.literal('true'), z.literal('false')])
+      .optional()
+      .transform((value) => (value === undefined ? undefined : value === 'true')),
     /**
      * Overrides the global `layout` configuration for the diagram.
      */
@@ -57,7 +64,7 @@ export const AttributesSchema = z
      */
     title: z.string().default('Diagram'),
     /**
-     * The default theme to use for the diagrams.
+     * The default theme to use for the diagram.
      *
      * @see https://d2lang.com/tour/themes
      */

package/libs/d2.ts

@@ -2,15 +2,20 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import url from 'node:url'
 
+import { D2, type CompileRequest } from '@terrastruct/d2'
+
 import type { DiagramAttributes } from './attributes'
 import { exec } from './exec'
 import type { RemarkAstroD2Config } from './remark'
 
 const viewBoxRegex = /viewBox="\d+ \d+ (?<width>\d+) (?<height>\d+)"/
 
-export async function isD2Installed() {
+// When using D2.js, we cache the loaded fonts to avoid reading them for each diagram.
+const jsFonts: Partial<Record<D2Font, Uint8Array>> = {}
+
+export async function isD2BinaryInstalled() {
   try {
-    await getD2Version()
+    await getD2BinaryVersion()
 
     return true
   } catch {
@@ -24,6 +29,17 @@ export async function generateD2Diagram(
   input: string,
   outputPath: string,
   cwd: string,
+) {
+  const generateFn = config.experimental.useD2js ? generateD2jsDiagram : generateD2BinaryDiagram
+  return generateFn(config, attributes, input, outputPath, cwd)
+}
+
+async function generateD2BinaryDiagram(
+  config: RemarkAstroD2Config,
+  attributes: DiagramAttributes,
+  input: string,
+  outputPath: string,
+  cwd: string,
 ) {
   const extraArgs = []
 
@@ -58,6 +74,12 @@ export async function generateD2Diagram(
     extraArgs.push(`--font-bold=${path.relative(cwd, path.join(url.fileURLToPath(config.root), config.fonts.bold))}`)
   }
 
+  if (config.fonts?.semibold) {
+    extraArgs.push(
+      `--font-semibold=${path.relative(cwd, path.join(url.fileURLToPath(config.root), config.fonts.semibold))}`,
+    )
+  }
+
   if ((config.appendix && attributes.appendix !== false) || attributes.appendix === true) {
     extraArgs.push(`--force-appendix`)
   }
@@ -85,26 +107,90 @@ export async function generateD2Diagram(
   return await getD2Diagram(outputPath)
 }
 
-export async function getD2Diagram(diagramPath: string): Promise<D2Diagram | undefined> {
+async function generateD2jsDiagram(
+  config: RemarkAstroD2Config,
+  attributes: DiagramAttributes,
+  input: string,
+  outputPath: string,
+) {
   try {
-    const content = await fs.readFile(diagramPath, 'utf8')
-    const match = viewBoxRegex.exec(content)
-    const { height, width } = match?.groups ?? {}
+    const request: CompileRequest = {
+      fs: { [outputPath]: input },
+      inputPath: outputPath,
+      options: {
+        // @ts-expect-error - We enforce that the layout cannot be 'tala' when using D2.js when validating the config.
+        layout: attributes.layout ?? config.layout,
+        pad: attributes.pad ?? config.pad,
+        sketch: (attributes.sketch === 'true' ? true : attributes.sketch) ?? config.sketch,
+        themeID: Number.parseInt(attributes.theme ?? config.theme.default, 10),
+      },
+    }
+
+    const darkTheme = attributes.darkTheme ?? config.theme.dark
+    if (darkTheme !== false) request.options.darkThemeID = Number.parseInt(darkTheme, 10)
+
+    if (attributes.animateInterval) request.options.animateInterval = Number.parseInt(attributes.animateInterval, 10)
 
-    if (!height || !width) {
-      return
+    if (attributes.target !== undefined) request.options.target = attributes.target
+    else if (attributes.animateInterval) request.options.target = '*'
+
+    if (config.fonts?.regular) {
+      request.options.fontRegular = await getD2jsFont('regular', config.root, config.fonts.regular)
     }
 
-    const computedHeight = Number.parseInt(height, 10)
-    const computedWidth = Number.parseInt(width, 10)
+    if (config.fonts?.italic) {
+      request.options.fontItalic = await getD2jsFont('italic', config.root, config.fonts.italic)
+    }
 
-    return { content, size: { height: computedHeight, width: computedWidth } }
+    if (config.fonts?.bold) {
+      request.options.fontBold = await getD2jsFont('bold', config.root, config.fonts.bold)
+    }
+
+    if (config.fonts?.semibold) {
+      request.options.fontSemibold = await getD2jsFont('semibold', config.root, config.fonts.semibold)
+    }
+
+    if ((config.appendix && attributes.appendix !== false) || attributes.appendix === true) {
+      request.options.forceAppendix = true
+    }
+
+    const d2 = new D2()
+    const response = await d2.compile(request)
+    const content = await d2.render(response.diagram, response.renderOptions)
+
+    await fs.mkdir(path.dirname(outputPath), { recursive: true })
+    await fs.writeFile(outputPath, content)
+
+    return getD2DiagramFromContent(content)
+  } catch (error) {
+    throw new Error('Failed to generate D2 diagram using D2.js.', { cause: error })
+  }
+}
+
+export async function getD2Diagram(diagramPath: string): Promise<D2Diagram | undefined> {
+  try {
+    const content = await fs.readFile(diagramPath, 'utf8')
+    return getD2DiagramFromContent(content)
   } catch (error) {
     throw new Error(`Failed to get D2 diagram size at '${diagramPath}'.`, { cause: error })
   }
 }
 
-async function getD2Version() {
+function getD2DiagramFromContent(content: string): D2Diagram | undefined {
+  const match = viewBoxRegex.exec(content)
+  const { height, width } = match?.groups ?? {}
+
+  if (!height || !width) {
+    return
+  }
+
+  const computedHeight = Number.parseInt(height, 10)
+  const computedWidth = Number.parseInt(width, 10)
+
+  return { content, size: { height: computedHeight, width: computedWidth } }
+}
+
+async function getD2BinaryVersion() {
   try {
     const [version] = await exec('d2', ['--version'])
 
@@ -118,6 +204,17 @@ async function getD2Version() {
   }
 }
 
+async function getD2jsFont(font: D2Font, root: URL, fontPath: string): Promise<Uint8Array> {
+  if (jsFonts[font]) return jsFonts[font]
+
+  const buffer = await fs.readFile(path.join(url.fileURLToPath(root), fontPath))
+
+  // Necessary when crossing the JS/WASM boundary.
+  jsFonts[font] = [...buffer] as unknown as Uint8Array
+
+  return jsFonts[font]
+}
+
 export interface D2Diagram {
   content: string
   size: D2Size
@@ -129,3 +226,5 @@ export type D2Size =
       width: number
     }
   | undefined
+
+type D2Font = 'regular' | 'italic' | 'bold' | 'semibold'

package/libs/remark.ts

@@ -59,7 +59,7 @@ export function remarkAstroD2(config: RemarkAstroD2Config) {
           parent.children.splice(
             index,
             1,
-            config.inline
+            (attributes.inline ?? config.inline)
               ? makeHtmlSvgNode(attributes, diagram)
               : makeHtmlImgNode(attributes, outputPath.imgPath, diagram?.size),
           )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-d2",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "license": "MIT",
   "description": "Astro integration and remark plugin to transform D2 Markdown code blocks into diagrams.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
@@ -10,6 +10,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@terrastruct/d2": "^0.1.33",
     "hast-util-from-html": "^2.0.3",
     "hast-util-to-html": "^9.0.4",
     "unist-util-visit": "^5.0.0"