coradoc-html 1.1.14 → 1.1.15

data/lib/coradoc/html/layout_renderer.rb

@@ -15,25 +15,27 @@ module Coradoc
         @dist_assets_cache = {}
       end
 
-      def render_static(document, body_html, options)
+      def render_static(document, body_html, opts)
+        opts = RenderOptions.new(**opts) unless opts.is_a?(RenderOptions)
         layout_template = load_layout('default')
-        return build_static_fallback(document, body_html, options) unless layout_template
+        return build_static_fallback(document, body_html, opts) unless layout_template
 
-        layout_template.render(build_static_layout_data(document, body_html, options)).strip
+        layout_template.render(build_static_layout_data(document, body_html, opts)).strip
       end
 
-      def render_spa(document, options, body_html, toc_data)
-        dist_dir = options[:dist_dir] || File.expand_path('../../../frontend/dist', __dir__)
+      def render_spa(document, opts, body_html, toc_data)
+        opts = RenderOptions.new(**opts) unless opts.is_a?(RenderOptions)
+        dist_dir = opts.dist_dir || File.expand_path('../../../frontend/dist', __dir__)
         assets = load_dist_assets(dist_dir)
 
-        content_data = build_spa_content_data(document, body_html, options, toc_data)
+        content_data = build_spa_content_data(document, body_html, opts, toc_data)
         safe_json = Escape.safe_json(content_data)
 
         layout_template = load_layout('spa')
         if layout_template
-          layout_template.render(build_spa_layout_data(document, options, assets, safe_json)).strip
+          layout_template.render(build_spa_layout_data(document, opts, assets, safe_json)).strip
         else
-          build_spa_fallback(document, options, assets, safe_json)
+          build_spa_fallback(document, opts, assets, safe_json)
         end
       end
 
@@ -47,25 +49,25 @@ module Coradoc
         TitleText.escape(document&.title) || Config::DEFAULT_TITLE
       end
 
-      def resolve_lang(options)
-        options[:lang] || Config::DEFAULT_LANG
+      def resolve_lang(opts)
+        opts.lang || Config::DEFAULT_LANG
       end
 
-      def build_static_layout_data(document, body_html, options)
+      def build_static_layout_data(document, body_html, opts)
         {
-          'lang' => resolve_lang(options),
+          'lang' => resolve_lang(opts),
           'title' => resolve_escaped_title(document),
-          'author' => options[:author],
-          'description' => options[:description],
+          'author' => opts.author,
+          'description' => opts.description,
           'generator_version' => Coradoc::VERSION.to_s,
           'body' => body_html,
-          'custom_css' => options[:custom_css]
+          'custom_css' => opts.custom_css
         }
       end
 
-      def build_static_fallback(document, body_html, options)
+      def build_static_fallback(document, body_html, opts)
         Nokogiri::HTML::Builder.new do |doc|
-          doc.html(lang: resolve_lang(options)) do
+          doc.html(lang: resolve_lang(opts)) do
             doc.head do
               doc.meta(charset: 'UTF-8')
               doc.meta(name: 'viewport', content: 'width=device-width, initial-scale=1.0')
@@ -76,42 +78,42 @@ module Coradoc
         end.to_html
       end
 
-      def build_spa_content_data(document, body_html, options, toc_data)
+      def build_spa_content_data(document, body_html, opts, toc_data)
         {
           mode: 'classic',
           contentHtml: body_html,
           toc: toc_data,
-          meta: build_spa_meta(document, options),
-          options: build_spa_options(options)
+          meta: build_spa_meta(document, opts),
+          options: build_spa_options(opts)
         }
       end
 
-      def build_spa_meta(document, options)
+      def build_spa_meta(document, _opts)
         {
           title: TitleText.resolve(document&.title) || Config::DEFAULT_TITLE,
-          author: options[:author],
-          date: options[:revdate],
+          author: _opts.author,
+          date: nil,
           generator: "Coradoc #{Coradoc::VERSION}"
         }
       end
 
