opentui-markdown-render 0.0.0-stage → 0.1.0

package/src/config/theme.ts

@@ -0,0 +1,88 @@
+import type { ThemeOverride } from "../theme/types"
+import type { ConfigReporter } from "./load"
+
+// A JSON file only carries strings, not RGBA instances. OpenTUI accepts these
+// colour names and hex forms; rejecting anything else here avoids its silent
+// magenta fallback for misspelled colours.
+const colorNames = new Set([
+  "transparent", "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",
+])
+
+type Field = "color" | "mode" | "colors" | { readonly [key: string]: Field }
+const colors = <K extends string>(keys: readonly K[]): Record<K, Field> =>
+  Object.fromEntries(keys.map((key) => [key, "color"])) as Record<K, Field>
+
+// The allowlist follows ThemeOverride, not the resolved Theme: headingLevels
+// is an internal six-colour array, while heading1..heading6 are file options.
+const themeFields: Record<string, Field> = {
+  mode: "mode",
+  accent: "color",
+  categorical: "colors",
+  text: {
+    base: "color",
+    muted: "color",
+    feedback: colors(["error", "warning", "success", "info"]),
+    action: { primary: { focused: "color" } },
+  },
+  background: { base: "color" },
+  border: { base: "color" },
+  frame: colors(["border", "title"]),
+  statusline: colors(["background", "foreground", "title", "muted", "border"]),
+  markdown: colors([
+    "text", "heading", "heading1", "heading2", "heading3", "heading4", "heading5", "heading6",
+    "link", "linkText", "code", "blockQuote", "emphasis", "strong", "horizontalRule",
+    "listItem", "listEnumeration", "image", "imageText", "codeBlock",
+  ]),
+  syntax: colors(["comment", "keyword", "function", "variable", "string", "number", "type", "operator", "punctuation"]),
+  diff: {
+    text: colors(["added", "removed", "context"]),
+    background: colors(["added", "removed", "context"]),
+  },
+}
+
+function isColor(value: unknown): value is string {
+  return typeof value === "string" && (
+    /^#?(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(value) ||
+    colorNames.has(value.toLowerCase())
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+export function validateTheme(value: Record<string, unknown>, file: string, report?: ConfigReporter): ThemeOverride {
+  const warn = (message: string) => {
+    if (report) report(message)
+    else console.warn(`[opentui-markdown-render] ${message}`)
+  }
+  const validate = (source: Record<string, unknown>, fields: Record<string, Field>, prefix: string): Record<string, unknown> => {
+    const result: Record<string, unknown> = Object.create(null)
+    for (const [key, entry] of Object.entries(source)) {
+      const field = Object.hasOwn(fields, key) ? fields[key] : undefined
+      const location = `${prefix}.${key}`
+      if (field === undefined) {
+        warn(`Unknown theme option "${location}" in ${file}`)
+        continue
+      }
+      if (field === "color" && isColor(entry)) result[key] = entry
+      else if (field === "mode" && (entry === "light" || entry === "dark" || entry === "solarized-light" || entry === "solarized-dark")) result[key] = entry
+      else if (field === "colors" && Array.isArray(entry)) {
+        result[key] = entry.filter((color, index) => {
+          if (isColor(color)) return true
+          warn(`Invalid theme option "${location}[${index}]" in ${file}`)
+          return false
+        })
+      } else if (typeof field === "object" && isRecord(entry)) {
+        result[key] = validate(entry, field, location)
+      } else {
+        warn(`Invalid theme option "${location}" in ${file}`)
+      }
+    }
+    return result
+  }
+  return validate(value, themeFields, "theme") as ThemeOverride
+}

package/src/config/types.ts

@@ -0,0 +1,102 @@
+import type { FrameConfig } from "../core/frame"
+import type { TablesConfig } from "../core/tables"
+import type { ThemeOverride } from "../theme/types"
+
+// The configuration file is a plain JSON/JSONC object. Every section is
+// optional; a missing section keeps the bundled default.
+export type MarkdownConfig = {
+  // Colour scheme. Mirrors the theme override shape.
+  readonly theme?: ThemeOverride
+  readonly statusline?: StatusLineConfig
+  readonly images?: ImagesConfig
+  readonly mermaid?: MermaidConfig
+  readonly headings?: HeadingsConfig
+  // How the viewer window is drawn around the document.
+  readonly frame?: FrameConfig
+  // How tables size themselves and what happens when they are too wide.
+  readonly tables?: TablesConfig
+}
+
+// The status line is a single row of labelled fields. `fields` selects and
+// orders them; a field without a value is skipped.
+export type StatusLineConfig = {
+  readonly enabled?: boolean
+  readonly fields?: readonly StatusLineField[]
+  readonly separator?: string
+  readonly border?: StatusLineBorder
+  // "plain" keeps the line in the page colours, "bar" gives it its own
+  // background and an accent border.
+  readonly style?: StatusLineStyle
+  // The field that gets the accent treatment.
+  readonly highlight?: StatusLineField
+}
+
+export type StatusLineField = "title" | "mode" | "protocol" | "cell" | "mathScale" | "position" | "hint" | "text"
+
+export type StatusLineBorder = "none" | "top" | "bottom"
+
+export type StatusLineStyle = "plain" | "bar"
+
+export const statusLineStyles: readonly StatusLineStyle[] = ["plain", "bar"]
+
+export function isStatusLineStyle(value: unknown): value is StatusLineStyle {
+  return typeof value === "string" && statusLineStyles.includes(value as StatusLineStyle)
+}
+
+export type ImagesConfig = {
+  // Maximum width of a rendered image in terminal columns.
+  readonly maxColumns?: number
+  // Maximum height of a rendered image in terminal rows.
+  readonly maxRows?: number
+}
+
+export type MermaidConfig = {
+  readonly compact?: boolean
+  readonly layoutMaxWidth?: number
+  /** Class diagrams only; defaults to the built-in layout. */
+  readonly classLayout?: "builtin" | "dagre"
+}
+
+// The heading levels are addressed by their number, the way Markdown writes
+// them.
+export type HeadingLevelKey = "1" | "2" | "3" | "4" | "5" | "6"
+
+// The look of a single heading level. Every option is optional: a missing one
+// keeps the bundled default for that level.
+export type HeadingLevelConfig = {
+  readonly bold?: boolean
+  readonly italic?: boolean
+  readonly underline?: boolean
+  readonly dim?: boolean
+  // Render the text of the heading in upper case.
+  readonly uppercase?: boolean
+  // Empty rows above the heading.
+  readonly marginTop?: number
+  // Empty rows below the heading.
+  readonly marginBottom?: number
+}
+
+export type HeadingsConfig = {
+  readonly levels?: { readonly [K in HeadingLevelKey]?: HeadingLevelConfig }
+}
+
+export const headingLevelKeys: readonly HeadingLevelKey[] = ["1", "2", "3", "4", "5", "6"]
+
+export function isHeadingLevelKey(value: string): value is HeadingLevelKey {
+  return (headingLevelKeys as readonly string[]).includes(value)
+}
+
+export const statusLineFields: readonly StatusLineField[] = [
+  "title",
+  "mode",
+  "protocol",
+  "cell",
+  "mathScale",
+  "position",
+  "hint",
+  "text",
+]
+
+export function isStatusLineField(value: unknown): value is StatusLineField {
+  return typeof value === "string" && statusLineFields.includes(value as StatusLineField)
+}

package/src/core/document.ts

@@ -0,0 +1,44 @@
+export type SourceRange = { readonly start: number; readonly end: number }
+
+export type NodeBase = { readonly raw: string; readonly source: SourceRange | null }
+
+export type Document = { readonly source: string; readonly blocks: readonly Block[] }
+
+export type Block =
+  | (NodeBase & { readonly type: 'paragraph'; readonly children: readonly Inline[] })
+  | (NodeBase & { readonly type: 'heading'; readonly level: 1 | 2 | 3 | 4 | 5 | 6; readonly children: readonly Inline[] })
+  | (NodeBase & { readonly type: 'quote'; readonly blocks: readonly Block[] })
+  | (NodeBase & { readonly type: 'list'; readonly ordered: boolean; readonly start: number; readonly loose: boolean; readonly items: readonly ListItem[] })
+  | (NodeBase & { readonly type: 'table'; readonly align: readonly ('left' | 'center' | 'right' | null)[]; readonly header: readonly TableCell[]; readonly rows: readonly (readonly TableCell[])[] })
+  | (NodeBase & { readonly type: 'code'; readonly language: string | null; readonly content: string; readonly fenced: boolean })
+  | (NodeBase & { readonly type: 'mermaid'; readonly content: string; readonly language: string })
+  | (NodeBase & { readonly type: 'rule' })
+  | (NodeBase & { readonly type: 'display-math'; readonly content: string; readonly open: '$$' | '\\['; readonly close: '$$' | '\\]' })
+  | (NodeBase & { readonly type: 'image'; readonly href: string; readonly alt: string; readonly title: string | null })
+  | (NodeBase & { readonly type: 'literal'; readonly text: string })
+
+export type ListItem = {
+  readonly task: boolean
+  readonly checked: boolean | null
+  readonly loose: boolean
+  readonly blocks: readonly Block[]
+  readonly source: SourceRange | null
+}
+
+export type UnitInfo =
+  | { readonly kind: 'block'; readonly block: Exclude<Block, { type: 'list' }>; readonly source: SourceRange | null }
+  | { readonly kind: 'list-item'; readonly item: ListItem; readonly source: SourceRange | null }
+
+export type TableCell = { readonly children: readonly Inline[]; readonly header: boolean; readonly align: 'left' | 'center' | 'right' | null }
+
+export type Inline =
+  | { readonly type: 'text' | 'code'; readonly text: string }
+  | { readonly type: 'strong' | 'em' | 'del'; readonly children: readonly Inline[] }
+  | { readonly type: 'link'; readonly href: string; readonly title: string | null; readonly children: readonly Inline[] }
+  | { readonly type: 'inline-image'; readonly href: string; readonly alt: string; readonly title: string | null }
+  | { readonly type: 'break'; readonly hard: boolean }
+  | { readonly type: 'math'; readonly content: string; readonly open: '$' | '\\('; readonly close: '$' | '\\)'; readonly raw: string }
+
+export function assertNever(value: never): never {
+  throw new Error(`Unexpected document node: ${String(value)}`)
+}

package/src/core/frame.ts

@@ -0,0 +1,144 @@
+import stringWidth from "string-width"
+
+// The frame is the chrome of the viewer: a window the document is drawn in. It
+// only ever constrains and decorates the area around the document; the document
+// itself stays anchored to the left edge of that area.
+export const frameAligns = ["left", "center", "right"] as const
+
+export type FrameAlign = (typeof frameAligns)[number]
+
+export function isFrameAlign(value: unknown): value is FrameAlign {
+  return typeof value === "string" && (frameAligns as readonly string[]).includes(value)
+}
+
+export const frameStyles = ["box", "ascii", "rounded", "heavy", "double"] as const
+
+// "box" is the bundled single-line window. "ascii" draws the same window with
+// `+ - |` for terminals and fonts where the Unicode box characters do not line
+// up. The rest are the native OpenTUI border sets.
+export type FrameStyle = (typeof frameStyles)[number]
+
+export function isFrameStyle(value: unknown): value is FrameStyle {
+  return typeof value === "string" && (frameStyles as readonly string[]).includes(value)
+}
+
+export type FrameConfig = {
+  // The frame is opt-in: without it the document uses the whole measured area,
+  // which is what an embedded host (a message bubble, a sidebar) wants.
+  readonly enabled?: boolean
+  // The width of the frame in terminal columns, border and padding included.
+  // Omitted means "as wide as the area allows".
+  readonly width?: number
+  // Where the frame sits when it is narrower than the area around it.
+  readonly align?: FrameAlign
+  readonly style?: FrameStyle
+  // Empty columns between the border and the document.
+  readonly paddingX?: number
+  // Empty rows between the border and the document.
+  readonly paddingY?: number
+  // A label carved out of the middle of the top border.
+  readonly title?: string
+  readonly titleAlign?: FrameAlign
+}
+
+export type FrameInsets = {
+  readonly left: number
+  readonly right: number
+  readonly top: number
+  readonly bottom: number
+}
+
+export type ResolvedFrame = {
+  readonly enabled: boolean
+  // The width every block of the document is laid out for. This is the single
+  // content width shared across the document.
+  readonly contentWidth: number
+  // The outer width, border and padding included.
+  readonly width: number
+  // The column the frame starts at inside the area around it.
+  readonly offsetX: number
+  readonly insets: FrameInsets
+  readonly align: FrameAlign
+  readonly style: FrameStyle
+  readonly paddingX: number
+  readonly paddingY: number
+  readonly title?: string
+  readonly titleAlign: FrameAlign
+}
+
+const borderWidth = 1
+const noInsets: FrameInsets = { left: 0, right: 0, top: 0, bottom: 0 }
+
+function whole(value: number | undefined, fallback: number) {
+  if (value === undefined) return fallback
+  if (!Number.isFinite(value)) return fallback
+  return Math.max(0, Math.floor(value))
+}
+
+function alignOffset(align: FrameAlign, available: number, width: number) {
+  if (align === "right") return Math.max(0, available - width)
+  if (align === "center") return Math.max(0, Math.floor((available - width) / 2))
+  return 0
+}
+
+// A title wider than the top border would be clipped by the terminal instead of
+// by us, so it is cut here where the layout knows the frame width.
+function fitTitle(title: string | undefined, columns: number) {
+  if (!title || columns <= 0) return undefined
+  let result = ""
+  for (const character of title) {
+    if (stringWidth(result + character) > columns) break
+    result += character
+  }
+  return result || undefined
+}
+
+// `resolveFrame` is the single place that turns the host's area width and the
+// frame configuration into the widths the renderer uses. It has no dependency on
+// OpenTUI or Solid, so a host can call it without mounting anything.
+export function resolveFrame(viewport: number, config?: FrameConfig): ResolvedFrame {
+  const available = Math.max(1, Math.floor(viewport) || 1)
+  const align = config?.align ?? "left"
+  const style = config?.style ?? "box"
+  const titleAlign = config?.titleAlign ?? "left"
+  const enabled = config?.enabled ?? false
+  if (!enabled) {
+    return {
+      enabled: false,
+      contentWidth: available,
+      width: available,
+      offsetX: 0,
+      insets: noInsets,
+      align,
+      style,
+      paddingX: 0,
+      paddingY: 0,
+      title: undefined,
+      titleAlign,
+    }
+  }
+  const paddingX = whole(config?.paddingX, 1)
+  const paddingY = whole(config?.paddingY, 0)
+  const insets: FrameInsets = {
+    left: borderWidth + paddingX,
+    right: borderWidth + paddingX,
+    top: borderWidth + paddingY,
+    bottom: borderWidth + paddingY,
+  }
+  const minWidth = insets.left + insets.right + 1
+  const width = config?.width === undefined ? available : Math.max(minWidth, Math.min(available, Math.floor(config.width)))
+  const contentWidth = Math.max(1, width - insets.left - insets.right)
+  return {
+    enabled: true,
+    contentWidth,
+    width,
+    offsetX: alignOffset(align, available, width),
+    insets,
+    align,
+    style,
+    paddingX,
+    paddingY,
+    title: fitTitle(config?.title, Math.max(0, width - borderWidth * 2 - 2)),
+    titleAlign,
+  }
+}

package/src/core/image.ts

@@ -0,0 +1,9 @@
+// Retained as a public helper for hosts validating a standalone image before
+// passing the Markdown to the renderer.
+export type MarkdownImage = { readonly alt: string; readonly href: string }
+
+export function standaloneImage(source: string): MarkdownImage | undefined {
+  const match = /^!\[([^\]]*)\]\((?:<([^>]+)>|([^\s)]+))\)\s*$/.exec(source.trim())
+  if (!match) return undefined
+  return { alt: match[1] ?? "", href: match[2] ?? match[3] ?? "" }
+}

