@oh-my-pi/pi-utils 16.0.7 → 16.0.9

package/src/vendor/mermaid-ascii/ascii/shapes/stadium.ts

@@ -0,0 +1,114 @@
+// ============================================================================
+// Stadium (pill) shape renderer — special parentheses-based rendering
+// ============================================================================
+//
+// Stadium has unique rendering: single-line is inline `(Label)`, multi-line
+// uses parentheses or rounded corners. This differs from other shapes that
+// use corner decorators with box lines.
+
+import type { Canvas, DrawingCoord, Direction } from '../types'
+import { mkCanvas } from '../canvas'
+import { splitLines } from '../multiline-utils'
+import type { ShapeRenderer, ShapeDimensions, ShapeRenderOptions } from './types'
+import { getBoxAttachmentPoint } from './rectangle'
+import { displayWidth, toCells } from '../../text-metrics'
+
+/**
+ * Stadium (pill) shape renderer.
+ *
+ * Single-line:  ( Label )
+ *
+ * Multi-line unicode:
+ *   ╭──────────╮
+ *   │  Label   │
+ *   ╰──────────╯
+ *
+ * Multi-line ASCII:
+ *   (----------)
+ *   (  Label   )
+ *   (----------)
+ */
+export const stadiumRenderer: ShapeRenderer = {
+  getDimensions(label: string, options: ShapeRenderOptions): ShapeDimensions {
+    const lines = splitLines(label)
+    const maxLineWidth = Math.max(...lines.map(l => displayWidth(l)), 0)
+    const lineCount = lines.length
+
+    const innerWidth = 2 * options.padding + maxLineWidth
+    const width = innerWidth + 4  // Extra for rounded ends
+    const innerHeight = lineCount + 2 * options.padding
+    const height = Math.max(innerHeight + 2, 3)
+
+    return {
+      width,
+      height,
+      labelArea: {
+        x: 2 + options.padding,
+        y: 1 + options.padding,
+        width: maxLineWidth,
+        height: lineCount,
+      },
+      gridColumns: [2, innerWidth, 2],
+      gridRows: [1, innerHeight, 1],
+    }
+  },
+
+  render(label: string, dimensions: ShapeDimensions, options: ShapeRenderOptions): Canvas {
+    const { width, height } = dimensions
+    const canvas = mkCanvas(width - 1, height - 1)
+
+    const centerY = Math.floor(height / 2)
+    const hChar = options.useAscii ? '-' : '─'
+
+    if (height === 3) {
+      // Single row pill: (  Label  )
+      canvas[0]![centerY] = '('
+      canvas[width - 1]![centerY] = ')'
+    } else if (!options.useAscii) {
+      // Multi-row stadium with rounded corners (unicode)
+      canvas[0]![0] = '╭'
+      for (let x = 1; x < width - 1; x++) canvas[x]![0] = hChar
+      canvas[width - 1]![0] = '╮'
+
+      for (let y = 1; y < height - 1; y++) {
+        canvas[0]![y] = '│'
+        canvas[width - 1]![y] = '│'
+      }
+
+      canvas[0]![height - 1] = '╰'
+      for (let x = 1; x < width - 1; x++) canvas[x]![height - 1] = hChar
+      canvas[width - 1]![height - 1] = '╯'
+    } else {
+      // Multi-row stadium ASCII — parentheses on all sides
+      for (let y = 0; y < height; y++) {
+        canvas[0]![y] = '('
+        canvas[width - 1]![y] = ')'
+      }
+      for (let x = 1; x < width - 1; x++) {
+        canvas[x]![0] = hChar
+        canvas[x]![height - 1] = hChar
+      }
+    }
+
+    // Center the label
+    const lines = splitLines(label)
+    const startY = centerY - Math.floor((lines.length - 1) / 2)
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]!
+      const cells = toCells(line)
+      const textX = Math.floor(width / 2) - Math.floor(cells.length / 2)
+      for (let j = 0; j < cells.length; j++) {
+        const x = textX + j
+        const y = startY + i
+        if (x > 0 && x < width - 1 && y >= 0 && y < height) {
+          canvas[x]![y] = cells[j]!
+        }
+      }
+    }
+
+    return canvas
+  },
+
+  getAttachmentPoint: getBoxAttachmentPoint,
+}

