@yassimba/pi-loom-mermaid 0.2.0

package/src/loom-mermaid/source-box.ts

@@ -0,0 +1,111 @@
+/**
+ * The raw source in a framed box.
+ *
+ * What to show when `render` returns `null`, or returns art too wide for the
+ * space at hand. Both are the caller's call, so this is theirs to invoke — and
+ * theirs to caption, since only they know whether some other view of the
+ * diagram exists to point the reader at.
+ */
+
+import { srcLines, stripControls } from './labels.ts'
+import { sat } from './layout.ts'
+import type { MermaidArt, Span } from './types.ts'
+import { measured, stringWidth } from './width.ts'
+
+/**
+ * Frame `src` in a titled box, hard-wrapping its lines to `maxWidth` columns.
+ *
+ * The result can still exceed `maxWidth`: the body wraps to
+ * `max(8, maxWidth - 4)` and the ` mermaid: <kind> ` title is never truncated,
+ * so a long first token sets a floor. Check `width` if it matters.
+ */
+export function sourceBox(src: string, maxWidth?: number): MermaidArt {
+  src = stripControls(src)
+  const header = src.split(/\s+/).filter((w) => w !== '')[0] ?? 'diagram'
+  const title = ` mermaid: ${header} `
+  const limit = maxWidth === undefined ? undefined : Math.max(8, sat(maxWidth, 4))
+
+  const body = srcLines(src)
+    .map((l) => expandTabs(l).replace(/\s+$/, ''))
+    .reduce<{ started: boolean; lines: string[] }>(
+      (acc, l) => {
+        if (!acc.started && l === '') return acc
+        acc.started = true
+        acc.lines.push(...chunkLine(l, limit))
+        return acc
+      },
+      { started: false, lines: [] },
+    ).lines
+
+  // reduce, not a spread: a spread of stringWidths overflows the arg limit
+  // on very large sources.
+  const contentW = body.reduce((w, l) => Math.max(w, stringWidth(l)), stringWidth(title))
+  const inner = contentW + 2
+
+  const plain: string[] = []
+  const styled: Span[][] = []
+
+  const rule = '─'.repeat(sat(inner, stringWidth(title)))
+  plain.push(`╭${title}${rule}╮`)
+  styled.push([
+    { text: '╭', role: 'border' },
+    { text: title, role: 'title' },
+    { text: `${rule}╮`, role: 'border' },
+  ])
+
+  for (const line of body) {
+    const pad = ' '.repeat(sat(contentW, stringWidth(line)))
+    plain.push(`│ ${line}${pad} │`)
+    styled.push([
+      { text: '│ ', role: 'border' },
+      { text: line, role: 'text' },
+      { text: `${pad} │`, role: 'border' },
+    ])
+  }
+
+  const bottom = `╰${'─'.repeat(inner)}╯`
+  plain.push(bottom)
+  styled.push([{ text: bottom, role: 'border' }])
+
+  return { plain, styled, width: inner + 2, classDefs: {}, warnings: [] }
+}
+
+/**
+ * Expand tabs to 4-column stops. A literal tab measures one column here but
+ * whatever the terminal's tab stops say there, so the frame would misalign.
+ */
+function expandTabs(line: string): string {
+  if (!line.includes('\t')) return line
+  let out = ''
+  let col = 0
+  for (const [c, cw] of measured(line)) {
+    if (c === '\t') {
+      const pad = 4 - (col % 4)
+      out += ' '.repeat(pad)
+      col += pad
+    } else {
+      out += c
+      col += cw
+    }
+  }
+  return out
+}
+
+/** Hard-break a line at `limit` columns, never splitting a wide glyph. */
+function chunkLine(line: string, limit: number | undefined): string[] {
+  if (limit === undefined || stringWidth(line) <= limit) return [line]
+  const out: string[] = []
+  let cur = ''
+  let curW = 0
+  for (const [c, cw] of measured(line)) {
+    if (curW + cw > limit && cur !== '') {
+      out.push(cur)
+      cur = ''
+      curW = 0
+    }
+    cur += c
+    curW += cw
+  }
+  if (cur !== '') out.push(cur)
+  return out
+}

package/src/loom-mermaid/statements.ts