-      def build_spa_options(options)
+      def build_spa_options(opts)
         {
-          toc: options[:toc] ? true : false,
-          tocPlacement: (options[:toc_placement] || :auto).to_s,
-          sectnums: options[:section_numbers] == true,
-          themeToggle: options[:theme_toggle] != false,
-          readingProgress: options[:reading_progress] != false,
-          lang: resolve_lang(options)
+          toc: opts.toc ? true : false,
+          tocPlacement: (opts.toc_placement || :auto).to_s,
+          sectnums: opts.section_numbers == true,
+          themeToggle: opts.theme_toggle != false,
+          readingProgress: opts.reading_progress != false,
+          lang: resolve_lang(opts)
         }
       end
 
-      def build_spa_layout_data(document, options, assets, safe_json)
+      def build_spa_layout_data(document, opts, assets, safe_json)
         {
-          'lang' => resolve_lang(options),
+          'lang' => resolve_lang(opts),
           'title' => resolve_escaped_title(document),
-          'author' => options[:author],
-          'description' => options[:description],
+          'author' => opts.author,
+          'description' => opts.description,
           'generator_version' => Coradoc::VERSION.to_s,
           'css' => assets[:css],
           'js' => assets[:js],
@@ -119,9 +121,9 @@ module Coradoc
         }
       end
 
-      def build_spa_fallback(document, options, assets, safe_json)
+      def build_spa_fallback(document, opts, assets, safe_json)
         Nokogiri::HTML::Builder.new do |doc|
-          doc.html(lang: resolve_lang(options)) do
+          doc.html(lang: resolve_lang(opts)) do
             doc.head do
               doc.meta(charset: 'UTF-8')
               doc.meta(name: 'viewport', content: 'width=device-width, initial-scale=1.0')

data/lib/coradoc/html/render_options.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Html
+    class RenderOptions
+      attr_reader :layout, :lang, :toc, :toc_levels, :section_numbers,
+                  :section_number_levels, :author, :description, :custom_css,
+                  :dist_dir, :theme_toggle, :reading_progress, :toc_placement
+
+      def initialize(layout: :static, lang: 'en', toc: false, toc_levels: 2,
+                     section_numbers: false, section_number_levels: 3,
+                     author: nil, description: nil, custom_css: nil,
+                     dist_dir: nil, theme_toggle: true, reading_progress: true,
+                     toc_placement: :auto)
+        @layout = layout
+        @lang = lang
+        @toc = toc
+        @toc_levels = toc_levels
+        @section_numbers = section_numbers
+        @section_number_levels = section_number_levels
+        @author = author
+        @description = description
+        @custom_css = custom_css
+        @dist_dir = dist_dir
+        @theme_toggle = theme_toggle
+        @reading_progress = reading_progress
+        @toc_placement = toc_placement
+        freeze
+      end
+
+      def spa?
+        @layout == :spa
+      end
+
+      def static?
+        @layout == :static
+      end
+    end
+  end
+end

data/lib/coradoc/html/renderer.rb

@@ -48,8 +48,9 @@ module Coradoc
         template.render(assigns, registers: { renderer: self, section_numbers: @section_numbers }).strip
       end
 
-      def render_html5(document, **options)
-        builder = TocBuilder.from_options(options)
+      def render_html5(document, **)
+        opts = RenderOptions.new(**)
+        builder = TocBuilder.from_options(opts)
         @toc, @section_numbers = if document.is_a?(CoreModel::StructuralElement)
                                    builder.build_with_numbers(document)
                                  else
@@ -58,10 +59,10 @@ module Coradoc
 
         body_html = render(document)
 
-        if options[:layout] == :spa
-          render_spa_layout(document, body_html, options)
+        if opts.spa?
+          render_spa_layout(document, body_html, opts)
         else
-          render_static_layout(document, body_html, options)
+          render_static_layout(document, body_html, opts)
         end
       end
 
@@ -79,22 +80,22 @@ module Coradoc
 
       private
 
-      def render_static_layout(document, body_html, options)
-        if options[:toc] && @toc
+      def render_static_layout(document, body_html, opts)
+        if opts.toc && @toc
           toc_html = render(@toc)
           body_html = "#{toc_html}\n#{body_html}" unless toc_html.empty?
         end