package/src/core/index.ts

@@ -0,0 +1,6 @@
+export * from "./image"
+export * from "./frame"
+export * from "./layout"
+export * from "./tables"
+export * from "./document"
+export { parseDocument } from "./parse"

package/src/core/layout.ts

@@ -0,0 +1,27 @@
+import { resolveFrame, type FrameConfig, type ResolvedFrame } from "./frame"
+import { resolveTableOptions, type ResolvedTableOptions, type TablesConfig } from "./tables"
+
+export type DocumentLayoutInput = {
+  // The width the host gives the document, in terminal columns.
+  readonly viewport: number
+  readonly frame?: FrameConfig
+  readonly tables?: TablesConfig
+}
+
+// Everything a host needs to size the document without mounting the renderer.
+// The frame width and the content width are resolved together so no block can
+// disagree about where the right edge is.
+export type DocumentLayout = {
+  readonly frame: ResolvedFrame
+  readonly contentWidth: number
+  readonly tables: ResolvedTableOptions
+}
+
+export function createDocumentLayout(input: DocumentLayoutInput): DocumentLayout {
+  const frame = resolveFrame(input.viewport, input.frame)
+  return {
+    frame,
+    contentWidth: frame.contentWidth,
+    tables: resolveTableOptions(input.tables),
+  }
+}

