coradoc-html 1.1.7

data/lib/coradoc/html/converter_base.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Html
+    # Abstract base class for HTML output converters
+    #
+    # This class defines the interface that all HTML output converters must implement.
+    # It provides common functionality for document validation, configuration building,
+    # and HTML output generation.
+    #
+    # @abstract Subclass and implement {#convert} to create a custom converter
+    #
+    # @example Creating a custom converter
+    #   class MyConverter < Coradoc::Html::ConverterBase
+    #     def convert
+    #       # Generate HTML from document
+    #     end
+    #   end
+    class ConverterBase
+      # Error class for converter validation errors
+      class ValidationError < Coradoc::Error; end
+
+      # Error class for unsupported document types
+      class UnsupportedDocumentError < Coradoc::Error; end
+
+      attr_reader :document, :config
+
+      # Initialize a new converter instance
+      #
+      # @param document [Coradoc::CoreModel::StructuralElement] The document to convert
+      # @param config [Hash, Configuration] Converter configuration
+      # @raise [UnsupportedDocumentError] if document is not a valid type
+      def initialize(document, config = {})
+        @document = validate_input(document)
+        @config = build_config(config)
+      end
+
+      # Convert the document to HTML
+      #
+      # @abstract Subclasses must implement this method
+      # @return [String] HTML output
+      # @raise [NotImplementedError] if not implemented by subclass
+      def convert
+        raise NotImplementedError,
+              "#{self.class.name} must implement #convert method"
+      end
+
+      # Convert and write to file
+      #
+      # @param output_path [String] Path to write the output file
+      # @return [String] The output path
+      def to_file(output_path)
+        html = convert
+
+        # Ensure parent directory exists
+        output_dir = File.dirname(output_path)
+        FileUtils.mkdir_p(output_dir) unless output_dir == '.'
+
+        File.write(output_path, html)
+
+        output_path
+      end
+
+      # Class method to convert a document
+      #
+      # @param document [Coradoc::CoreModel::StructuralElement] The document to convert
+      # @param config [Hash] Converter configuration
+      # @return [String] HTML output
+      def self.convert(document, config = {})
+        new(document, config).convert
+      end
+
+      # Class method to convert and write to file
+      #
+      # @param document [Coradoc::CoreModel::StructuralElement] The document to convert
+      # @param output_path [String] Path to write the output file
+      # @param config [Hash] Converter configuration
+      # @return [String] The output path
+      def self.to_file(document, output_path, config = {})
+        new(document, config).to_file(output_path)
+      end
+
+      # Get the converter name
+      #
+      # @return [Symbol] Converter name (e.g., :static, :spa)
+      def converter_name
+        @converter_name ||= self.class.name.split('::').last
+                                .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                                .downcase
+                                .to_sym
+      end
+
+      protected
+
+      # Validate the input document
+      #
+      # @param document [Object] The document to validate
+      # @return [Coradoc::CoreModel::Base] The validated document
+      # @raise [UnsupportedDocumentError] if document is not valid
+      def validate_input(document)
+        # Handle transformer hash output
+        document = Coradoc::Transformer.transform(document) if document.is_a?(Hash) && document.key?(:document)
+
+        # Validate document type - ONLY accept CoreModel types
+        unless document.is_a?(Coradoc::CoreModel::Base)
+          raise UnsupportedDocumentError,
+                "Expected CoreModel document, got: #{document.class}. " \
+                'Transform your document to CoreModel first using the appropriate ' \
+                'format transformer (e.g., ToCoreModel for your source format).'
+        end
+
+        document
+      end
+
+      # Build configuration from options
+      #
+      # @param config [Hash, Object] Configuration options or object
+      # @return [Object] Built configuration object
+      def build_config(config)
+        if config.public_methods.include?(:validate!)
+          config.validate!
+          return config
+        end
+
+        config
+      end
+
+      def extract_document_title
+        if @document.is_a?(Coradoc::CoreModel::StructuralElement) && @document.title
+          title = @document.title
+          return title if title.is_a?(String)
+          return title.text if title.is_a?(Coradoc::CoreModel::Base) && title.text
+
+          return title.to_s
+        end
+
+        'Untitled Document'
+      end
+
+      def extract_text_from_content(content)
+        case content
+        when Array
+          content.map { |item| extract_text_from_content(item) }.join
+        when String
+          content
+        when Coradoc::CoreModel::InlineElement
+          content.content.to_s
+        when Coradoc::CoreModel::Base
+          if content.content
+            extract_text_from_content(content.content)
+          else
+            content.to_s
+          end
+        else
+          content.to_s
+        end
+      end
+
+      # Escape HTML content
+      #
+      # @param text [String] Text to escape
+      # @return [String] Escaped text
+      def escape_html(text)
+        Coradoc::Html::Base.escape_html(text.to_s)
+      end
+
+      # Escape HTML attribute value
+      #
+      # @param value [String] Value to escape
+      # @return [String] Escaped value
+      def escape_attr(value)
+        value.to_s.gsub('"', '&quot;').gsub('<', '&lt;').gsub('>', '&gt;')
+      end
+    end
+  end
+end

