@herb-tools/formatter 0.8.10 → 0.9.0

package/src/text-flow-engine.ts

@@ -0,0 +1,311 @@
+import { isNode, getTagName, isPureWhitespaceNode } from "@herb-tools/core"
+import { Node, HTMLTextNode, HTMLElementNode, ERBContentNode, WhitespaceNode } from "@herb-tools/core"
+
+import type { ContentUnitWithNode } from "./format-helpers.js"
+
+import {
+  ASCII_WHITESPACE,
+  buildLineWithWord,
+  countAdjacentInlineElements,
+  isClosingPunctuation,
+  isInlineElement,
+  isLineBreakingElement,
+  needsSpaceBetween,
+} from "./format-helpers.js"
+
+import {
+  collectTextFlowRun as collectTextFlowRunHelper,
+  isInTextFlowContext as isInTextFlowContextHelper,
+  isTextFlowNode as isTextFlowNodeHelper,
+  tryMergePunctuationText as tryMergePunctuationTextHelper,
+} from "./text-flow-helpers.js"
+
+import { TextFlowAnalyzer } from "./text-flow-analyzer.js"
+import type { TextFlowAnalyzerDelegate } from "./text-flow-analyzer.js"
+
+/**
+ * Interface that the FormatPrinter implements to provide
+ * rendering capabilities to the TextFlowEngine.
+ */
+export interface TextFlowDelegate extends TextFlowAnalyzerDelegate {
+  readonly indent: string
+  readonly maxLineLength: number
+
+  push(line: string): void
+  pushWithIndent(line: string): void
+  renderInlineElementAsString(element: HTMLElementNode): string
+  visit(node: Node): void
+}
+
+/**
+ * TextFlowEngine handles the formatting of mixed text + inline elements + ERB content.
+ *
+ * It orchestrates analysis (via TextFlowAnalyzer) and rendering phases:
+ * groups adjacent inline elements, and wraps words to fit within line length constraints.
+ */
+export class TextFlowEngine {
+  private analyzer: TextFlowAnalyzer
+
+  constructor(private delegate: TextFlowDelegate) {
+    this.analyzer = new TextFlowAnalyzer(delegate)
+  }
+
+  visitTextFlowChildren(children: Node[]): void {
+    const adjacentInlineCount = countAdjacentInlineElements(children)
+
+    if (adjacentInlineCount >= 2) {
+      const { processedIndices } = this.renderAdjacentInlineElements(children, adjacentInlineCount)
+      this.visitRemainingChildrenAsTextFlow(children, processedIndices)
+
+      return
+    }
+
+    this.buildAndWrapTextFlow(children)
+  }
+
+  isInTextFlowContext(children: Node[]): boolean {
+    return isInTextFlowContextHelper(children)
+  }
+
+  collectTextFlowRun(body: Node[], startIndex: number): { nodes: Node[], endIndex: number } | null {
+    return collectTextFlowRunHelper(body, startIndex)
+  }
+
+  isTextFlowNode(node: Node): boolean {
+    return isTextFlowNodeHelper(node)
+  }
+
+  private renderAdjacentInlineElements(children: Node[], count: number, startIndex = 0, alreadyProcessed?: Set<number>): { processedIndices: Set<number>; lastIndex: number } {
+    let inlineContent = ""
+    let processedCount = 0
+    let lastProcessedIndex = -1
+    const processedIndices = new Set<number>()
+
+    for (let index = startIndex; index < children.length && processedCount < count; index++) {
+      const child = children[index]
+
+      if (isPureWhitespaceNode(child) || isNode(child, WhitespaceNode)) {
+        continue
+      }
+
+      if (alreadyProcessed?.has(index)) {
+        continue
+      }
+
+      if (isNode(child, HTMLElementNode) && isInlineElement(getTagName(child))) {
+        inlineContent += this.delegate.renderInlineElementAsString(child)
+        processedCount++
+        lastProcessedIndex = index
+        processedIndices.add(index)
+
+        if (inlineContent && isLineBreakingElement(child)) {
+          this.delegate.pushWithIndent(inlineContent)
+          inlineContent = ""
+        }
+      } else if (isNode(child, ERBContentNode)) {
+        inlineContent += this.delegate.renderERBAsString(child)
+        processedCount++
+        lastProcessedIndex = index
+        processedIndices.add(index)
+      }
+    }
+
+    if (inlineContent && lastProcessedIndex >= 0) {
+      for (let index = lastProcessedIndex + 1; index < children.length; index++) {
+        const child = children[index]
+
+        if (isPureWhitespaceNode(child) || isNode(child, WhitespaceNode)) {
+          continue
+        }
+
+        if (alreadyProcessed?.has(index)) {
+          break
+        }
+
+        if (isNode(child, ERBContentNode)) {
+          inlineContent += this.delegate.renderERBAsString(child)
+          processedIndices.add(index)
+          lastProcessedIndex = index
+          continue
+        }
+
+        if (isNode(child, HTMLTextNode)) {
+          const trimmed = child.content.trim()
+
+          if (trimmed && /^[.!?:;%]/.test(trimmed)) {
+            const wrapWidth = this.delegate.maxLineLength - this.delegate.indent.length
+            const result = tryMergePunctuationTextHelper(inlineContent, trimmed, wrapWidth, this.delegate.indent)
+
+            inlineContent = result.mergedContent
+            processedIndices.add(index)
+            lastProcessedIndex = index
+
+            if (result.shouldStop) {
+              if (inlineContent) {
+                this.delegate.pushWithIndent(inlineContent)
+              }
+
+              result.wrappedLines.forEach(line => this.delegate.push(line))
+
+              return { processedIndices, lastIndex: lastProcessedIndex }
+            }
+          }
+        }
+
+        break
+      }
+    }
+
+    if (inlineContent) {
+      this.delegate.pushWithIndent(inlineContent)
+    }
+
+    return {
+      processedIndices,
+      lastIndex: lastProcessedIndex >= 0 ? lastProcessedIndex : startIndex + count - 1
+    }
+  }
+
+  private visitRemainingChildrenAsTextFlow(children: Node[], processedIndices: Set<number>): void {
+    let index = 0
+    let textFlowBuffer: Node[] = []
+
+    const flushTextFlow = () => {
+      if (textFlowBuffer.length > 0) {
+        this.buildAndWrapTextFlow(textFlowBuffer)
+        textFlowBuffer = []
+      }
+    }
+
+    while (index < children.length) {
+      const child = children[index]
+
+      if (processedIndices.has(index)) {
+        index++
+        continue
+      }
+
+      if (isPureWhitespaceNode(child) || isNode(child, WhitespaceNode)) {
+        textFlowBuffer.push(child)
+        index++
+        continue
+      }
+
+      const adjacentCount = countAdjacentInlineElements(children, index, processedIndices)
+
+      if (adjacentCount >= 2) {
+        flushTextFlow()
+
+        const { processedIndices: newProcessedIndices, lastIndex } =
+          this.renderAdjacentInlineElements(children, adjacentCount, index, processedIndices)
+
+        newProcessedIndices.forEach(i => processedIndices.add(i))
+        index = lastIndex + 1
+      } else {
+        textFlowBuffer.push(child)
+        index++
+      }
+    }
+
+    flushTextFlow()
+  }
+
+  private buildAndWrapTextFlow(children: Node[]): void {
+    const unitsWithNodes: ContentUnitWithNode[] = this.analyzer.buildContentUnits(children)
+    const words: Array<{ word: string, isHerbDisable: boolean }> = []
+
+    for (const { unit, node } of unitsWithNodes) {
+      if (unit.breaksFlow) {
+        this.flushWords(words)
+
+        if (node) {
+          this.delegate.visit(node)
+        }
+      } else if (unit.isAtomic) {
+        words.push({ word: unit.content, isHerbDisable: unit.isHerbDisable || false })
+      } else {
+        const text = unit.content.replace(ASCII_WHITESPACE, ' ')
+        const hasLeadingSpace = text.startsWith(' ')
+        const hasTrailingSpace = text.endsWith(' ')
+        const trimmedText = text.trim()
+
+        if (trimmedText) {
+          if (hasLeadingSpace && words.length > 0) {
+            const lastWord = words[words.length - 1]
+
+            if (!lastWord.word.endsWith(' ')) {
+              lastWord.word += ' '
+            }
+          }
+
+          const textWords = trimmedText.split(' ').map(w => ({ word: w, isHerbDisable: false }))
+          words.push(...textWords)
+
+          if (hasTrailingSpace && words.length > 0) {
+            const lastWord = words[words.length - 1]
+
+            if (!isClosingPunctuation(lastWord.word)) {
+              lastWord.word += ' '
+            }
+          }
+        } else if (text === ' ' && words.length > 0) {
+          const lastWord = words[words.length - 1]
+
+          if (!lastWord.word.endsWith(' ')) {
+            lastWord.word += ' '
+          }
+        }
+      }
+    }
+
+    // Trim trailing space from last word before final flush - trailing spaces are
+    // informational for spacing with subsequent words but shouldn't inflate
+    // effective length when it's the final word (it gets trimmed from output anyway)
+    if (words.length > 0) {
+      words[words.length - 1].word = words[words.length - 1].word.trimEnd()
+    }
+
+    this.flushWords(words)
+  }
+
+  private flushWords(words: Array<{ word: string, isHerbDisable: boolean }>): void {
+    if (words.length > 0) {
+      this.wrapAndPushWords(words)
+      words.length = 0
+    }
+  }
+
+  private wrapAndPushWords(words: Array<{ word: string, isHerbDisable: boolean }>): void {
+    const wrapWidth = this.delegate.maxLineLength - this.delegate.indent.length
+    const lines: string[] = []
+    let currentLine = ""
+    let effectiveLength = 0
+
+    for (const { word, isHerbDisable } of words) {
+      const nextLine = buildLineWithWord(currentLine, word)
+
+      let nextEffectiveLength = effectiveLength
+
+      if (!isHerbDisable) {
+        const spaceBefore = currentLine && needsSpaceBetween(currentLine, word) ? 1 : 0
+        nextEffectiveLength = effectiveLength + spaceBefore + word.length
+      }
+
+      if (currentLine && !isClosingPunctuation(word) && nextEffectiveLength > wrapWidth) {
+        lines.push(this.delegate.indent + currentLine.trim())
+
+        currentLine = word
+        effectiveLength = isHerbDisable ? 0 : word.length
+      } else {
+        currentLine = nextLine
+        effectiveLength = nextEffectiveLength
+      }
+    }
+
+    if (currentLine) {
+      lines.push(this.delegate.indent + currentLine.trim())
+    }
+
+    lines.forEach(line => this.delegate.push(line))
+  }
+}