package/src/vendor/mermaid-ascii/ascii/shapes/state.ts

@@ -0,0 +1,192 @@
+// ============================================================================
+// State pseudo-state renderers — UML start and end states
+// ============================================================================
+
+import type { Canvas, DrawingCoord, Direction } from '../types'
+import { Up, Down, Left, Right, UpperLeft, UpperRight, LowerLeft, LowerRight } from '../types'
+import { mkCanvas } from '../canvas'
+import type { ShapeRenderer, ShapeDimensions, ShapeRenderOptions } from './types'
+import { dirEquals } from '../edge-routing'
+
+/**
+ * State start pseudo-state renderer — filled circle in rounded box.
+ * Renders as:
+ *   ╭───╮
+ *   │ ● │   (Unicode)
+ *   ╰───╯
+ *
+ *   .---.
+ *   | * |   (ASCII)
+ *   '---'
+ *
+ * This represents the UML initial pseudo-state.
+ */
+export const stateStartRenderer: ShapeRenderer = {
+  getDimensions(_label: string, _options: ShapeRenderOptions): ShapeDimensions {
+    // Start state is a 5x3 rounded box with centered symbol
+    const width = 5
+    const height = 3
+
+    return {
+      width,
+      height,
+      labelArea: { x: 2, y: 1, width: 1, height: 1 },
+      gridColumns: [1, 3, 1],
+      gridRows: [1, 1, 1],
+    }
+  },
+
+  render(_label: string, dimensions: ShapeDimensions, options: ShapeRenderOptions): Canvas {
+    const { width, height } = dimensions
+    const canvas = mkCanvas(width - 1, height - 1)
+
+    const centerX = Math.floor(width / 2)  // = 2
+
+    if (!options.useAscii) {
+      // Unicode rounded box with filled circle: ╭───╮ │ ● │ ╰───╯
+      canvas[0]![0] = '╭'
+      canvas[1]![0] = '─'
+      canvas[2]![0] = '─'
+      canvas[3]![0] = '─'
+      canvas[4]![0] = '╮'
+
+      canvas[0]![1] = '│'
+      canvas[centerX]![1] = '●'
+      canvas[4]![1] = '│'
+
+      canvas[0]![2] = '╰'
+      canvas[1]![2] = '─'
+      canvas[2]![2] = '─'
+      canvas[3]![2] = '─'
+      canvas[4]![2] = '╯'
+    } else {
+      // ASCII rounded box: .---. | * | '---'
+      canvas[0]![0] = '.'
+      canvas[1]![0] = '-'
+      canvas[2]![0] = '-'
+      canvas[3]![0] = '-'
+      canvas[4]![0] = '.'
+
+      canvas[0]![1] = '|'
+      canvas[centerX]![1] = '*'
+      canvas[4]![1] = '|'
+
+      canvas[0]![2] = '\''
+      canvas[1]![2] = '-'
+      canvas[2]![2] = '-'
+      canvas[3]![2] = '-'
+      canvas[4]![2] = '\''
+    }
+
+    return canvas
+  },
+
+  getAttachmentPoint(
+    dir: Direction,
+    dimensions: ShapeDimensions,
+    baseCoord: DrawingCoord
+  ): DrawingCoord {
+    const { width, height } = dimensions
+    const centerX = baseCoord.x + Math.floor(width / 2)
+    const centerY = baseCoord.y + Math.floor(height / 2)
+
+    if (dirEquals(dir, Up)) return { x: centerX, y: baseCoord.y }
+    if (dirEquals(dir, Down)) return { x: centerX, y: baseCoord.y + height - 1 }
+    if (dirEquals(dir, Left)) return { x: baseCoord.x, y: centerY }
+    if (dirEquals(dir, Right)) return { x: baseCoord.x + width - 1, y: centerY }
+    // All diagonals and middle point to center
+    return { x: centerX, y: centerY }
+  },
+}
+
+/**
+ * State end pseudo-state renderer — bullseye in double-bordered box.
+ * Renders as:
+ *   ╔═══╗
+ *   ║ ◎ ║   (Unicode)
+ *   ╚═══╝
+ *
+ *   #===#
+ *   # * #   (ASCII)
+ *   #===#
+ *
+ * This represents the UML final state. The double border distinguishes it
+ * from the start state's single rounded border.
+ */
+export const stateEndRenderer: ShapeRenderer = {
+  getDimensions(_label: string, _options: ShapeRenderOptions): ShapeDimensions {
+    // End state is a 5x3 double-bordered box with centered symbol
+    const width = 5
+    const height = 3
+
+    return {
+      width,
+      height,
+      labelArea: { x: 2, y: 1, width: 1, height: 1 },
+      gridColumns: [1, 3, 1],
+      gridRows: [1, 1, 1],
+    }
+  },
+
+  render(_label: string, dimensions: ShapeDimensions, options: ShapeRenderOptions): Canvas {
+    const { width, height } = dimensions
+    const canvas = mkCanvas(width - 1, height - 1)
+
+    const centerX = Math.floor(width / 2)  // = 2
+
+    if (!options.useAscii) {
+      // Unicode double-bordered box with bullseye: ╔═══╗ ║ ◎ ║ ╚═══╝
+      canvas[0]![0] = '╔'
+      canvas[1]![0] = '═'
+      canvas[2]![0] = '═'
+      canvas[3]![0] = '═'
+      canvas[4]![0] = '╗'
+
+      canvas[0]![1] = '║'
+      canvas[centerX]![1] = '◎'
+      canvas[4]![1] = '║'
+
+      canvas[0]![2] = '╚'
+      canvas[1]![2] = '═'
+      canvas[2]![2] = '═'
+      canvas[3]![2] = '═'
+      canvas[4]![2] = '╝'
+    } else {
+      // ASCII double-bordered box: #===# # * # #===#
+      canvas[0]![0] = '#'
+      canvas[1]![0] = '='
+      canvas[2]![0] = '='
+      canvas[3]![0] = '='
+      canvas[4]![0] = '#'
+
+      canvas[0]![1] = '#'
+      canvas[centerX]![1] = '*'
+      canvas[4]![1] = '#'
+
+      canvas[0]![2] = '#'
+      canvas[1]![2] = '='
+      canvas[2]![2] = '='
+      canvas[3]![2] = '='
+      canvas[4]![2] = '#'
+    }
+
+    return canvas
+  },
+
+  getAttachmentPoint(
+    dir: Direction,
+    dimensions: ShapeDimensions,
+    baseCoord: DrawingCoord
+  ): DrawingCoord {
+    const { width, height } = dimensions
+    const centerX = baseCoord.x + Math.floor(width / 2)
+    const centerY = baseCoord.y + Math.floor(height / 2)
+
+    if (dirEquals(dir, Up)) return { x: centerX, y: baseCoord.y }
+    if (dirEquals(dir, Down)) return { x: centerX, y: baseCoord.y + height - 1 }
+    if (dirEquals(dir, Left)) return { x: baseCoord.x, y: centerY }
+    if (dirEquals(dir, Right)) return { x: baseCoord.x + width - 1, y: centerY }
+    // All diagonals and middle point to center
+    return { x: centerX, y: centerY }
+  },
+}