data/lib/coradoc/html/converters/admonition.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Html
+    module Converters
+      # Converter for CoreModel::AnnotationBlock to HTML admonition block
+      class Admonition < Base
+        # Convert CoreModel::AnnotationBlock to HTML admonition block
+        def self.to_html(admonition, _options = {})
+          return '' unless admonition
+
+          # Get admonition type (NOTE, TIP, IMPORTANT, WARNING, CAUTION)
+          type = admonition.annotation_type ? admonition.annotation_type.to_s.upcase : 'NOTE'
+
+          # Build div attributes
+          attrs = build_attributes(admonition, type)
+
+          # Build title if present
+          title_html = build_title(admonition)
+
+          # Build admonition label
+          label = build_label(type)
+
+          # Process admonition content
+          content = process_content(admonition.content)
+
+          # Combine label, title, and content
+          admonition_html = ''
+          admonition_html += "#{label}\n"
+          admonition_html += "#{title_html}\n" if title_html
+          admonition_html += content
+
+          %(<div#{attrs}>\n#{admonition_html}\n</div>)
+        end
+
+        # Convert HTML admonition div to CoreModel::AnnotationBlock
+        def self.to_coradoc(element, _options = {})
+          return nil unless element.name == 'div'
+          return nil unless element['class']&.include?('admonition')
+
+          # Extract admonition type from class
+          type = extract_type(element)
+          return nil unless type
+
+          # Extract title if present
+          title_elem = element.at_css('.admonition-title')
+          title = title_elem&.text&.strip
+
+          # Extract content - all children except label and title
+          content_nodes = element.children.reject do |node|
+            node == element.at_css('.admonition-label') ||
+              node == title_elem ||
+              (node.text? && node.text.strip.empty?)
+          end
+
+          content = extract_content(content_nodes)
+
+          # Extract ID if present
+          id = element['id']
+
+          Coradoc::CoreModel::AnnotationBlock.new(
+            annotation_type: type.downcase,
+            content: content,
+            title: title,
+            id: id
+          )
+        end
+
+        def self.build_attributes(admonition, type)
+          attrs = [%( class="admonition admonition-#{type.downcase}")]
+
+          # Add ID if present
+          attrs << %( id="#{escape_attribute(admonition.id)}") if admonition.id
+
+          attrs.join
+        end
+
+        def self.build_label(type)
+          %(<div class="admonition-label">#{escape_html(type)}</div>)
+        end
+
+        def self.build_title(admonition)
+          return nil unless admonition.title
+
+          title_text = admonition.title.to_s
+          return nil if title_text.empty?
+
+          %(<div class="admonition-title">#{escape_html(title_text)}</div>)
+        end
+
+        def self.process_content(content)
+          return '' if content.nil?
+
+          if content.is_a?(Array)
+            # Group consecutive lines into paragraphs, handling inline elements
+            result = []
+            current_para = []
+
+            content.each do |item|
+              case item
+              when String
+                current_para << item
+              else
+                # End current paragraph and start a new one
+                if current_para.any?
+                  result << build_paragraph(current_para)
+                  current_para = []
+                end
+                result << convert_item(item)
+              end
+            end
+
+            # Don't forget the last paragraph
+            result << build_paragraph(current_para) if current_para.any?
+
+            result.compact.join("\n")
+          elsif content.is_a?(String)
+            "<p>#{escape_html(content)}</p>"
+          else
+            convert_item(content)
+          end
+        end
+
+        def self.build_paragraph(items)
+          return nil if items.nil? || items.empty?
+
+          # Convert all items to HTML and join them
+          content_html = items.map do |item|
+            case item
+            when String
+              escape_html(item)
+            else
+              convert_content_to_html(item)
+            end
+          end.join
+
+          return nil if content_html.empty?
+
+          "<p>#{content_html}</p>"
+        end
+
+        def self.convert_item(item)
+          case item
+          when String
+            "<p>#{escape_html(item)}</p>"
+          else
+            convert_content_to_html(item)
+          end
+        end
+
+        def self.extract_type(element)
+          return nil unless element['class']
+
+          # Extract type from class like "admonition-note", "admonition-warning", etc.
+          classes = element['class'].split
+          type_class = classes.find { |c| c.start_with?('admonition-') && c != 'admonition' }
+          return nil unless type_class
+
+          type_class.sub(/^admonition-/, '').upcase
+        end
+
+        def self.extract_content(nodes)
+          # Extract and convert content nodes
+          nodes.map do |node|
+            if node.text? && !node.text.strip.empty?
+              node.text.strip
+            elsif node.element?
+              case node.name
+              when 'p'
+                Paragraph.to_coradoc(node)
+              else
+                node.text.strip
+              end
+            end
+          end.compact
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/html/converters/attribute.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module Coradoc
+  module Html
+    module Converters
+      # Converts document attributes to/from HTML
+      #
+      # Attributes are document-level directives (e.g., :author:, :toc:).
+      # In HTML, we represent them as HTML comments to preserve the attribute
+      # information without affecting the rendered output.
+      #
+      # Examples:
+      #   :author: John Doe  => <!-- :author: John Doe -->
+      #   :toc:              => <!-- :toc: -->
+      class Attribute
+        # Convert CoreModel::Block (attribute) to HTML comment
+        def self.to_html(model, _options = {})
+          key = model.metadata&.dig(:key).to_s
+          key = escape_html(key)
+
+          # Handle single value or array of values
+          values = Array(model.metadata&.dig(:value)).compact
+
+          if values.empty?
+            # Attribute with no value (e.g., :toc:)
+            "<!-- :#{key}: -->"
+          else
+            # Attribute with value(s)
+            value_str = values.map { |v| escape_html(v.to_s) }.join(', ')
+            "<!-- :#{key}: #{value_str} -->"
+          end
+        end
+
+        # Convert HTML comment to CoreModel::Block (attribute)
+        def self.to_coradoc(element, _options = {})
+          return nil unless element.is_a?(Nokogiri::XML::Comment)
+
+          content = element.content.strip
+
+          # Match attribute pattern: :key: or :key: value
+          return nil unless content.match?(/^:([^:]+):(.*)$/)
+
+          match = content.match(/^:([^:]+):(.*)$/)
+          key = match[1].strip
+          value_part = match[2].strip
+
+          # Parse value(s) - could be comma-separated
+          values = if value_part.empty?
+                     []
+                   else
+                     value_part.split(',').map(&:strip)
+                   end
+
+          Coradoc::CoreModel::Block.new(
+            element_type: 'attribute',
+            content: key,
+            metadata: {
+              key: key,
+              value: values
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/html/converters/attribute_reference.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Html
+    module Converters
+      # Converts CoreModel::InlineElement with format_type "attribute_reference"
+      #
+      # Attribute references are inline placeholders that reference document attributes
+      # (e.g., {author}, {docname}, {revnumber}).
+      #
+      # In HTML, we render them as-is with the curly braces to preserve the
+      # reference syntax. Actual substitution of attribute values would happen
+      # at a different processing layer if needed.
+      #
+      # Examples:
+      #   {author}    => {author}
+      #   {docname}   => {docname}
+      class AttributeReference < Base
+        # Convert CoreModel::InlineElement (attribute_reference) to HTML
+        #
+        # @param model [Coradoc::CoreModel::InlineElement] the attribute reference model
+        # @param options [Hash] conversion options
+        # @option options [Hash] :document_attributes Document attributes for substitution
+        # @return [String] HTML representation of the attribute reference
+        def self.to_html(model, options = {})
+          name = model.target.to_s
+
+          # Try to substitute with actual attribute value if document_attributes provided
+          if options[:document_attributes]
+            value = options[:document_attributes][name] || options[:document_attributes][name]
+            return escape_html(value.to_s) if value
+          end
+
+          # Fallback: render as-is with curly braces
+          escape_html("{#{name}}")
+        end
+
+        # Convert HTML text to CoreModel::InlineElement (attribute_reference)
+        #
+        # @param text [String] the HTML text
+        # @param _options [Hash] conversion options (unused)
+        # @return [Coradoc::CoreModel::InlineElement, nil] the attribute reference model or nil
+        def self.to_coradoc(text, _options = {})
+          return nil unless text.is_a?(String)
+
+          # Match attribute reference pattern: {name}
+          match = text.match(/^\{([^}]+)\}$/)
+          return nil unless match
+
+          name = match[1]
+
+          Coradoc::CoreModel::InlineElement.new(
+            format_type: 'attribute_reference',
+            target: name
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/html/converters/audio.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Html
+    module Converters
+      # Converter for audio elements
+      class Audio < Base
+        # Convert CoreModel::Block (audio) to HTML <audio>
+        def self.to_html(audio, _options = {})
+          return '' unless audio
+
+          # Build audio attributes
+          attrs = build_attributes(audio)
+
+          # Get audio source from metadata or content
+          src = audio.metadata&.dig(:src) || audio.content
+
+          # Build source element
+          source_tag = %(<source src="#{escape_attribute(src)}"#{build_type_attr(src)}>)
+
+          # Build optional caption/title
+          caption = audio.title
+
+          # Determine if we need a wrapper (for block audio with caption)
+          if caption
+            <<~HTML.strip
+              <figure#{build_figure_attrs(audio)}>
+                <audio#{attrs}>
+                  #{source_tag}
+                  Your browser does not support the audio tag.
+                </audio>
+                <figcaption>#{escape_html(caption)}</figcaption>
+              </figure>
+            HTML
+          else
+            <<~HTML.strip
+              <audio#{attrs}>
+                #{source_tag}
+                Your browser does not support the audio tag.
+              </audio>
+            HTML
+          end
+        end
+
+        # Convert HTML <audio> to CoreModel::Block (audio)
+        def self.to_coradoc(element, _options = {})
+          # Handle both <audio> and <figure><audio> structures
+          audio_elem = if element.name == 'figure'
+                         element.at_css('audio')
+                       elsif element.name == 'audio'
+                         element
+                       else
+                         return nil
+                       end
+
+          return nil unless audio_elem
+
+          # Extract source from <source> tag or src attribute
+          src = extract_audio_src(audio_elem)
+          return nil unless src
+
+          # Extract caption if in figure
+          caption = if element.name == 'figure'
+                      figcaption = element.at_css('figcaption')
+                      figcaption&.text&.strip
+                    end
+
+          # Extract ID if present
+          id = audio_elem['id'] || element['id']
+
+          # Extract audio attributes
+          metadata = extract_audio_metadata(audio_elem)
+          metadata[:src] = src
+
+          Coradoc::CoreModel::Block.new(
+            element_type: 'audio',
+            content: src,
+            title: caption,
+            id: id,
+            metadata: metadata
+          )
+        end
+
+        def self.build_attributes(audio)
+          attrs = []
+
+          # Extract options from metadata
+          options = audio.metadata&.dig(:options) || []
+
+          # Add controls by default (unless nocontrols option is set)
+          has_controls = !options.include?('nocontrols')
+          attrs << ' controls' if has_controls
+
+          # Add autoplay if specified in options
+          attrs << ' autoplay' if options.include?('autoplay')
+
+          # Add loop if specified in options
+          attrs << ' loop' if options.include?('loop')
+
+          # Add muted if specified in options
+          attrs << ' muted' if options.include?('muted')
+
+          # Add ID if present
+          attrs << %( id="#{escape_attribute(audio.id)}") if audio.id
+
+          attrs.join
+        end
+
+        def self.build_type_attr(src)
+          # Determine audio MIME type from extension
+          ext = File.extname(src).downcase
+          type = case ext
+                 when '.mp3'
+                   'audio/mpeg'
+                 when '.ogg', '.oga'
+                   'audio/ogg'
+                 when '.wav'
+                   'audio/wav'
+                 when '.m4a'
+                   'audio/mp4'
+                 when '.aac'
+                   'audio/aac'
+                 when '.flac'
+                   'audio/flac'
+                 end
+
+          type ? %( type="#{type}") : ''
+        end
+
+        def self.build_figure_attrs(audio)
+          attrs = []
+
+          # Add ID to figure if present
+          attrs << %( id="#{escape_attribute(audio.id)}-figure") if audio.id
+
+          attrs.join
+        end
+
+        def self.extract_audio_src(element)
+          # Try to get src from <source> tag first
+          source = element.at_css('source')
+          return source['src'] if source && source['src']
+
+          # Fall back to src attribute on <audio>
+          element['src']
+        end
+
+        def self.extract_audio_metadata(element)
+          metadata = {}
+          options = []
+
+          # Extract boolean attributes
+          options << 'controls' if element.has_attribute?('controls')
+          options << 'autoplay' if element.has_attribute?('autoplay')
+          options << 'loop' if element.has_attribute?('loop')
+          options << 'muted' if element.has_attribute?('muted')
+
+          metadata[:options] = options unless options.empty?
+
+          metadata
+        end
+      end
+    end
+  end
+end