package/src/text-flow-helpers.ts

@@ -0,0 +1,319 @@
+import { isNode, getTagName } from "@herb-tools/core"
+import { Node, HTMLTextNode, HTMLElementNode, ERBContentNode, WhitespaceNode } from "@herb-tools/core"
+
+import type { ContentUnitWithNode } from "./format-helpers.js"
+
+import {
+  endsWithWhitespace,
+  hasWhitespaceBetween,
+  isInlineElement,
+  normalizeAndSplitWords,
+} from "./format-helpers.js"
+
+
+/**
+ * Check if a node participates in text flow
+ */
+export function isTextFlowNode(node: Node): boolean {
+  if (isNode(node, ERBContentNode)) return true
+  if (isNode(node, HTMLTextNode) && node.content.trim() !== "") return true
+  if (isNode(node, HTMLElementNode) && isInlineElement(getTagName(node))) return true
+
+  return false
+}
+
+/**
+ * Check if a node is whitespace that can appear within a text flow run
+ */
+export function isTextFlowWhitespace(node: Node): boolean {
+  if (isNode(node, WhitespaceNode)) return true
+  if (isNode(node, HTMLTextNode) && node.content.trim() === "" && !node.content.includes('\n\n')) return true
+
+  return false
+}
+
+/**
+ * Collect a run of text flow nodes starting at the given index.
+ * Returns the nodes in the run and the index after the last node.
+ * Returns null if the run doesn't qualify (needs 2+ text flow nodes with both text and atomic content).
+ */
+export function collectTextFlowRun(body: Node[], startIndex: number): { nodes: Node[], endIndex: number } | null {
+  const nodes: Node[] = []
+  let index = startIndex
+  let textFlowCount = 0
+
+  while (index < body.length) {
+    const child = body[index]
+
+    if (isTextFlowNode(child)) {
+      nodes.push(child)
+      textFlowCount++
+      index++
+    } else if (isTextFlowWhitespace(child)) {
+      let hasMoreTextFlow = false
+
+      for (let lookaheadIndex = index + 1; lookaheadIndex < body.length; lookaheadIndex++) {
+        if (isTextFlowNode(body[lookaheadIndex])) {
+          hasMoreTextFlow = true
+          break
+        }
+
+        if (isTextFlowWhitespace(body[lookaheadIndex])) {
+          continue
+        }
+
+        break
+      }
+
+      if (hasMoreTextFlow) {
+        nodes.push(child)
+        index++
+      } else {
+        break
+      }
+    } else {
+      break
+    }
+  }
+
+  if (textFlowCount >= 2) {
+    const hasText = nodes.some(node => isNode(node, HTMLTextNode) && node.content.trim() !== "")
+    const hasAtomicContent = nodes.some(node => isNode(node, ERBContentNode) || (isNode(node, HTMLElementNode) && isInlineElement(getTagName(node))))
+
+    if (hasText && hasAtomicContent) {
+      return { nodes, endIndex: index }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Check if children represent a text flow context
+ * (has text content mixed with inline elements or ERB)
+ */
+export function isInTextFlowContext(children: Node[]): boolean {
+  const hasTextContent = children.some(child => isNode(child, HTMLTextNode) && child.content.trim() !== "")
+  const nonTextChildren = children.filter(child => !isNode(child, HTMLTextNode))
+
+  if (!hasTextContent) return false
+  if (nonTextChildren.length === 0) return false
+
+  const allInline = nonTextChildren.every(child => {
+    if (isNode(child, ERBContentNode)) return true
+
+    if (isNode(child, HTMLElementNode)) {
+      return isInlineElement(getTagName(child))
+    }
+
+    return false
+  })
+
+  if (!allInline) return false
+
+  return true
+}
+
+/**
+ * Try to merge text that follows an atomic unit (ERB/inline) with no whitespace.
+ * Merges the first word of the text into the preceding atomic unit.
+ * Returns true if merge was performed.
+ */
+export function tryMergeTextAfterAtomic(result: ContentUnitWithNode[], textNode: HTMLTextNode): boolean {
+  if (result.length === 0) return false
+
+  const lastUnit = result[result.length - 1]
+
+  if (!lastUnit.unit.isAtomic || (lastUnit.unit.type !== 'erb' && lastUnit.unit.type !== 'inline')) {
+    return false
+  }
+
+  const words = normalizeAndSplitWords(textNode.content)
+  if (words.length === 0 || !words[0]) return false
+
+  const firstWord = words[0]
+  const firstChar = firstWord[0]
+
+  if (' \t\n\r'.includes(firstChar)) {
+    return false
+  }
+
+  lastUnit.unit.content += firstWord
+
+  if (words.length > 1) {
+    let remainingText = words.slice(1).join(' ')
+
+    if (endsWithWhitespace(textNode.content)) {
+      remainingText += ' '
+    }
+
+    result.push({
+      unit: { content: remainingText, type: 'text', isAtomic: false, breaksFlow: false },
+      node: textNode
+    })
+  } else if (endsWithWhitespace(textNode.content)) {
+    result.push({
+      unit: { content: ' ', type: 'text', isAtomic: false, breaksFlow: false },
+      node: textNode
+    })
+  }
+
+  return true
+}
+
+/**
+ * Try to merge an atomic unit (ERB/inline) with preceding text that has no whitespace.
+ * Splits preceding text, merges last word with atomic content.
+ * Returns true if merge was performed.
+ */
+export function tryMergeAtomicAfterText(result: ContentUnitWithNode[], children: Node[], lastProcessedIndex: number, atomicContent: string, atomicType: 'erb' | 'inline', atomicNode: Node): boolean {
+  if (result.length === 0) return false
+
+  const lastUnit = result[result.length - 1]
+  if (lastUnit.unit.type !== 'text' || lastUnit.unit.isAtomic) return false
+
+  const words = normalizeAndSplitWords(lastUnit.unit.content)
+  const lastWord = words[words.length - 1]
+  if (!lastWord) return false
+
+  result.pop()
+
+  if (words.length > 1) {
+    const remainingText = words.slice(0, -1).join(' ')
+
+    result.push({
+      unit: { content: remainingText, type: 'text', isAtomic: false, breaksFlow: false },
+      node: children[lastProcessedIndex]
+    })
+  }
+
+  result.push({
+    unit: { content: lastWord + atomicContent, type: atomicType, isAtomic: true, breaksFlow: false },
+    node: atomicNode
+  })
+
+  return true
+}
+
+/**
+ * Check if there's whitespace between current node and last processed node
+ */
+export function hasWhitespaceBeforeNode(children: Node[], lastProcessedIndex: number, currentIndex: number, currentNode: Node): boolean {
+  if (hasWhitespaceBetween(children, lastProcessedIndex, currentIndex)) {
+    return true
+  }
+
+  if (isNode(currentNode, HTMLTextNode) && /^[ \t\n\r]/.test(currentNode.content)) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Check if last unit in result ends with whitespace
+ */
+export function lastUnitEndsWithWhitespace(result: ContentUnitWithNode[]): boolean {
+  if (result.length === 0) return false
+
+  const lastUnit = result[result.length - 1]
+
+  return lastUnit.unit.type === 'text' && endsWithWhitespace(lastUnit.unit.content)
+}
+
+/**
+ * Wrap remaining words that don't fit on the current line.
+ * Returns the wrapped lines with proper indentation.
+ */
+export function wrapRemainingWords(words: string[], wrapWidth: number, indent: string): string[] {
+  const lines: string[] = []
+  let line = ""
+
+  for (const word of words) {
+    const testLine = line + (line ? " " : "") + word
+
+    if (testLine.length > wrapWidth && line) {
+      lines.push(indent + line)
+      line = word
+    } else {
+      line = testLine
+    }
+  }
+
+  if (line) {
+    lines.push(indent + line)
+  }
+
+  return lines
+}
+
+/**
+ * Try to merge text starting with punctuation to inline content.
+ * Returns object with merged content and whether processing should stop.
+ */
+export function tryMergePunctuationText(inlineContent: string, trimmedText: string, wrapWidth: number, indent: string): { mergedContent: string, shouldStop: boolean, wrappedLines: string[] } {
+  const combined = inlineContent + trimmedText
+
+  if (combined.length <= wrapWidth) {
+    return {
+      mergedContent: inlineContent + trimmedText,
+      shouldStop: false,
+      wrappedLines: []
+    }
+  }
+
+  const match = trimmedText.match(/^[.!?:;%]+/)
+
+  if (!match) {
+    return {
+      mergedContent: inlineContent,
+      shouldStop: false,
+      wrappedLines: []
+    }
+  }
+
+  const punctuation = match[0]
+  const restText = trimmedText.substring(punctuation.length).trim()
+
+  if (!restText) {
+    return {
+      mergedContent: inlineContent + punctuation,
+      shouldStop: false,
+      wrappedLines: []
+    }
+  }
+
+  const words = restText.split(/[ \t\n\r]+/)
+  let toMerge = punctuation
+  let mergedWordCount = 0
+
+  for (const word of words) {
+    const testMerge = toMerge + ' ' + word
+
+    if ((inlineContent + testMerge).length <= wrapWidth) {
+      toMerge = testMerge
+      mergedWordCount++
+    } else {
+      break
+    }
+  }
+
+  const mergedContent = inlineContent + toMerge
+
+  if (mergedWordCount >= words.length) {
+    return {
+      mergedContent,
+      shouldStop: false,
+      wrappedLines: []
+    }
+  }
+
+  const remainingWords = words.slice(mergedWordCount)
+  const wrappedLines = wrapRemainingWords(remainingWords, wrapWidth, indent)
+
+  return {
+    mergedContent,
+    shouldStop: true,
+    wrappedLines
+  }
+}