coradoc 1.1.7 → 2.0.1

data/coradoc-html/lib/coradoc/html.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+# Load HTML input module to register with Coradoc::Input
+require 'coradoc/html/input'
+# Load HTML output module to register with Coradoc::Output
+require 'coradoc/html/output'
+
+module Coradoc
+  module Html
+    # Register HTML format with coradoc when loaded
+    def self.register_with_coradoc
+      return if @registered
+
+      # Register with the main coradoc registry
+      Coradoc.register_format(:html, self,
+                              aliases: %w[html htm],
+                              extensions: %w[.html .htm]) if Coradoc.respond_to?(:register_format)
+
+      @registered = true
+    end
+
+    # Call registration when this module is included/required
+    register_with_coradoc
+
+    module Converters
+      # Autoload HTML converters - they will be loaded when accessed
+      autoload :Base, 'coradoc/html/converters/base'
+      autoload :Admonition, 'coradoc/html/converters/admonition'
+      autoload :AttributeReference, 'coradoc/html/converters/attribute_reference'
+      autoload :Attribute, 'coradoc/html/converters/attribute'
+      autoload :Audio, 'coradoc/html/converters/audio'
+      autoload :BibliographyEntry, 'coradoc/html/converters/bibliography_entry'
+      autoload :Bibliography, 'coradoc/html/converters/bibliography'
+      autoload :BlockImage, 'coradoc/html/converters/block_image'
+      autoload :Bold, 'coradoc/html/converters/bold'
+      autoload :Break, 'coradoc/html/converters/break'
+      autoload :CommentBlock, 'coradoc/html/converters/comment_block'
+      autoload :CommentLine, 'coradoc/html/converters/comment_line'
+      autoload :CrossReference, 'coradoc/html/converters/cross_reference'
+      autoload :Document, 'coradoc/html/converters/document'
+      autoload :Example, 'coradoc/html/converters/example'
+      autoload :Highlight, 'coradoc/html/converters/highlight'
+      autoload :Include, 'coradoc/html/converters/include'
+      autoload :InlineImage, 'coradoc/html/converters/inline_image'
+      autoload :Italic, 'coradoc/html/converters/italic'
+      autoload :LineBreak, 'coradoc/html/converters/line_break'
+      autoload :Link, 'coradoc/html/converters/link'
+      autoload :ListItem, 'coradoc/html/converters/list_item'
+      autoload :Listing, 'coradoc/html/converters/listing'
+      autoload :Literal, 'coradoc/html/converters/literal'
+      autoload :Monospace, 'coradoc/html/converters/monospace'
+      autoload :Ordered, 'coradoc/html/converters/ordered'
+      autoload :Open, 'coradoc/html/converters/open'
+      autoload :Paragraph, 'coradoc/html/converters/paragraph'
+      autoload :Quote, 'coradoc/html/converters/quote'
+      autoload :ReviewerComment, 'coradoc/html/converters/reviewer_comment'
+      autoload :ReviewerNote, 'coradoc/html/converters/reviewer_note'
+      autoload :Section, 'coradoc/html/converters/section'
+      autoload :Sidebar, 'coradoc/html/converters/sidebar'
+      autoload :Source, 'coradoc/html/converters/source'
+      autoload :SourceCode, 'coradoc/html/converters/source_code'
+      autoload :Span, 'coradoc/html/converters/span'
+      autoload :Strikethrough, 'coradoc/html/converters/strikethrough'
+      autoload :Subscript, 'coradoc/html/converters/subscript'
+      autoload :Superscript, 'coradoc/html/converters/superscript'
+      autoload :TableCell, 'coradoc/html/converters/table_cell'
+      autoload :TableRow, 'coradoc/html/converters/table_row'
+      autoload :Table, 'coradoc/html/converters/table'
+      autoload :Term, 'coradoc/html/converters/term'
+      autoload :TextElement, 'coradoc/html/converters/text_element'
+      autoload :Underline, 'coradoc/html/converters/underline'
+      autoload :Unordered, 'coradoc/html/converters/unordered'
+      autoload :Verse, 'coradoc/html/converters/verse'
+      autoload :Video, 'coradoc/html/converters/video'
+    end
+
+    # Autoload HTML components
+    autoload :Config, 'coradoc/html/config'
+    autoload :Base, 'coradoc/html/base'
+    autoload :Entity, 'coradoc/html/entity'
+    autoload :ElementMapping, 'coradoc/html/element_mapping'
+
+    # Autoload HTML output converters
+    autoload :ConverterBase, 'coradoc/html/converter_base'
+    autoload :Static, 'coradoc/html/static'
+    autoload :Spa, 'coradoc/html/spa'
+
+    # Theme system
+    autoload :Theme, 'coradoc/html/theme'
+    autoload :TemplateLocator, 'coradoc/html/template_locator'
+    autoload :TemplateConfig, 'coradoc/html/template_config'
+    autoload :TemplateHelpers, 'coradoc/html/template_helpers'
+    autoload :Renderer, 'coradoc/html/renderer'
+
+    # CoreModel transformers
+    module Transform
+      autoload :ToCoreModel, 'coradoc/html/transform/to_core_model'
+      autoload :FromCoreModel, 'coradoc/html/transform/from_core_model'
+    end
+
+    # Validate that input is a CoreModel type
+    #
+    # @param document [Object] Document to validate
+    # @raise [ArgumentError] If document is not a CoreModel type
+    # @return [Object] The validated document
+    def self.validate_core_model!(document)
+      return document if document.nil?
+
+      unless document.is_a?(Coradoc::CoreModel::Base)
+        raise ArgumentError,
+              'coradoc-html only accepts CoreModel types. ' \
+              "Got: #{document.class}. " \
+              'Transform your document to CoreModel before passing to HTML conversion.'
+      end
+
+      document
+    end
+
+    # Parse HTML content and return CoreModel elements (may be an Array)
+    def self.parse(html, options = {})
+      # Input::Html is autoloaded via Coradoc::Input
+      ::Coradoc::Html::Input.to_coradoc(html, options)
+    end
+
+    # Parse HTML content directly into a CoreModel document
+    #
+    # Unlike #parse which returns an Array of CoreModel elements,
+    # this wraps the result into a top-level StructuralElement document
+    # suitable for use with Coradoc.serialize and other CoreModel pipelines.
+    #
+    # @param html [String] HTML content
+    # @param options [Hash] Parse options
+    # @return [Coradoc::CoreModel::StructuralElement] CoreModel document
+    def self.parse_to_core(html, options = {})
+      elements = parse(html, options)
+
+      return elements if elements.is_a?(Coradoc::CoreModel::Base)
+
+      # Extract document title from the first heading element
+      title = nil
+      children = elements
+      if elements.is_a?(Array) && !elements.empty?
+        first = elements.first
+        if first.is_a?(Coradoc::CoreModel::StructuralElement) &&
+           first.section? && first.level == 1
+          title = first.title
+          children = first.children + elements[1..]
+        end
+      end
+
+      Coradoc::CoreModel::StructuralElement.new(
+        element_type: 'document',
+        title: title,
+        children: Array(children)
+      )
+    end
+
+    # Parse HTML file
+    def self.from_file(filename, **options)
+      content = File.read(filename)
+      parse(content, **options)
+    end
+
+    # Serialize CoreModel document to HTML
+    #
+    # Uses the theme system to render HTML. Default theme is :classic.
+    #
+    # @param document [Coradoc::CoreModel::Base] CoreModel document to serialize
+    # @param options [Hash] Output options
+    # @return [String] HTML output
+    def self.serialize(document, options = {})
+      # Validate input is CoreModel
+      validate_core_model!(document)
+
+      # Trigger theme autoloads to ensure renderers are registered
+      Theme::ClassicRenderer if options[:theme].nil? || options[:theme] == :classic
+      Theme::ModernRenderer if options[:theme] == :modern
+
+      # Use theme registry to find and use the appropriate renderer
+      theme = options[:theme] || :classic
+      renderer_class = Theme::Registry.find(theme)
+      renderer = renderer_class.new(document, options)
+      renderer.render_html5
+    end
+
+    # Serialize CoreModel document to static HTML
+    #
+    # Uses the classic theme renderer for traditional HTML output.
+    #
+    # @param document [Coradoc::CoreModel::Base] CoreModel document to serialize
+    # @param config [Hash, Static::Configuration] Static converter configuration
+    # @return [String] HTML output
+    def self.serialize_static(document, config = {})
+      # Validate input is CoreModel
+      validate_core_model!(document)
+
+      Static.convert(document, config)
+    end
+
+    # Serialize CoreModel document to SPA HTML
+    #
+    # Uses the modern theme renderer for Vue.js + Tailwind output.
+    #
+    # @param document [Coradoc::CoreModel::Base] CoreModel document to serialize
+    # @param config [Hash, Spa::Configuration] SPA converter configuration
+    # @return [String] HTML output
+    def self.serialize_spa(document, config = {})
+      # Validate input is CoreModel
+      validate_core_model!(document)
+
+      Spa.convert(document, config)
+    end
+
+    # Serialize CoreModel document to HTML with specified format
+    #
+    # @param document [Coradoc::CoreModel::Base] CoreModel document to serialize
+    # @param format [Symbol] Output format (:static, :spa, :classic)
+    # @param options [Hash] Converter options
+    # @return [String] HTML output
+    def self.serialize_as(document, format, options = {})
+      # Validate input is CoreModel
+      validate_core_model!(document)
+
+      case format.to_sym
+      when :static, :html_static, :classic
+        serialize_static(document, options)
+      when :spa, :html_spa, :modern
+        serialize_spa(document, options)
+      else
+        raise ArgumentError, "Unknown output format: #{format}. " \
+          'Valid formats: :static, :spa'
+      end
+    end
+
+    # Transform HTML model to CoreModel
+    #
+    # @param document [Object] HTML input model
+    # @return [Coradoc::CoreModel::Base] CoreModel document
+    def self.to_core_model(document)
+      Transform::ToCoreModel.transform(document)
+    end
+
+    # Check if this format can transform the given model to CoreModel
+    #
+    # HTML produces CoreModel directly, so it only handles already-CoreModel objects.
+    #
+    # @param model [Object] The model to check
+    # @return [Boolean] true if the model is already CoreModel
+    def self.handles_model?(model)
+      model.is_a?(Coradoc::CoreModel::Base)
+    end
+
+    def self.to_core(document)
+      to_core_model(document)
+    end
+
+    # Transform CoreModel to HTML-ready structure
+    #
+    # @param core_document [Coradoc::CoreModel::Base] CoreModel document
+    # @return [Object] HTML-ready structure
+    def self.from_core_model(core_document)
+      Transform::FromCoreModel.transform(core_document)
+    end
+  end
+end