package/src/vendor/mermaid-ascii/ascii/shapes/types.ts

@@ -0,0 +1,73 @@
+// ============================================================================
+// Shape renderer types — interface for pluggable ASCII shape renderers
+// ============================================================================
+
+import type { Canvas, DrawingCoord, Direction, AsciiNodeShape } from '../types'
+
+/**
+ * Dimensions calculated for a shape, used by layout and rendering.
+ */
+export interface ShapeDimensions {
+  /** Total width in characters including borders */
+  width: number
+  /** Total height in characters including borders */
+  height: number
+  /** Label area bounds (where text can be placed) */
+  labelArea: {
+    x: number
+    y: number
+    width: number
+    height: number
+  }
+  /** Grid column widths for the 3-column layout [left, center, right] */
+  gridColumns: [number, number, number]
+  /** Grid row heights for the 3-row layout [top, middle, bottom] */
+  gridRows: [number, number, number]
+}
+
+/**
+ * Options passed to shape renderers.
+ */
+export interface ShapeRenderOptions {
+  /** Use ASCII chars (+,-,|) vs Unicode box-drawing (┌,─,│) */
+  useAscii: boolean
+  /** Padding inside the shape */
+  padding: number
+}
+
+/**
+ * Interface for pluggable shape renderers.
+ * Each shape type implements this interface.
+ */
+export interface ShapeRenderer {
+  /**
+   * Calculate dimensions for this shape given a label.
+   * Used during layout to determine node size.
+   */
+  getDimensions(label: string, options: ShapeRenderOptions): ShapeDimensions
+
+  /**
+   * Render the shape to a canvas.
+   * Returns a standalone canvas containing just the shape.
+   */
+  render(
+    label: string,
+    dimensions: ShapeDimensions,
+    options: ShapeRenderOptions
+  ): Canvas
+
+  /**
+   * Get the edge attachment point for a given direction.
+   * Used by edge routing to determine where edges connect.
+   */
+  getAttachmentPoint(
+    dir: Direction,
+    dimensions: ShapeDimensions,
+    baseCoord: DrawingCoord
+  ): DrawingCoord
+}
+
+/**
+ * Registry of shape renderers keyed by shape type.
+ */
+export type ShapeRegistry = Map<AsciiNodeShape, ShapeRenderer>

