opentui-markdown-render 0.0.0-stage → 0.2.0

package/src/merman/sequence/drawing.ts

@@ -0,0 +1,288 @@
+import { BorderChars, type BorderStyle } from "@opentui/core"
+import { DiagramCanvas } from "../core/canvas.js"
+import { diagramTextWidth } from "../core/text.js"
+import { DEFAULT_FRAGMENT_BORDER_STYLE } from "./options.js"
+import {
+  createSequencePlacementPlan,
+  isFragmentStart,
+  type SequenceGroupPlacement,
+  type SequenceHorizontalBounds,
+  type SequenceStepPlacement,
+} from "./placement.js"
+import type { SequenceGrid } from "./render-grid.js"
+import { SEQUENCE_FADE_STEPS as FADE_STEPS } from "./style.js"
+import type {
+  MessageStyle,
+  SequenceArrowHead,
+  SequenceCellStyle,
+  SequenceDiagram,
+  SequenceDiagramRenderOptions,
+} from "./types.js"
+
+const SEQUENCE_BORDER = BorderChars.rounded
+
+function centeredStart(center: number, text: string): number {
+  return center - Math.floor(diagramTextWidth(text) / 2)
+}
+
+function arrowHeadChar(head: SequenceArrowHead | undefined, direction: 1 | -1): string {
+  switch (head) {
+    case "open":
+      return direction === 1 ? ">" : "<"
+    case "cross":
+      return "✕"
+    case "async":
+      return direction === 1 ? ")" : "("
+    default:
+      return direction === 1 ? "►" : "◄"
+  }
+}
+
+function createGrid(width: number, height: number): SequenceGrid {
+  return new DiagramCanvas(width, height)
+}
+
+function setCell(grid: SequenceGrid, x: number, y: number, char: string, style?: SequenceCellStyle): void {
+  grid.setCell(x, y, char, style)
+}
+
+function setText(grid: SequenceGrid, x: number, y: number, text: string, style?: SequenceCellStyle): void {
+  grid.setText(Math.max(0, x), y, text, style)
+}
+
+function setArrowDepartureFade(
+  grid: SequenceGrid,
+  x: number,
+  y: number,
+  direction: 1 | -1,
+  style: SequenceCellStyle,
+): void {
+  setCell(
+    grid,
+    x,
+    y,
+    direction === 1 ? SEQUENCE_BORDER.leftT : SEQUENCE_BORDER.rightT,
+    `${style}Fade1` as SequenceCellStyle,
+  )
+  for (let step = 2; step <= 5; step++) {
+    setCell(grid, x + direction * (step - 1), y, SEQUENCE_BORDER.horizontal, `${style}Fade${step}` as SequenceCellStyle)
+  }
+}
+
+function groupVerticalChar(existing: string | undefined): string | undefined {
+  switch (existing) {
+    case undefined:
+    case " ":
+      return SEQUENCE_BORDER.vertical
+    case SEQUENCE_BORDER.vertical:
+      return SEQUENCE_BORDER.vertical
+    default:
+      return undefined
+  }
+}
+
+function setGroupVerticalCell(grid: SequenceGrid, x: number, y: number): void {
+  const existing = grid.getCell(x, y)?.char
+  const char = groupVerticalChar(existing)
+  if (char) setCell(grid, x, y, char, "group")
+}
+
+function renderParticipantGroups(
+  grid: SequenceGrid,
+  groupBounds: readonly SequenceGroupPlacement[],
+  bottomY: number,
+): void {
+  for (const bounds of groupBounds) {
+    for (let x = bounds.leftX; x <= bounds.rightX; x++) {
+      setCell(grid, x, 0, SEQUENCE_BORDER.horizontal, "group")
+      setCell(grid, x, bottomY, SEQUENCE_BORDER.horizontal, "group")
+    }
+
+    setCell(grid, bounds.leftX, 0, SEQUENCE_BORDER.topLeft, "group")
+    setCell(grid, bounds.rightX, 0, SEQUENCE_BORDER.topRight, "group")
+    setCell(grid, bounds.leftX, bottomY, SEQUENCE_BORDER.bottomLeft, "group")
+    setCell(grid, bounds.rightX, bottomY, SEQUENCE_BORDER.bottomRight, "group")
+
+    for (let y = 1; y < bottomY; y++) {
+      setGroupVerticalCell(grid, bounds.leftX, y)
+      setGroupVerticalCell(grid, bounds.rightX, y)
+    }
+
+    if (bounds.labelText) {
+      setText(grid, bounds.leftX + 2, 0, bounds.labelText, "group")
+    }
+  }
+}
+
+function drawFragmentWalls(
+  grid: SequenceGrid,
+  bounds: SequenceHorizontalBounds,
+  startY: number,
+  endY: number,
+  borderStyle: BorderStyle,
+): void {
+  if (endY < startY) return
+  const border = BorderChars[borderStyle]
+
+  for (let y = startY; y <= endY; y++) {
+    setCell(grid, bounds.leftX, y, border.vertical, "fragment")
+    setCell(grid, bounds.rightX, y, border.vertical, "fragment")
+  }
+}
+
+function renderFragment(
+  grid: SequenceGrid,
+  placement: Extract<SequenceStepPlacement, { type: "fragment" }>,
+  borderStyle: BorderStyle,
+): void {
+  const { bounds, fragment, labelText: label, y } = placement
+  const border = BorderChars[borderStyle]
+  const { leftX, rightX } = bounds
+
+  const leftChar =
+    isFragmentStart(fragment.kind)
+      ? border.topLeft
+      : fragment.kind !== "end"
+        ? border.leftT
+        : border.bottomLeft
+  const rightChar =
+    isFragmentStart(fragment.kind)
+      ? border.topRight
+      : fragment.kind !== "end"
+        ? border.rightT
+        : border.bottomRight
+
+  for (let x = leftX; x <= rightX; x++) {
+    setCell(grid, x, y, border.horizontal, "fragment")
+  }
+
+  setCell(grid, leftX, y, leftChar, "fragment")
+  setCell(grid, rightX, y, rightChar, "fragment")
+  if (label) {
+    setText(grid, leftX + 2, y, label, "fragmentLabel")
+  }
+}
+
+function renderSelfMessage(
+  grid: SequenceGrid,
+  placement: Extract<SequenceStepPlacement, { type: "selfMessage" }>,
+  style: MessageStyle,
+): void {
+  const { centerX, rightX, topY: topRow, bottomY: bottomRow, labelLines, message } = placement
+
+  setArrowDepartureFade(grid, centerX, topRow, 1, style)
+  for (let x = centerX + FADE_STEPS.length; x < rightX; x++) {
+    setCell(grid, x, topRow, SEQUENCE_BORDER.horizontal, style)
+  }
+  setCell(grid, rightX, topRow, SEQUENCE_BORDER.topRight, style)
+
+  for (let lineIndex = 0; lineIndex < labelLines.length; lineIndex++) {
+    const y = topRow + lineIndex + 1
+    setCell(grid, centerX, y, SEQUENCE_BORDER.vertical, "lifeline")
+    setText(grid, centerX + 2, y, labelLines[lineIndex]!, style)
+    setCell(grid, rightX, y, SEQUENCE_BORDER.vertical, style)
+  }
+
+  for (let x = centerX + 1; x < rightX; x++) {
+    setCell(grid, x, bottomRow, SEQUENCE_BORDER.horizontal, style)
+  }
+  const headX = message.head === undefined ? centerX : centerX + 1
+  setCell(grid, headX, bottomRow, arrowHeadChar(message.head, -1), style)
+  setCell(grid, rightX, bottomRow, SEQUENCE_BORDER.bottomRight, style)
+}
+
+function renderNote(grid: SequenceGrid, placement: Extract<SequenceStepPlacement, { type: "note" }>): void {
+  placement.textLines.forEach((line, index) =>
+    setText(grid, placement.textX, placement.textY + index, line, "noteBadge"),
+  )
+}
+
+export function drawSequenceDiagramGrid(
+  diagram: SequenceDiagram,
+  options: SequenceDiagramRenderOptions = {},
+): SequenceGrid {
+  const plan = createSequencePlacementPlan(diagram, options)
+  if (plan.width === 0 || plan.height === 0) return createGrid(0, 0)
+  const fragmentBorderStyle = options.fragmentBorderStyle ?? DEFAULT_FRAGMENT_BORDER_STYLE
+  const grid = createGrid(plan.width, plan.height)
+
+  if (plan.groups.length > 0) renderParticipantGroups(grid, plan.groups, plan.height - 1)
+
+  for (const placement of plan.participants) {
+    const { centerX: center, headerLeftX, headerRightX, labelLines } = placement
+    const { participantHeaderTopY, participantHeaderY, participantRuleY, lifelineStartY, lifelineEndY } = plan.rows
+
+    if (options.compact) {
+      labelLines.forEach((line, index) =>
+        setText(grid, centeredStart(center, line), participantHeaderY + index, line, "participant"),
+      )
+    } else {
+      labelLines.forEach((line, index) =>
+        setText(grid, centeredStart(center, line), participantHeaderTopY + index, line, "participant"),
+      )
+      for (let x = headerLeftX; x <= headerRightX; x++) {
+        setCell(grid, x, participantRuleY, SEQUENCE_BORDER.horizontal, "participant")
+      }
+      setCell(grid, center, participantRuleY, SEQUENCE_BORDER.topT, "participant")
+    }
+
+    for (let y = lifelineStartY; y <= lifelineEndY; y++) {
+      const distance = y - lifelineStartY
+      const style = !options.compact && distance < 3 ? (`lifelineRamp${distance + 1}` as SequenceCellStyle) : "lifeline"
+      setCell(grid, center, y, SEQUENCE_BORDER.vertical, style)
+    }
+  }
+
+  for (const placement of plan.steps) {
+    if (placement.type === "note") {
+      renderNote(grid, placement)
+      continue
+    }
+
+    if (placement.type === "fragment") {
+      if (placement.wallsBefore) {
+        drawFragmentWalls(
+          grid,
+          placement.wallsBefore.bounds,
+          placement.wallsBefore.startY,
+          placement.wallsBefore.endY,
+          fragmentBorderStyle,
+        )
+      }
+      renderFragment(grid, placement, fragmentBorderStyle)
+      continue
+    }
+
+    const message = placement.message
+    const messageStyle: MessageStyle = message.style === "dashed" ? "response" : "request"
+
+    if (placement.type === "selfMessage") {
+      renderSelfMessage(grid, placement, messageStyle)
+      continue
+    }
+
+    if (!placement.inlineLabel) {
+      for (let lineIndex = 0; lineIndex < placement.labelLines.length; lineIndex++) {
+        setText(grid, placement.labelX, placement.labelY + lineIndex, placement.labelLines[lineIndex]!, messageStyle)
+      }
+    }
+
+    for (let x = placement.leftX + 1; x < placement.rightX; x++) {
+      setCell(grid, x, placement.arrowY, SEQUENCE_BORDER.horizontal, messageStyle)
+    }
+
+    setArrowDepartureFade(grid, placement.fromX, placement.arrowY, placement.direction, messageStyle)
+    setCell(grid, placement.headX, placement.arrowY, arrowHeadChar(message.head, placement.direction), messageStyle)
+    if (placement.inlineLabel) setText(grid, placement.labelX, placement.labelY, placement.inlineLabel, messageStyle)
+  }
+
+  for (const activation of plan.activations) {
+    for (let y = activation.startY; y <= activation.endY; y++) {
+      if (grid.getCell(activation.centerX, y)?.char === SEQUENCE_BORDER.vertical) {
+        setCell(grid, activation.centerX, y, "┃", "lifeline")
+      }
+    }
+  }
+
+  return grid
+}