@@ -0,0 +1,228 @@
+/**
+ * The shared statement layer: source text to statements, plus the small
+ * string-reading helpers every grammar leans on.
+ */
+
+import { asciiLower, srcLines } from './labels.ts'
+
+function flushStatement(cur: string, out: string[]): string {
+  const trimmed = cur.trim()
+  if (trimmed !== '') out.push(trimmed)
+  return ''
+}
+
+/**
+ * Split one source line into statements on `;`, stopping at a `%%` comment.
+ *
+ * Quoted spans are opaque, so a label may contain `;` and `%%`.
+ */
+function splitStatements(line: string, out: string[]): void {
+  const chars = [...line]
+  let cur = ''
+  let inQuotes = false
+  for (let i = 0; i < chars.length; i++) {
+    const c = chars[i]
+    if (inQuotes) {
+      if (c === '"') inQuotes = false
+      cur += c
+    } else if (c === '"') {
+      inQuotes = true
+      cur += c
+    } else if (c === '%' && chars[i + 1] === '%') {
+      break
+    } else if (c === ';') {
+      cur = flushStatement(cur, out)
+    } else {
+      cur += c
+    }
+  }
+  flushStatement(cur, out)
+}
+
+/**
+ * Index just past a leading YAML frontmatter block (`---` … `---`), or 0 when
+ * there is none. While the block is still unterminated everything is
+ * frontmatter, so a streamed diagram stays blank until it closes.
+ */
+export function frontmatterEnd(lines: string[]): number {
+  let i = 0
+  while (i < lines.length && lines[i].trim() === '') i++
+  if (lines[i]?.trim() !== '---') return 0
+  i++
+  while (i < lines.length && lines[i].trim() !== '---') i++
+  return i + 1
+}
+
+/**
+ * All statements in a source block, in order. A leading YAML frontmatter
+ * block, part of the mermaid grammar since v10, is skipped.
+ */
+export function statementsOf(src: string): string[] {
+  const lines = srcLines(src)
+  const out: string[] = []
+  for (const line of lines.slice(frontmatterEnd(lines))) splitStatements(line, out)
+  return out
+}
+
+/**
+ * The `title:` of a leading frontmatter block, or null. The one frontmatter
+ * key with terminal meaning — `config` and friends style mermaid's own
+ * renderers and are deliberately ignored.
+ */
+export function frontmatterTitle(src: string): string | null {
+  const lines = srcLines(src)
+  const end = frontmatterEnd(lines)
+  for (const line of lines.slice(0, end)) {
+    const kv = splitOnce(line, ':')
+    // Untrimmed on the left: an indented `title:` is nested under some other
+    // key, not the diagram's.
+    if (kv === null || kv[0].trimEnd() !== 'title') continue
+    const t = kv[1].trim()
+    const quoted =
+      t.length > 1 &&
+      ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'")))
+    const title = (quoted ? t.slice(1, -1) : t).trim()
+    return title === '' ? null : title
+  }
+  return null
+}
+
+/** Per-char flags: 1 where the char lies inside a double-quoted span (quotes included). */
+export function quoteMask(chars: string[]): Uint8Array {
+  const mask = new Uint8Array(chars.length)
+  let inQuotes = false
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === '"') {
+      mask[i] = 1
+      inQuotes = !inQuotes
+    } else if (inQuotes) {
+      mask[i] = 1
+    }
+  }
+  return mask
+}
+
+/**
+ * Split on separator chars sitting outside double quotes and parentheses,
+ * dropping empty segments — the one splitter every grammar shares, so quote
+ * rules cannot drift between them.
+ */
+export function splitTop(s: string, isSep: (c: string) => boolean): string[] {
+  const out: string[] = []
+  let cur = ''
+  let inQuotes = false
+  let depth = 0
+  for (const c of s) {
+    if (c === '"') inQuotes = !inQuotes
+    else if (!inQuotes && c === '(') depth++
+    else if (!inQuotes && c === ')' && depth > 0) depth--
+    if (!inQuotes && depth === 0 && isSep(c)) {
+      if (cur !== '') out.push(cur)
+      cur = ''
+    } else {
+      cur += c
+    }
+  }
+  if (cur !== '') out.push(cur)
+  return out
+}
+
+/**
+ * Split `head : rest` at the first label colon, skipping `:::` tag runs so
+ * `A:::hot : desc` keeps its tag with the id. `null` when there is no colon.
+ */
+export function splitColon(s: string): [string, string] | null {
+  const chars = [...s]
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] !== ':') continue
+    let run = i
+    while (run < chars.length && chars[run] === ':') run++
+    if (run - i >= 3) {
+      i = run - 1
+      continue
+    }
+    return [chars.slice(0, i).join(''), chars.slice(i + 1).join('')]
+  }
+  return null
+}
+
+/** Strip trailing `:::name` tags from an id token: `A:::hot` → id `A`, classes `[hot]`. */
+export function takeTags(token: string): { id: string; classes: string[] } {
+  const parts = token.split(':::')
+  if (parts.length === 1 || parts[0] === '') return { id: token, classes: [] }
+  return { id: parts[0], classes: parts.slice(1).filter((c) => c !== '') }
+}
+
+/**
+ * The body of a `class A,B name` statement → `[ids, names]`. The last
+ * whitespace-separated token is the name list, everything before it the ids —
+ * so a space after a comma (`class A, B warn`) still reads as two ids.
+ */
+export function parseClassAssign(rest: string): [string[], string[]] | null {
+  const body = rest.trim()
+  const ws = body.search(/\s\S*$/)
+  if (ws === -1) return null
+  const split = (s: string): string[] =>
+    s
+      .split(',')
+      .map((t) => t.trim())
+      .filter((t) => t !== '')
+  return [split(body.slice(0, ws)), split(body.slice(ws))]
+}
+
+/**
+ * `A "url" [tooltip]` / `A href "url" …` → `[id, url]`. The callback forms
+ * (`call`/`callback`) return null — their quoted string is a tooltip.
+ */
+export function parseHref(rest: string): [string, string] | null {
+  const [id, second] = words(rest)
+  if (id === undefined || second === 'call' || second === 'callback') return null
+  const url = rest.match(/"([^"]+)"/)
+  return url === null ? null : [id, url[1]]
+}
+
+export const firstWord = (s: string): string => s.split(/\s+/).filter((w) => w !== '')[0] ?? ''
+export const words = (s: string): string[] => s.split(/\s+/).filter((w) => w !== '')
+
+/** Split on the first occurrence of `sep`, Rust's `split_once`. */
+export function splitOnce(s: string, sep: string): [string, string] | null {
+  const i = s.indexOf(sep)
+  return i === -1 ? null : [s.slice(0, i), s.slice(i + sep.length)]
+}
+
+export const nonEmpty = (s: string): string | null => (s === '' ? null : s)
+
+/** Diagram kind from the header statement, lowercased. */
+export function headerKind(statements: string[]): string | null {
+  const header = statements[0]
+  if (header === undefined) return null
+  const kind = firstWord(header)
+  return kind === '' ? null : asciiLower(kind)
+}
+
+/**
+ * Parse the body of a `classDef` statement: `name[,name2] k1:v1,k2:v2`.
+ * Values are kept verbatim; malformed pairs are skipped.
+ */
+export function parseClassDef(
+  rest: string,
+): { names: string[]; props: Record<string, string> } | null {
+  const body = rest.trim()
+  const ws = body.search(/\s/)
+  if (ws === -1) return null
+  const names = body
+    .slice(0, ws)
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s !== '')
+  const props: Record<string, string> = {}
+  // splitTop keeps `rgb(255,0,0)` whole; a bare comma still separates pairs.
+  for (const pair of splitTop(body.slice(ws).trim(), (c) => c === ',')) {
+    const kv = splitOnce(pair, ':')
+    if (kv === null) continue
+    const k = kv[0].trim()
+    const v = kv[1].trim()
+    if (k !== '' && v !== '') props[k] = v
+  }
+  return names.length === 0 ? null : { names, props }
+}