-        @layout_renderer.render_static(document, body_html, options)
+        @layout_renderer.render_static(document, body_html, opts)
       end
 
-      def render_spa_layout(document, body_html, options)
-        numbered = options[:section_numbers] == true
+      def render_spa_layout(document, body_html, opts)
+        numbered = opts.section_numbers == true
         toc_data = if @toc
                      { entries: TocSerializer.new.serialize_entries(@toc.entries), numbered: numbered }
                    else
                      { entries: [], numbered: false }
                    end
-        @layout_renderer.render_spa(document, options, body_html, toc_data)
+        @layout_renderer.render_spa(document, opts, body_html, toc_data)
       end
 
       def find_and_load_template(type_name)

data/lib/coradoc/html/spa.rb

@@ -12,33 +12,16 @@ module Coradoc
     # Uses the unified Liquid template pipeline.
     class Spa < ConverterBase
       class Configuration < ConverterBase::ConfigurationBase
-        attr_accessor :theme_toggle, :reading_progress,
-                      :toc_sticky, :toc_levels, :lang,
-                      :template_dirs, :dist_dir
-
-        def initialize(**options)
-          @theme_toggle = options.fetch(:theme_toggle, true)
-          @reading_progress = options.fetch(:reading_progress, true)
-          @toc_sticky = options.fetch(:toc_sticky, true)
-          @toc_levels = options[:toc_levels] || 2
-          @lang = options[:lang] || 'en'
-          @template_dirs = options[:template_dirs]
-          @dist_dir = options[:dist_dir]
-        end
-
-        def to_h
-          {
-            theme_toggle: @theme_toggle, reading_progress: @reading_progress,
-            toc_sticky: @toc_sticky, toc_levels: @toc_levels,
-            lang: @lang, template_dirs: @template_dirs, dist_dir: @dist_dir
-          }
-        end
+        attribute :theme_toggle, default: true
+        attribute :reading_progress, default: true
+        attribute :toc_sticky, default: true
+        attribute :toc_levels, default: 2
+        attribute :lang, default: 'en'
+        attribute :template_dirs
+        attribute :dist_dir
 
         def validate!
-          return if @toc_levels.is_a?(Integer) && @toc_levels.between?(1, 5)
-
-          raise ConverterBase::ValidationError,
-                'TOC levels must be an integer between 1 and 5'
+          range_check(:toc_levels, 1, 5, label: 'TOC levels')
         end
       end
 

data/lib/coradoc/html/static.rb

@@ -12,44 +12,19 @@ module Coradoc
     # the unified Liquid template pipeline.
     class Static < ConverterBase
       class Configuration < ConverterBase::ConfigurationBase
-        attr_accessor :include_toc, :toc_levels,
-                      :section_numbering, :section_numbering_levels,
-                      :lang, :meta_tags, :custom_css, :embedded,
-                      :template_dirs
-
-        def initialize(**options)
-          @include_toc = options.fetch(:include_toc, false)
-          @toc_levels = options[:toc_levels] || 2
-          @section_numbering = options.fetch(:section_numbering, false)
-          @section_numbering_levels = options[:section_numbering_levels] || 3
-          @lang = options[:lang] || 'en'
-          @meta_tags = options[:meta_tags] || {}
-          @custom_css = options[:custom_css]
-          @embedded = options.fetch(:embedded, false)
-          @template_dirs = options[:template_dirs]
-        end
-
-        def to_h
-          {
-            include_toc: @include_toc, toc_levels: @toc_levels,
-            section_numbering: @section_numbering,
-            section_numbering_levels: @section_numbering_levels,
-            lang: @lang, meta_tags: @meta_tags, custom_css: @custom_css,
-            embedded: @embedded, template_dirs: @template_dirs
-          }
-        end
+        attribute :include_toc, default: false
+        attribute :toc_levels, default: 2
+        attribute :section_numbering, default: false
+        attribute :section_numbering_levels, default: 3
+        attribute :lang, default: 'en'
+        attribute :meta_tags, default: {}
+        attribute :custom_css
+        attribute :embedded, default: false
+        attribute :template_dirs
 
         def validate!