package/src/merman/sequence/options.ts

@@ -0,0 +1,8 @@
+import type { BorderStyle } from "@opentui/core"
+
+export const DEFAULT_MIN_PARTICIPANT_GAP = 18
+export const DEFAULT_FRAGMENT_BORDER_STYLE = "rounded" satisfies BorderStyle
+
+export function normalizeSequenceMinParticipantGap(value: number | undefined): number {
+  return value === undefined || !Number.isFinite(value) ? DEFAULT_MIN_PARTICIPANT_GAP : Math.max(1, Math.floor(value))
+}

package/src/merman/sequence/parser.ts

@@ -0,0 +1,303 @@
+import {
+  firstMeaningfulMermaidLine,
+  meaningfulNumberedMermaidLines,
+  stripMermaidQuotes as stripQuotes,
+} from "../core/mermaid.js"
+import { MermaidSyntaxError } from "../diagnostics.js"
+import type {
+  SequenceArrowHead,
+  SequenceDiagram,
+  SequenceMessage,
+  SequenceParticipant,
+  SequenceParticipantGroup,
+  SequenceStep,
+} from "./types.js"
+
+const MESSAGE_RE = /^(.+?)\s*(-->>|->>|--x|-x|--\)|-\)|-->|->)([+-]?)\s*(.+?)\s*:\s*(.*)$/
+const NOTE_RE = /^note\s+(over|left\s+of|right\s+of)\s+(.+?)\s*:\s*(.*)$/i
+const PARTICIPANT_RE = /^(?:participant|actor)\s+(\S+)(?:\s+as\s+(.+))?$/i
+const ACTIVATION_RE = /^(activate|deactivate)\s+(.+)$/i
+const BOX_RE = /^box(?:\s+(.+))?$/i
+const ALT_RE = /^alt\s+(.+)$/i
+const ELSE_RE = /^else(?:\s+(.+))?$/i
+const LOOP_RE = /^loop\s+(.+)$/i
+const FRAGMENT_START_RE = /^(opt|par|critical|break)(?:\s+(.+))?$/i
+const FRAGMENT_BRANCH_RE = /^(and|option)(?:\s+(.+))?$/i
+const AUTONUMBER_RE = /^autonumber(?:\s+(\d+)(?:\s+(\d+))?)?$/i
+const UNSUPPORTED_BIDIRECTIONAL_MESSAGE_RE = /<<-{1,2}>>/
+const MESSAGE_OPERATOR_RE = /-->>|->>|--x|-x|--\)|-\)|-->|->/
+const CSS_COLOR_NAMES = new Set([
+  "black",
+  "white",
+  "red",
+  "green",
+  "blue",
+  "yellow",
+  "cyan",
+  "magenta",
+  "silver",
+  "gray",
+  "grey",
+  "maroon",
+  "olive",
+  "lime",
+  "aqua",
+  "teal",
+  "navy",
+  "fuchsia",
+  "purple",
+  "orange",
+  "brightblack",
+  "brightred",
+  "brightgreen",
+  "brightblue",
+  "brightyellow",
+  "brightcyan",
+  "brightmagenta",
+  "brightwhite",
+])
+
+function arrowHeadForSyntax(arrow: string): SequenceArrowHead | undefined {
+  if (arrow.endsWith("x")) return "cross"
+  if (arrow.endsWith(")")) return "async"
+  if (arrow.endsWith(">") && !arrow.endsWith(">>")) return "open"
+  return undefined
+}
+
+function isBoxColorToken(value: string): boolean {
+  const lowerValue = value.toLowerCase()
+  return (
+    lowerValue === "transparent" ||
+    CSS_COLOR_NAMES.has(lowerValue) ||
+    /^#[0-9a-f]{3,8}$/i.test(value) ||
+    /^rgba?\(.+\)$/i.test(value)
+  )
+}
+
+function splitLeadingBoxToken(value: string): { token: string; rest: string } {
+  if (/^rgba?\(/i.test(value)) {
+    const closeIndex = value.indexOf(")")
+    if (closeIndex >= 0) {
+      return { token: value.slice(0, closeIndex + 1), rest: value.slice(closeIndex + 1).trim() }
+    }
+  }
+
+  const firstSpace = value.search(/\s/)
+  return firstSpace < 0
+    ? { token: value, rest: "" }
+    : { token: value.slice(0, firstSpace), rest: value.slice(firstSpace + 1).trim() }
+}
+
+function boxLabelText(value: string | undefined): string {
+  const rawLabel = (value ?? "").trim()
+  if ((rawLabel.startsWith('"') && rawLabel.endsWith('"')) || (rawLabel.startsWith("'") && rawLabel.endsWith("'"))) {
+    return stripQuotes(rawLabel)
+  }
+
+  const label = stripQuotes(rawLabel)
+  if (!label) return ""
+  const { token, rest } = splitLeadingBoxToken(label)
+  return isBoxColorToken(token) ? stripQuotes(rest) : label
+}
+
+function addParticipantToGroup(group: SequenceParticipantGroup | undefined, participantId: string): void {
+  if (!group || group.participantIds.includes(participantId)) return
+  group.participantIds.push(participantId)
+}
+
+function ensureParticipant(
+  participants: SequenceParticipant[],
+  id: string,
+  label: string = id,
+  replaceExistingLabel: boolean = false,
+): void {
+  const existing = participants.find((participant) => participant.id === id)
+  if (existing) {
+    if (replaceExistingLabel) existing.label = label
+    return
+  }
+  participants.push({ id, label })
+}
+
+export function isMermaidSequenceDiagram(content: string): boolean {
+  return firstMeaningfulMermaidLine(content)?.toLowerCase() === "sequencediagram"
+}
+
+export function parseMermaidSequenceDiagram(content: string): SequenceDiagram {
+  const participants: SequenceParticipant[] = []
+  const messages: SequenceMessage[] = []
+  const steps: SequenceStep[] = []
+  const groups: SequenceParticipantGroup[] = []
+  const blockStack: Array<{ kind: "box" | "alt" | "loop" | "opt" | "par" | "critical" | "break"; lineNumber: number; sourceLine: string }> = []
+  const groupStack: SequenceParticipantGroup[] = []
+  let nextMessageNumber: number | undefined
+  let messageNumberIncrement = 1
+
+  for (const source of meaningfulNumberedMermaidLines(content)) {
+    const line = source.text
+    if (line.toLowerCase() === "sequencediagram") continue
+    if (UNSUPPORTED_BIDIRECTIONAL_MESSAGE_RE.test(line)) {
+      throw new MermaidSyntaxError("sequence", source.lineNumber, line)
+    }
+
+    const autonumberMatch = line.match(AUTONUMBER_RE)
+    if (autonumberMatch) {
+      nextMessageNumber = Number.parseInt(autonumberMatch[1] ?? "1", 10)
+      messageNumberIncrement = Number.parseInt(autonumberMatch[2] ?? "1", 10)
+      continue
+    }
+
+    const boxMatch = line.match(BOX_RE)
+    if (boxMatch) {
+      const group: SequenceParticipantGroup = { label: boxLabelText(boxMatch[1]), participantIds: [] }
+      groups.push(group)
+      groupStack.push(group)
+      blockStack.push({ kind: "box", lineNumber: source.lineNumber, sourceLine: line })
+      continue
+    }
+
+    const participantMatch = line.match(PARTICIPANT_RE)
+    if (participantMatch) {
+      const id = stripQuotes(participantMatch[1]!)
+      ensureParticipant(participants, id, stripQuotes(participantMatch[2] ?? id), true)
+      addParticipantToGroup(groupStack[groupStack.length - 1], id)
+      continue
+    }
+
+    const noteMatch = line.match(NOTE_RE)
+    if (noteMatch) {
+      const position = noteMatch[1]!.toLowerCase().replace(/\s+of$/, "") as "over" | "left" | "right"
+      const over = noteMatch[2]!
+        .split(",")
+        .map((participant) => stripQuotes(participant))
+        .filter((participant) => participant.length > 0)
+      for (const participant of over) ensureParticipant(participants, participant)
+      steps.push({
+        type: "note",
+        note: {
+          over,
+          label: stripQuotes(noteMatch[3]!),
+          ...(position === "over" ? {} : { position }),
+        },
+      })
+      continue
+    }
+
+    const activationMatch = line.match(ACTIVATION_RE)
+    if (activationMatch) {
+      const participant = stripQuotes(activationMatch[2]!)
+      ensureParticipant(participants, participant)
+      steps.push({
+        type: "activation",
+        activation: { participant, active: activationMatch[1]!.toLowerCase() === "activate" },
+      })
+      continue
+    }
+
+    const altMatch = line.match(ALT_RE)
+    if (altMatch) {
+      blockStack.push({ kind: "alt", lineNumber: source.lineNumber, sourceLine: line })
+      steps.push({ type: "fragment", fragment: { kind: "alt", label: stripQuotes(altMatch[1]!) } })
+      continue
+    }
+
+    const loopMatch = line.match(LOOP_RE)
+    if (loopMatch) {
+      blockStack.push({ kind: "loop", lineNumber: source.lineNumber, sourceLine: line })
+      steps.push({ type: "fragment", fragment: { kind: "loop", label: stripQuotes(loopMatch[1]!) } })
+      continue
+    }
+
+    const fragmentStart = line.match(FRAGMENT_START_RE)
+    if (fragmentStart) {
+      const kind = fragmentStart[1]!.toLowerCase() as "opt" | "par" | "critical" | "break"
+      blockStack.push({ kind, lineNumber: source.lineNumber, sourceLine: line })
+      steps.push({ type: "fragment", fragment: { kind, label: stripQuotes(fragmentStart[2] ?? "") } })
+      continue
+    }
+
+    const branchMatch = line.match(FRAGMENT_BRANCH_RE)
+    if (branchMatch) {
+      const kind = branchMatch[1]!.toLowerCase() as "and" | "option"
+      const expected = kind === "and" ? "par" : "critical"
+      if (blockStack[blockStack.length - 1]?.kind !== expected) {
+        throw new MermaidSyntaxError("sequence", source.lineNumber, line, `Unexpected "${kind}" without an open "${expected}" block`)
+      }
+      steps.push({ type: "fragment", fragment: { kind, label: stripQuotes(branchMatch[2] ?? "") } })
+      continue
+    }
+
+    const elseMatch = line.match(ELSE_RE)
+    if (elseMatch) {
+      if (blockStack[blockStack.length - 1]?.kind !== "alt") {
+        throw new MermaidSyntaxError(
+          "sequence",
+          source.lineNumber,
+          line,
+          'Unexpected "else" without an open "alt" block',
+        )
+      }
+      steps.push({ type: "fragment", fragment: { kind: "else", label: stripQuotes(elseMatch[1] ?? "") } })
+      continue
+    }
+
+    if (line.toLowerCase() === "end") {
+      const block = blockStack.pop()
+      if (!block)
+        throw new MermaidSyntaxError("sequence", source.lineNumber, line, 'Unexpected "end" without an open block')
+      if (block.kind === "box") {
+        groupStack.pop()
+        continue
+      }
+      steps.push({ type: "fragment", fragment: { kind: "end", label: block.kind } })
+      continue
+    }
+
+    const messageMatch = line.match(MESSAGE_RE)
+    if (messageMatch) {
+      const from = stripQuotes(messageMatch[1]!)
+      const arrow = messageMatch[2]!
+      const activationMarker = messageMatch[3]!
+      const to = stripQuotes(messageMatch[4]!)
+      if (MESSAGE_OPERATOR_RE.test(from) || MESSAGE_OPERATOR_RE.test(to)) {
+        throw new MermaidSyntaxError("sequence", source.lineNumber, line)
+      }
+      const message: SequenceMessage = {
+        from,
+        to,
+        label: stripQuotes(messageMatch[5]!),
+        style: arrow.startsWith("--") ? "dashed" : "solid",
+      }
+      const activeGroup = groupStack[groupStack.length - 1]
+      ensureParticipant(participants, from)
+      ensureParticipant(participants, to)
+      addParticipantToGroup(activeGroup, from)
+      addParticipantToGroup(activeGroup, to)
+      const head = arrowHeadForSyntax(arrow)
+      if (head) message.head = head
+      if (nextMessageNumber !== undefined) {
+        message.number = nextMessageNumber
+        nextMessageNumber += messageNumberIncrement
+      }
+      if (activationMarker === "+") message.activate = to
+      else if (activationMarker === "-") message.deactivate = from
+      messages.push(message)
+      steps.push({ type: "message", message })
+      continue
+    }
+
+    throw new MermaidSyntaxError("sequence", source.lineNumber, line)
+  }
+
+  const unclosedBlock = blockStack[blockStack.length - 1]
+  if (unclosedBlock) {
+    throw new MermaidSyntaxError(
+      "sequence",
+      unclosedBlock.lineNumber,
+      unclosedBlock.sourceLine,
+      `Unclosed ${unclosedBlock.kind} block; expected "end"`,
+    )
+  }
+
+  return { participants, messages, steps, groups }
+}