diagramo

Diagramo renders Surface, Core, and NCF S-expression diagrams into SVG.

This package includes:

• src/diagramo.js: editable source module
• src/browser-entry.js: browser-global auto-render entry
• dist/diagramo.js: npm ESM entry
• dist/diagramo.browser.js: standalone browser bundle for static pages

Install

npm install diagramo

Dev Demo

clone repo then enter root project repo

python -m http.server

Publishable package layout

Edit src/diagramo.js, then regenerate the browser bundle with:

npm install
npm run build

That command:

• copies src/diagramo.js to dist/diagramo.js
• bundles src/browser-entry.js to dist/diagramo.browser.js

ESM usage

import { renderAll, renderElement, renderSource, compileSource } from "diagramo";

renderAll(document);

Render a single element:

import { renderElement } from "diagramo";

const el = document.querySelector("pre.diagramo");
renderElement(el, { zoom: false });

Render directly into a host element:

import { renderSource } from "diagramo";

const host = document.querySelector("#diagram-host");
renderSource(`(program (X) (-> f X Y))`, host, { zoom: false, height: 320 });

Static page drop-in

After publishing, you can use the browser bundle from a CDN:

<pre class="diagramo">
(program
  (X)
  (ZinsideX:X)
  (-> f A B)
  (-> g B A)
  (-> h X Y)
)</pre>

<script src="https://unpkg.com/diagramo/dist/diagramo.browser.js"></script>

The browser bundle auto-renders pre.diagramo elements on page load.

Default behavior

• zoom is off by default
• source <pre> elements are replaced with rendered hosts
• labels default to IDs in Surface shorthand
• (-> f A B) synthesizes missing nodes A and B
• the host auto-grows to avoid clipping labels and arrowheads

Data attributes

These can be placed on the source element or the host:

• data-diagramo-mode="auto|surface|core|ncf"
• data-diagramo-zoom="on|off"
• data-diagramo-ortho="on|off"
• data-diagramo-wiring="on|off"
• data-diagramo-glyphs="on|off"
• data-diagramo-height="360"

Example:

<pre class="diagramo" data-diagramo-height="420" data-diagramo-zoom="off">
(program
  (X)
  (-> f X Y)
)</pre>

Browser global API

The standalone browser bundle exposes window.Diagramo with:

• parseSexpr
• compileAst
• compileSource
• emitCoreDoc
• emitNCFDoc
• renderSource
• renderElement
• renderAll
• autoRender

API

compileSource(source, mode = "auto")

Returns:

{
  kind,     // "surface" | "core" | "ncf"
  core,     // canonical core doc object or null
  ncf,      // canonical ncf doc object
  coreText, // core serialization
  ncfText,  // ncf serialization
  warnings  // array of warning strings
}

renderSource(source, host, options = {})

Options:

• mode
• zoom
• ortho
• wiring
• glyphs
• height
• observeResize
• replaceSource

Returns:

{
  host,
  compiled,
  fit,
  rerender
}

Surface shorthand supported

(A)              ; node A, label "A"
(ZinsideX:X)     ; child ZinsideX under X
(-> f A B)       ; arrow f from A to B, label "f", synthesize A/B if needed

Files

• src/diagramo.js
• src/browser-entry.js
• scripts/build.mjs
• dist/diagramo.js
• dist/diagramo.browser.js
• examples/static-page.html