package/src/core/math.ts

@@ -0,0 +1,170 @@
+import type { TokenizerAndRendererExtension } from "marked"
+
+export type MathInlineToken = {
+  type: "mathInline"
+  raw: string
+  text: string
+  content: string
+  open: "$" | "\\("
+  close: "$" | "\\)"
+}
+
+export type MathDisplayToken = {
+  type: "mathDisplay"
+  raw: string
+  text: string
+  content: string
+  open: "$$" | "\\["
+  close: "$$" | "\\]"
+}
+
+export type MathToken = MathInlineToken | MathDisplayToken
+
+function isEscaped(src: string, index: number): boolean {
+  let backslashes = 0
+  let i = index - 1
+  while (i >= 0 && src[i] === "\\") {
+    backslashes++
+    i--
+  }
+  return backslashes % 2 === 1
+}
+
+function closing(src: string, delimiter: string, start: number, singleLine: boolean): number {
+  for (let index = start; index < src.length; index++) {
+    if (singleLine && src[index] === "\n") break
+    if (src.startsWith(delimiter, index) && !isEscaped(src, index)) return index
+  }
+  return -1
+}
+
+export function createMathInlineExtension(): TokenizerAndRendererExtension {
+  return {
+    name: "mathInline",
+    level: "inline",
+    start(src: string) {
+      let i = 0
+      while (i < src.length) {
+        const ch = src[i]
+        if (ch === "\\") {
+          if (src[i + 1] === "(") {
+            if (!isEscaped(src, i)) return i
+          }
+          i += 2
+          continue
+        }
+        if (ch === "$") {
+          if (src[i + 1] === "$") {
+            i += 2
+            continue
+          }
+          if (!isEscaped(src, i)) return i
+        }
+        i++
+      }
+      return
+    },
+    tokenizer(src: string) {
+      // Try \(...\)
+      if (src.startsWith("\\(")) {
+        // look for \)
+        const end = closing(src, "\\)", 2, true)
+        if (end > 2 && src.slice(2, end).indexOf("\n") === -1) {
+          const content = src.slice(2, end)
+          const raw = src.slice(0, end + 2)
+          return {
+            type: "mathInline",
+            raw,
+            text: content,
+            content,
+            open: "\\(",
+            close: "\\)",
+          }
+        }
+      }
+      // Try single $
+      if (src[0] === "$" && src[1] !== "$") {
+        // find closing $ not escaped
+        let j = 1
+        while (j < src.length) {
+          if (src[j] === "\n") break
+          if (src[j] === "$" && !isEscaped(src, j)) {
+            if (j === 1) break // empty
+            const content = src.slice(1, j)
+            const raw = src.slice(0, j + 1)
+            return {
+              type: "mathInline",
+              raw,
+              text: content,
+              content,
+              open: "$",
+              close: "$",
+            }
+          }
+          j++
+        }
+      }
+      return
+    },
+  }
+}
+
+export function createMathDisplayExtension(): TokenizerAndRendererExtension {
+  return {
+    name: "mathDisplay",
+    level: "inline",
+    start(src: string) {
+      let i = 0
+      while (i < src.length) {
+        const ch = src[i]
+        if (ch === "\\") {
+          if (src[i + 1] === "[") {
+            if (!isEscaped(src, i)) return i
+          }
+          i += 2
+          continue
+        }
+        if (ch === "$") {
+          if (src[i + 1] === "$" && !isEscaped(src, i)) return i
+        }
+        i++
+      }
+      return
+    },
+    tokenizer(src: string) {
+      // $$...$$
+      if (src.startsWith("$$")) {
+        const end = closing(src, "$$", 2, false)
+        if (end > 2) {
+          const content = src.slice(2, end)
+          const raw = src.slice(0, end + 2)
+          return {
+            type: "mathDisplay",
+            raw,
+            text: content,
+            content,
+            open: "$$",
+            close: "$$",
+          }
+        }
+      }
+      // \[...\]
+      if (src.startsWith("\\[")) {
+        const end = closing(src, "\\]", 2, false)
+        if (end > 2) {
+          const content = src.slice(2, end)
+          const raw = src.slice(0, end + 2)
+          return {
+            type: "mathDisplay",
+            raw,
+            text: content,
+            content,
+            open: "\\[",
+            close: "\\]",
+          }
+        }
+      }
+      return
+    },
+  }
+}