package/src/loom-mermaid/types.ts

@@ -0,0 +1,64 @@
+/**
+ * Semantic role of a run of cells — what a cell *is*, decided by the
+ * renderer. The renderer never knows about colour; consumers map roles to
+ * their own theme (see `toAnsi` for the common case).
+ *
+ * - `border`     box outlines, subgraph frames, compartment rules
+ * - `text`       node / participant / compartment labels
+ * - `edge`       connector lines and arrowheads
+ * - `edgeLabel`  text sitting on an edge
+ * - `title`      the `mermaid: <kind>` header of a source box
+ * - `none`       blank filler
+ *
+ * Distinct from `classes`, which is what the *author* assigned.
+ */
+export type Role = 'border' | 'text' | 'edge' | 'edgeLabel' | 'title' | 'none'
+
+/** A run of adjacent cells sharing one role and one set of author classes. */
+export interface Span {
+  text: string
+  role: Role
+  /**
+   * Author-assigned class names of the node these cells belong to, from a
+   * `:::name` shorthand or a `class A,B name` statement. The renderer never
+   * interprets them — pair with `MermaidArt.classDefs` to style. Absent on
+   * cells that belong to no classed node.
+   */
+  classes?: string[]
+  /**
+   * Link target of the node these cells belong to, from a `click A "url"`
+   * (flowchart) or `link A "url"` (class diagram) statement. `toAnsi` emits
+   * it as an OSC 8 hyperlink; other consumers map it to their own linking.
+   */
+  href?: string
+}
+
+/**
+ * A rendered diagram. `plain[i]` and `styled[i]` describe the same row:
+ * `plain` is right-trimmed for display width and copy/paste, `styled` keeps
+ * the run structure needed to colour it.
+ *
+ * `width` is the display columns the widest row needs — the number to compare
+ * against the space you have. It cannot be recovered from `plain`, whose rows
+ * are strings of code points, not columns.
+ *
+ * `classDefs` are the diagram's `classDef` declarations, parsed:
+ * `classDef warning fill:#f96,stroke:#333` becomes
+ * `{ warning: { fill: '#f96', stroke: '#333' } }`. The renderer ignores them;
+ * a consumer can map them onto its own styling of the classes spans carry.
+ *
+ * `warnings` lists source the grammar could not read and dropped, and any
+ * size-cap truncation. Non-empty means the art is real but incomplete — some
+ * of what was written is not in it.
+ *
+ * They are advisory. Do not gate rendering on them: the art is the best drawing
+ * of the source either way, and a diagram being typed or streamed warns at
+ * nearly every intermediate state. Show them alongside, or once it settles.
+ */
+export interface MermaidArt {
+  plain: string[]
+  styled: Span[][]
+  width: number
+  classDefs: Record<string, Record<string, string>>
+  warnings: string[]
+}