data/coradoc-html/spec/coradoc/html/converter_base_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'tempfile'
+
+RSpec.describe Coradoc::Html::ConverterBase do
+  let(:document) { Coradoc::CoreModel::StructuralElement.new(element_type: 'document') }
+
+  describe '.new' do
+    it 'accepts a document' do
+      converter = described_class.new(document)
+      expect(converter.document).to eq(document)
+    end
+
+    it 'accepts configuration options' do
+      converter = described_class.new(document, { key: 'value' })
+      expect(converter.config).to eq({ key: 'value' })
+    end
+
+    it 'raises error for invalid document type' do
+      expect do
+        described_class.new('not a document')
+      end.to raise_error(Coradoc::Html::ConverterBase::UnsupportedDocumentError)
+    end
+  end
+
+  describe '#convert' do
+    it 'raises NotImplementedError' do
+      converter = described_class.new(document)
+      expect do
+        converter.convert
+      end.to raise_error(NotImplementedError, /must implement #convert/)
+    end
+  end
+
+  describe '#converter_name' do
+    it 'returns the converter name' do
+      converter = described_class.new(document)
+      expect(converter.converter_name).to eq(:converter_base)
+    end
+  end
+
+  describe '.convert' do
+    it 'creates instance and calls convert' do
+      # Create a test subclass that implements convert
+      test_class = Class.new(described_class) do
+        def convert
+          '<html>test</html>'
+        end
+      end
+
+      result = test_class.convert(document)
+      expect(result).to eq('<html>test</html>')
+    end
+  end
+
+  describe '.to_file' do
+    it 'writes output to file' do
+      test_class = Class.new(described_class) do
+        def convert
+          '<html>test</html>'
+        end
+      end
+
+      Tempfile.create(['test', '.html']) do |file|
+        path = file.path
+        file.close
+
+        test_class.to_file(document, path)
+        expect(File.read(path)).to eq('<html>test</html>')
+      end
+    end
+
+    it 'creates parent directories' do
+      test_class = Class.new(described_class) do
+        def convert
+          '<html>test</html>'
+        end
+      end
+
+      Dir.mktmpdir do |dir|
+        output_path = File.join(dir, 'subdir', 'test.html')
+
+        test_class.to_file(document, output_path)
+        expect(File.exist?(output_path)).to be true
+        expect(File.read(output_path)).to eq('<html>test</html>')
+      end
+    end
+  end
+
+  describe Coradoc::Html::ConverterBase::ValidationError do
+    it 'is a StandardError' do
+      expect(described_class).to be < StandardError
+    end
+  end
+
+  describe Coradoc::Html::ConverterBase::UnsupportedDocumentError do
+    it 'is a StandardError' do
+      expect(described_class).to be < StandardError
+    end
+  end
+end

data/coradoc-html/spec/coradoc/html/converters/annotation_block_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'coradoc/html'
+require 'coradoc/core_model'
+
+RSpec.describe 'AnnotationBlock HTML conversion' do
+  describe 'dispatch ordering' do
+    it 'routes AnnotationBlock to render_core_annotation_block, not render_core_block' do
+      annotation = Coradoc::CoreModel::AnnotationBlock.new(
+        annotation_type: 'note',
+        content: 'Important detail'
+      )
+
+      html = Coradoc::Html::Converters::Base.convert_content_to_html(annotation)
+
+      # AnnotationBlock should produce admonition markup, not a plain <p>
+      expect(html).to include('admonition')
+      expect(html).to include('note')
+      expect(html).to include('Important detail')
+    end
+  end
+
+  describe 'render_core_annotation_block' do
+    it 'renders NOTE with type class and uppercase label' do
+      annotation = Coradoc::CoreModel::AnnotationBlock.new(
+        annotation_type: 'note',
+        content: 'This is a note'
+      )
+
+      html = Coradoc::Html::Converters::Base.convert_content_to_html(annotation)
+
+      expect(html).to include('class="admonition note"')
+      expect(html).to include('admonition-label')
+      expect(html).to include('NOTE')
+      expect(html).to include('This is a note')
+    end
+
+    it 'renders WARNING annotation' do
+      annotation = Coradoc::CoreModel::AnnotationBlock.new(
+        annotation_type: 'warning',
+        content: 'Danger ahead'
+      )
+
+      html = Coradoc::Html::Converters::Base.convert_content_to_html(annotation)
+
+      expect(html).to include('class="admonition warning"')
+      expect(html).to include('WARNING')
+    end
+
+    it 'renders annotation with custom label' do
+      annotation = Coradoc::CoreModel::AnnotationBlock.new(
+        annotation_type: 'reviewer',
+        annotation_label: 'john.doe',
+        content: 'Please review'
+      )
+
+      html = Coradoc::Html::Converters::Base.convert_content_to_html(annotation)
+
+      expect(html).to include('class="admonition reviewer"')
+      expect(html).to include('john.doe')
+    end
+
+    it 'renders annotation with id attribute' do
+      annotation = Coradoc::CoreModel::AnnotationBlock.new(
+        annotation_type: 'tip',
+        id: 'helpful-tip',
+        content: 'Use Ruby 3.x'
+      )
+
+      html = Coradoc::Html::Converters::Base.convert_content_to_html(annotation)
+
+      expect(html).to include('id="helpful-tip"')
+    end
+
+    it 'renders annotation with inline element children' do
+      bold = Coradoc::CoreModel::InlineElement.new(format_type: 'bold', content: 'critical')
+      annotation = Coradoc::CoreModel::AnnotationBlock.new(
+        annotation_type: 'warning',
+        content: 'This is critical',
+        children: ['This is ', bold]
+      )
+
+      html = Coradoc::Html::Converters::Base.convert_content_to_html(annotation)
+
+      expect(html).to include('admonition warning')
+      expect(html).to include('<strong>critical</strong>')
+      expect(html).to include('This is ')
+    end
+  end
+end

data/coradoc-html/spec/coradoc/html/converters/paragraph_e2e_spec.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'coradoc/html'
+
+RSpec.describe 'Paragraph Normalization - End to End' do
+  describe 'parsing and converting paragraphs' do
+    it 'normalizes multi-line paragraphs correctly' do
+      # AsciiDoc source:
+      # Line 1
+      # Line 2
+      # Line 3
+      input = <<~ASCIIDOC
+        Line 1
+        Line 2
+        Line 3
+      ASCIIDOC
+
+      document = Coradoc.parse(input, format: :asciidoc)
+      html = Coradoc::Html::Converters::Document.to_html(document)
+
+      # Lines should be joined with spaces
+      expect(html).to include('<p>Line 1 Line 2 Line 3</p>')
+    end
+
+    it 'handles single line paragraphs' do
+      input = 'Single line paragraph'
+
+      document = Coradoc.parse(input, format: :asciidoc)
+      html = Coradoc::Html::Converters::Document.to_html(document)
+
+      expect(html).to include('<p>Single line paragraph</p>')
+    end
+
+    it 'handles multiple paragraphs' do
+      input = <<~ASCIIDOC
+        First paragraph
+        with multiple lines.
+
+        Second paragraph
+        also with multiple lines.
+      ASCIIDOC
+
+      document = Coradoc.parse(input, format: :asciidoc)
+      html = Coradoc::Html::Converters::Document.to_html(document)
+
+      expect(html).to include('<p>First paragraph with multiple lines.</p>')
+      expect(html).to include('<p>Second paragraph also with multiple lines.</p>')
+    end
+
+    it 'preserves explicit hard line breaks' do
+      # NOTE: This test documents the expected behavior
+      # The parser may need updates to properly detect hard line breaks
+      input = <<~ASCIIDOC
+        Line 1 +
+        Line 2
+      ASCIIDOC
+
+      document = Coradoc.parse(input, format: :asciidoc)
+      Coradoc::Html::Converters::Document.to_html(document)
+
+      # Should preserve line break with <br>
+      # Note: This may not work until parser is updated
+      # expect(html).to include("<br>")
+    end
+
+    it 'handles line continuation' do
+      # NOTE: This test documents the expected behavior
+      input = <<~ASCIIDOC
+        Line 1 +
+        Line 2
+      ASCIIDOC
+
+      document = Coradoc.parse(input, format: :asciidoc)
+      Coradoc::Html::Converters::Document.to_html(document)
+
+      # Should join without space
+      # Note: This may not work until parser is updated
+    end
+  end
+end

data/coradoc-html/spec/coradoc/html/converters/paragraph_normalization_spec.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'coradoc/html'
+require 'coradoc/core_model'
+
+RSpec.describe Coradoc::Html::Converters::Paragraph do
+  describe '#to_html - Paragraph Conversion' do
+    # CoreModel::Block with element_type "paragraph" should convert to HTML <p>
+
+    it 'converts a basic paragraph to HTML' do
+      paragraph = Coradoc::CoreModel::Block.new(
+        element_type: 'paragraph',
+        content: 'This is a paragraph.'
+      )
+
+      html = described_class.to_html(paragraph)
+
+      expect(html).to include('<p>This is a paragraph.</p>')
+    end
+
+    it 'converts paragraph with multi-line content' do
+      # In CoreModel, content is already normalized (lines joined with spaces)
+      # by the ToCoreModel transformer
+      paragraph = Coradoc::CoreModel::Block.new(
+        element_type: 'paragraph',
+        content: 'Line 1 Line 2 Line 3'
+      )
+
+      html = described_class.to_html(paragraph)
+
+      expect(html).to include('<p>Line 1 Line 2 Line 3</p>')
+    end
+
+    it 'converts paragraph with ID' do
+      paragraph = Coradoc::CoreModel::Block.new(
+        element_type: 'paragraph',
+        id: 'my-paragraph',
+        content: 'Content here'
+      )
+
+      html = described_class.to_html(paragraph)
+
+      expect(html).to include('id="my-paragraph"')
+      expect(html).to include('<p')
+      expect(html).to include('Content here')
+    end
+
+    it 'escapes HTML in paragraph content' do
+      paragraph = Coradoc::CoreModel::Block.new(
+        element_type: 'paragraph',
+        content: "<script>alert('xss')</script>"
+      )
+
+      html = described_class.to_html(paragraph)
+
+      expect(html).to include('&lt;script&gt;')
+      expect(html).not_to include('<script>')
+    end
+
+    it 'handles empty paragraph' do
+      paragraph = Coradoc::CoreModel::Block.new(
+        element_type: 'paragraph',
+        content: ''
+      )
+
+      html = described_class.to_html(paragraph)
+
+      expect(html).to include('<p></p>')
+    end
+
+    it 'handles paragraph with inline elements' do
+      paragraph = Coradoc::CoreModel::Block.new(
+        element_type: 'paragraph',
+        children: [
+          'Text with ',
+          Coradoc::CoreModel::InlineElement.new(format_type: 'bold', content: 'bold'),
+          ' text'
+        ]
+      )
+
+      html = described_class.to_html(paragraph)
+
+      expect(html).to include('<p>Text with <strong>bold</strong> text</p>')
+    end
+
+    it 'handles paragraph with link' do
+      paragraph = Coradoc::CoreModel::Block.new(
+        element_type: 'paragraph',
+        children: [
+          'Visit ',
+          Coradoc::CoreModel::InlineElement.new(
+            format_type: 'link',
+            content: 'example.com',
+            target: 'https://example.com'
+          )
+        ]
+      )
+
+      html = described_class.to_html(paragraph)
+
+      expect(html).to include('<a href="https://example.com">example.com</a>')
+    end
+  end
+end