package/src/vendor/mermaid-ascii/ascii/types.ts

@@ -0,0 +1,273 @@
+// ============================================================================
+// ASCII renderer — type definitions
+//
+// Ported from AlexanderGrooff/mermaid-ascii (Go).
+// These types model the grid-based coordinate system, 2D text canvas,
+// and graph structures used by the ASCII/Unicode renderer.
+// ============================================================================
+
+import type { NodeShape } from '../types'
+
+// Re-export NodeShape for convenience
+export type { NodeShape }
+
+/**
+ * Shape type for ASCII rendering — maps parser shapes to ASCII renderers.
+ * Most shapes from the parser are supported, with fallback to 'rectangle'.
+ */
+export type AsciiNodeShape = NodeShape
+
+/** Logical grid coordinate — nodes occupy 3x3 blocks on this grid. */
+export interface GridCoord {
+  x: number
+  y: number
+}
+
+/** Character-level coordinate on the 2D text canvas. */
+export interface DrawingCoord {
+  x: number
+  y: number
+}
+
+/**
+ * Direction constants model positions on a node's 3x3 grid block.
+ * Each node occupies grid cells [x..x+2, y..y+2].
+ * Directions are offsets into that block, used for edge attachment points.
+ *
+ *   (0,0) UL   (1,0) Up   (2,0) UR
+ *   (0,1) Left (1,1) Mid  (2,1) Right
+ *   (0,2) LL   (1,2) Down (2,2) LR
+ */
+export interface Direction {
+  readonly x: number
+  readonly y: number
+}
+
+export const Up: Direction         = { x: 1, y: 0 }
+export const Down: Direction       = { x: 1, y: 2 }
+export const Left: Direction       = { x: 0, y: 1 }
+export const Right: Direction      = { x: 2, y: 1 }
+export const UpperRight: Direction = { x: 2, y: 0 }
+export const UpperLeft: Direction  = { x: 0, y: 0 }
+export const LowerRight: Direction = { x: 2, y: 2 }
+export const LowerLeft: Direction  = { x: 0, y: 2 }
+export const Middle: Direction     = { x: 1, y: 1 }
+
+/** All named directions for iteration. */
+export const ALL_DIRECTIONS: readonly Direction[] = [
+  Up, Down, Left, Right, UpperRight, UpperLeft, LowerRight, LowerLeft, Middle,
+]
+
+/**
+ * 2D text canvas — column-major (canvas[x][y]).
+ * Each cell holds a single character (or space).
+ */
+export type Canvas = string[][]
+
+/** A node in the ASCII graph, positioned on the grid. */
+export interface AsciiNode {
+  /** Unique identity key — the original node ID from the parser (e.g. "A", "B"). */
+  name: string
+  /** Human-readable label for rendering inside the box (e.g. "Web Server"). */
+  displayLabel: string
+  /** Node shape from the parser (e.g. "rectangle", "diamond", "circle"). */
+  shape: AsciiNodeShape
+  index: number
+  gridCoord: GridCoord | null
+  drawingCoord: DrawingCoord | null
+  drawing: Canvas | null
+  drawn: boolean
+  styleClassName: string
+  styleClass: AsciiStyleClass
+}
+
+/** Style class for colored node text (ported from Go's classDef). */
+export interface AsciiStyleClass {
+  name: string
+  styles: Record<string, string>
+}
+
+/** Edge line style for ASCII rendering. */
+export type AsciiEdgeStyle = 'solid' | 'dotted' | 'thick'
+
+/** An edge in the ASCII graph, with a routed path. */
+export interface AsciiEdge {
+  from: AsciiNode
+  to: AsciiNode
+  text: string
+  path: GridCoord[]
+  labelLine: GridCoord[]
+  startDir: Direction
+  endDir: Direction
+  /** Line style: solid (default), dotted (-.->) or thick (==>) */
+  style: AsciiEdgeStyle
+  /** Whether to render an arrowhead at the start (source end) of the edge */
+  hasArrowStart: boolean
+  /** Whether to render an arrowhead at the end (target end) of the edge */
+  hasArrowEnd: boolean
+  /** Bundle this edge belongs to (if any). Set during bundling analysis. */
+  bundle?: EdgeBundle
+  /**
+   * For bundled edges: path from source/target to the junction point.
+   * The full visual path is: pathToJunction + bundle.sharedPath (for fan-in)
+   * or bundle.sharedPath + pathToJunction (for fan-out).
+   */
+  pathToJunction?: GridCoord[]
+}
+
+/** A subgraph container with bounding box for rendering. */
+export interface AsciiSubgraph {
+  name: string
+  nodes: AsciiNode[]
+  parent: AsciiSubgraph | null
+  children: AsciiSubgraph[]
+  minX: number
+  minY: number
+  maxX: number
+  maxY: number
+  /** Optional direction override for layout within this subgraph (LR or TD). */
+  direction?: 'LR' | 'TD'
+}
+
+/** Configuration for ASCII rendering. */
+export interface AsciiConfig {
+  /** true = ASCII chars (+,-,|), false = Unicode box-drawing (┌,─,│). Default: false */
+  useAscii: boolean
+  /** Horizontal spacing between nodes. Default: 5 */
+  paddingX: number
+  /** Vertical spacing between nodes. Default: 5 */
+  paddingY: number
+  /** Padding inside node boxes. Default: 1 */
+  boxBorderPadding: number
+  /** Graph direction: "LR" or "TD". */
+  graphDirection: 'LR' | 'TD'
+}
+
+/** Full ASCII graph state used during layout and rendering. */
+export interface AsciiGraph {
+  nodes: AsciiNode[]
+  edges: AsciiEdge[]
+  canvas: Canvas
+  /** Role canvas — tracks the role of each character for colored output. */
+  roleCanvas: RoleCanvas
+  /** Grid occupancy map — maps "x,y" keys to node references. */
+  grid: Map<string, AsciiNode>
+  columnWidth: Map<number, number>
+  rowHeight: Map<number, number>
+  subgraphs: AsciiSubgraph[]
+  config: AsciiConfig
+  /** Offset applied to all drawing coords to accommodate subgraph borders. */
+  offsetX: number
+  offsetY: number
+  /** Edge bundles for parallel link visualization. Set during bundling analysis. */
+  bundles: EdgeBundle[]
+}
+
+// ============================================================================
+// Coordinate helpers
+// ============================================================================
+
+export function gridCoordEquals(a: GridCoord, b: GridCoord): boolean {
+  return a.x === b.x && a.y === b.y
+}
+
+export function drawingCoordEquals(a: DrawingCoord, b: DrawingCoord): boolean {
+  return a.x === b.x && a.y === b.y
+}
+
+/** Apply a direction offset to a grid coordinate (move into the 3x3 block). */
+export function gridCoordDirection(c: GridCoord, dir: Direction): GridCoord {
+  return { x: c.x + dir.x, y: c.y + dir.y }
+}
+
+/** Key for storing GridCoord in a Map. */
+export function gridKey(c: GridCoord): string {
+  return `${c.x},${c.y}`
+}
+
+/** Default empty style class. */
+export const EMPTY_STYLE: AsciiStyleClass = { name: '', styles: {} }
+
+// ============================================================================
+// Character role types for colored output
+// ============================================================================
+
+/**
+ * Role of a character in the ASCII diagram, used for theming.
+ * Each role maps to a different color when colors are enabled.
+ */
+export type CharRole =
+  | 'text'      // Node labels, edge labels
+  | 'border'    // Node box borders, subgraph borders
+  | 'line'      // Edge lines (paths between nodes)
+  | 'arrow'     // Arrowheads (▲▼◄► or ^v<>)
+  | 'corner'    // Corner characters at path bends
+  | 'junction'  // Junction characters (┬┴├┤ where edges meet boxes)
+
+/**
+ * Role canvas — parallel to Canvas, tracks the role of each character.
+ * Same column-major structure: roleCanvas[x][y] gives the role at (x, y).
+ * null means the character has no role (whitespace).
+ */
+export type RoleCanvas = (CharRole | null)[][]
+
+/**
+ * Theme colors for ASCII output — hex color strings.
+ * Derived from the SVG theme system for visual consistency.
+ */
+export interface AsciiTheme {
+  /** Text color (node labels, edge labels) */
+  fg: string
+  /** Box border color (node borders, subgraph borders) */
+  border: string
+  /** Edge line color (paths between nodes) */
+  line: string
+  /** Arrowhead color (▲▼◄► or ^v<>) */
+  arrow: string
+  /** Theme accent color (optional, used by xycharts for series 0) */
+  accent?: string
+  /** Background color (optional, used by xycharts for dark-mode-aware shading) */
+  bg?: string
+  /** Corner character color (optional, defaults to line) */
+  corner?: string
+  /** Junction character color (optional, defaults to border) */
+  junction?: string
+}
+
+/** Color mode for output. */
+export type ColorMode =
+  | 'none'      // No colors (plain text)
+  | 'ansi16'    // 16-color ANSI (basic terminals)
+  | 'ansi256'   // 256-color ANSI (xterm)
+  | 'truecolor' // 24-bit RGB (modern terminals)
+  | 'html'      // HTML <span> tags with inline color styles (browsers)
+
+// ============================================================================
+// Edge bundling types
+// ============================================================================
+
+/**
+ * Edge bundle — groups edges that share a common source or target.
+ * Used to visually merge parallel links before they reach the shared node.
+ *
+ * For fan-in (A & B --> C): multiple sources converge to one target.
+ * For fan-out (A --> B & C): one source diverges to multiple targets.
+ */
+export interface EdgeBundle {
+  /** Bundle type: fan-in = many→one, fan-out = one→many */
+  type: 'fan-in' | 'fan-out'
+  /** Edges in this bundle */
+  edges: AsciiEdge[]
+  /** The common node (target for fan-in, source for fan-out) */
+  sharedNode: AsciiNode
+  /** The non-shared nodes (sources for fan-in, targets for fan-out) */
+  otherNodes: AsciiNode[]
+  /** Junction point where edges merge/split — set during routing */
+  junctionPoint: GridCoord | null
+  /** Path from junction to shared node (drawn once for all edges) */
+  sharedPath: GridCoord[]
+  /** Direction when entering/exiting the junction */
+  junctionDir: Direction
+  /** Direction when entering/exiting the shared node */
+  sharedNodeDir: Direction
+}