-          unless @toc_levels.is_a?(Integer) && @toc_levels.between?(1, 5)
-            raise ConverterBase::ValidationError,
-                  'TOC levels must be an integer between 1 and 5'
-          end
-
-          unless @section_numbering_levels.is_a?(Integer) &&
-                 @section_numbering_levels.between?(1, 6)
-            raise ConverterBase::ValidationError,
-                  'Section numbering levels must be an integer between 1 and 6'
-          end
+          range_check(:toc_levels, 1, 5, label: 'TOC levels')
+          range_check(:section_numbering_levels, 1, 6, label: 'Section numbering levels')
         end
       end
 

data/lib/coradoc/html/tag_mapping.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Html
+    module TagMapping
+      ELEMENT_TO_TAG = {
+        # Sections
+        section: 'section',
+        header: 'header',
+
+        # Blocks
+        paragraph: 'p',
+        example: 'div',
+        sidebar: 'aside',
+        quote: 'blockquote',
+        verse: 'div',
+        listing: 'pre',
+        literal: 'pre',
+        source: 'pre',
+        source_code: 'pre',
+        open: 'div',
+        horizontal_rule: 'hr',
+        comment: 'div',
+        pass: 'div',
+        reviewer: 'div',
+
+        # Lists
+        ordered_list: 'ol',
+        unordered_list: 'ul',
+        list_item: 'li',
+        description_list: 'dl',
+        description_term: 'dt',
+        description_detail: 'dd',
+
+        # List marker type aliases (from ListBlock#marker_type)
+        ordered: 'ol',
+        unordered: 'ul',
+        definition: 'dl',
+
+        # Tables
+        table: 'table',
+        table_row: 'tr',
+        table_cell: 'td',
+        table_header: 'th',
+
+        # Inline formatting (symbol keys from TagMapping, string keys from format_type)
+        bold: 'strong',
+        italic: 'em',
+        monospace: 'code',
+        highlight: 'mark',
+        superscript: 'sup',
+        subscript: 'sub',
+        underline: 'u',
+        strikethrough: 'del',
+        small_caps: 'span',
+
+        # Inline format type aliases (from InlineElement#resolve_format_type)
+        link: 'a',
+        xref: 'a',
+        footnote: 'sup',
+        span: 'span',
+        term: 'span',
+        quotation: 'q',
+        small: 'small',
+        stem: 'code',
+        attribute_reference: 'span',
+
+        # Links (semantic names)
+        anchor: 'a',
+        cross_reference: 'a',
+
+        # Media
+        image: 'img',
+        video: 'video',
+        audio: 'audio',
+
+        # Other
+        break: 'hr',
+        line_break: 'br',
+        admonition: 'div'
+      }.freeze
+
+      ELEMENT_CSS_CLASS = {
+        example: 'example',
+        sidebar: 'sidebar',
+        literal: 'literal'
+      }.freeze
+
+      def self.tag_for(element_type)
+        return 'div' if element_type.nil?
+
+        key = element_type.is_a?(Symbol) ? element_type : element_type.to_sym
+        ELEMENT_TO_TAG[key] || 'div'
+      end
+
+      def self.css_class_for(element_type)
+        return nil if element_type.nil?
+
+        key = element_type.is_a?(Symbol) ? element_type : element_type.to_sym
+        ELEMENT_CSS_CLASS[key]
+      end
+    end
+  end
+end

data/lib/coradoc/html/toc_builder.rb

@@ -19,11 +19,12 @@ module Coradoc
       #
       # @param options [Hash] options with :section_number_levels, :toc_levels, :section_numbers
       # @return [TocBuilder]
-      def self.from_options(options)
-        section_number_levels = options[:section_number_levels] || 3
-        toc_levels = options[:toc_levels] || 2
+      def self.from_options(opts)
+        opts = RenderOptions.new(**opts) unless opts.is_a?(RenderOptions)
+        section_number_levels = opts.section_number_levels || 3
+        toc_levels = opts.toc_levels || 2
         max_level = [toc_levels, section_number_levels].min
-        new(max_level: max_level, numbered: options[:section_numbers] == true, section_number_levels: section_number_levels)
+        new(max_level: max_level, numbered: opts.section_numbers == true, section_number_levels: section_number_levels)
       end
 
       # Build a Toc model from a document.

data/lib/coradoc/html/toc_serializer.rb

@@ -6,11 +6,12 @@ module Coradoc
     #
     # Used by the SPA layout to provide client-side navigation data.
     class TocSerializer
-      def build_json(document, options)
+      def build_json(document, opts)
         return { entries: [], numbered: false } unless document.is_a?(CoreModel::StructuralElement)
 
-        numbered = options[:section_numbers] == true
-        builder = TocBuilder.from_options(options)
+        opts = RenderOptions.new(**opts) unless opts.is_a?(RenderOptions)
+        numbered = opts.section_numbers == true
+        builder = TocBuilder.from_options(opts)
         toc = builder.build(document)
         { entries: serialize_entries(toc.entries), numbered: numbered }
       end

data/lib/coradoc/html/transform/from_core_model.rb

@@ -10,6 +10,8 @@ module Coradoc
       # This transformer converts CoreModel to HTML strings by delegating
       # to the existing theme/renderer pipeline.
       class FromCoreModel
+        include Coradoc::Transform::Base
+
         class << self
           # Transform a CoreModel to HTML string
           #

data/lib/coradoc/html/transform/to_core_model.rb

@@ -12,6 +12,8 @@ module Coradoc
       # Nokogiri::XML::Document or Nokogiri::XML::Node objects into CoreModel
       # by delegating to the existing input converter pipeline.
       class ToCoreModel
+        include Coradoc::Transform::Base
+
         class << self
           # Transform an HTML model (Nokogiri node) to CoreModel
           #

data/lib/coradoc/html/version.rb

@@ -2,6 +2,6 @@
 
 module Coradoc
   module Html
-    VERSION = '1.1.14'
+    VERSION = '1.1.15'
   end
 end

data/lib/coradoc/html.rb

@@ -21,6 +21,8 @@ module Coradoc
   module Html
     # Autoload HTML components
     autoload :Config, 'coradoc/html/config'
+    autoload :AssetResolver, 'coradoc/html/asset_resolver'
+    autoload :TagMapping, 'coradoc/html/tag_mapping'
     autoload :Escape, 'coradoc/html/escape'
     autoload :SectionNumberable, 'coradoc/html/section_numberable'
     autoload :TemplateCaching, 'coradoc/html/template_caching'
@@ -43,6 +45,7 @@ module Coradoc
     require 'coradoc/html/template_helpers'
     autoload :Renderer, 'coradoc/html/renderer'
     autoload :LayoutRenderer, 'coradoc/html/layout_renderer'
+    autoload :RenderOptions, 'coradoc/html/render_options'
     autoload :TocSerializer, 'coradoc/html/toc_serializer'
 
     # CoreModel transformers

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc-html
 version: !ruby/object:Gem::Version
-  version: 1.1.14
+  version: 1.1.15
 platform: ruby
 authors:
 - Ribose Inc.
@@ -117,6 +117,7 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - lib/coradoc/html.rb
+- lib/coradoc/html/asset_resolver.rb
 - lib/coradoc/html/config.rb
 - lib/coradoc/html/converter_base.rb
 - lib/coradoc/html/drop.rb
@@ -189,10 +190,12 @@ files:
 - lib/coradoc/html/input/postprocessor.rb
 - lib/coradoc/html/layout_renderer.rb
 - lib/coradoc/html/output.rb
+- lib/coradoc/html/render_options.rb
 - lib/coradoc/html/renderer.rb
 - lib/coradoc/html/section_numberable.rb
 - lib/coradoc/html/spa.rb
 - lib/coradoc/html/static.rb
+- lib/coradoc/html/tag_mapping.rb
 - lib/coradoc/html/template_caching.rb
 - lib/coradoc/html/template_config.rb
 - lib/coradoc/html/template_helpers.rb